symop.ccr.algebra.density.poly¶

Symbolic density polynomials for CCR algebra.

A density polynomial is represented as a finite linear combination of outer products of normally ordered monomials,

\[\rho \sim \sum_i c_i \, |L_i\rangle\langle R_i|.\]

This module defines DensityPoly, an immutable wrapper around a tuple of density terms. It delegates algebraic operations to the pure functional implementations in symop.ccr.algebra.density.

Only symbolic CCR logic is performed here. No matrices are constructed. Presentation / pretty-printing is intentionally out of scope.

Classes

DensityPoly([terms])

Symbolic density polynomial.

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

_density_poly_check: DensityPolyProtocol¶