symop.core.operators¶

Operator primitives for mode and ladder-operator bookkeeping.

This module defines logical modes and their associated ladder operators, including signatures and commutation behavior based on overlaps.

A logical mode is represented by ModeOp, which is defined by a composite mode label (typically including path, polarization, and envelope). The generalized canonical commutation relations are implemented by LadderOp using overlaps induced by the mode label.

Classes

`LadderOp`(kind, mode)	A bosonic ladder operator bound to a specific logical mode.
`ModeOp`(label, user_label, display_index)	A logical mode, defined by a composite mode label.

class LadderOp(kind: OperatorKind, mode: ModeOp) → None¶

Bases: object

A bosonic ladder operator bound to a specific logical mode.

A LadderOp is either an annihilation operator \(a\) or a creation operator \(a^\dagger\) acting on the mode specified by mode.

The (generalized) canonical commutation relations used here are determined by the overlap of the logical modes. For two logical modes \(i\) and \(j\), define:

\[G_{ij} = \langle \mathrm{mode}_i, \mathrm{mode}_j \rangle = \langle \mathrm{label}_i, \mathrm{label}_j \rangle.\]

Then the commutators are:

\[[a_i, a_j^\dagger] = G_{ij}, \qquad [a_i^\dagger, a_j] = -G_{ij}, \qquad [a_i, a_j] = [a_i^\dagger, a_j^\dagger] = 0.\]

If the mode overlap is (numerically) zero, the operators commute.

Notes

LadderOp is immutable (frozen=True). The with_* helpers return updated copies via dataclasses.replace().

This implements LadderOp protocol.

Parameters:

kind (OperatorKind)
mode (ModeOp)

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

Return an approximate signature.

Parameters:

decimals (int)
ignore_global_phase (bool)

Return type:

tuple[object, …]

commutator(other: LadderOp) → complex¶

Compute the commutator with another ladder operator.

The result implements the generalized CCR based on logical-mode overlap:

\[[a_i, a_j^\dagger] = \langle \mathrm{mode}_i, \mathrm{mode}_j \rangle = \langle \mathrm{label}_i, \mathrm{label}_j \rangle.\]

The other cases follow by antisymmetry and vanishing same-kind commutators:

\[[a_i^\dagger, a_j] = -[a_j, a_i^\dagger], \qquad [a_i, a_j] = [a_i^\dagger, a_j^\dagger] = 0.\]

Numerical note

If the overlap magnitude is below 1e-15, this returns 0j to avoid noise from nearly-orthogonal modes.

Parameters:: other (LadderOp)
Return type:: complex

dagger() → LadderOp¶

Return the Hermitian adjoint of this ladder operator.

\[(a_i)^\dagger = a_i^\dagger, \qquad (a_i^\dagger)^\dagger = a_i.\]

Return type:: LadderOp

property is_annihilation: bool¶: Return True if this operator is an annihilation operator \(a\).

property is_creation: bool¶: Return True if this operator is a creation operator \(a^\dagger\).

kind: OperatorKind¶

mode: ModeOp¶

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

class ModeOp(label: ModeLabel, user_label: str | None = None, display_index: int | None = <factory>) → None¶

Bases: object

A logical mode, defined by a composite mode label.

Conceptually, a ModeOp represents a (possibly composite) bosonic mode characterized by a label label that fully specifies how the mode overlaps with other modes (e.g., via path, polarization, and envelope components).

This object is also the factory for its ladder operators ann and create:

\[a_{\mathrm{mode}}, \quad a_{\mathrm{mode}}^\dagger.\]

The commutation relations are implemented on LadderOp using the overlap induced by label.

Notes

ModeOp is immutable (frozen=True). The with_* helpers return updated copies via dataclasses.replace().

The display_index is intended purely for UI/debugging and does not contribute to signatures.

This implements ModeOp protocol.

Parameters:

label (ModeLabel)
user_label (str | None)
display_index (int | None)

_ann: LadderOp¶

_cre: LadderOp¶

_with_semantic_label(label: ModeLabel) → Self¶

Parameters:: label (ModeLabel)
Return type:: Self

property ann: LadderOp¶: Public reference to an annihilation LadderOp.

property annihilate: LadderOp¶: Alias for self.ann.

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

Return an approximate signature.

Parameters:

decimals (int)
ignore_global_phase (bool)

Return type:

tuple[object, …]

property cre: LadderOp¶: Public reference to an creation LadderOp.

property create: LadderOp¶: Alias for self.cre.

display_index: int | None¶

label: ModeLabel¶

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

user_label: str | None = None¶

with_envelope(envelope: Envelope) → Self¶

Return an updated ModeOp with new Envelope.

Parameters:: envelope (Envelope)
Return type:: Self

with_index(idx: int) → Self¶

Return an updated ModeOp with new index.

Parameters:: idx (int)
Return type:: Self

with_label(label: ModeLabel) → Self¶

Return an updated ModeOp with new label.

Parameters:: label (ModeLabel)
Return type:: Self

with_path(path: Path) → Self¶

Return an updated ModeOp with new Path.

Parameters:: path (Path)
Return type:: Self

with_polarization(polarization: Polarization) → Self¶

Return an updated ModeOp with new Polarization.

Parameters:: polarization (Polarization)
Return type:: Self

with_user_label(tag: str) → Self¶

Return an updated ModeOp with new user_label.

Parameters:: tag (str)
Return type:: Self