symop.modes.labels¶

Mode label implementations.

This package provides concrete implementations of logical mode labels: - ModeLabel: composite label combining path, polarization, and envelope. - PathLabel: spatial or logical path identifier. - PolarizationLabel: normalized Jones-vector polarization label.

These labels define overlap behavior and stable signatures used for mode construction and caching.

class ModeLabel(path: Path, polarization: Polarization, envelope: Envelope) → None¶

Bases: object

Mode label composed of a path label and a polarization label.

The overlap factorizes into the product of the component overlaps:

\[\langle m_1, m_2 \rangle = \langle p_1, p_2 \rangle \langle \pi_1, \pi_2 \rangle \langle \zeta_1, \zeta_2 \rangle,\]

where \(p\) denotes the path component ,:math:pi denotes the polarization component and \(\zeta\) denotes the envelope component.

Parameters:

path (Path)
polarization (Polarization)
envelope (Envelope)

path¶: Path label.

polarization¶: Polarization label.

envelope¶: Envelope label.

approx_signature(*, decimals: int = 12, ignore_global_phase: bool = False) → tuple[object, ...]¶

Approximate signature.

Parameters are forwarded to component approx_signature() methods.

Parameters:

decimals (int) – Number of decimal places used for rounding float parameters.
ignore_global_phase (bool) – If True, component signatures may ignore global phase where applicable.

Returns:

Approximate signature tuple.

Return type:

Signature

envelope: Envelope¶

overlap(other: ModeLabel) → complex¶

Compute the overlap with another mode label.

The total overlap factorizes into path, polarization, and envelope contributions. Evaluatinon short-circuits when an intremediate factor is zero.

Parameters:: other (ModeLabel) – Another mode label.
Returns:: Product of path, polarization, and envelope overlaps.
Return type:: complex

path: Path¶

polarization: Polarization¶

property signature: tuple[object, ...]¶

Stable signature for caching/comparison.

Returns:: Tuple identifying the mode label and its components.
Return type:: Signature

with_envelope(envelope: Envelope) → Self¶

Return a copy with replaced envelope.

Parameters:: envelope (Envelope) – New envelope.
Returns:: Updated mode label.
Return type:: ModeLabel

with_path(path: Path) → Self¶

Return a copy with a replaced path label.

Parameters:: path (Path) – New path label.
Returns:: Updated mode label.
Return type:: ModeLabel

with_polarization(polarization: Polarization) → Self¶

Return a copy with a replaced polarization label.

Parameters:: polarization (Polarization) – New polarization label.
Returns:: Updated mode label.
Return type:: ModeLabel

class Path(name: str) → None¶

Bases: object

Path label identifying a spatial (or logical) mode path.

Two path labels overlap if and only if their names are identical:

\[\begin{split}\langle \mathrm{path}(a), \mathrm{path}(b) \rangle = \begin{cases} 1, & a=b \\ 0, & a\neq b \end{cases}.\end{split}\]

Parameters:: name (str)

approx_signature(*, decimals: int = 12, ignore_global_phase: bool = False) → tuple[object, ...]¶

Approximate signature with rounded floating parameters.

Parameters:

decimals (int) – Number of decimal places used for rounding float parameters.
ignore_global_phase (bool) – If True, component signatures may ignore global phase where applicable.

Returns:

Approximate signature tuple.

Return type:

Signature

name: str¶

overlap(other: Path) → complex¶

Compute the overlap with another path label.

Parameters:: other (Path) – Another path label.
Returns:: \(1\) if names match, otherwise \(0\).
Return type:: complex

property signature: tuple[object, ...]¶

Stable signature for caching/comparison.

Returns:: Tuple identifying the path label.
Return type:: Signature

class Polarization(jones: tuple[complex, complex]) → None¶

Bases: object

Polarization label represented by a normalized Jones vector.

The Jones vector is stored as a 2-component complex vector:

\[\begin{split}\mathbf{v} = \begin{pmatrix} a \\ b \end{pmatrix},\end{split}\]

normalized such that \(\|\mathbf{v}\|_2 = 1\).

