dreams API reference

This page contains the autogenerated API reference for selected dreams modules.

jax_tmat

dreams.jax_tmat.core_shell_sphere(lmax: int, k0: float, radii, epsilon, mu=None, kappa=None, poltype='helicity')

T-matrix of a multilayered sphere.

Construct the T-matrix of a homogeneous sphere or a concentric multilayered sphere of the given multipole order. The sphere may consist of multiple spherical shells with arbitrary material parameters.

The radii are specified from the inside to the outside. The material parameters are likewise ordered from the innermost region to the embedding medium, so that the last entry corresponds to the surrounding medium.

Parameters:

• lmax (int) – Maximum multipole order of the T-matrix.

• k0 (float) – Vacuum wavenumber.

• radii (float or array-like) – Radii from inside to outside. For a simple sphere, this can be a single radius. For a multilayered sphere, this should contain the radii of all concentric shells in increasing order.

• epsilon (array-like) – Relative permittivities of all layers and the embedding medium. Its length must be len(radii) + 1.

• mu (array-like, optional) – Relative permeabilities of all layers and the embedding medium. If None, all values are set to 1.

• kappa (array-like, optional) – Chirality parameters of all layers and the embedding medium. If None, all values are set to 0.

• poltype (str, optional) – Polarization basis of the returned T-matrix. Supported values are "helicity" and "parity". Defaults to "helicity".

Returns:

T-matrix of shape (N, N), where N = 2 * lmax * (lmax + 2).

Return type:

ndarray

dreams.jax_tmat.elchi(positions, radii, epsilon, lmax=3, k=6.283185307179586)

Compute a chirality metric from the global T-matrix.

The global T-matrix is built in the helicity basis (helicity=True) and split into + and - helicity sub-blocks. The function compares the singular values of these blocks and returns a normalized difference.

Parameters:

• positions – Array of shape (num, 3), particle positions.

• radii – Array of shape (num,), particle radii.

• epsilon – Array of shape (num, 2), [eps_sphere_i, eps_env].

• lmax – Maximum multipole order used for the local T-matrices.

• k – Vacuum wavenumber.

Returns:

Chirality metric (0 ~ achiral).

Return type:

float

dreams.jax_tmat.global_tmat(positions, radii, epsilon, lmax, k0, helicity, lmax_glob=None)

Build the global T-matrix for multiple spheres.

This is a convenience wrapper that:

1. Constructs local single-particle T-matrices (no interaction).

2. Adds multiple-scattering interactions.

3. Translates everything to a common origin.

Parameters:

• positions (array) – Particle positions, shape (num, 3).

• radii (array-like) – Radii of the spheres, shape (num,).

• epsilon (array-like) – Permittivities, shape (num, 2). For each i: epsilon[i, 0] = permittivity of sphere i, epsilon[i, 1] = permittivity of the embedding medium (same for all).

• lmax (int) – Local maximum multipole order.

• k0 (float) – Vacuum wavenumber.

• helicity (bool) – If True, result is in helicity basis.

• lmax_glob (int, optional) – Global maximum multipole order. If None, lmax_glob = lmax.

Returns:

global_t (ndarray): Global T-matrix about the origin. modes2 (tuple): Global modes (l, m, pol) for a single center. positions (array): The origin, shape (1, 3).

Return type:

tuple

dreams.jax_tmat.globfromloc(tlocal, positions, lmax, k0, num, helicity, epsilon, lmax_glob=None, mu=1, kappa=0)

Convert local, interacting T-matrix to a global T-matrix about the origin.

This function:

1. Includes interactions between particles via tmats_interact.

2. Translates the T-matrix from particle-centered coordinates to a common origin using spherical-wave translation operators.

Parameters:

• tlocal (ndarray) – Local block-diagonal T-matrix WITHOUT interactions.

• positions (array) – Particle positions, shape (num, 3).

• lmax (int) – Local maximum multipole order.

• k0 (float) – Vacuum wavenumber.

• num (int) – Number of particles.

• helicity (bool) – Helicity basis flag.

• epsilon (array-like) – Medium permittivity container. Only epsilon[0, 1] (a scalar) is used as the embedding permittivity.

• lmax_glob (int, optional) – Maximum multipole order for the global T-matrix. If None, lmax_glob = lmax.

• mu – Medium parameters.

• kappa – Medium parameters.

Returns:

global_t (ndarray): Global T-matrix about the origin. modes2 (tuple): Mode indices for the global basis (l, m, pol). positions (array): The origin, shape (1, 3).

Return type:

tuple

dreams.jax_tmat.sphere(lmax, k0, rad, epsilon, helicity)

T-Matrix of a sphere.

Construct the T-matrix of the given order and material for a sphere, in a given polarization basis.

