symop.polynomial.kernels.measurements.number.common¶

Common helpers for polynomial number measurement.

This module implements structural utilities used by polynomial-number measurement kernels for both ket and density-state wrappers.

The helpers in this module support three main tasks:

resolving semantic measurement targets into concrete polynomial modes
enumerating number-measurement support on selected modes or ports
projecting states onto number or joint-number outcome sectors

The implementation is structural: it infers photon-number content by counting creation operators associated with the selected mode signatures. For density-polynomial inputs, projective number statistics are only resolved from terms whose left and right number counts agree on the measured subsystem.

Notes

The routines here do not define user-facing measurement devices. Instead, they provide the low-level logic reused by observe, detect, and postselect kernels for number measurement.

For ket states, destructive removal of measured modes is not implemented directly. A destructive number measurement should first be represented as a density state and then reduced by tracing out the measured subsystem.

raises NumberMeasurementError:: Raised when number measurement cannot be evaluated structurally, for example because a term violates assumptions required by the current implementation.

Functions

`count_selected_creators_by_port`(monomial, ...)	Count selected creation operators per port in a monomial.
`count_selected_creators_in_monomial`(...)	Count selected creation operators in a monomial.
`count_selected_quanta_ket_term`(term, ...)	Count selected quanta in a ket term.
`count_selected_quanta_left`(term, measured_sigs)	Count selected quanta in the left monomial of a density term.
`count_selected_quanta_right`(term, measured_sigs)	Count selected quanta in the right monomial of a density term.
`counts_from_joint_outcome`(outcome)	Extract per-port number counts from a joint outcome.
`discard_measured_modes_number_density`(state, ...)	Discard measured modes after number measurement on a density state.
`discard_measured_modes_number_ket`(state, target)	Discard measured modes after number measurement on a ket state.
`iter_joint_number_support_poly_density`(...)	Enumerate joint number outcomes supported by a density state.
`iter_joint_number_support_poly_ket`(state, target)	Enumerate joint number outcomes supported by a ket state.
`iter_number_support_poly_density`(state, target)	Enumerate number outcomes supported by a density state.
`iter_number_support_poly_ket`(state, target)	Enumerate number outcomes supported by a ket state.
`joint_number_counts_for_ket_term`(term, ...)	Count selected quanta per port for a ket term.
`joint_number_counts_left`(term, ...)	Count selected quanta per port in the left monomial of a density term.
`joint_number_counts_right`(term, ...)	Count selected quanta per port in the right monomial of a density term.
`joint_outcome_from_counts`(counts_by_port)	Build a joint number outcome from per-port counts.
`project_onto_joint_number_poly_density`(...)	Project a density state onto a selected joint number outcome.
`project_onto_joint_number_poly_ket`(state, ...)	Project a ket state onto a selected joint number outcome.
`project_onto_number_poly_density`(state, ...)	Project a density state onto a selected number outcome.
`project_onto_number_poly_ket`(state, target, ...)	Project a ket state onto a selected number outcome.
`require_number_outcome`(outcome)	Validate that an outcome is a number outcome.
`resolve_joint_number_stats_poly_density`(...)	Resolve joint number statistics for a density state.
`resolve_joint_number_stats_poly_ket`(state, ...)	Resolve joint number statistics for a ket state.
`resolve_number_stats_poly_density`(state, ...)	Resolve projective number statistics for a density state.
`resolve_number_stats_poly_ket`(state, target, *)	Resolve projective number statistics for a ket state.
`selected_mode_signatures`(state, target)	Return the signatures of all modes selected by a target.
`selected_mode_signatures_by_port`(state, target)	Return selected mode signatures grouped by semantic port.
`selected_modes`(state, target)	Resolve a measurement target into concrete selected modes.

Classes

NumberMeasurementStats(probabilities)

Resolved number statistics on a selected target.

Exceptions

NumberMeasurementError

Raised when number measurement cannot be evaluated structurally.

exception NumberMeasurementError¶

Bases: ValueError

Raised when number measurement cannot be evaluated structurally.

This exception indicates that the polynomial state or term structure does not satisfy the assumptions required by the current number measurement implementation.

Examples include creator-only requirements being violated in places where structural number counting is expected to act on normally ordered creation monomials.

class NumberMeasurementStats(probabilities: Mapping[NumberOutcome, float]) → None¶