Canonicalization¶

Jones vectors have a physically irrelevant global phase. This class canonicalizes the input vector by removing an overall phase so that the first non-negligible component is real and non-negative. This makes signatures stable and reduces spurious differences due to global phase.

jones¶: Tuple \((a, b)\) representing the Jones vector components.

classmethod A() → Self¶

Anti-diagonal linear polarization.

Returns:: \(\frac{1}{\sqrt{2}}(1, -1)\).
Return type:: Polarization

classmethod D() → Self¶

Diagonal linear polarization.

Returns:: \(\frac{1}{\sqrt{2}}(1, 1)\).
Return type:: Polarization

classmethod H() → Self¶

Horizontal linear polarization.

Returns:: \((1, 0)\).
Return type:: Polarization

classmethod L() → Self¶

Left-circular polarization (one common convention).

Returns:: \(\frac{1}{\sqrt{2}}(1, i)\).
Return type:: Polarization

classmethod R() → Self¶

Right-circular polarization (one common convention).

Returns:: \(\frac{1}{\sqrt{2}}(1, -i)\).
Return type:: Polarization

classmethod V() → Self¶

Vertical linear polarization.

Returns:: \((0, 1)\).
Return type:: Polarization

approx_signature(*, decimals: int = 12, ignore_global_phase: bool = False) → tuple[object, ...]¶

Approximate signature with rounded components.

Parameters:

decimals (int) – Number of decimals to round to.
ignore_global_phase (bool) – If True, component signatures may ignore global phase where applicable.

Returns:

Signature tuple with rounded real/imag parts.

Return type:

Signature

jones: tuple[complex, complex]¶

classmethod linear(theta: float) → Self¶

Linear polarization at angle \(\theta\).

The Jones vector is:

\[\begin{split}\mathbf{v}(\theta) = \begin{pmatrix}\cos\theta \\ \sin\theta\end{pmatrix}.\end{split}\]

Parameters:: theta (float) – Polarization angle (radians).
Returns:: Linear polarization label at angle \(\theta\).
Return type:: Polarization

overlap(other: Polarization) → complex¶

Compute the polarization overlap.

This is the usual complex inner product of normalized Jones vectors:

\[\langle \mathbf{v}_1, \mathbf{v}_2 \rangle = \mathbf{v}_1^\dagger \mathbf{v}_2.\]

Parameters:: other (Polarization) – Another polarization label.
Returns:: Complex overlap \(\langle \mathbf{v}_1, \mathbf{v}_2 \rangle\).
Return type:: complex

rotated(theta: float) → Self¶

Rotate the polarization by angle \(\theta\).

This applies the real rotation matrix:

\[\begin{split}R(\theta)=\begin{pmatrix} \cos\theta & -\sin\theta\\ \sin\theta & \cos\theta \end{pmatrix}\end{split}\]

to the Jones vector.

Parameters:: theta (float) – Rotation angle (radians).
Returns:: Rotated polarization label.
Return type:: Polarization

property signature: tuple[object, ...]¶

Stable signature for caching/comparison.

The signature is based on the canonicalized Jones components.

transformed(unitary: ndarray, *, atol: float = 1e-12) → Self¶

Apply a 2x2 unitary Jones transformation.

This method applies a unitary matrix \(U\) to the Jones vector,

\[\mathbf{v}' = U \mathbf{v},\]

where \(U\) must satisfy

\[U^\dagger U = I\]

up to the specified tolerance.

Since Polarization canonicalizes global phase, transformed states that differ only by a global phase compare equal.

Parameters:

unitary (ndarray) – Complex 2x2 unitary Jones matrix.
atol (float) – Absolute tolerance used when checking unitarity.

Returns:

Transformed polarization label.

Return type:

Polarization

Raises:

ValueError – If unitary does not have shape (2, 2) or is not unitary within the requested tolerance.

Parameters:: jones (tuple[complex, complex])

Modules

`mode`	Composite mode labels.
`path`	Path labels for spatial or logical mode identification.
`polarization`	Polarization labels.