symop.ccr.algebra.ket.poly

Symbolic ket polynomials for CCR algebra.

This module defines KetPoly, a small immutable wrapper around a tuple of ket terms.

A ket polynomial represents a finite expansion

\[\lvert \psi \rangle \;\sim\; \sum_k c_k\, M_k,\]

where each \(M_k\) is a normally ordered monomial of ladder operators. All operations are purely symbolic and based on CCR normal ordering and term canonicalization; no matrix representations are used.

Presentation / pretty-printing is intentionally out of scope for this package.

Classes

KetPoly([terms])

Symbolic ket polynomial.
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).

_ket_poly_check: KetPolyProtocol