Bases: object

Resolved number statistics on a selected target.

Parameters:: probabilities (Mapping[NumberOutcome, float]) – Mapping from number outcomes to their corresponding probabilities.

Notes

The probabilities are expected to represent the distribution of the measured number observable restricted to a selected subsystem.

property expectation: float¶

Return the expected number of quanta.

Returns:

Expectation value of the resolved number distribution, computed as

\[\mathbb{E}[N] = \sum_n n\,p(n).\]

Return type:

float

probabilities: Mapping[NumberOutcome, float]¶

count_selected_creators_by_port(monomial: Monomial, measured_sigs_by_port: Mapping[str, frozenset[tuple[object, ...]]]) → tuple[tuple[str, int], ...]¶

Count selected creation operators per port in a monomial.

Parameters:

monomial (Monomial) – Monomial whose creation operators are to be counted.
measured_sigs_by_port (Mapping[str, frozenset[tuple[object, ...]]]) – Mapping from port name to the set of selected mode signatures for that port.

Returns:

Tuple of (port_name, count) pairs giving the number of creation operators in monomial whose mode signatures belong to each port selection.

Return type:

tuple[tuple[str, int], …]

Notes

Counting is performed only over monomial.creators.

count_selected_creators_in_monomial(measured_sigs: frozenset[tuple[object, ...]], monomial: Monomial) → int¶

Count selected creation operators in a monomial.

Parameters:

measured_sigs (frozenset[tuple[object, ...]]) – Signatures of the selected measured modes.
monomial (Monomial) – Monomial whose creation operators are to be counted.

Returns:

Number of creation operators in monomial whose mode signatures belong to measured_sigs.

Return type:

int

count_selected_quanta_ket_term(term: KetTerm, measured_sigs: frozenset[tuple[object, ...]]) → int¶

Count selected quanta in a ket term.

Parameters:

term (KetTerm) – Ket term whose monomial is to be inspected.
measured_sigs (frozenset[tuple[object, ...]]) – Signatures of the selected measured modes.

Returns:

Number of creation operators in term whose mode signatures are contained in measured_sigs.

Return type:

int

count_selected_quanta_left(term: DensityTerm, measured_sigs: frozenset[tuple[object, ...]]) → int¶

Count selected quanta in the left monomial of a density term.

Parameters:

term (DensityTerm) – Density term whose left monomial is to be inspected.
measured_sigs (frozenset[tuple[object, ...]]) – Signatures of the selected measured modes.

Returns:

Number of selected creation operators in term.left.

Return type:

int

Raises:

NumberMeasurementError – If term.left contains annihilators.

Notes

The current structural number-measurement logic assumes creator-only left monomials.

count_selected_quanta_right(term: DensityTerm, measured_sigs: frozenset[tuple[object, ...]]) → int¶

Count selected quanta in the right monomial of a density term.

Parameters:

term (DensityTerm) – Density term whose right monomial is to be inspected.
measured_sigs (frozenset[tuple[object, ...]]) – Signatures of the selected measured modes.

Returns:

Number of selected creation operators in term.right.

Return type:

int

Raises:

NumberMeasurementError – If term.right contains annihilators.

Notes

The current structural number-measurement logic assumes creator-only right monomials.

counts_from_joint_outcome(outcome: JointOutcome) → tuple[tuple[str, int], ...]¶

Extract per-port number counts from a joint outcome.

Parameters:: outcome (JointOutcome) – Joint outcome to unpack.
Returns:: Tuple of (port_name, count) pairs.
Return type:: tuple[tuple[str, int], …]
Raises:: TypeError – If any per-port outcome is not a NumberOutcome.

discard_measured_modes_number_density(state: DensityPolyState, target: MeasurementTarget) → DensityPolyState¶

Discard measured modes after number measurement on a density state.

Parameters:

state (DensityPolyState) – Density-state wrapper from which measured modes should be removed.
target (MeasurementTarget) – Semantic measurement target specifying the measured subsystem.

Returns:

Reduced density state obtained by tracing out the measured modes.

Return type:

DensityPolyState

Notes

This models destructive removal of the measured subsystem at the density-state level.

discard_measured_modes_number_ket(state: KetPolyState, target: MeasurementTarget) → KetPolyState¶

Discard measured modes after number measurement on a ket state.

Parameters:

