symop.ccr.algebra.density.combine

Combine like terms in symbolic density-operator polynomials.

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

\[\rho \sim \sum_k c_k\, L_k\, R_k,\]

where each term stores a complex coefficient c_k and two monomials (left=L_k, right=R_k). Two terms are considered “like” if their left and right monomials match under either an exact signature or an approximate signature (for example after rounding envelope-dependent quantities).

This module provides a canonicalization step that groups like terms, sums their coefficients, drops near-zero groups, and returns a deterministically sorted tuple of concrete density terms.

Functions

combine_like_terms_density(terms[, eps, ...])

Combine like density terms by summing coefficients and dropping zeros.
combine_like_terms_density(terms: Iterable[DensityTerm], eps: float = 1e-12, *, approx: bool = False, decimals: int = 12, ignore_global_phase: bool = False) → tuple[DensityTerm, ...]

Combine like density terms by summing coefficients and dropping zeros.

This function groups density terms by a (left, right) signature key and sums complex coefficients within each group. Groups whose total coefficient magnitude is below eps are discarded. The output is returned as a tuple of concrete DensityTerm instances sorted deterministically by the exact monomial signatures.

Grouping is driven by sig_density(). When approx=True, the key may be constructed from approximate monomial signatures (for example by rounding envelope-dependent quantities).

Parameters:

  • terms (Iterable[DensityTerm]) – Iterable of density terms to combine.

  • eps (float) – Threshold for dropping groups with near-zero total coefficient. A group is dropped if abs(c_total) < eps.

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

  • decimals (int) – Number of decimal digits used by approximate signatures (if applicable).

  • ignore_global_phase (bool) – Whether approximate signatures may ignore global phase (if applicable).

Returns:

A tuple of merged density terms with like terms combined, near-zero groups removed, and deterministic ordering.

Return type:

tuple[DensityTerm, …]

Notes

This function is purely algebraic: it does not evaluate any operator matrices. It only merges terms that are identical under the chosen signature scheme.

Complexity

Let N be the number of input terms and K the number of unique signature keys. The runtime is \(O(N + K \log K)\) due to one-pass accumulation and a final sort over the K merged terms.