symop.ccr.common.signatures

Signature helpers for CCR algebra canonicalization.

This module provides small helpers that extract exact or approximate signatures from algebraic atoms (monomials, ket terms, density terms).

These signatures are intended to be used as stable, hashable keys in canonicalization routines such as “combine like terms”.

Exact vs approximate

Many objects in the CCR layer expose two related notions of identity:

  • signature: exact structural identity (stable, hashable).

  • approx_signature(decimals=..., ignore_global_phase=...): identity up to an approximation scheme based on rounding floating parameters and (optionally) ignoring global phase.

This module standardizes the selection logic:

\[\begin{split}\mathrm{sig}(x) = \begin{cases} x.\mathrm{signature}, & \text{if approx is False}, \\ x.\mathrm{approx\_signature}(\ldots), & \text{if approx is True}. \end{cases}\end{split}\]

Notes

This file is intentionally dependency-light and should remain stable, since it sits at the bottom of the CCR dependency tree.

Functions

sig_density(t, *[, approx, decimals, ...])

Return an exact or approximate signature for a density term.

sig_ket(t, *[, approx, decimals, ...])

Return an exact or approximate signature for a ket term.

sig_mono(m, *[, approx, decimals, ...])

Return an exact or approximate signature for a monomial.
sig_density(t: DensityTerm, *, approx: bool = False, decimals: int = 12, ignore_global_phase: bool = False) → tuple[object, ...]

Return an exact or approximate signature for a density term.

Parameters:

  • t (DensityTerm) – A density-term-like object that provides the attribute signature and the method approx_signature(decimals=..., ignore_global_phase=...).

  • approx (bool) – If True, return t.approx_signature(...). If False, return t.signature.

  • decimals (int) – Number of decimals to round to (forwarded to approx_signature).

  • ignore_global_phase (bool) – If True, treat global phase parameters as zero for grouping (forwarded to approx_signature).

Returns:

A hashable signature tuple suitable for use as a dictionary key.

Return type:

SignatureProto

sig_ket(t: KetTerm, *, approx: bool = False, decimals: int = 12, ignore_global_phase: bool = False) → tuple[object, ...]

Return an exact or approximate signature for a ket term.

Parameters:

  • t (KetTerm) – A ket-term-like object that provides the attribute signature and the method approx_signature(decimals=..., ignore_global_phase=...).

  • approx (bool) – If True, return t.approx_signature(...). If False, return t.signature.

  • decimals (int) – Number of decimals to round to (forwarded to approx_signature).

  • ignore_global_phase (bool) – If True, treat global phase parameters as zero for grouping (forwarded to approx_signature).

Returns:

A hashable signature tuple suitable for use as a dictionary key.

Return type:

SignatureProto

sig_mono(m: Monomial, *, approx: bool = False, decimals: int = 12, ignore_global_phase: bool = False) → tuple[object, ...]

Return an exact or approximate signature for a monomial.

Parameters:

  • m (Monomial) – A monomial-like object that provides the attribute signature and the method approx_signature(decimals=..., ignore_global_phase=...).

  • approx (bool) – If True, return m.approx_signature(...). If False, return m.signature.

  • decimals (int) – Number of decimals to round to (forwarded to approx_signature).

  • ignore_global_phase (bool) – If True, treat global phase parameters as zero for grouping (forwarded to approx_signature).

Returns:

A hashable signature tuple suitable for use as a dictionary key.

Return type:

SignatureProto