state (KetPolyState) – Ket-state wrapper from which measured modes would be discarded.
target (MeasurementTarget) – Semantic measurement target specifying the measured subsystem.

Returns:

This function does not return normally.

Return type:

KetPolyState

Raises:

NotImplementedError – Always raised, because destructive number measurement is not implemented directly for ket states.

Notes

Destructive number measurement should first be represented at the density-state level and then reduced by tracing out the measured subsystem.

iter_joint_number_support_poly_density(state: DensityPolyState, target: MeasurementTarget) → tuple[JointOutcome, ...]¶

Enumerate joint number outcomes supported by a density state.

Parameters:

state (DensityPolyState) – Density-state wrapper whose joint number support should be resolved.
target (MeasurementTarget) – Semantic measurement target containing per-port selections.

Returns:

Sorted tuple of supported joint number outcomes.

Return type:

tuple[JointOutcome, …]

Notes

A joint count contributes to the support only when left and right per-port counts agree for the density term.

iter_joint_number_support_poly_ket(state: KetPolyState, target: MeasurementTarget) → tuple[JointOutcome, ...]¶

Enumerate joint number outcomes supported by a ket state.

Parameters:

state (KetPolyState) – Ket-state wrapper whose joint number support should be resolved.
target (MeasurementTarget) – Semantic measurement target containing per-port selections.

Returns:

Sorted tuple of joint outcomes occurring across the ket terms.

Return type:

tuple[JointOutcome, …]

Notes

Support is determined structurally by counting selected creation operators port by port for each ket term.

iter_number_support_poly_density(state: DensityPolyState, target: MeasurementTarget) → tuple[NumberOutcome, ...]¶

Enumerate number outcomes supported by a density state.

Parameters:

state (DensityPolyState) – Density-state wrapper whose number support should be resolved.
target (MeasurementTarget) – Semantic measurement target specifying the measured subsystem.

Returns:

Sorted tuple of number outcomes supported by diagonal number sectors of the selected subsystem.

Return type:

tuple[NumberOutcome, …]

Notes

A count contributes to the support only when the selected number on the left and right side of a density term agrees.

iter_number_support_poly_ket(state: KetPolyState, target: MeasurementTarget) → tuple[NumberOutcome, ...]¶

Enumerate number outcomes supported by a ket state.

Parameters:

state (KetPolyState) – Ket-state wrapper whose number support should be resolved.
target (MeasurementTarget) – Semantic measurement target specifying the measured subsystem.

Returns:

Sorted tuple of number outcomes that occur across the ket terms of the selected subsystem.

Return type:

tuple[NumberOutcome, …]

Notes

Support is determined structurally by counting selected creation operators in each ket term.

joint_number_counts_for_ket_term(term: KetTerm, measured_sigs_by_port: Mapping[str, frozenset[tuple[object, ...]]]) → tuple[tuple[str, int], ...]¶

Count selected quanta per port for a ket term.

Parameters:

term (KetTerm) – Ket term whose monomial is to be inspected.
measured_sigs_by_port (Mapping[str, frozenset[tuple[object, ...]]]) – Mapping from port name to selected mode signatures.

Returns:

Tuple of (port_name, count) pairs describing the selected number counts for the term on each port.

Return type:

tuple[tuple[str, int], …]

joint_number_counts_left(term: DensityTerm, measured_sigs_by_port: Mapping[str, frozenset[tuple[object, ...]]]) → tuple[tuple[str, int], ...]¶

Count selected quanta per port in the left monomial of a density term.

Parameters:

term (DensityTerm) – Density term whose left monomial is to be inspected.
measured_sigs_by_port (Mapping[str, frozenset[tuple[object, ...]]]) – Mapping from port name to selected mode signatures.

Returns:

Tuple of (port_name, count) pairs for term.left.

Return type:

tuple[tuple[str, int], …]

Raises:

NumberMeasurementError – If term.left contains annihilators.

joint_number_counts_right(term: DensityTerm, measured_sigs_by_port: Mapping[str, frozenset[tuple[object, ...]]]) → tuple[tuple[str, int], ...]¶

Count selected quanta per port in the right monomial of a density term.

Parameters:

term (DensityTerm) – Density term whose right monomial is to be inspected.
measured_sigs_by_port (Mapping[str, frozenset[tuple[object, ...]]]) – Mapping from port name to selected mode signatures.