Parameters:

• lmax (int) – Positive integer for the maximum degree of the T-matrix.

• k0 (float) – Wave number in vacuum.

• rad (float or array) – Radius of the sphere.

• epsilon (list[Material]) – The permittivities: the first material in the list specifies the sphere, the last material specifies the embedding medium.

• helicity (bool) – Flag for helicity basis.

Returns:

TMatrix

dreams.jax_tmat.sphere_parity(lmax, k, rad, epsilon, mu=None)

T-matrix (parity basis) of a single homogeneous sphere.

Parameters:

• lmax (int) – Maximum multipole order.

• k (float) – Vacuum wavenumber k0.

• rad (float) – Radius of the sphere.

• epsilon (array-like) – Length-2 array/list of permittivities [eps_sphere, eps_env].

• mu (array-like, optional) – Permeabilities corresponding to epsilon. If None, mu = 1 for all media.

Returns:

Diagonal T-matrix of shape (N, N) in parity basis, where

N = 2 * lmax * (lmax + 2).

Return type:

ndarray

dreams.jax_tmat.tmats_interact(ts, positions, modes, k0, helicity, epsilon, mu=1, kappa=0)

Dress local T-matrices with multiple-scattering interactions.

Parameters:

• ts (ndarray) – Local T-matrix of all particles combined (block diagonal), shape (M, M).

• positions (array) – Particle positions in Cartesian coordinates, shape (num, 3).

• modes (tuple) – Mode indices as returned by defaultmodes(lmax, num).

• k0 (float) – Vacuum wavenumber.

• helicity (bool) – Helicity basis flag.

• epsilon (array-like) – Medium permittivity information.

• mu – Magnetic and chiral parameters for the medium.

• kappa – Magnetic and chiral parameters for the medium.

Returns:

Full T-matrix including multiple scattering, shape (M, M).

Return type:

ndarray

dreams.jax_tmat.tmats_no_int(radii, epsilon, lmax, k0, helicity)

Compute local T-matrices for multiple non-interacting spheres.

Each sphere i is described by its radius radii[i] and by a pair of permittivities epsilon[i] = [eps_sphere_i, eps_env]. The embedding permittivity is assumed to be the same for all spheres and taken from the second entry (index 1).

Parameters:

• radii (array-like) – Radii of the spheres, shape (num,).

• epsilon (array-like) – Permittivities, shape (num, 2). For each i: epsilon[i, 0] = permittivity of sphere i, epsilon[i, 1] = permittivity of the embedding medium.

• lmax (int) – Maximum multipole order.

• k0 (float) – Vacuum wavenumber.

• helicity (bool) – If True, transform the result to helicity basis.

Returns:

Block-diagonal local T-matrix of shape (num*N, num*N),

where N = 2 * lmax * (lmax + 2) is the size of the single-sphere T-matrix in parity basis.

Return type:

ndarray

dreams.jax_tmat.xs(tmat, illu, k0, epsilon, flux=0.5, num=1, positions=Array([0., 0., 0.], dtype=float64), helicity=True)

Scattering and extinction cross section.

Possible for all T-matrices (global and local) in non-absorbing embedding. The values are calculated by

