symop.ccr.common.keys

Key helpers for CCR algebra canonicalization.

This module defines small, strict helpers that produce hashable keys for grouping and sorting CCR objects in algorithms such as “combine like terms”.

Keys vs signatures

Objects in the CCR layer expose:

  • signature: exact structural identity.

  • approx_signature(decimals=..., ignore_global_phase=...): identity under an approximation scheme based on rounding and optional phase normalization.

A key is the value used by algorithms to bucket or sort objects. In most cases, the key is simply the object’s signature (exact or approximate), but this module centralizes the decision logic to keep the CCR layer consihstent.

Strict keyword convention

This project standardizes approximate signatures to accept only:

  • decimals: int

  • ignore_global_phase: bool

Accordingly, the helpers in this module do not accept **kwargs and forward only these parameters.

Notes

This module should remain dependency-light and must not import concrete CCR polynomial implementations. It is intended to sit near the bottom of the CCR dependency tree.

Functions

sig_lop(op, *[, approx, decimals, ...])

Return an exact or approximate key for a ladder operator.

sig_obj(obj, *[, approx, decimals, ...])

Return an exact or approximate key for a signature-bearing object.

sig_word(ops, *[, approx, decimals, ...])

Return a key for an operator word (ordered product of ladder operators).
sig_lop(op: HasSignature, *, approx: bool = False, decimals: int = 12, ignore_global_phase: bool = False) → tuple[object, ...]

Return an exact or approximate key for a ladder operator.

Parameters:

  • op (HasSignature) – A ladder-operator-like object with signature and approx_signature(decimals=..., ignore_global_phase=...).

  • approx (bool) – If True, return op.approx_signature(...). If False, return op.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:

Hashable ladder-operator key.

Return type:

SignatureProto

Notes

This function exists mostly for readability. It is equivalent to sig_obj() but communicates intent at call sites.

sig_obj(obj: HasSignature, *, approx: bool = False, decimals: int = 12, ignore_global_phase: bool = False) → tuple[object, ...]

Return an exact or approximate key for a signature-bearing object.

Parameters:

  • obj (HasSignature) – Any object that provides signature and approx_signature(decimals=..., ignore_global_phase=...).

  • approx (bool) – If True, return obj.approx_signature(...). If False, return obj.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_word(ops: Iterable[HasSignature], *, approx: bool = False, decimals: int = 12, ignore_global_phase: bool = False) → tuple[tuple[object, ...], ...]

Return a key for an operator word (ordered product of ladder operators).

Parameters:

  • ops (Iterable[HasSignature]) – Iterable of ladder operators defining a word. The iterable is materialized into a tuple to make the key stable and hashable.

  • approx (bool) – If True, each operator key is taken from approx_signature(...). If False, each operator key is taken from signature.

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

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

Returns:

Hashable key representing the ordered operator word.

Return type:

tuple[SignatureProto, …]