symop.ccr.algebra.density

Symbolic density-operator algebra for bosonic CCR systems.

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

\[\rho \;=\; \sum_i c_i \, \lvert L_i \rangle \langle R_i \rvert,\]

where each term consists of a complex coefficient and a pair of normally ordered ladder-operator monomials. All computations are performed using canonical commutation relations (CCR) and symbolic normal ordering. No matrix representations or finite-dimensional truncations are constructed.

Functionality provided in this package includes:

• Construction of pure states

  \[\rho = \lvert \psi \rangle \langle \psi \rvert.\]

• Trace evaluation and trace normalization.

• Hilbert–Schmidt inner products

  \[\langle A, B \rangle = \mathrm{Tr}(A^\dagger B),\]

  and purity

  \[\mathrm{Tr}(\rho^2).\]

• Left and right application of operator words.

• Partial trace over selected modes.

• Canonicalization by combining like terms.

• Symbolic expansion of monomial and word products.

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

Design principles

• Fully symbolic CCR-based manipulation.

• Support for non-orthogonal modes via overlap factors.

• Deterministic canonical ordering using monomial signatures.

• Strict separation between algebraic logic and representation.

Public API

• DensityPoly

class DensityPoly(terms: tuple[DensityTerm, ...] = ()) → None

Bases: object

Symbolic density polynomial.

A DensityPoly stores a tuple of density terms, each term being a coefficient times an outer product of monomials:

\[c \, |L\rangle\langle R|.\]

Parameters:

terms (tuple[DensityTerm, ...]) – Tuple of density terms. Terms are not automatically canonicalized on construction; call combine_like_terms() (or normalize()) when needed.

Notes

This class is intentionally logic-only. It wraps functional algebra routines and provides convenient structural queries and standard linear-algebra-like operations (addition and scalar scaling).

apply_left(word: Iterable[LadderOp]) → DensityPoly

Apply an operator word to the left: word * rho.

This symbolically applies the ladder-operator word to each term’s left monomial.

Parameters:

word (Iterable[LadderOp]) – Ordered ladder-operator word to apply on the left.

Returns:

Resulting density polynomial.

Return type:

DensityPoly

apply_right(word: Iterable[LadderOp]) → DensityPoly

Apply an operator word to the right: rho * word.

This symbolically applies the ladder-operator word to each term’s right monomial.

Parameters:

word (Iterable[LadderOp]) – Ordered ladder-operator word to apply on the right.

Returns:

Resulting density polynomial.

Return type:

DensityPoly

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

Return a canonicalized polynomial by merging identical terms.

Density terms are bucketed by signatures of their left/right monomials, and coefficients within each bucket are summed.

Parameters:

• eps (float) – Buckets whose summed coefficient magnitude is smaller than eps are removed.

• approx (bool) – If True, use approximate signatures for matching.

• decimals (int) – Number of decimals used when rounding floating components in approximate signatures.

• ignore_global_phase (bool) – If True, component signatures may ignore global phase when constructing approximate signatures.

Returns:

Polynomial with like terms merged and near-zero terms removed.

Return type:

DensityPoly

Notes

This is purely signature-based merging. It does not apply CCR commutation relations or reorder monomials.

hs_norm() → float

Return the Hilbert-Schmidt norm.

Returns:

\(\|\rho\|_{\mathrm{HS}}\).

Return type:

float

hs_norm2() → float

Return the squared Hilbert-Schmidt norm.

\[\| \rho \|_{\mathrm{HS}}^2 = \langle \rho, \rho \rangle_{\mathrm{HS}}.\]

Returns:

Squared Hilbert-Schmidt norm (real-valued).

Return type:

float

static identity() → DensityPoly

Return the identity operator as a density polynomial.

This returns the single-term polynomial

\[|I\rangle\langle I|,\]

where \(I\) is the identity monomial (empty word).

Returns:

Identity density polynomial.

Return type:

DensityPoly

inner(other: DensityPoly) → complex

Return the Hilbert-Schmidt inner product <self, other>.

This delegates to density_inner() and is typically equivalent to

\[\langle A, B \rangle_{\mathrm{HS}} = \mathrm{Tr}(A^\dagger B).\]

Parameters:

other (DensityPoly) – Another density polynomial.

Returns:

Hilbert-Schmidt inner product.

Return type:

complex

is_block_diagonal_by_modes() → bool

Return True iff each term matches left/right mode lists.

This checks that the ordered list of mode signatures appearing in the left monomial matches that of the right monomial for every term.

Return type:

bool

property is_creator_only: bool

Return True iff every term is creator-only or identity on both sides.

