symop.polynomial.state¶

State containers for symbolic polynomial representations.

This package defines state objects that wrap symbolic CCR polynomial structures (e.g., density polynomials) together with convenience operations such as normalization, mode relabeling, and channel application.

The classes in this package provide the interface used by higher-level device kernels operating on symbolic quantum states.

class DensityPolyState(rho: DensityPoly, label: str | None = None, index: int | None = <factory>) → None¶

Bases: DensityPolyState

Polynomial density state wrapper.

Notes

Semantic mode information is derived from the concrete modes present in rho. Labels are not stored independently; they are derived from the unique modes appearing in the density polynomial.

Parameters:

rho (DensityPoly)
label (str | None)
index (int | None)

_abc_impl = <_abc._abc_data object>¶

_is_protocol = False¶

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 density polynomial.

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

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

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:

DensityPolyState

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 density 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]) → DensityPolyState¶

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:

DensityPolyState

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_densitypoly(rho: DensityPoly) → DensityPolyState¶

Construct a state wrapper from a density polynomial.

Parameters:: rho (DensityPoly) – Density polynomial to wrap.
Returns:: New wrapper around the combined density polynomial.
Return type:: DensityPolyState

index: int | None¶

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

Check whether the density operator is trace normalized.

Parameters:: eps (float) – Numerical tolerance used when comparing to 1.
Returns:: True if |Tr(rho) - 1| <= eps.
Return type:: bool

join(other: DensityPolyState) → DensityPolyState¶

Return the algebraic join of two density states.

Parameters:: other (DensityPolyState) – Density state to combine with this state.
Returns:: Product state obtained by multiplying the two underlying density polynomials.
Return type:: DensityPolyState

Notes

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

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 density polynomial.

Returns:: Unique modes appearing in rho.
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: DensityPolyState) → DensityPolyState¶

Return the symbolic product of two density states.

Parameters:: other (DensityPolyState) – Right-hand density state.
Returns:: State wrapping the product density polynomial.
Return type:: DensityPolyState

normalize_trace(*, eps: float = 1e-14) → DensityPolyState¶

Return a trace-normalized copy of the state.

Parameters:: eps (float) – Threshold below which the trace is treated as zero.
Returns:: New state with density polynomial scaled to unit trace.
Return type:: DensityPolyState
Raises:: ValueError – If the trace is numerically too close to zero.

static pure(ket: KetPolyState) → DensityPolyState¶

Construct a pure density state from a ket state.

Parameters:: ket (KetPolyState) – Ket state representing the pure state.
Returns:: Density-state wrapper containing the corresponding pure density polynomial.
Return type:: DensityPolyState

relabel_labels(label_map: Mapping[tuple[object, ...], ModeLabel]) → DensityPolyState¶

Return a new density state with selected labels replaced.

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

relabel_modes(mode_map: Mapping[tuple[object, ...], ModeOp]) → DensityPolyState¶

Return a new density state with selected ``ModeOp``s relabeled.

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

Notes

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

relabel_paths(path_map: Mapping[Path, Path]) → DensityPolyState¶

Return a new density state with selected paths relabeled.

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

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.

rho: DensityPoly¶

property state_kind: Literal['density']¶

Return the state kind of this object.

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

trace() → complex¶

Return the trace of the density polynomial.

Returns:: Trace of the density operator represented by rho.
Return type:: complex

Notes

For a properly normalized quantum state the trace should equal 1.

trace_out_modes(trace_over_modes: Sequence[ModeOp]) → DensityPolyState¶

Return the reduced density state after tracing out selected modes.

Parameters:: trace_over_modes (Sequence[ModeOp]) – Sequence of concrete modes to be traced out of the density polynomial.
Returns:: Reduced density-state wrapper obtained after partial trace over the selected modes.
Return type:: DensityPolyState

Notes

Modes not listed in trace_over_modes are retained. The resulting density polynomial is combined before the new wrapper is returned.

trace_out_signatures(mode_sigs: Sequence[tuple[object, ...]]) → DensityPolyState¶

Return the reduced density state after tracing out selected modes.

Parameters:: mode_sigs (Sequence[tuple[object, ...]]) – Sequence of mode signatures identifying the modes to trace out.
Returns:: Reduced density-state wrapper obtained after partial trace over the selected modes.
Return type:: DensityPolyState

Notes

Only signatures present in the state are used. Missing signatures are ignored.

static vacuum() → DensityPolyState¶

Construct the vacuum density state.

Returns:: Density state wrapping the identity / vacuum polynomial used by the density representation.
Return type:: DensityPolyState

with_index(index: int | None) → DensityPolyState¶

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:: DensityPolyState

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) → DensityPolyState¶

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:: DensityPolyState

Notes

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

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)

Modules

`density`	Polynomial density-state wrapper.
`ket`	Polynomial ket-state wrapper.