symop.ccr.algebra.ket

Symbolic ket algebra for bosonic CCR systems.

This package implements purely symbolic manipulations of ket polynomials of the form

\[\lvert \psi \rangle \;=\; \sum_i c_i \, \lvert M_i \rangle,\]

where each \(\lvert M_i \rangle\) is a normally ordered ladder-operator monomial acting on the vacuum. All computations are performed using canonical commutation relations (CCR) and symbolic normal ordering. No matrix representations or Hilbert-space truncations are constructed.

Functionality provided in this package includes:

  • Construction from creators/annihilators or arbitrary operator words.

  • Symbolic normal ordering of operator products.

  • Linear combination and canonicalization (combining like terms).

  • Scalar multiplication and ket–ket multiplication.

  • Symbolic inner products

    \[\langle \phi \mid \psi \rangle,\]

    computed as identity coefficients of normal-ordered products.

  • Application of operator words

    \[W \lvert \psi \rangle,\]

    including linear combinations of words.

All routines operate purely at the algebraic level using commutator relations

\[[a_i, a_j^\dagger] = \langle m_i \mid m_j \rangle,\]

where the mode overlap may be non-orthogonal.

The module-level API is functional and stateless. The class KetPoly provides a thin immutable wrapper exposing these operations in object-oriented form while delegating the algebra to the underlying functional implementations.

Design principles

  • Fully symbolic CCR-based manipulation.

  • Support for non-orthogonal modes via overlap factors.

  • Deterministic canonical ordering using monomial signatures.

  • Separation of algebraic logic and representation.

Public API

class KetPoly(terms: tuple[KetTerm, ...] = ()) → None

Bases: object

Symbolic ket polynomial.

Parameters:

terms (tuple[KetTerm, ...]) – Tuple of ket terms. Terms are not automatically canonicalized on construction; call combine_like_terms() when needed.

Notes

The class is intentionally logic-only. It provides algebraic operations and structural queries, but no string/latex rendering.

property annihilation_count: int

Total number of annihilation operators across all terms.

apply_word(word: Iterable[LadderOp], *, eps: float = 1e-12) → KetPoly

Apply an operator word on the left: word * self.

Parameters:

  • word (Iterable[LadderOp]) – Ordered ladder-operator word to apply.

  • eps (float) – Numerical tolerance forwarded to normal ordering / canonicalization.

Returns:

Resulting ket polynomial.

Return type:

KetPoly

apply_words(terms: Iterable[tuple[complex, Iterable[LadderOp]]], *, eps: float = 1e-12) → KetPoly

Apply a linear combination of operator words on the left.

Interprets terms as an operator polynomial

\[\left(\sum_i c_i W_i\right)\lvert \psi \rangle.\]
Parameters:

  • terms (Iterable[tuple[complex, Iterable[LadderOp]]]) – Iterable of pairs (coeff, word).

  • eps (float) – Numerical tolerance forwarded to normal ordering / canonicalization.

Returns:

Resulting ket polynomial in canonical form.

Return type:

KetPoly

combine_like_terms(*, eps: float = 1e-12, approx: bool = False, decimals: int = 12, ignore_global_phase: bool = False) → KetPoly

Return a canonicalized polynomial by merging identical monomials.

Parameters:
Return type:

KetPoly

property creation_count: int

Total number of creation operators across all terms.

static from_ops(*, creators: Iterable[LadderOp] = (), annihilators: Iterable[LadderOp] = (), coeff: complex = 1.0, approx: bool = False, decimals: int = 12, ignore_global_phase: bool = False) → KetPoly

Construct from explicit creators and annihilators.

Parameters:
Return type:

KetPoly

static from_word(*, ops: Iterable[LadderOp], eps: float = 1e-12) → KetPoly

Construct by normal-ordering an operator word.

Parameters:
Return type:

KetPoly

static identity() → KetPoly

Construct identity object `KetPoly`.

Return type:

KetPoly

inner(other: KetPoly, *, eps: float = 1e-12) → complex

Return the symbolic inner product <self|other>.

Parameters:
Return type:

complex

property is_annihilator_only: bool

Return True if every term is annihilators-only or identity.

property is_creator_only: bool

Return True if every term is creators-only or identity.

property is_identity: bool

Return True if every term is the identity monomial.

is_normalized(*, eps: float = 1e-14) → bool

Return True if the polynomial has unit norm within tolerance.

Parameters:

eps (float)

Return type:

bool

property mode_count: int

Return the number of unique modes appearing in the polynomial.

multiply(other: KetPoly, *, eps: float = 1e-12, approx: bool = False, decimals: int = 12, ignore_global_phase: bool = False) → KetPoly

Return the symbolic product self * other.

Parameters:
Return type:

KetPoly

norm2(*, eps: float = 1e-12) → float

Return <self|self> as a real float.

Parameters:

eps (float)

Return type:

float

normalize(*, eps: float = 1e-14) → KetPoly

Return a normalized copy of the polynomial.

Parameters:

eps (float)

Return type:

KetPoly

require_creator_only() → None

Raise ValueError unless the polynomial is creators-only (or identity).

Return type:

None

scaled(c: complex) → KetPoly

Return c * self.

Parameters:

c (complex)

Return type:

KetPoly

terms: tuple[KetTerm, ...] = ()
property total_degree: int

Total ladder-operator degree across all terms.

property unique_modes: tuple[ModeOp, ...]

Return unique modes appearing in the polynomial (first-seen order).

Modules

apply

Apply operator words to symbolic kets.

combine

Canonicalization helpers for CCR ket terms.

from_ops

Construct ket terms directly from creators and annihilators.

from_word

Symbolic normal ordering of ladder-operator words for ket expansions.

identity_coeff

Identity-coefficient extraction for CCR ket expansions.

inner

Symbolic inner products for CCR ket expansions.

multiply

Symbolic multiplication of CCR ket expansions.

poly

Symbolic ket polynomials for CCR algebra.

scale

Scalar multiplication for CCR ket expansions.