symop.ccr.algebra.ket.combine¶

Canonicalization helpers for CCR ket terms.

This module provides utilities to canonicalize finite sums of ket terms by merging terms that share the same monomial (exactly or approximately) and discarding numerically negligible coefficients.

Given a formal sum

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

where each \(M_i\) is a normally ordered monomial of ladder operators, canonicalization groups all terms with identical monomials and replaces them by a single term with summed coefficient.

Approximate canonicalization¶

When approx=True, monomials are grouped using their approx_signature(decimals=..., ignore_global_phase=...). This is intended for numerically robust merging when mode parameters differ only by small floating errors and when global phase parameters should be ignored.

This file is logic-only and contains no formatting or pretty-printing.

Functions

combine_like_terms_ket(terms[, eps, approx, ...])

Combine like terms in a ket-term expansion.

combine_like_terms_ket(terms: Iterable[KetTerm], eps: float = 1e-12, *, approx: bool = False, decimals: int = 12, ignore_global_phase: bool = False) → tuple[KetTerm, ...]¶

Combine like terms in a ket-term expansion.

Terms are grouped by monomial identity and their coefficients are summed:

\[\sum_{i:\,\mathrm{sig}(M_i)=k} c_i\,M_i \;\mapsto\; \left(\sum_{i:\,\mathrm{sig}(M_i)=k} c_i\right) M_k.\]

Grouping can be either exact (approx=False) or approximate (approx=True) via the monomial’s approximate signature.

Parameters:

terms (Iterable[KetTerm]) – Iterable of ket terms to combine.
eps (float) – Discard threshold. Any combined coefficient with \(|c| \le \texttt{eps}\) is dropped.
approx (bool) – If True, group terms using approx_signature instead of signature.
decimals (int) – Rounding precision forwarded to approx_signature when approx=True.
ignore_global_phase (bool) – Forwarded to approx_signature when approx=True.

Returns:

Combined terms sorted by monomial exact signature.

Return type:

tuple[KetTerm, …]