treams_rs.operators¶
Basis and field operators, as functions and as operator objects.
Mirrors the operators of treams: the functions rotate, translate,
expand, expandlattice, permute, changepoltype and efield to
ffield, and the matching classes Rotate to FField.
Each function returns its matrix as a plain NumPy array; treams returns a
PhysicsArray. The keyword-only arguments describe the coefficients the matrix
acts on: basis, k0, material, poltype, modetype, and
lattice and kpar for periodic arrays. An operator object such as
Rotate(phi) stores the other arguments, and Rotate(phi) @ array reads
the keyword-only ones from the attributes of array. Physics objects keep
their metadata through their own methods (in_basis, rotate, ...).
PhysicsArray lives here because it exists for these operators: it holds the
attributes they read, and its attributes rotate, expand, ... apply them:
import numpy as np
import treams_rs as tr
basis = tr.SphericalBasis.default(1)
array = tr.operators.PhysicsArray(np.eye(len(basis)), basis=basis)
rotation = tr.operators.rotate(0.3, basis=basis)
assert np.allclose(tr.operators.Rotate(0.3) @ array, rotation)
assert np.allclose(array.rotate.apply_left(0.3), rotation)
BField¶
Magnetic flux density evaluation.
BField.__init__¶
BField(r: ArrayLike) -> None
BField.isinv¶
BField.isinv: bool
Whether this operator applies the inverse of its function.
BField.inv¶
BField.inv: BField
Raises NotImplementedError: sampled fields have no general inverse.
BField.FUNC¶
BField.FUNC: Callable[..., NDArray[np.generic]]
The function that builds the matrix, for example operators.rotate.
BField.get_kwargs¶
BField.get_kwargs(obj: Any, dim: int=-1) -> dict[str, Any]
Keyword arguments of FUNC read from the attributes of obj.
A tuple attribute holds one value per array axis; dim picks the axis.
Missing and None attributes are left out.
ChangePoltype¶
Helicity/parity conversion; omission selects the opposite input convention.
ChangePoltype.__init__¶
ChangePoltype(poltype: str | tuple[str, str] | None=None, *, isinv: bool=False) -> None
ChangePoltype.isinv¶
ChangePoltype.isinv: bool
Whether this operator applies the inverse of its function.
ChangePoltype.inv¶
ChangePoltype.inv: ChangePoltype
The inverse operator: the same arguments with isinv toggled.
ChangePoltype.FUNC¶
ChangePoltype.FUNC: Callable[..., NDArray[np.generic]]
The function that builds the matrix, for example operators.rotate.
ChangePoltype.get_kwargs¶
ChangePoltype.get_kwargs(obj: Any, dim: int=-1) -> dict[str, Any]
As Operator.get_kwargs; without a stored poltype, switch the object's.
DField¶
Displacement field evaluation.
DField.__init__¶
DField(r: ArrayLike) -> None
DField.isinv¶
DField.isinv: bool
Whether this operator applies the inverse of its function.
DField.inv¶
DField.inv: DField
Raises NotImplementedError: sampled fields have no general inverse.
DField.FUNC¶
DField.FUNC: Callable[..., NDArray[np.generic]]
The function that builds the matrix, for example operators.rotate.
DField.get_kwargs¶
DField.get_kwargs(obj: Any, dim: int=-1) -> dict[str, Any]
Keyword arguments of FUNC read from the attributes of obj.
A tuple attribute holds one value per array axis; dim picks the axis.
Missing and None attributes are left out.
EField¶
Electric field evaluation.
EField.__init__¶
EField(r: ArrayLike) -> None
EField.isinv¶
EField.isinv: bool
Whether this operator applies the inverse of its function.
EField.inv¶
EField.inv: EField
Raises NotImplementedError: sampled fields have no general inverse.
EField.FUNC¶
EField.FUNC: Callable[..., NDArray[np.generic]]
The function that builds the matrix, for example operators.rotate.
EField.get_kwargs¶
EField.get_kwargs(obj: Any, dim: int=-1) -> dict[str, Any]
Keyword arguments of FUNC read from the attributes of obj.
A tuple attribute holds one value per array axis; dim picks the axis.
Missing and None attributes are left out.
Expand¶
Expand into a destination basis, obtaining the source from keyword metadata.
Expand.__init__¶
Expand(basis: FieldBasis | tuple[FieldBasis, FieldBasis], modetype: str | tuple[str, str] | None=None, *, isinv: bool=False) -> None
Expand.isinv¶
Expand.isinv: bool
Whether this operator applies the inverse of its function.
Expand.inv¶
Expand.inv: Expand
The inverse operator: the same arguments with isinv toggled.
Expand.FUNC¶
Expand.FUNC: Callable[..., NDArray[np.generic]]
The function that builds the matrix, for example operators.rotate.
Expand.get_kwargs¶
Expand.get_kwargs(obj: Any, dim: int=-1) -> dict[str, Any]
As Operator.get_kwargs, plus the source basis and modetype.
ExpandLattice¶
Periodic expansion into an optional destination basis.
ExpandLattice.__init__¶
ExpandLattice(lattice: ArrayLike | Lattice | None=None, kpar: ArrayLike | WaveVector | None=None, basis: FieldBasis | None=None, modetype: str | None=None, eta: complex=0) -> None
ExpandLattice.isinv¶
ExpandLattice.isinv: bool
Whether this operator applies the inverse of its function.
ExpandLattice.inv¶
ExpandLattice.inv: ExpandLattice
Raises NotImplementedError: a periodic image sum has no inverse.
ExpandLattice.FUNC¶
ExpandLattice.FUNC: Callable[..., NDArray[np.generic]]
The function that builds the matrix, for example operators.rotate.
ExpandLattice.get_kwargs¶
ExpandLattice.get_kwargs(obj: Any, dim: int=-1) -> dict[str, Any]
As Operator.get_kwargs, plus the object's lattice and kpar.
FField¶
Riemann-Silberstein field F, with explicit helicity and sample points.
FField.__init__¶
FField(pol: int, r: ArrayLike) -> None
FField.isinv¶
FField.isinv: bool
Whether this operator applies the inverse of its function.
FField.inv¶
FField.inv: FField
Raises NotImplementedError: sampled fields have no general inverse.
FField.FUNC¶
FField.FUNC: Callable[..., NDArray[np.generic]]
The function that builds the matrix, for example operators.rotate.
FField.get_kwargs¶
FField.get_kwargs(obj: Any, dim: int=-1) -> dict[str, Any]
Keyword arguments of FUNC read from the attributes of obj.
A tuple attribute holds one value per array axis; dim picks the axis.
Missing and None attributes are left out.
FieldOperator¶
Cartesian field evaluation; no inverse from sampled fields is assumed.
FieldOperator.__init__¶
FieldOperator(r: ArrayLike) -> None
FieldOperator.isinv¶
FieldOperator.isinv: bool
Whether this operator applies the inverse of its function.
FieldOperator.inv¶
FieldOperator.inv: FieldOperator
Raises NotImplementedError: sampled fields have no general inverse.
FieldOperator.FUNC¶
FieldOperator.FUNC: Callable[..., NDArray[np.generic]]
The function that builds the matrix, for example operators.rotate.
FieldOperator.get_kwargs¶
FieldOperator.get_kwargs(obj: Any, dim: int=-1) -> dict[str, Any]
Keyword arguments of FUNC read from the attributes of obj.
A tuple attribute holds one value per array axis; dim picks the axis.
Missing and None attributes are left out.
GField¶
Riemann-Silberstein field G, with explicit helicity and sample points.
GField.__init__¶
GField(pol: int, r: ArrayLike) -> None
GField.isinv¶
GField.isinv: bool
Whether this operator applies the inverse of its function.
GField.inv¶
GField.inv: GField
Raises NotImplementedError: sampled fields have no general inverse.
GField.FUNC¶
GField.FUNC: Callable[..., NDArray[np.generic]]
The function that builds the matrix, for example operators.rotate.
GField.get_kwargs¶
GField.get_kwargs(obj: Any, dim: int=-1) -> dict[str, Any]
Keyword arguments of FUNC read from the attributes of obj.
A tuple attribute holds one value per array axis; dim picks the axis.
Missing and None attributes are left out.
HField¶
Magnetic field evaluation.
HField.__init__¶
HField(r: ArrayLike) -> None
HField.isinv¶
HField.isinv: bool
Whether this operator applies the inverse of its function.
HField.inv¶
HField.inv: HField
Raises NotImplementedError: sampled fields have no general inverse.
HField.FUNC¶
HField.FUNC: Callable[..., NDArray[np.generic]]
The function that builds the matrix, for example operators.rotate.
HField.get_kwargs¶
HField.get_kwargs(obj: Any, dim: int=-1) -> dict[str, Any]
Keyword arguments of FUNC read from the attributes of obj.
A tuple attribute holds one value per array axis; dim picks the axis.
Missing and None attributes are left out.
Operator¶
Reusable operator: stores its arguments and builds its matrix on demand.
Mirrors treams.Operator. Calling the operator with the keyword-only
arguments of its function returns the matrix as a plain array.
op @ obj reads those arguments from the attributes of obj with the
same names (basis, k0, material, poltype, modetype, ...)
and multiplies.
Operator.__init__¶
Operator(*args: Any, isinv: bool=False) -> None
Operator.isinv¶
Operator.isinv: bool
Whether this operator applies the inverse of its function.
Operator.inv¶
Operator.inv: Operator
The inverse operator: the same arguments with isinv toggled.
Operator.FUNC¶
Operator.FUNC: Callable[..., NDArray[np.generic]]
The function that builds the matrix, for example operators.rotate.
Operator.get_kwargs¶
Operator.get_kwargs(obj: Any, dim: int=-1) -> dict[str, Any]
Keyword arguments of FUNC read from the attributes of obj.
A tuple attribute holds one value per array axis; dim picks the axis.
Missing and None attributes are left out.
OperatorAttribute¶
Operator bound to the object it is read from, such as PhysicsArray.rotate.
Mirrors treams.OperatorAttribute. Calling the attribute transforms the
object: a.rotate(phi) returns R @ a for a vector and R @ a @ inv(R)
for a matrix, as a plain array. Unlike treams' OperatorAttribute, binding
creates a new object, so a saved bound attribute keeps its object.
OperatorAttribute.__init__¶
OperatorAttribute(op: type[Operator], obj: Any=None) -> None
OperatorAttribute.OP¶
OperatorAttribute.OP: type[Operator]
The operator class, for example Rotate.
OperatorAttribute.eval¶
OperatorAttribute.eval(*args: Any, **kwargs: Any) -> NDArray[np.generic]
Matrix of the operator for the bound object, as a plain array.
The arguments are those of the operator class and of its function; the object supplies the remaining keyword arguments.
OperatorAttribute.eval_inv¶
OperatorAttribute.eval_inv(*args: Any, **kwargs: Any) -> NDArray[np.generic]
Matrix of the inverse operator for the bound object.
OperatorAttribute.apply_left¶
OperatorAttribute.apply_left(*args: Any, **kwargs: Any) -> NDArray[np.generic]
The operator matrix times the bound object: eval(...) @ obj.
OperatorAttribute.apply_right¶
OperatorAttribute.apply_right(*args: Any, **kwargs: Any) -> NDArray[np.generic]
The bound object times the inverse matrix: obj @ eval_inv(...).
Permute¶
Cyclic plane-wave coordinate permutation.
Permute.__init__¶
Permute(n: int=1, *, isinv: bool=False) -> None
Permute.isinv¶
Permute.isinv: bool
Whether this operator applies the inverse of its function.
Permute.inv¶
Permute.inv: Permute
The inverse operator: the same arguments with isinv toggled.
Permute.FUNC¶
Permute.FUNC: Callable[..., NDArray[np.generic]]
The function that builds the matrix, for example operators.rotate.
Permute.get_kwargs¶
Permute.get_kwargs(obj: Any, dim: int=-1) -> dict[str, Any]
Keyword arguments of FUNC read from the attributes of obj.
A tuple attribute holds one value per array axis; dim picks the axis.
Missing and None attributes are left out.
PhysicsArray¶
Read-only array with the metadata that the operators read.
Mirrors treams.PhysicsArray. Unlike treams.PhysicsArray this is not an
ndarray subclass; arithmetic and slicing return plain arrays, so no
result carries metadata that no longer fits it. Use .array for NumPy
work and the bound operators (.rotate, .expand, .efield, ...)
for physics; they also return plain arrays.
A scalar metadata value describes every axis; a tuple gives one value per axis, from left to right. ScatteringBlock builds on this class.
Args
arr: The values; stored as an owned, read-only complex128 copy.basis: Basis of the axes.k0: Vacuum angular wavenumber.material: Medium, vacuum by default.poltype: Polarization convention,"helicity"by default.modetype: Kind of the waves:"regular","singular","up"or"down".lattice: Lattice of a periodic arrangement.kpar: Bloch vector of a periodic arrangement.
PhysicsArray.__init__¶
PhysicsArray(arr: ArrayLike, *, basis: FieldBasis | tuple[FieldBasis | None, ...] | None=None, k0: float | tuple[float | None, ...] | None=None, material: MaterialLike | tuple[MaterialLike | None, ...]=1, poltype: str | tuple[str | None, ...] | None=None, modetype: str | tuple[str | None, ...] | None=None, lattice: Lattice | None=None, kpar: WaveVector | None=None) -> None
PhysicsArray.shape¶
PhysicsArray.shape: tuple[int, ...]
Shape of array.
PhysicsArray.ndim¶
PhysicsArray.ndim: int
Number of dimensions of array.
PhysicsArray.changepoltype¶
PhysicsArray.changepoltype = op.OperatorAttribute(op.ChangePoltype)
Helicity/parity conversion; omission selects the opposite input convention. Bound OperatorAttribute: call applies to the owning object; .eval returns the operator matrix.
PhysicsArray.rotate¶
PhysicsArray.rotate = op.OperatorAttribute(op.Rotate)
Euler rotation with an exact inverse obtained by reversing the angles. Bound OperatorAttribute: call applies to the owning object; .eval returns the operator matrix.
PhysicsArray.translate¶
PhysicsArray.translate = op.OperatorAttribute(op.Translate)
Translation with the inverse displacement in the reversed basis pair. Bound OperatorAttribute: call applies to the owning object; .eval returns the operator matrix.
PhysicsArray.expand¶
PhysicsArray.expand = op.OperatorAttribute(op.Expand)
Expand into a destination basis, obtaining the source from keyword metadata. Bound OperatorAttribute: call applies to the owning object; .eval returns the operator matrix.
PhysicsArray.expandlattice¶
PhysicsArray.expandlattice = op.OperatorAttribute(op.ExpandLattice)
Periodic expansion into an optional destination basis. Bound OperatorAttribute: call applies to the owning object; .eval returns the operator matrix.
PhysicsArray.permute¶
PhysicsArray.permute = op.OperatorAttribute(op.Permute)
Cyclic plane-wave coordinate permutation. Bound OperatorAttribute: call applies to the owning object; .eval returns the operator matrix.
PhysicsArray.efield¶
PhysicsArray.efield = op.OperatorAttribute(op.EField)
Electric field evaluation. Bound OperatorAttribute: call applies to the owning object; .eval returns the operator matrix.
PhysicsArray.hfield¶
PhysicsArray.hfield = op.OperatorAttribute(op.HField)
Magnetic field evaluation. Bound OperatorAttribute: call applies to the owning object; .eval returns the operator matrix.
PhysicsArray.dfield¶
PhysicsArray.dfield = op.OperatorAttribute(op.DField)
Displacement field evaluation. Bound OperatorAttribute: call applies to the owning object; .eval returns the operator matrix.
PhysicsArray.bfield¶
PhysicsArray.bfield = op.OperatorAttribute(op.BField)
Magnetic flux density evaluation. Bound OperatorAttribute: call applies to the owning object; .eval returns the operator matrix.
PhysicsArray.gfield¶
PhysicsArray.gfield = op.OperatorAttribute(op.GField)
Riemann-Silberstein field G, with explicit helicity and sample points. Bound OperatorAttribute: call applies to the owning object; .eval returns the operator matrix.
PhysicsArray.ffield¶
PhysicsArray.ffield = op.OperatorAttribute(op.FField)
Riemann-Silberstein field F, with explicit helicity and sample points. Bound OperatorAttribute: call applies to the owning object; .eval returns the operator matrix.
Rotate¶
Euler rotation with an exact inverse obtained by reversing the angles.
Rotate.__init__¶
Rotate(phi: float, theta: float=0, psi: float=0, *, isinv: bool=False) -> None
Rotate.isinv¶
Rotate.isinv: bool
Whether this operator applies the inverse of its function.
Rotate.inv¶
Rotate.inv: Rotate
The inverse operator: the same arguments with isinv toggled.
Rotate.FUNC¶
Rotate.FUNC: Callable[..., NDArray[np.generic]]
The function that builds the matrix, for example operators.rotate.
Rotate.get_kwargs¶
Rotate.get_kwargs(obj: Any, dim: int=-1) -> dict[str, Any]
Keyword arguments of FUNC read from the attributes of obj.
A tuple attribute holds one value per array axis; dim picks the axis.
Missing and None attributes are left out.
Translate¶
Translation with the inverse displacement in the reversed basis pair.
Translate.__init__¶
Translate(r: ArrayLike, *, isinv: bool=False) -> None
Translate.isinv¶
Translate.isinv: bool
Whether this operator applies the inverse of its function.
Translate.inv¶
Translate.inv: Translate
The inverse operator: the same arguments with isinv toggled.
Translate.FUNC¶
Translate.FUNC: Callable[..., NDArray[np.generic]]
The function that builds the matrix, for example operators.rotate.
Translate.get_kwargs¶
Translate.get_kwargs(obj: Any, dim: int=-1) -> dict[str, Any]
Keyword arguments of FUNC read from the attributes of obj.
A tuple attribute holds one value per array axis; dim picks the axis.
Missing and None attributes are left out.
bfield¶
bfield(r: ArrayLike, *, basis: FieldBasis, k0: float, material: MaterialLike=1, modetype: str | None=None, poltype: str | None=None) -> NDArray[np.complex128]
Magnetic-flux-density matrix, in units of E over the vacuum speed of light.
Mirrors treams.bfield. The output has shape (..., 3, modes).
Args
r: Sample points, shape (..., 3).basis: Basis of the coefficients (metadata).k0: Vacuum angular wavenumber (metadata).material: Medium at the sample points (metadata).modetype: Kind of the waves (metadata):"regular"(default) or"singular"for multipoles,"up"(default) or"down"for PlaneWavePorts.poltype: Polarization convention (metadata),"helicity"by default.
changepoltype¶
changepoltype(poltype: str | tuple[str, str] | None=None, *, basis: FieldBasis | tuple[FieldBasis, FieldBasis], where: ArrayLike=True) -> NDArray[np.float64]
Matrix that changes the polarization convention between helicity and parity.
Mirrors treams.changepoltype. The real matrix is the same in both
directions and is its own inverse when the basis holds both pol of every
mode. A (destination, source) basis pair selects a rectangular part.
Args
poltype: Destination convention,"helicity"or"parity", or a (destination, source) pair; it must name a change."helicity"when omitted.basis: Basis, or (destination, source) pair, of one wave family (metadata).where: Boolean mask of the entries to keep, broadcast to the output.
dfield¶
dfield(r: ArrayLike, *, basis: FieldBasis, k0: float, material: MaterialLike=1, modetype: str | None=None, poltype: str | None=None) -> NDArray[np.complex128]
Electric-displacement matrix, in units of the vacuum permittivity times E.
Mirrors treams.dfield. The output has shape (..., 3, modes).
Args
r: Sample points, shape (..., 3).basis: Basis of the coefficients (metadata).k0: Vacuum angular wavenumber (metadata).material: Medium at the sample points (metadata).modetype: Kind of the waves (metadata):"regular"(default) or"singular"for multipoles,"up"(default) or"down"for PlaneWavePorts.poltype: Polarization convention (metadata),"helicity"by default.
efield¶
efield(r: ArrayLike, *, basis: FieldBasis, k0: float, material: MaterialLike=1, modetype: str | None=None, poltype: str | None=None) -> NDArray[np.complex128]
Electric-field matrix of shape (..., 3, modes) at the sample points r.
Mirrors treams.efield.
Args
r: Sample points, shape (..., 3).basis: Basis of the coefficients (metadata).k0: Vacuum angular wavenumber (metadata).material: Medium at the sample points (metadata).modetype: Kind of the waves (metadata):"regular"(default) or"singular"for multipoles,"up"(default) or"down"for PlaneWavePorts.poltype: Polarization convention (metadata),"helicity"by default.
expand¶
expand(basis: FieldBasis | tuple[FieldBasis, FieldBasis], modetype: str | tuple[str, str] | None=None, *, k0: float, material: MaterialLike=1, poltype: str | None=None, where: ArrayLike=True) -> NDArray[np.complex128]
Expansion matrix from a source basis into a destination basis.
Mirrors treams.expand. It covers multipoles of one family, regular
cylindrical waves into regular spherical waves, and plane waves into plane
waves or regular multipoles. The matrix includes every pair of destination
and source positions.
Args
basis: Basis, or (destination, source) pair (metadata).modetype: Kinds of the destination and source waves (metadata): one kind for both, or a (destination, source) pair. Multipoles take("regular", "regular")(default),("singular", "singular")or("regular", "singular"); plane waves take"up"or"down".k0: Vacuum angular wavenumber (metadata).material: Medium (metadata).poltype: Polarization convention (metadata),"helicity"by default.where: Boolean mask of the entries to keep, broadcast to the output.
Differences from treams
Between spherical and cylindrical bases with several positions, the matrix adds every pair of positions; treams pairs only equal particle indices.
expandlattice¶
expandlattice(lattice: ArrayLike | Lattice | None=None, kpar: ArrayLike | WaveVector | None=None, *, basis: FieldBasis | tuple[FieldBasis, FieldBasis], k0: float, material: MaterialLike=1, poltype: str | None=None, modetype: str | tuple[str, str] | None=None, eta: complex=0) -> NDArray[np.complex128]
Coupling or radiation matrix of a periodic array of multipoles.
Mirrors treams.expandlattice. A same-family destination gives the
lattice coupling (singular to regular waves); PlaneWavePorts give the
radiation into diffraction channels; a cylindrical destination of a
spherical source gives the radiation of sphere chains into cylindrical
waves. Spherical lattices are z, xy or xyz in 1D, 2D or 3D; cylindrical
lattices are x or xy.
Args
lattice: Lattice vectors or aLattice(metadata); the basis lattice when omitted.kpar: Bloch vector, or aWaveVector(metadata); the basis Bloch vector when omitted.basis: Basis, or (destination, source) pair (metadata).k0: Vacuum angular wavenumber (metadata).material: Medium (metadata).poltype: Polarization convention (metadata),"helicity"by default.modetype: Kinds of the destination and source waves (metadata), one kind or a (destination, source) pair.eta: Ewald split parameter, which balances the real-space and reciprocal-space parts of the lattice sum; 0 chooses it automatically.
Differences from treams
Between spherical and cylindrical bases with several positions, the matrix adds every pair of positions; treams pairs only equal particle indices.
ffield¶
ffield(pol: int, r: ArrayLike, *, basis: FieldBasis, k0: float, material: MaterialLike=1, modetype: str | None=None, poltype: str | None=None) -> NDArray[np.complex128]
Riemann-Silberstein field F of helicity pol, with the chiral index weights.
Mirrors treams.ffield. The output has shape (..., 3, modes).
Args
pol: Helicity of the field: 1 positive, 0 or -1 negative.r: Sample points, shape (..., 3).basis: Basis of the coefficients (metadata).k0: Vacuum angular wavenumber (metadata).material: Medium at the sample points (metadata).modetype: Kind of the waves (metadata), as forefield.poltype: Polarization convention (metadata),"helicity"by default.
gfield¶
gfield(pol: int, r: ArrayLike, *, basis: FieldBasis, k0: float, material: MaterialLike=1, modetype: str | None=None, poltype: str | None=None) -> NDArray[np.complex128]
Riemann-Silberstein field G of helicity pol, scaled like treams.
Mirrors treams.gfield. The scaling depends on the wave family and the
polarization convention, as in treams. For a scaling independent of the
basis, form (E +/- i Z H) / sqrt(2) from efield and hfield. The
output has shape (..., 3, modes).
Args
pol: Helicity of the field: 1 positive, 0 or -1 negative.r: Sample points, shape (..., 3).basis: Basis of the coefficients (metadata).k0: Vacuum angular wavenumber (metadata).material: Medium at the sample points (metadata).modetype: Kind of the waves (metadata), as forefield.poltype: Polarization convention (metadata),"helicity"by default.
hfield¶
hfield(r: ArrayLike, *, basis: FieldBasis, k0: float, material: MaterialLike=1, modetype: str | None=None, poltype: str | None=None) -> NDArray[np.complex128]
Magnetic-field matrix, in units of E over the vacuum impedance.
Mirrors treams.hfield. The output has shape (..., 3, modes).
Args
r: Sample points, shape (..., 3).basis: Basis of the coefficients (metadata).k0: Vacuum angular wavenumber (metadata).material: Medium at the sample points (metadata).modetype: Kind of the waves (metadata):"regular"(default) or"singular"for multipoles,"up"(default) or"down"for PlaneWavePorts.poltype: Polarization convention (metadata),"helicity"by default.
permute¶
permute(n: int=1, *, basis: PlaneWavePorts | PlaneWaveBasis, k0: float | None=None, material: MaterialLike=1, modetype: str='up', poltype: str | None=None, where: ArrayLike=True) -> NDArray[np.complex128]
Matrix of n cyclic permutations x -> y -> z of the plane-wave coordinates.
Mirrors treams.permute. The matrix maps the polarization amplitudes;
the directions change with the basis, so the output basis is
basis.permute(n). The permuted coefficients describe the same field
with its coordinate axes permuted.
Args
n: Number of cyclic permutations.basis: PlaneWaveBasis or PlaneWavePorts (metadata).k0: Vacuum angular wavenumber (metadata); PlaneWavePorts need it.material: Medium (metadata).modetype:"up"or"down"for PlaneWavePorts (metadata).poltype: Polarization convention (metadata),"helicity"by default.where: Boolean mask of the entries to keep, broadcast to the output.
rotate¶
rotate(phi: float, theta: float=0, psi: float=0, *, basis: FieldBasis | tuple[FieldBasis, FieldBasis], where: ArrayLike=True) -> NDArray[np.complex128]
Rotation matrix for the Euler angles phi, theta, psi (z-y-z convention).
Mirrors treams.rotate. Multipole positions stay fixed. A plane-wave
rotation keeps the coefficients and rotates the direction labels: its
output basis is basis.rotate(phi + psi). As in treams, plane waves need
theta = 0, and PlaneWavePorts need the alignment "xy".
Args
phi: First angle, about z.theta: Second angle, about y.psi: Third angle, about z.basis: Basis, or (destination, source) pair (metadata).where: Boolean mask of the entries to keep, broadcast to the output.
translate¶
translate(r: ArrayLike, *, basis: FieldBasis | tuple[FieldBasis, FieldBasis], k0: float, material: MaterialLike=1, poltype: str | None=None, modetype: str='up', where: ArrayLike=True) -> NDArray[np.complex128]
Translation matrix of a displacement r, shape (..., 3), at fixed positions.
Mirrors treams.translate. Multipole translations pair equal particle
indices and do not use the stored positions; use expand to couple
waves at different positions. Plane-wave translations multiply matching
wavevectors and polarizations by exp(i k.r).
Args
r: Displacements, shape (..., 3); the output has shape (..., destination modes, source modes).basis: Basis, or (destination, source) pair of one family (metadata).k0: Vacuum angular wavenumber (metadata).material: Medium (metadata).poltype: Polarization convention (metadata),"helicity"by default.modetype:"up"or"down"for PlaneWavePorts (metadata).where: Boolean mask of the entries to keep, broadcast to the output.