symop.core.terms

Algebraic terms used in operator constructions.

class DensityTerm(coeff: complex, left: Monomial, right: Monomial) → None

Bases: object

A single term in a density-operator expression.

A DensityTerm represents a coefficient multiplying a left and right monomial, matching the common pattern for outer-product-like or superoperator bookkeeping:

\[\rho \;\sim\; c \, L \, (\cdot) \, R,\]

or, in a bra-ket flavored picture, a term proportional to \(c\, L \lvert \psi \rangle \langle \phi \rvert R\) depending on the surrounding formalism.

The class stores left/right monomials explicitly, and provides helpers for structural queries (identity, creator-only, degree counts, etc.).

Notes

DensityTerm is immutable (frozen=True). Use scaled() to obtain a modified copy with a scaled coefficient.

This class implements DensityTerm protocol.

Parameters:

  • coeff (complex)

  • left (Monomial)

  • right (Monomial)

adjoint() → DensityTerm

Return the adjoint (Hermitian conjugate) of this density term.

The adjoint conjugates the coefficient and swaps left/right:

\[(c, L, R)^\dagger = (c^*, R, L).\]
Return type:

DensityTerm

property annihilation_count_left: int

Return the number of creation operators in the right monomial.

property annihilation_count_right: int

Return the number of annihilation operators in the right monomial.

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, …]

coeff: complex
property creation_count_left: int

Return the number of creation operators in the left monomial.

property creation_count_right: int

Return the number of creation operators in the right monomial.

static identity() → DensityTerm

Return the multiplicative identity density term.

This is the term with unit coefficient and identity monomials on both sides:

\[1 \cdot I \;\; \text{(left)} \quad,\quad 1 \cdot I \;\; \text{(right)}.\]
Return type:

DensityTerm

property is_annihilator_only: bool

Return True if both left and right are annihilator-only or identity.

property is_annihilator_only_left: bool

Return True if the left monomial is annihilator-only or identity.

property is_annihilator_only_right: bool

Return True if the right monomial is annihilator-only or identity.

property is_creator_only: bool

Return True if both left and right are creator-only or identity.

property is_creator_only_left: bool

Return True if the left monomial is creator-only or identity.

property is_creator_only_right: bool

Return True if the right monomial is creator-only or identity.

property is_diagonal_in_monomials: bool

Return True if left and right monomials are structurally identical.

This checks equality at the signature level:

\[\mathrm{sig}(L) = \mathrm{sig}(R).\]
property is_identity_left: bool

Return True if the left monomial is the identity.

property is_identity_right: bool

Return True if the right monomial is the identity.

left: Monomial
property mode_ops_left: tuple[ModeOp, ...]

Return the ordered mode operators appearing in the left monomial.

property mode_ops_right: tuple[ModeOp, ...]

Return the ordered mode operators appearing in the right monomial.

right: Monomial
scaled(s: complex) → DensityTerm

Return a copy with the coefficient scaled by s.

\[(c, L, R) \mapsto (s\,c, L, R).\]
Parameters:

s (complex)

Return type:

DensityTerm

property signature: tuple[object, ...]

Return a signature.

class KetTerm(coeff: complex, monomial: Monomial) → None

Bases: object

A single term in a ket-like operator expression.

A KetTerm represents a coefficient multiplied by a monomial in ladder operators (typically in normal-ordered form, depending on how Monomial is defined):

\[\lvert \psi \rangle \;\sim\; c \, M,\]

where \(c \in \mathbb{C}\) and \(M\) is a monomial of ladder operators (e.g., products of \(a_i\) and \(a_i^\dagger\)).

Notes

KetTerm is immutable (frozen=True). Use scaled() to obtain a modified copy with a scaled coefficient.

This class implements KetTerm protocol.

Parameters:

  • coeff (complex)

  • monomial (Monomial)

adjoint() → KetTerm

Return the adjoint (Hermitian conjugate) of this term.

The adjoint is defined by conjugating the scalar coefficient and taking the monomial adjoint:

\[(c\,M)^\dagger = c^*\, M^\dagger.\]
Return type:

KetTerm

property annihilation_count: int

Return the number of annihilation operators in the monomial.

\[n_\mathrm{ann} = \#\{\text{annihilators in } M\}.\]
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, …]

coeff: complex
property creation_count: int

Return the number of creation operators in the monomial.

\[n_\mathrm{create} = \#\{\text{creators in } M\}.\]
static identity() → KetTerm

Return the multiplicative identity term.

This is the term with unit coefficient and the identity monomial:

\[1 \cdot I.\]
Return type:

KetTerm

property is_annihilator_only: bool

Return True if the monomial contains only annihilation operators.

property is_creator_only: bool

Return True if the monomial contains only creation operators.

property is_identity: bool

Return True if the monomial is the identity.

property mode_ops: tuple[ModeOp, ...]

Return the ordered mode operators appearing in the monomial.

monomial: Monomial
scaled(s: complex) → KetTerm

Return a copy with the coefficient scaled by s.

The monomial is unchanged:

\[(c\,M) \mapsto (s\,c)\,M.\]
Parameters:

s (complex)

Return type:

KetTerm

property signature: tuple[object, ...]

Return a signature.

property total_degree: int

Return the total ladder-operator degree of the monomial.

\[\deg(M) = n_\mathrm{create} + n_\mathrm{ann}.\]
class OpTerm(ops: tuple[LadderOp, ...], coeff: complex = 1.0) → None

Bases: object

Single operator word with a complex coefficient.

An OpTerm represents an ordered product of ladder operators:

\[T \equiv c \, \hat o_1 \hat o_2 \cdots \hat o_L.\]

The adjoint is defined by reversing the operator order, taking daggers, and conjugating the scalar:

\[T^\dagger = c^* \, \hat o_L^\dagger \cdots \hat o_2^\dagger \hat o_1^\dagger.\]

Notes

identity() creates the empty word (no operators) with a given coefficient. The class is immutable.

Parameters:
adjoint() → OpTerm

Return the Hermitian adjoint term.

Return type:

OpTerm

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

Approximate signature, delegating to ladder-operator components.

Parameters:

  • decimals (int)

  • ignore_global_phase (bool)

Return type:

tuple[object, …]

coeff: complex = 1.0
static identity(c: complex = 1.0) → OpTerm

Return the identity term (empty word) with coefficient c.

Parameters:

c (complex)

Return type:

OpTerm

ops: tuple[LadderOp, ...]
scaled(c: complex) → OpTerm

Return a copy with coefficient multiplied by c.

Parameters:

c (complex)

Return type:

OpTerm

property signature: tuple[object, ...]

Exact signature, stable under structural equality.