symop.polynomial.rewrites.relabel_modes

Mode relabeling utilities for symbolic CCR term structures.

This module provides helpers for replacing the mode attached to ladder operators inside symbolic ket and density terms. Relabeling is performed by matching the signature of each operator’s mode against a mapping from old signatures to replacement modes.

The implementation is structure preserving:

  • ladder operators are recreated only when their mode changes,

  • monomials are recreated only when at least one contained operator changes,

  • terms are recreated only when one of their monomials changes.

This minimizes allocations while keeping the symbolic objects immutable.

The relabeling routines assume that the involved operator, monomial, and term objects are dataclass instances so that dataclasses.replace can be used to construct updated copies.

Notes

The mapping is keyed by Signature rather than by mode object identity. This allows structurally equivalent modes to be relabeled consistently even when distinct mode instances share the same signature.

Functions

density_relabel_modes(terms, *, mode_map)

Relabel modes appearing in density terms.

ket_relabel_modes(terms, *, mode_map)

Relabel modes appearing in ket terms.
_map_ops(ops: tuple[LadderOp, ...], mode_map: Mapping[tuple[object, ...], ModeOp]) → tuple[LadderOp, ...]

Relabel the modes of all ladder operators in a tuple.

Parameters:

  • ops (tuple[LadderOp, ...]) – Tuple of ladder operators to relabel.

  • mode_map (Mapping[tuple[object, ...], ModeOp]) – Mapping from old mode signatures to replacement mode objects.

Returns:

Tuple containing relabeled operators. If no operator changes, the original tuple is returned.

Return type:

tuple of LadderOpProtocol

_maybe_replace_mode(op: LadderOp, mode_map: Mapping[tuple[object, ...], ModeOp]) → LadderOp

Replace the mode of a ladder operator if its signature is mapped.

Parameters:

  • op (LadderOp) – Ladder operator whose mode may be replaced.

  • mode_map (Mapping[tuple[object, ...], ModeOp]) – Mapping from old mode signatures to replacement mode objects.

Returns:

The original operator if its mode signature is not present in mode_map; otherwise a copied operator with the updated mode.

Return type:

LadderOpProtocol

Raises:

TypeError – If a replacement is required but the operator is not a dataclass instance and therefore cannot be copied with replace.

density_relabel_modes(terms: tuple[DensityTerm, ...], *, mode_map: Mapping[tuple[object, ...], ModeOp]) → tuple[DensityTerm, ...]

Relabel modes appearing in density terms.

Each ladder operator in the left and right monomials of every density term is inspected. Operators whose mode signature appears in mode_map are copied with the replacement mode.

Parameters:

  • terms (tuple[DensityTerm, ...]) – Density terms whose left and right monomials should be relabeled.

  • mode_map (Mapping[tuple[object, ...], ModeOp]) – Mapping from old mode signatures to replacement mode objects.

Returns:

Tuple of density terms with updated mode references. Terms whose monomials are unchanged are returned unchanged.

Return type:

tuple of DensityTerm

Raises:

TypeError – If a density term or one of its monomials needs to be updated but is not a dataclass instance.

Notes

This function assumes that each density term exposes dataclass-like left and right monomials, and that each monomial exposes creators and annihilators fields compatible with dataclasses.replace.

ket_relabel_modes(terms: tuple[KetTerm, ...], *, mode_map: Mapping[tuple[object, ...], ModeOp]) → tuple[KetTerm, ...]

Relabel modes appearing in ket terms.

Each ladder operator in the creators and annihilators of every ket term monomial is inspected. If the operator’s mode signature is present in mode_map, the operator is copied with the replacement mode.

Parameters:

  • terms (tuple[KetTerm, ...]) – Ket terms whose monomials should be relabeled.

  • mode_map (Mapping[tuple[object, ...], ModeOp]) – Mapping from old mode signatures to replacement mode objects.

Returns:

Tuple of ket terms with updated mode references. Terms whose operators are unchanged are returned unchanged.

Return type:

tuple of KetTerm

Raises:

TypeError – If a monomial or term needs to be updated but is not a dataclass instance.

Notes

mode_map is interpreted as

old_mode.signature -> new_mode.