property is_creator_only_left: bool

Return True iff every term is creator-only or identity on the left.

property is_creator_only_right: bool

Return True iff every term is creator-only or identity on the right.

property is_diagonal_in_monomials: bool

Return True iff each term has identical left/right monomials.

property is_identity_left: bool

Return True iff every term has identity on the left.

property is_identity_right: bool

Return True iff every term has identity on the right.

is_pure(eps: float = 1e-12) → bool

Return True if purity is 1 within tolerance.

Parameters:

eps (float)

Return type:

bool

is_trace_normalized(eps: float = 1e-12) → bool

Return True if \(\mathrm{Tr}(\rho)=1\) within tolerance.

Parameters:

eps (float)

Return type:

bool

property mode_count: int

Return the number of unique modes appearing in the density.

multiply(other: DensityPoly, *, eps: float = 1e-12) → DensityPoly

Return the symbolic product self * other.

For density terms |L><R| and |A><B|, multiplication is defined as

\[|L\rangle\langle R|\,|A\rangle\langle B| = \langle R \mid A \rangle\, |L\rangle\langle B|,\]

extended linearly over all terms.

Parameters:

• other (DensityPoly) – Right-hand density polynomial.

• eps (float) – Contributions with negligible intermediate overlap are dropped.

Returns:

Resulting symbolic density polynomial.

Return type:

DensityPoly

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

Return a normalized structural form of the polynomial.

This is a convenience alias for combine_like_terms().

Returns:

Polynomial with merged like terms.

Return type:

DensityPoly

Parameters:

• eps (float)

• approx (bool)

• decimals (int)

• ignore_global_phase (bool)

normalize_trace(*, eps: float = 1e-14) → DensityPoly

Return a trace-normalized density polynomial.

This scales the density so that its trace is unity.

Parameters:

eps (float) – If |Tr(rho)| < eps a ValueError is raised.

Returns:

Trace-normalized density polynomial.

Return type:

DensityPoly

Raises:

ValueError – If the trace is too small to safely normalize.

partial_trace(trace_over_modes: Iterable[object]) → DensityPoly

Return the partial trace over a set of modes.

Parameters:

trace_over_modes (Iterable[object]) – Iterable of mode identifiers to trace out. The expected identifier type is determined by the underlying term/mode implementation (typically objects with a stable signature).

Returns:

Reduced density polynomial.

Return type:

DensityPoly

static pure(ket: KetPoly) → DensityPoly

Construct a pure-state density polynomial |psi><psi|.

Parameters:

ket (KetPoly) – Ket polynomial describing \(|\psi\rangle\).

Returns:

Density polynomial representing \(|\psi\rangle\langle\psi|\).

Return type:

DensityPoly

purity() → float

Return the purity \(\mathrm{Tr}(\rho^2)\).

Returns:

Purity of the density polynomial.

Return type:

float

require_trace_normalized(eps: float = 1e-12) → None

Raise ValueError unless the density is trace-normalized.

Parameters:

eps (float)

Return type:

None

scaled(c: complex) → DensityPoly

Return c * self.

Parameters:

c (complex) – Scalar multiplier.

Returns:

Scaled density polynomial.

Return type:

DensityPoly

terms: tuple[DensityTerm, ...] = ()

trace() → complex

Return the trace \(\mathrm{Tr}(\rho)\).

Returns:

Trace of the density polynomial.

Return type:

complex

property unique_modes: tuple[ModeOp, ...]

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

Modes are extracted from both left and right monomials and uniqued by exact mode signature.

Returns:

Unique modes in first-seen order.

Return type:

tuple[ModeOpProto, …]

static zero() → DensityPoly

Return the zero density operator.

Returns:

The empty polynomial (no terms).

Return type:

DensityPoly

Modules

apply_left	Left-application of operator words to density polynomials.
apply_right	Right-application of operator words to density polynomials.
combine	Combine like terms in symbolic density-operator polynomials.
expand_monomial_times_word	Expansion of a monomial multiplied by an operator word.
expand_word_times_monomial	Expansion of an operator word acting on a monomial from the left.
inner	Hilbert--Schmidt inner product for symbolic density polynomials.
multiply	Density polynomial multiplication.
normalize_trace	Trace normalization for symbolic density polynomials.
overlap_right_left	Symbolic overlaps between monomials via normal ordering.
partial_trace	Partial trace for symbolic density polynomials.
poly	Symbolic density polynomials for CCR algebra.
pure	Pure-state density construction for symbolic kets.
purity	Purity of symbolic density polynomials.
scale	Scaling of symbolic density polynomials.
trace	Trace of symbolic density polynomials.