symop.polynomial.state.ket¶

Polynomial ket-state wrapper.

This module provides a lightweight state container around KetPoly, exposing semantic information about modes, paths, and labels derived from the polynomial representation.

The wrapper serves several roles:

attaches lightweight metadata (label, index) to a ket polynomial
exposes convenient views of the modes contained in the state
supports relabeling operations used by device kernels
provides normalization helpers for ket states

Important

Mode labels are not stored independently. They are derived directly from the concrete modes present in the ket polynomial, ensuring that semantic information always reflects the actual algebraic state.

The wrapper also enforces the ket-state invariant that the underlying polynomial is creators only (plus the identity term).

Classes

KetPolyState(ket, label, index)

Polynomial ket state wrapper.

class KetPolyState(ket: KetPoly, label: str | None = None, index: int | None = <factory>) → None¶

Bases: object

Polynomial ket state wrapper.

Invariant¶

The underlying ket polynomial must be creators only (plus identity).

Notes

Semantic mode information is derived from the concrete modes present in ket. In particular, mode labels are not stored independently; they are derived from the unique modes appearing in the polynomial.

property _mode_by_signature_cached: dict[tuple[object, ...], ModeOp]¶

Cache a lookup from mode signature to mode object.

Returns:: Mapping from mode signature to the corresponding concrete mode.
Return type:: dict[Signature, ModeOpProtocol]

property _mode_labels_cached: dict[tuple[object, ...], ModeLabel]¶

Cache a lookup from mode signature to semantic mode label.

Returns:: Mapping from mode signature to the corresponding mode label.
Return type:: dict[Signature, ModeLabelProtocol]

property _modes_by_path_cached: dict[Path, tuple[ModeOp, ...]]¶

Cache grouping of modes by path.

Returns:: Mapping from path to the tuple of modes whose labels lie on that path.
Return type:: dict[PathProtocol, tuple[ModeOpProtocol, …]]

property _modes_cached: tuple[ModeOp, ...]¶

Cache the unique modes appearing in the ket polynomial.

Returns:: Unique modes extracted from ket in the order provided by KetPoly.unique_modes.
Return type:: tuple[ModeOpProtocol, …]

apply_label_edits(edits: Sequence[LabelEdit]) → KetPolyState¶

Apply semantic label edits to the state.

Parameters:

edits (Sequence[LabelEdit]) – Sequence of label edits to apply.

Returns:

New state with the requested label changes applied.

Return type:

KetPolyState

Raises:

KeyError – If an edit refers to a missing mode signature.
NotImplementedError – If a delete-label edit is requested.
TypeError – If an unsupported edit type is encountered.

Notes

Since labels are derived from concrete modes in the ket polynomial, edits are implemented by rebuilding the affected modes and relabeling them algebraically.

filtered_on_path(*, in_path: Path, out_path: Path | None, update_label: Callable[[ModeLabel], ModeLabel]) → KetPolyState¶

Apply a label update to all modes on an input path.

Parameters:

in_path (Path) – Path whose modes should be updated.
out_path (Path | None) – Optional replacement path for the affected modes. If None, the original paths are retained.
update_label (Callable[[ModeLabel], ModeLabel]) – Callable that transforms each mode label before optional path replacement.

Returns:

New state with updated labels for all modes on in_path.

Return type:

KetPolyState

Notes

This is a convenience helper for path-bound devices whose action is naturally expressed as a relabeling of all modes on a selected path.

static from_creators(creators: Iterable[LadderOp], *, coeff: complex = 1.0) → KetPolyState¶

Build a ket state from a word of creation operators.

Parameters:

creators (Iterable[LadderOp]) – Iterable of ladder operators, all of which must be creation operators.
coeff (complex) – Scalar coefficient multiplying the resulting ket term.

Returns:

Ket state constructed from the supplied creation-operator word.

Return type:

KetPolyState

Raises:

ValueError – If any supplied operator is not a creation operator.

static from_ketpoly(ket: KetPoly) → KetPolyState¶

Construct a state wrapper from a ket polynomial.

Parameters:: ket (KetPoly) – Ket polynomial to wrap.
Returns:: New wrapper around the combined ket polynomial.
Return type:: KetPolyState

index: int | None¶

is_normalized(*, eps: float = 1e-14) → bool¶

Check whether the ket state is normalized.

Parameters:: eps (float) – Numerical tolerance used by the underlying normalization check.
Returns:: True if the ket polynomial is normalized within eps.
Return type:: bool

join(other: KetPolyState) → KetPolyState¶

Return the algebraic join of two ket states.

Parameters:: other (KetPolyState) – Ket state to combine with this state.
Returns:: Product state obtained by multiplying the two underlying ket polynomials.
Return type:: KetPolyState

Notes

This is a convenience alias for multiply(). It is useful in contexts where combining states is more naturally described as joining branches or subsystems.

ket: KetPoly¶

label: str | None = None¶

label_for_mode(mode_sig: tuple[object, ...]) → ModeLabel¶

Return the semantic label for a given mode signature.

Parameters:: mode_sig (tuple[object, ...]) – Signature of the mode whose label should be returned.
Returns:: Semantic label associated with the mode.
Return type:: ModeLabelProtocol
Raises:: KeyError – If the mode signature is not present in the state.

labels_on_path(path: Path) → dict[tuple[object, ...], ModeLabel]¶

Return labels for all modes on a given path.