\[\begin{split}\sigma_\mathrm{sca} = \frac{1}{2 I} a_{slm}^\ast T_{s'l'm',slm}^\ast k_{s'}^{-2} C_{s'l'm',s''l''m''}^{(1)} T_{s''l''m'',s'''l'''m'''} a_{s'''l'''m'''} \\ \sigma_\mathrm{ext} = \frac{1}{2 I} a_{slm}^\ast k_s^{-2} T_{slm,s'l'm'} a_{s'l'm'}\end{split}\]

where \(a_{slm}\) are the expansion coefficients of the illumination, \(T\) is the T-matrix, \(C^{(1)}\) is the (regular) translation matrix and \(k_s\) are the wave numbers in the medium. All repeated indices are summed over. The incoming flux is \(I\).

Parameters:

• tmat (ndarray) – T-matrix, shape (N, N).

• illu (array-like) – Illumination coefficients a_{slm}, shape (N,).

• k0 (float) – Vacuum wavenumber.

• epsilon (array-like) – Permittivity information used to compute refractive indices via refractive_index(epsilon).

• flux (float, optional) – Incident flux used for normalization. A plane wave in these units has flux = 0.5 (default).

• num (int, optional) – Number of particles .

• positions (array-like, optional) – Particle positions, shape (num, 3), used to build the singular spherical-wave expansion operator for the scattered field. Default is a single particle at the origin.

• helicity (bool, optional) – Helicity basis flag used in sw_expand.

tuple[float, float]:

sigma_sca: Total scattering cross section. sigma_ext: Total extinction cross section.

dreams.jax_tmat.xs_1(lind, tmat, illu, k0, epsilon, flux=0.5, num=1, positions=Array([0., 0., 0.], dtype=float64), helicity=True)

Partial scattering cross section for selected multipole orders and polarizations.

This is a variant of xs that resolves the scattering cross section into electric and magnetic contributions for a chosen set of multipole orders lind. The T-matrix is assumed to be given in a single combined basis (possibly global) for num particles.

The calculation is based on the scattered coefficients

p = T @ a

where a are the illumination coefficients. The scattered power is expressed mode-wise and then summed only over the selected multipole orders and polarizations.

Parameters:

• lind (array-like) – Array of multipole orders l to include in the sum.

• tmat (ndarray) – T-matrix, shape (N, N).

• illu (array-like) – Illumination coefficients a_{slm}, shape (N,).

• k0 (float) – Vacuum wavenumber.

• epsilon (array-like) – Permittivity information used to compute refractive indices via refractive_index(epsilon).

• flux (float, optional) – Incident flux used for normalization. A plane wave in these units has flux = 0.5 (default).

• num (int, optional) – Number of particles represented in tmat.

• positions (array-like, optional) – Particle positions, shape (num, 3), used to construct the singular spherical-wave expansion operator. Default is a single particle at the origin.

• helicity (bool, optional) – Helicity basis flag used in sw_expand.

Returns:

xs_e1: Scattering cross section summed over electric-type modes

(pol == 1) with l in lind.

xs_m1: Scattering cross section summed over magnetic-type modes

(pol == 0) with l in lind.

Return type:

tuple[float, float]

dreams.jax_tmat.xs_ext_avg(tm, ks)

Rotation and polarization averaged extinction cross section.

The average is calculated as

\[\langle \sigma_\mathrm{ext} \rangle = -2 \pi \sum_{slm} \frac{\Re(T_{slm,slm})}{k_s^2}\]

where \(k_s\) is the wave number in the embedding medium for the polarization \(s\). It is only implemented for global T-matrices.

Returns:

float or complex

dreams.jax_tmat.xs_sca_avg(tm, ks)

Rotation and polarization averaged scattering cross section.

The average is calculated as

\[\langle \sigma_\mathrm{sca} \rangle = 2 \pi \sum_{slm} \sum_{s'l'm'} \frac{|T_{slm,s'l'm'}|^2}{k_s^2}\]

where \(k_s\) is the wave number in the embedding medium for the polarization \(s\). It is only implemented for global T-matrices.

Returns:

float or complex

jax_smat

dreams.jax_smat.add(scur, sadd, check_materials=True, check_modes=False)

Couple another S-matrix on top of the current one

Parameters:

• items (SMatrix) – S-matrices in their intended order

• check_materials (bool, optional) – Check for matching material parameters at each S-matrix

• check_materials – Check for matching modes at each Q-matrix

Returns:

SMatrix

dreams.jax_smat.array2dt(t, lmax, helicity, kx, ky, kz, pwpol, a, epsilon_medium, origin=None, eta=0.0, positions=None, nondifsum=True)

Convert a two-dimensional array of T-matrices into an S-matrix

Unlike for the 1d-case there is no local S-matrix used, so the result is taken with respect to the reference origin.

Parameters:

• kx (float, array_like) – X component of the plane wave

• ky (float, array_like) – Y component of the plane wave

• kz (float, array_like) – Z component of the plane wave

• pwpol (int, array_like) – Plane wave polarizations

• a (float, (2,2)-array) – Lattice vectors

• origin (float, (3,)-array, optional) – Reference origin of the result

• eta (float or complex, optional) – Splitting parameter in the lattice summation

Returns:

complex, array

dreams.jax_smat.arrayt(tmat, lmax, helicity, kpars, k0, a, epsilon_medium, origin=None, eta=0, mu=1, kappa=0, positions=None, nondifsum=True)

S-matrix from an array of T-matrices

Create a S-matrix for a two-dimensional array of objects described by the T-Matrix or an one-dimensional array of objects described by a cylindrical T-matrix.

Parameters:

• tmat (TMatrix or TMatrixC) – (Cylindrical) T-matrix to put in the array

• kpars (float, (N, 2)-array) – Tangential components of the wave vector

• a (array) – Definition of the lattice

• eta (float or complex, optional) – Splitting parameter in the lattice summation

Returns:

SMatrix

dreams.jax_smat.firstbrillouin2d(kpar, b, n=2, nondifsum=False)

Reduce the 2d wave vector to the first Brillouin zone.

The reduction to the first Brillouin zone is first approximated roughly. From this approximated vector and its 8 neighbours, the shortest one is picked. As a sufficient approximation is not guaranteed (especially for extreme geometries), this process is iterated n times.

Parameters:

• kpar (1d-array) – parallel wave vector

• b (2d-array) – reciprocal lattice vectors

• n (int) – number of iterations

Returns:

(1d-array)

dreams.jax_smat.illuminate_pw(kx, ky, kz, pol, pidx, helicity, positions, modes, nondif=True)

Illuminate with a plane wave

Parameters:

• kx (float, scalar or (N,)-array) – X component of the wave vector

• ky (float, scalar or (N,)-array) – Y component of the wave vector

• kz (float or complex, scalar or (N,)-array) – Z component of the wave vector

• pol (int, scalar or (N,)-array) – Polarization of wave, corresponding to the attribute TMatrix.helicity

dreams.jax_smat.interface(eps1, eps2, k0, modes, mu=1, kappa=0)

Planar interface between two media.

Parameters:

• basis (PlaneWaveBasisByComp) – Basis definitions.

• k0 (float) – Wave number in vacuum

• materials (Sequence[Material]) – Material definitions.

• poltype (str, optional) – Polarization type (params:Polarizations).

Returns:

SMatrix

dreams.jax_smat.latticecoupling(ks, kpar, a, positions, fullmodes, helicity, t, eta=0.0, nondifsum=True)

The coupling of the T-matrix in a lattice

Returns

\[\mathbb 1 - T C\]

The inverse of this multiplied to the T-matrix in latticeinteract. The lattice type is inferred from kpar.

Parameters:

• kpar (float) – The parallel component of the T-matrix

• a (array) – Definition of the lattice

• eta (float or complex, optional) – Splitting parameter in the lattice summation

Returns:

complex, array

dreams.jax_smat.periodic_to_pw(kx, ky, kz, pol, l, m, qol, area, posout=0, posin=0, helicity=True)

Convert periodic spherical wave to plane wave

Returns the coefficient for the basis change in a periodic arrangement of spherical modes to plane waves. For multiple positions only diagonal values (with respect to the position) are returned. A correct phase factor is still necessary for the full result.

The polarization values 0 and 1 refer to negative and positive helicity waves or, if helicity == False, to TE and TM parity.

Parameters:

• kx (float, array_like) – X component of destination mode wave vector

• ky (float, array_like) – Y component of destination mode wave vector

• kz (float or complex, array_like) – Z component of destination mode wave vector

• pol (int, array_like) – Polarization of the destination mode

• l (int, array_like) – Degree of the source mode

• m (int, array_like) – Order of the source mode

• qol (int, array_like) – Polarization of the source mode

• area (float, array_like) – Unit cell area

• posout (int, optional) – Output positions

• posin (int, optional) – Input positions

• helicity (bool, optional) – If true, helicity basis is assumed, else parity basis. Defaults to True.

Returns:

complex

dreams.jax_smat.propagation(epsilon, r, k0, modes, mu=1, kappa=0, modetype='up')

S-matrix for the propagation along a distance.

This S-matrix translates the reference origin along r.

Parameters:

• r (float, (3,)-array) – Translation vector.

• k0 (float) – Wave number in vacuum.

• basis (PlaneWaveBasis) – Basis definition.

• material (Material, optional) – Material definition.

• poltype (str, optional) – Polarization type (params:Polarizations).

Returns:

SMatrix

dreams.jax_smat.stack(items)

dreams.jax_smat.to_sw(l, m, polsw, kx, ky, kz, polpw, helicity=True)

Coefficient for the expansion of a plane wave in spherical waves

Returns the coefficient for the basis change from a plane wave to a spherical wave. For multiple positions only diagonal values (with respect to the position) are returned.

The polarization values 0 and 1 refer to negative and positive helicity waves or, if helicity == False, to TE and TM parity.

Parameters:

• l (int, array_like) – Degree of the spherical wave

• m (int, array_like) – Order of the spherical wave

• polsw (int, array_like) – Polarization of the destination mode

• kx (float, array_like) – X component of plane wave’s wave vector

• ky (float, array_like) – Y component of plane wave’s wave vector

• kz (float, array_like) – Z component of plane wave’s wave vector

• polpw (int, array_like) – Polarization of the plane wave

• helicity (bool, optional) – If true, helicity basis is assumed, else parity basis. Defaults to True.

Returns:

complex

dreams.jax_smat.to_sw_h(l, m, polvsw, kx, ky, kz, polpw)

dreams.jax_smat.to_sw_p(l, m, polvsw, kx, ky, kz, polpw)

dreams.jax_smat.translate_periodic(ks, kpar, a, rs, out, in_=None, rsin=None, helicity=True, eta=0)

Translation coefficients in a lattice

Returns the translation coefficients for the given modes in a lattice. The calculation uses the fast converging sums of ptsa.lattice.

The polarization values 0 and 1 refer to negative and positive helicity waves or, if helicity == False, to TE and TM parity.

Parameters:

• ks (float or complex, scalar or (2,)-array) – Wave number(s) in the medium, use two values in chiral media, indexed analogous to the polarization values

• kpar (float, (D,)-array) – Parallel component of the wave, defines the dimension with 1 <= D <= 3

• a (float, (D,D)-array) – Lattice vectors in each row of the array

• rs (float, (M, 3)-array) – Shift vectors with respect to one lattice point

• out (3- or 4-tuple of integer arrays) – Output modes

• in (3- or 4-tuple of integer arrays) – Input modes, if none are given equal to the output modes

• rsin (float) – Shift vectors to use with the input modes, if non are given equal to rs

• helicity (bool, optional) – If true, helicity basis is assumed, else parity basis. Defaults to True.

• eta (float or complex, optional) – Cut between real and reciprocal space summation, if equal to zero, an estimation for the optimal value is done.

Returns:

complex array

dreams.jax_smat.translate_periodic_h(lambda_, mu, pol1, l, m, pol2, *dlms)

dreams.jax_smat.translate_periodic_p(lambda_, mu, pol1, l, m, pol2, dlms)

jax_tr

dreams.jax_tr.changebasis(q, modes=None)

Swap between helicity and parity basis

Parameters:

modes (array, optional) – Change the number of modes while changing the basis

Returns:

SMatrix

dreams.jax_tr.field_outside(q, modes, illu)

Field coefficients above and below the Q-matrix

Given an illumination defined by the coefficients of each incoming mode calculate the coefficients for the outgoing field above and below the Q-matrix.

Parameters:

illu (tuple) – A 2-tuple of arrays, with the entries corresponding to upwards and downwards incoming modes.

Returns:

tuple

dreams.jax_tr.illuminate(sm, illu, illu2=None, /, *, smat=None)

Field coefficients above and below the S-matrix.

Given an illumination defined by the coefficients of each incoming mode calculate the coefficients for the outgoing field above and below the S-matrix. If a second SMatrix is given, the field expansions in between are also calculated.

Parameters:

• sm (array-like) – 2×2 block S-matrix. Each block is an (N, N) array acting on incoming/outgoing mode coefficients.

• illu (array-like) – Illumination, if modetype is specified, the direction will be chosen accordingly.

• illu2 (array-like, optional) – Second illumination. If used, the first argument is taken to be coming from below and this one to be coming from above.

• smat (SMatrix, optional) – Second S-matrix for the calculation of the field expansion between two S-matrices.

Returns:

If smat is None, returns (field_up, field_down). Otherwise returns (field_up, field_down, field_in_up, field_in_down).

Return type:

tuple

dreams.jax_tr.poynting_avg(coeffs, modes, ks, helicity, epsilon=1, mu=None, above=True)

Time-averaged z-component of the Poynting vector

Calculate the time-averaged Poynting vector’s z-component

\[\langle S_z \rangle = \frac{1}{2} \Re (\boldsymbol E \times \boldsymbol H^\ast) \boldsymbol{\hat{z}}\]

on one side of the Q-matrix with the given coefficients.

Parameters:

• coeffs (2-tuple) – The first entry are the upwards propagating modes the second one the downwards propagating modes

• above (bool, optional) – Calculate the Poynting vector above or below the Q-matrix

Returns:

float

dreams.jax_tr.poynting_avg_z(modes, k0, epsilon, mu, poltype, modetype)

Time-averaged z-component of the Poynting vector.

Calculate the time-averaged Poynting vector’s z-component

\[\langle S_z \rangle = \frac{1}{2} \Re (\boldsymbol E \times \boldsymbol H^\ast) \boldsymbol{\hat{z}}\]

on one side of the S-matrix with the given coefficients.

Parameters:

• modes (array_like, shape (N, 3)) – Per-mode data [kx, ky, pol], where pol is 0 or 1.

• k0 (float) – Vacuum wave number.

• epsilon (float or array_like) – Relative permittivity of the medium.

• mu (float or array_like) – Relative permeability of the medium.

• poltype ({"parity", "helicity"}) – Polarization basis of the modes.

• modetype ({"up", "down"}) – Direction of propagation.

Returns:

Two arrays of shape (N, N) to be used as quadratic forms in the Poynting-flux expressions.

Return type:

(a, b)

dreams.jax_tr.smat_array(tmat, lmax, helicity, kx, ky, k0, pitch, eps_medium, origin=None, eta=0.0, mu=1, kappa=0, rmax_coef=1, positions=None, nondifsum=True)

dreams.jax_tr.smat_full(tmat, lmax, helicity, kx, ky, k0, pitch, eps_medium, eps_below=1, eps_above=1, origin=None, eta=0.0, mu=1, kappa=0, rmax_coef=1, positions=None)

dreams.jax_tr.smat_spheres(radii, epsilons, eps_medium, lmax, k0, positions, helicity, kx, ky, pitch, origin=None, eta=0.0, mu=1, kappa=0, rmax_coef=1, local=False, lmax_glob=None)

S-matrix for a periodic array of spheres.

Parameters:

• radii (array_like, shape (num,)) – Radii of the spheres.

• epsilons (array_like) – Permittivities of the scatterers; shape and interpretation must match your T-matrix code.

• eps_medium (float or complex) – Embedding permittivity.

• lmax (int) – Maximum multipole order for the local T-matrix.

• k0 (float) – Vacuum wavenumber.

• positions (array_like, shape (num, 3)) – Sphere positions in the unit cell.

• helicity (bool) – True for helicity basis, False for parity.

• kx (float or array_like) – In-plane Bloch wavevector x-component.

• ky (float or array_like) – In-plane Bloch wavevector y-component.

• pitch (float) – Lattice constant (square lattice).

• origin (array_like, shape (3,), optional) – Origin of the lattice coordinate system. If None, defaults to (0, 0, 0).

• eta (float or complex, optional) – Ewald splitting parameter.

• mu (float or array_like, optional) – Relative permeability.

• kappa (float or array_like, optional) – Chirality parameter.

• rmax_coef (float, optional) – Cutoff factor for diffraction-order radius.

• local (bool, optional) – If True, use interacting local T-matrices.

• lmax_glob (int, optional) – Global multipole cutoff for the array. If None, defaults to lmax.

dreams.jax_tr.smat_spheres_full(radii, epsilons, eps_medium, lmax, k0, positions, helicity, kx, ky, pitch, eps_below=None, eps_above=None, origin=None, eta=0.0, mu=1, kappa=0, rmax_coef=1, local=False, lmax_glob=None)

dreams.jax_tr.stacking(smat, modes, helicity, kx, ky, k0, pitch, eps_medium, eps_below=1, eps_above=1, mu=1, kappa=0)

dreams.jax_tr.tr(q, k0, pitch, helicity, illu, basis, epsilon=1, mu=1, direction=1, modetype='up')

Transmittance and reflectance for one S-matrix.

Parameters:

• q – S-matrix of shape (2, 2, N, N).

• k0 – Vacuum wavenumber.

• pitch – Lattice constant (square array).

• helicity – True for helicity basis, False for parity.

• illu – Incoming plane-wave coefficients.

• basis – Mode list (kx, ky, pol).

• epsilon – Medium permittivity (scalar or pair).

• mu – Relative permeability.

• direction – +1 or -1 for incidence direction.

• modetype – “up” or “down”.

Returns:

Array [T, R] with transmittance and reflectance.

jax_op

dreams.jax_op.pw_translate(kx, ky, kz, x, y, z, where=True)

translate(kx, ky, kz, x, y, z)

Translation coefficient for plane wave modes

The translation coefficient is the phase factor \(\mathrm e^{\mathrm i \boldsymbol k \boldsymbol r}\).

Parameters:

• kx (float or complex, array_like) – Wave vector components

• ky (float or complex, array_like) – Wave vector components

• kz (float or complex, array_like) – Wave vector components

• x (float, array_like) – Translation vector components

• y (float, array_like) – Translation vector components

• z (float, array_like) – Translation vector components

Returns:

complex

dreams.jax_op.rotate(t, phi, theta, psi, rad=True, modes=None)

Rotate a T-matrix in a spherical-wave basis.

If modes is not given, the T-matrix is assumed to be a single-center global T-matrix, and the modes are inferred from its size using defaultlmax(len(t)) and defaultmodes(lmax, num=1).

If modes is given (as returned by defaultmodes(lmax, num)), the particle indices pidx are used to restrict the rotation to be block-diagonal in the particle index: modes belonging to different particles do not mix, which corresponds to rotating a local basis with several scatterers.

Parameters:

• t (ndarray) – T-matrix in a spherical-wave basis, shape (N, N).

• phi (float) – First Euler angle (rotation about z).

• theta (float) – Second Euler angle (rotation about y).

• psi (float) – Third Euler angle (rotation about z).

• rad (bool, optional) – If False, angles are given in degrees. If True (default), angles are in radians.

• modes (tuple, optional) – Tuple (pidx, l, m, pol) as returned by defaultmodes(lmax, num). If None, a single-center basis is assumed and modes are constructed automatically.

Returns:

Rotated T-matrix with the same shape as t.

Return type:

ndarray

dreams.jax_op.sw_expand(positions, modes, k0, helicity, epsilon, mu=1, kappa=0, modetype='singular', to_modetype=None)

Spherical-wave translation matrix for a set of scatterers.

Builds the pairwise translation matrix between spherical vector waves centered at the given particle positions.

Parameters:

• positions (array_like) – Particle positions of shape (num, 3) in Cartesian coordinates.

• modes (tuple) – Tuple (pidx, l, m, pol) as returned by defaultmodes(lmax, num). pidx is the particle index for each mode.

• k0 (float) – Vacuum wavenumber.

• helicity (bool) – If True, interpret pol as helicity indices. If False, use parity (TE/TM).

• epsilon (array_like or float) – Relative permittivity of the embedding medium. Passed to refractive_index.

• mu (array_like or float, optional) – Relative permeability of the embedding medium. Defaults to 1.

• kappa (array_like or float, optional) – Chirality parameter of the embedding medium. Defaults to 0.

• modetype (str, optional) – Mode type of the source waves (“regular” or “singular”). Defaults to “singular”.

• to_modetype (str, optional) – Mode type of the destination waves (“regular” or “singular”). If None, defaults to modetype.

Returns:

Translation matrix of shape (N, N), where N is the number of spherical modes in modes. The matrix maps coefficients at one set of centers to coefficients at another set of centers, using the chosen mode types.

Return type:

jax.Array

dreams.jax_op.sw_translate(lambda_, mu, pol, l, m, qol, kr, theta, phi, helicity=False, singular=True)

Translation coefficients between spherical vector waves.

This function computes the translation matrix between spherical vector waves at two centers. It dispatches to TE/TM (parity) or helicity implementations and to regular or singular waves.

Parameters:

• lambda (array_like) – Degrees l’ of the destination modes.

• mu (array_like) – Orders m’ of the destination modes.

• pol (array_like) – Polarizations of the destination modes (0/1 for TE/TM or -/+ helicity).

• l (array_like) – Degrees l of the source modes.

• m (array_like) – Orders m of the source modes.

• qol (array_like) – Polarizations of the source modes (0/1 for TE/TM or -/+ helicity).

• kr (array_like) – Radial arguments k r for the translation.

• theta (array_like) – Polar angles between source and destination centers (in radians).

• phi (array_like) – Azimuthal angles between source and destination centers (in radians).

• helicity (bool, optional) – If True, treat pol/qol as helicity indices. If False, treat them as parity (TE/TM). Defaults to False.

• singular (bool, optional) – If True, use singular (outgoing) spherical waves at the destination. If False, use regular spherical waves. Defaults to True.

Returns:

Translation matrix of shape determined by the broadcast of the input mode indices. Each entry maps a source mode (l, m, qol) to a destination mode (lambda_, mu, pol).

Return type:

jax.Array

dreams.jax_op.to_sw(l, m, polsw, kx, ky, kz, polpw, poltype=None)

Coefficient for the expansion of a plane wave in spherical waves.

Returns the coefficient for the basis change from a plane wave to a spherical wave. For multiple positions only diagonal values (with respect to the position) are returned. Args:

l (array_like): Degree(s) of the spherical waves. m (array_like): Order(s) of the spherical waves. polsw (array_like): Polarizations of the spherical waves

(0/1).

kx (array_like): x components of the plane-wave wave vectors. ky (array_like): y components of the plane-wave wave vectors. kz (array_like): z components of the plane-wave wave vectors. polpw (array_like): Polarizations of the plane waves (0/1). poltype (str, optional): Polarization type, “helicity” or

“parity”. If None, uses config.POLTYPE.

Returns:

jax.Array: Expansion coefficients of shape (N_sph, N_pw), where N_sph is the number of spherical modes and N_pw is the number of plane-wave modes.

dreams.jax_op.translate_rh(lambda_, mu, pol, l, m, qol, kr, theta, phi)

dreams.jax_op.translate_rp(lambda_, mu, pol, l, m, qol, kr, theta, phi)

dreams.jax_op.translate_sh(lambda_, mu, pol, l, m, qol, kr, theta, phi)

dreams.jax_op.translate_sp(lambda_, mu, pol, l, m, qol, kr, theta, phi)

jax_misc

dreams.jax_misc.basischange(out, in_=None)

Coefficients for the basis change between helicity and parity modes

Parameters:

• out (3- or 4-tuple of (M,)-arrays) – Output modes, the last array is taken as polarization.

• in (3- or 4-tuple of (N,)-arrays, optional) – Input modes, if none are given, equal to the output modes

Returns:

Change-of-basis matrix of shape (M, N).

Return type:

ndarray

dreams.jax_misc.defaultdim(lmax, nmax=1)

Default dimension

Given the maximal value of l return the size of the corresponding T-matrix. This is the inverse of defaultlmax. A value of zero is allowed.

Parameters:

• lmax (int) – Maximal value of l

• nmax (int, optional) – Number of particles, defaults to 1

Returns:

int

dreams.jax_misc.defaultlmax(dim, nmax=1)

Default maximal degree

Given the dimension of the T-matrix return the estimated maximal value of l. This is the inverse of defaultdim. A value of zero is allowed for empty T-matrices.

Parameters:

• dim (int) – Dimension of the T-matrix, respectively number of modes

• nmax (int, optional) – Number of particles, defaults to 1

Returns:

int

dreams.jax_misc.defaultmodes(lmax, nmax=1)

Default sortation of modes

Default sortation of the T-Matrix entries, including degree l, order m and polarization p.

Parameters:

• lmax (int) – Maximal value of l

• nmax (int, optional) – Number of particles, defaults to 1

Returns:

tuple

dreams.jax_misc.diffr_orders_circle(b, rmax)

Diffraction orders inside a circular cutoff.

Given a 2D reciprocal lattice with row vectors \(\mathbf{b}_0\) and \(\mathbf{b}_1\) stored in b, this function returns all pairs of integer indices \((m, n)\) such that the reciprocal lattice vector

\[\mathbf{G}_{mn} = m\,\mathbf{b}_0 + n\,\mathbf{b}_1\]

satisfies \(|\mathbf{G}_{mn}| \le r_ ext{max}\).

Parameters:

• b – (2, 2) array, reciprocal lattice vectors as rows.

• rmax – float, maximal radius in |G|.

Returns:

int64 array of shape (K, 2) with (m, n) indices.

dreams.jax_misc.minusonepow(l)

(-1) raised to an integer power.

Computes \((-1)^l\) for integer-like input.

Parameters:

l (array_like of int) – Exponent(s).

Returns:

Values in {-1, +1} with the same shape as l.

Return type:

ndarray

dreams.jax_misc.minusonepow_dif(l)

(-1) raised to an integer power.

Computes \((-1)^l\) for integer-like input.

Parameters:

l (array_like of int) – Exponent(s).

Returns:

Values in {-1, +1} with the same shape as l.

Return type:

ndarray

dreams.jax_misc.refractive_index(epsilon=1, mu=1, kappa=0)

Refractive index of a (chiral) medium

The refractive indices in a chiral medium \(\sqrt{\epsilon\mu} \mp \kappa\) are returned with the negative helicity result first.

Parameters:

• epsilon (float or complex, array_like, optional) – Relative permittivity, defaults to 1.

• mu (float or complex, array_like, optional) – Relative permeability, defaults to 1.

• kappa (float or complex, array_like, optional) – Chirality parameter, defaults to 0.

Returns:

float or complex, (2,)-array

dreams.jax_misc.sdefaultmodes(kpars, nondifsum=True)

Default ordering of plane-wave modes.

Given tangential wave vectors kpars = (kx, ky) this returns a tuple (kx, ky, pol) where each pair is duplicated for the two polarizations 1 and 0.

Parameters:

• kpars (array_like, shape (N, 2)) – Tangential components of the wave vector.

• nondifsum (bool, optional) – If True, use NumPy-on-JAX (anp), otherwise plain NumPy.

Returns:

(kx, ky, pol) each of length 2N.

Return type:

tuple of arrays

dreams.jax_misc.wave_vec_z(kx, ky, k, nondifsum=True)

Z component of the wave vector with positive imaginary part

The result is \(k_z = \sqrt{k^2 - k_x^2 - k_y^2}\) with \(\arg k_z \in \[ 0, \pi )\).

Parameters:

• kx (float, array_like) – X component of the wave vector

• ky (float, array_like) – Y component of the wave vector

• k (float or complex, array_like) – Wave number

• nondifsum (bool, optional) – If True, use plain numpy (anp), otherwise jax numpy.

Returns:

Complex z-components with the same broadcasted shape as kx, ky, and k.

Return type:

ndarray

dreams.jax_misc.wigner3j(l1, l2, l3, m1, m2, m3)

Vectorized Wigner 3-j symbol.

Thin wrapper around treams.special.cython_special.wigner3j() that evaluates the Wigner 3-j symbol on array inputs.

All arguments are broadcast to the shape of l3.

Parameters:

• l1 (array_like of int) – Degrees.

• l2 (array_like of int) – Degrees.

• l3 (array_like of int) – Degrees.

• m1 (array_like of int) – Orders.

• m2 (array_like of int) – Orders.

• m3 (array_like of int) – Orders.

Returns:

Complex array with the same shape as l3 containing \(\left(\begin{smallmatrix} l_1 & l_2 & l_3 \\ m_1 & m_2 & m_3 \end{smallmatrix}\right)\).

Return type:

ndarray