symop.polynomial.state.density¶

Polynomial density-state wrapper.

This module provides a lightweight state container around DensityPoly, 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 density polynomial
exposes convenient views of the modes contained in the state
supports relabeling operations used by device kernels
provides normalization and trace utilities

Important:¶

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

This avoids inconsistencies between symbolic operators and state metadata when transformations rewrite the polynomial.

Classes

DensityPolyState(rho, label, index)

Polynomial density state wrapper.

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.

_density_check: DensityPolyState¶