Parameters:: path (Path) – Path identifier.
Returns:: Mapping from mode signature to semantic label for modes on the given path.
Return type:: dict[Signature, ModeLabelProtocol]

property mode_by_signature: dict[tuple[object, ...], ModeOp]¶

Return a lookup from mode signature to mode object.

Returns:: Mapping from mode signature to the corresponding mode.
Return type:: dict[Signature, ModeOpProtocol]

property mode_labels: dict[tuple[object, ...], ModeLabel]¶

Return a lookup from mode signature to semantic label.

Returns:: Mapping from mode signature to the corresponding mode label.
Return type:: dict[Signature, ModeLabelProtocol]

property modes: tuple[ModeOp, ...]¶

Return the unique modes present in the ket polynomial.

Returns:: Unique modes appearing in ket.
Return type:: tuple[ModeOpProtocol, …]

property modes_by_path: dict[Path, tuple[ModeOp, ...]]¶

Return modes grouped by path.

Returns:: Mapping from path to the tuple of modes on that path.
Return type:: dict[PathProtocol, tuple[ModeOpProtocol, …]]

modes_on_path(path: Path) → tuple[ModeOp, ...]¶

Return all modes that live on a given path.

Parameters:: path (Path) – Path identifier.
Returns:: Modes whose label path matches path.
Return type:: tuple[ModeOpProtocol, …]

Notes

If no modes exist on the requested path, an empty tuple is returned.

multiply(other: KetPolyState) → KetPolyState¶

Return the symbolic product of two ket states.

Parameters:: other (KetPolyState) – Ket state whose polynomial should be multiplied onto this state.
Returns:: State wrapper around the combined product polynomial.
Return type:: KetPolyState

Notes

This operation does not require orthogonal or disjoint modes. It multiplies the underlying ket polynomials algebraically and returns the resulting creators-only state wrapper.

property norm2: float¶

Return the squared norm of the ket state.

Returns:: Squared norm of the underlying ket polynomial.
Return type:: float

normalized(*, eps: float = 1e-14) → KetPolyState¶

Return a normalized copy of the ket state.

Parameters:: eps (float) – Threshold used internally by ket normalization.
Returns:: New state with normalized ket polynomial.
Return type:: KetPolyState

relabel_labels(label_map: dict[tuple[object, ...], ModeLabel]) → KetPolyState¶

Return a new ket state with selected labels replaced.

Parameters:: label_map (dict[tuple[object, ...], ModeLabel]) – Mapping from mode signature to replacement label.
Returns:: New state with updated labels for the selected modes.
Return type:: KetPolyState
Raises:: KeyError – If a supplied mode signature is not present in the state.

relabel_modes(mode_map: dict[tuple[object, ...], ModeOp]) → KetPolyState¶

Return a new ket state with selected ModeOp objectss relabeled.

Parameters:: mode_map (dict[tuple[object, ...], ModeOp]) – Mapping from old labels to replacement label.
Returns:: New state with all matching mode paths updated.
Return type:: KetPolyState

Notes

Only modes whose current path appears in mode_map are modified. Other modes are left unchanged.

relabel_paths(path_map: dict[Path, Path]) → KetPolyState¶

Return a new ket state with selected paths relabeled.

Parameters:: path_map (dict[Path, Path]) – Mapping from old paths to replacement paths.
Returns:: New state with all matching mode paths updated.
Return type:: KetPolyState

Notes

Only modes whose current path appears in path_map are modified. Other modes are left unchanged.

property rep_kind: Literal['poly']¶

Return the representation kind of this state.

Returns:: The polynomial representation kind.
Return type:: Literal[“poly”]

resolve_target_modes(target: MeasurementTarget) → tuple[ModeOp, ...]¶

Resolve a semantic measurement target into concrete modes.

Parameters:: target (MeasurementTarget) – Semantic measurement target specifying paths and/or explicit mode signatures to be selected.
Returns:: Concrete modes selected by the target. Modes referenced both by path and by explicit signature are returned only once.
Return type:: tuple[ModeOpProtocol, …]

Notes

Resolution proceeds by first collecting all modes on the target paths and then adding any explicitly requested mode signatures. Missing explicit signatures are ignored.

property state_kind: Literal['ket']¶

Return the state kind of this object.

Returns:: The ket-state kind.
Return type:: Literal[“ket”]

to_density() → DensityPolyState¶

Convert the ket state to the corresponding pure density state.

Returns:: Pure density-state wrapper constructed from this ket state.
Return type:: DensityPolyState

static vacuum() → KetPolyState¶

Construct the vacuum state.

Returns:: Ket state represented by the identity-only ket polynomial.
Return type:: KetPolyState

with_index(index: int | None) → KetPolyState¶

Return a copy of the state with a new index.

Parameters:: index (int | None) – Optional state identifier.
Returns:: New state instance with updated index.
Return type:: KetPolyState

Notes

The index is typically used to distinguish states in simulation pipelines or logging but has no semantic meaning for the state representation itself.

with_label(label: str | None) → KetPolyState¶

Return a copy of the state with a new human-readable label.

Parameters:: label (str | None) – Optional label attached to the state wrapper.
Returns:: New state instance with updated label.
Return type:: KetPolyState

Notes

This label is metadata only and does not affect the underlying polynomial representation.

Parameters:

ket (KetPoly)
label (str | None)
index (int | None)

_ket_check: KetPolyState¶