symop.polynomial.rewrites.substitution

Symbolic rewrite utilities for CCR polynomial representations.

This module provides generic substitution and expansion routines for polynomial objects used in the canonical commutation relation (CCR) algebra implementation. The functions allow ladder operators appearing inside polynomial expressions to be replaced by linear combinations of other operators.

The rewrite process follows three conceptual steps:

  1. Local substitution Each ladder operator is replaced using a user-provided substitution function mapping

    a -> sum_i c_i * b_i.

  2. Word expansion Substitutions are applied to every operator in a word, producing a cartesian product of all substitution choices.

  3. Normal ordering The resulting operator words are normal ordered using the CCR normal-ordering routine, producing monomials compatible with the symbolic polynomial representation.

The utilities support rewriting of the following CCR polynomial types:

  • KetPoly : symbolic ket polynomials

  • DensityPoly : symbolic density polynomials

  • OpPoly : operator polynomials

The substitution logic is shared across these representations, ensuring consistent symbolic manipulation across states, operators, and channels.

Notes

These routines operate purely at the symbolic algebra level. They do not perform numerical evaluation or truncation of Hilbert spaces.

Small coefficient terms can be pruned using the eps parameter during intermediate expansion.

Functions

expand_word_substitution(word, subst_fn, *)

Expand a word of ladder operators using a substitution rule.

rewrite_densitypoly(rho, left_subst_fn[, ...])

Rewrite a density polynomial using ladder-operator substitutions.

rewrite_ketpoly(poly, subst_fn, *[, eps])

Apply a ladder-operator substitution to a KetPoly.

rewrite_oppoly(op, subst_fn, *[, eps])

Rewrite an operator polynomial using ladder-operator substitution.
_normalize_word_to_monomials(word: Sequence[LadderOp], *, eps: float) → list[tuple[complex, Monomial]]

Convert an operator word into normal-ordered monomials.

Parameters:

  • word (Sequence[LadderOp]) – Sequence of ladder operators representing an operator word.

  • eps (float) – Numerical pruning threshold passed to the normal-ordering routine.

Returns:

List of (coefficient, monomial) pairs obtained after normal ordering the operator word.

Return type:

list of tuple

Notes

Normal ordering is performed using the CCR ordering routine ket_from_word.

expand_word_substitution(word: Sequence[LadderOp], subst_fn: Callable[[LadderOp], Sequence[tuple[complex, LadderOp]]], *, eps: float = 0.0) → list[tuple[complex, tuple[LadderOp, ...]]]

Expand a word of ladder operators using a substitution rule.

Each operator in the input word is replaced using subst_fn. The substitutions are combined via a cartesian product, generating all possible operator words resulting from the replacements.

Parameters:

  • word (Sequence[LadderOp]) – Sequence of ladder operators forming the operator word.

  • subst_fn (Callable[[LadderOp], Sequence[tuple[complex, LadderOp]]]) – Substitution function mapping a ladder operator to a sequence of (coefficient, operator) pairs representing a linear combination replacement.

  • eps (float) – Optional pruning threshold. Intermediate products with absolute coefficient smaller than eps are discarded.

Returns:

List of (coefficient, new_word) pairs, where new_word is a tuple of substituted ladder operators.

Return type:

list of tuple

Notes

This routine does not perform normal ordering. It only performs substitution and expansion of operator words.

rewrite_densitypoly(rho: DensityPoly, left_subst_fn: Callable[[LadderOp], Sequence[tuple[complex, LadderOp]]], right_subst_fn: Callable[[LadderOp], Sequence[tuple[complex, LadderOp]]] | None = None, *, eps: float = 1e-12) → DensityPoly

Rewrite a density polynomial using ladder-operator substitutions.

Substitutions are applied independently to the left and right monomials of each density term.

Parameters:

  • rho (DensityPoly) – Input density polynomial.

  • left_subst_fn (Callable[[LadderOp], Sequence[tuple[complex, LadderOp]]]) – Substitution function applied to ladder operators appearing in left monomials.

  • right_subst_fn (Callable[[LadderOp], Sequence[tuple[complex, LadderOp]]] | None) – Optional substitution function for right monomials. If None, left_subst_fn is used for both sides.

  • eps (float) – Numerical pruning threshold used during intermediate expansions.

Returns:

Rewritten density polynomial with substitutions applied and like terms combined.

Return type:

DensityPolyProtocol

Notes

The rewrite process proceeds as:

  1. Expand substitutions for left and right words.

  2. Normal order each resulting word.

  3. Form the cartesian product of left/right monomial combinations.

  4. Construct new density terms from the resulting monomials.

rewrite_ketpoly(poly: KetPoly, subst_fn: Callable[[LadderOp], Sequence[tuple[complex, LadderOp]]], *, eps: float = 1e-12) → KetPoly

Apply a ladder-operator substitution to a KetPoly.

Each ladder operator appearing in the polynomial’s monomials is replaced using subst_fn. The resulting expressions are expanded and normal ordered.

Parameters:

  • poly (KetPoly) – Input ket polynomial.

  • subst_fn (Callable[[LadderOp], Sequence[tuple[complex, LadderOp]]]) – Substitution function mapping ladder operators to linear combinations of operators.

  • eps (float) – Numerical pruning threshold used during expansion and normal ordering.

Returns:

New polynomial with substitutions applied and terms combined.

Return type:

KetPoly

Notes

The output is always returned as the concrete KetPoly algebra implementation, even if the input object satisfies only the KetPolyProtocol.

rewrite_oppoly(op: OpPoly, subst_fn: Callable[[LadderOp], Sequence[tuple[complex, LadderOp]]], *, eps: float = 1e-12) → OpPoly

Rewrite an operator polynomial using ladder-operator substitution.

Parameters:

  • op (OpPoly) – Operator polynomial whose terms contain words of ladder operators.

  • subst_fn (Callable[[LadderOp], Sequence[tuple[complex, LadderOp]]]) – Substitution function mapping ladder operators to linear combinations of operators.

  • eps (float) – Numerical pruning threshold used during expansion.

Returns:

Operator polynomial with substitutions applied and like terms combined.

Return type:

OpPolyProtocol

Notes

Unlike state polynomials, operator polynomials do not require normal ordering during rewriting because the operator word structure is preserved.