Returns:

Tuple of (port_name, count) pairs for term.right.

Return type:

tuple[tuple[str, int], …]

Raises:

NumberMeasurementError – If term.right contains annihilators.

joint_outcome_from_counts(counts_by_port: tuple[tuple[str, int], ...]) → JointOutcome¶

Build a joint number outcome from per-port counts.

Parameters:: counts_by_port (tuple[tuple[str, int], ...]) – Tuple of (port_name, count) pairs.
Returns:: Joint outcome whose per-port outcomes are number outcomes with the supplied counts.
Return type:: JointOutcome

project_onto_joint_number_poly_density(state: DensityPolyState, target: MeasurementTarget, outcome: JointOutcome, *, eps: float = 1e-12) → DensityPolyState¶

Project a density state onto a selected joint number outcome.

Parameters:

state (DensityPolyState) – Density-state wrapper to project.
target (MeasurementTarget) – Semantic measurement target containing per-port selections.
outcome (JointOutcome) – Joint number outcome defining the desired per-port number sector.
eps (float) – Numerical threshold forwarded to term combination.

Returns:

Projected density state containing only terms whose per-port left and right counts both match the requested joint outcome.

Return type:

DensityPolyState

project_onto_joint_number_poly_ket(state: KetPolyState, target: MeasurementTarget, outcome: JointOutcome, *, eps: float = 1e-12) → KetPolyState¶

Project a ket state onto a selected joint number outcome.

Parameters:

state (KetPolyState) – Ket-state wrapper to project.
target (MeasurementTarget) – Semantic measurement target containing per-port selections.
outcome (JointOutcome) – Joint number outcome defining the desired per-port number sector.
eps (float) – Numerical threshold forwarded to term combination.

Returns:

Projected ket state containing only terms whose per-port selected counts match the requested joint outcome.

Return type:

KetPolyState

project_onto_number_poly_density(state: DensityPolyState, target: MeasurementTarget, outcome: NumberOutcome, *, eps: float = 1e-12) → DensityPolyState¶

Project a density state onto a selected number outcome.

Parameters:

state (DensityPolyState) – Density-state wrapper to project.
target (MeasurementTarget) – Semantic measurement target specifying the measured subsystem.
outcome (NumberOutcome) – Number outcome defining the desired number sector.
eps (float) – Numerical threshold forwarded to term combination.

Returns:

Projected density state containing only terms whose selected left and right number counts both match outcome.count.

Return type:

DensityPolyState

Notes

Projection is implemented structurally by keeping only terms that are diagonal in the selected number sector and match the requested count.

project_onto_number_poly_ket(state: KetPolyState, target: MeasurementTarget, outcome: NumberOutcome, *, eps: float = 1e-12) → KetPolyState¶

Project a ket state onto a selected number outcome.

Parameters:

state (KetPolyState) – Ket-state wrapper to project.
target (MeasurementTarget) – Semantic measurement target specifying the measured subsystem.
outcome (NumberOutcome) – Number outcome defining the desired number sector.
eps (float) – Numerical threshold forwarded to term combination.

Returns:

Projected ket state containing only terms whose selected number count matches outcome.count.

Return type:

KetPolyState

Notes

Projection is implemented structurally by keeping only those ket terms with the requested number of selected creation operators.

require_number_outcome(outcome: object) → NumberOutcome¶

Validate that an outcome is a number outcome.

Parameters:: outcome (object) – Outcome object to validate.
Returns:: The validated number outcome.
Return type:: NumberOutcome
Raises:: TypeError – If outcome is not an instance of NumberOutcome.

resolve_joint_number_stats_poly_density(state: DensityPolyState, target: MeasurementTarget, *, eps: float = 1e-12) → Mapping[JointOutcome, float]¶

Resolve joint number statistics for a density state.

Parameters:

state (DensityPolyState) – Density-state wrapper whose joint number statistics should be resolved.
target (MeasurementTarget) – Semantic measurement target containing per-port selections.
eps (float) – Numerical tolerance used to discard negligible probabilities and to guard against small imaginary or negative numerical artifacts.

Returns:

Mapping from joint number outcomes to probabilities.

Return type:

Mapping[JointOutcome, float]

Raises:

NumberMeasurementError – If a projected trace has a non-negligible imaginary part or a real part smaller than -eps.

Notes

For each supported joint outcome, the probability is obtained as the trace of the corresponding projected density state.

resolve_joint_number_stats_poly_ket(state: KetPolyState, target: MeasurementTarget, *, eps: float = 1e-12) → Mapping[JointOutcome, float]¶

Resolve joint number statistics for a ket state.

Parameters:

state (KetPolyState) – Ket-state wrapper whose joint number statistics should be resolved.
target (MeasurementTarget) – Semantic measurement target containing per-port selections.
eps (float) – Numerical tolerance used to discard negligible probabilities and to guard against small negative numerical artifacts.

Returns:

Mapping from joint number outcomes to probabilities.

Return type:

Mapping[JointOutcome, float]

Raises:

NumberMeasurementError – If a probability smaller than -eps is encountered.

Notes

For each supported joint outcome, the probability is given by the squared norm of the corresponding projected ket state.

resolve_number_stats_poly_density(state: DensityPolyState, target: MeasurementTarget, *, eps: float = 1e-12) → NumberMeasurementStats¶

Resolve projective number statistics for a density state.

Parameters:

state (DensityPolyState) – Density-state wrapper whose number statistics should be resolved.
target (MeasurementTarget) – Semantic measurement target specifying the measured subsystem.
eps (float) – Numerical tolerance used to discard negligible probabilities and to guard against small imaginary or negative numerical artifacts.

Returns:

Resolved probability distribution over number outcomes.

Return type:

NumberMeasurementStats

Raises:

NumberMeasurementError – If a projected trace has a non-negligible imaginary part or a real part smaller than -eps.

Notes

For each supported outcome \(n\), the probability is obtained as

\[p(n) = \mathrm{Tr}(\Pi_n \rho \Pi_n).\]

resolve_number_stats_poly_ket(state: KetPolyState, target: MeasurementTarget, *, eps: float = 1e-12) → NumberMeasurementStats¶

Resolve projective number statistics for a ket state.

Parameters:

state (KetPolyState) – Ket-state wrapper whose number statistics should be resolved.
target (MeasurementTarget) – Semantic measurement target specifying the measured subsystem.
eps (float) – Numerical tolerance used to discard negligible probabilities and to guard against small negative numerical artifacts.

Returns:

Resolved probability distribution over number outcomes.

Return type:

NumberMeasurementStats

Raises:

NumberMeasurementError – If a probability smaller than -eps is encountered.

Notes

For each supported outcome \(n\), the probability is obtained from the squared norm of the projected ket state,

\[p(n) = \lVert \Pi_n |\psi\rangle \rVert^2.\]

selected_mode_signatures(state: DensityPolyState | KetPolyState, target: MeasurementTarget) → frozenset[tuple[object, ...]]¶

Return the signatures of all modes selected by a target.

Parameters:

state (DensityPolyState | KetPolyState) – Polynomial ket or density-state wrapper on which the target is resolved.
target (MeasurementTarget) – Semantic measurement target specifying paths and/or explicit mode signatures.

Returns:

Frozen set of signatures for all selected concrete modes.

Return type:

frozenset[Signature]

Notes

Duplicate selections are removed by construction.

selected_mode_signatures_by_port(state: DensityPolyState | KetPolyState, target: MeasurementTarget) → dict[str, frozenset[tuple[object, ...]]]¶

Return selected mode signatures grouped by semantic port.

Parameters:

state (DensityPolyState | KetPolyState) – Polynomial ket or density-state wrapper on which the target is resolved.
target (MeasurementTarget) – Semantic measurement target containing per-port selections.

Returns:

Mapping from port name to the set of selected mode signatures for that port.

Return type:

dict[str, frozenset[Signature]]

Notes

Within each port selection, modes may be specified by path and/or by explicit signature. Duplicate references are collapsed to a single signature entry.

selected_modes(state: DensityPolyState | KetPolyState, target: MeasurementTarget) → tuple[ModeOp, ...]¶

Resolve a measurement target into concrete selected modes.

Parameters:

state (DensityPolyState | KetPolyState) – Polynomial ket or density-state wrapper on which the target is resolved.
target (MeasurementTarget) – Semantic measurement target specifying paths and/or explicit mode signatures.

Returns:

Concrete modes selected by the target.

Return type:

tuple[ModeOpProtocol, …]

Notes

This is a thin convenience wrapper around state.resolve_target_modes().