symop.polynomial.channels.primitives¶

Primitive channel-building operations for CCR polynomial channels.

This package provides low-level building blocks used to construct physical transformations on polynomial representations. It includes passive linear mode rewrites, active Bogoliubov rewrites, and generic unitary-dilation helpers that higher-level models can build upon.

class BogoliubovMap(modes: tuple[ModeOp, ...], X: ndarray, Y: ndarray, check_ccr: bool = False, atol: float = 1e-10) → None¶

Bases: object

Represent an active linear bosonic map on an ordered mode basis.

The ordered tuple modes defines the basis in which the matrices X and Y are interpreted. Column k of these matrices gives the image of input mode k in the ordered output basis.

In the Heisenberg picture, the ladder operators transform as

\[a_k^\dagger \;\mapsto\; \sum_j X_{j k}\, a_j^\dagger + Y_{j k}\, a_j,\]

and

\[a_k \;\mapsto\; \sum_j \overline{Y_{j k}}\, a_j^\dagger + \sum_j \overline{X_{j k}}\, a_j.\]

Optional CCR validation checks the bosonic constraints

\[X^\dagger X - Y^\dagger Y = I,\]

and

\[X^T Y - Y^T X = 0,\]

within the numerical tolerance atol.

Parameters:

modes (tuple[ModeOp, ...]) – Ordered mode basis used for the matrix representation.
X (ndarray) – Matrix multiplying creation operators in the Bogoliubov transformation.
Y (ndarray) – Matrix mixing creation and annihilation operators in the Bogoliubov transformation.
check_ccr (bool) – If True, validate the bosonic CCR consistency conditions.
atol (float) – Absolute tolerance used for optional CCR validation.

Notes

When Y = 0, this object describes an ordinary passive linear mode transformation.

X: ndarray¶

Y: ndarray¶

atol: float = 1e-10¶

check_ccr: bool = False¶

modes: tuple[ModeOp, ...]¶

class LinearModeMap(modes: tuple[ModeOp, ...], U: ndarray, check_unitary: bool = False, atol: float = 1e-10) → None¶

Bases: object

Represent a passive linear transformation on an ordered mode basis.

The ordered tuple modes defines both the input and output basis used to interpret the matrix U. The convention is that column k of U gives the image of input mode k in the ordered output basis.

In the Heisenberg picture, the ladder operators transform as

\[a_k^\dagger \;\mapsto\; \sum_j U_{j k}\, a_j^\dagger,\]

and

\[a_k \;\mapsto\; \sum_j \overline{U_{j k}}\, a_j.\]

Parameters:

modes (tuple[ModeOp, ...]) – Ordered mode basis used for the matrix representation.
U (ndarray) – Square matrix representing the passive linear transformation in the ordered basis given by modes.
check_unitary (bool) – If True, validate that U is unitary within the tolerance specified by atol.
atol (float) – Absolute tolerance used for optional unitary validation.

Notes

This class stores only the linear transformation data and does not itself apply the rewrite. Use make_substitution or one of the apply_to_* helpers to act on symbolic polynomial objects.

U: ndarray¶

atol: float = 1e-10¶

check_unitary: bool = False¶

modes: tuple[ModeOp, ...]¶

class UnitaryDilation(modes: tuple[ModeOp, ...], U: ndarray, trace_out_modes: tuple[ModeOp, ...], check_unitary: bool = False, atol: float = 1e-10) → None¶

Bases: object

Specification of a unitary dilation on an ordered tuple of modes.

Parameters:

modes (tuple[ModeOp, ...]) – Ordered modes on which the dilation unitary acts.
U (ndarray) – Square matrix whose ordering matches modes.
trace_out_modes (tuple[ModeOp, ...]) – Modes to trace out after the unitary action.
check_unitary (bool) – If True, validate unitarity of U.
atol (float) – Tolerance for optional unitary validation.

Notes

The mode ordering is the same convention as used by LinearModeMap: column k of U gives the image of input mode k in the ordered output basis modes.

U: ndarray¶

atol: float = 1e-10¶

check_unitary: bool = False¶

modes: tuple[ModeOp, ...]¶

trace_out_modes: tuple[ModeOp, ...]¶

apply_bogoliubov_to_densitypoly(rho: DensityPoly, *, bmap: BogoliubovMap) → DensityPoly¶

Apply a Bogoliubov rewrite to a density polynomial.

The density polynomial is rewritten as the symbolic adjoint action

rho -> S rho S^dagger

by using the ket-side substitution on the left monomials and the corresponding bra-side substitution on the right monomials.

Parameters:

rho (DensityPoly) – Input density polynomial.
bmap (BogoliubovMap) – Bogoliubov transformation to apply.

Returns:

Rewritten density polynomial after the active linear bosonic transformation.

Return type:

DensityPolyProtocol

apply_bogoliubov_to_ketpoly(poly: KetPoly, *, bmap: BogoliubovMap, reduce_ketpoly: Callable[[KetPoly], KetPoly]) → KetPoly¶

Apply a Bogoliubov rewrite to a ket polynomial and reduce the result.

The ket polynomial is first rewritten by substituting ladder operators according to the Bogoliubov transformation. Because active transformations may generate annihilation operators even when acting on creator-only expressions, the rewritten polynomial must then be reduced using a caller-supplied CCR reduction routine.

Parameters:

poly (KetPoly) – Input ket polynomial.
bmap (BogoliubovMap) – Bogoliubov transformation to apply.
reduce_ketpoly (Callable[[KetPoly], KetPoly]) – Callback that performs the required CCR reduction or normal ordering after substitution.

Returns:

Reduced ket polynomial after substitution and CCR reduction.

Return type:

KetPoly

Notes

Unlike passive linear mode maps, a Bogoliubov transformation cannot in general be handled by simply discarding annihilator-containing terms. The reduction callback is responsible for applying the CCR relations and returning a valid ket representation.

apply_bogoliubov_to_oppoly(op: OpPoly, *, bmap: BogoliubovMap) → OpPoly¶

Apply a Bogoliubov rewrite to an operator polynomial.

Each ladder operator in the operator polynomial is rewritten according to the Bogoliubov transformation defined by bmap.

Parameters:

op (OpPoly) – Input operator polynomial.
bmap (BogoliubovMap) – Bogoliubov transformation to apply.

Returns:

Rewritten operator polynomial after the active linear bosonic transformation.

Return type:

OpPolyProtocol

apply_to_densitypoly(rho: DensityPoly, *, lmap: LinearModeMap) → DensityPoly¶

Apply a passive linear mode map to a density polynomial.

The density polynomial is rewritten by substituting ladder operators on both the left and right monomials according to the Heisenberg action of lmap.

Parameters:

rho (DensityPoly) – Input density polynomial.
lmap (LinearModeMap) – Passive linear mode transformation to apply.

Returns:

Rewritten density polynomial after the linear mode transformation.

Return type:

DensityPolyProtocol

Notes

This function applies the same substitution map to both sides of the density polynomial, with annihilation operators transformed using the conjugated matrix elements as required by the Heisenberg convention.

apply_to_ketpoly(poly: KetPoly, *, lmap: LinearModeMap) → KetPoly¶

Apply a passive linear mode map to a ket polynomial.

The transformation is implemented by rewriting all ladder operators in the polynomial according to the Heisenberg action of lmap and then discarding terms incompatible with the vacuum reference state.

Parameters:

poly (KetPoly) – Input ket polynomial.
lmap (LinearModeMap) – Passive linear mode transformation to apply.

Returns:

Rewritten ket polynomial after vacuum-compatible projection.

Return type:

KetPoly

Notes

The final projection step keeps only creator-only monomials and the identity term, corresponding to the usual vacuum-based ket polynomial semantics.

apply_to_oppoly(op: OpPoly, *, lmap: LinearModeMap) → OpPoly¶

Apply a passive linear mode map to an operator polynomial.

Each ladder operator in the operator polynomial is rewritten according to the Heisenberg action of lmap.

Parameters:

op (OpPoly) – Input operator polynomial.
lmap (LinearModeMap) – Passive linear mode transformation to apply.

Returns:

Rewritten operator polynomial after the linear mode transformation.

Return type:

OpPolyProtocol

apply_unitary_dilation_densitypoly(rho: DensityPoly, *, dilation: UnitaryDilation, normalize_trace: bool = False, eps: float = 1e-14) → DensityPoly¶

Apply a generic unitary-dilation channel to a density polynomial.

The channel is implemented by first applying the passive linear mode transformation associated with dilation.U on dilation.modes, then tracing out dilation.trace_out_modes:

\[\Phi(\rho) = \mathrm{Tr}_{T}\!\left[ U\, \rho\, U^\dagger \right],\]

where \(T\) is the subsystem spanned by the traced modes.

Parameters:

rho (DensityPoly) – Input symbolic density polynomial.
dilation (UnitaryDilation) – Dilation specification.
normalize_trace (bool) – If True, trace-normalize the reduced output density.
eps (float) – Threshold used by trace normalization if enabled.

Returns:

Reduced density polynomial after the unitary action and partial trace.

Return type:

DensityPoly

Notes

This helper is the generic building block for channels such as pure loss, thermal-loss variants with suitable ancilla handling, and other ancilla-assisted linear bosonic channels.

In the common “fresh environment mode” pattern, the traced modes are newly introduced ancilla modes not otherwise present in the retained system.

apply_unitary_dilation_densitypoly_direct(rho: DensityPoly, *, modes: tuple[ModeOp, ...], U: ndarray, trace_out_modes: tuple[ModeOp, ...], normalize_trace: bool = False, eps: float = 1e-14, check_unitary: bool = False, atol: float = 1e-10) → DensityPoly¶

Apply a unitary-dilation channel from explicit dilation data.

This is a convenience wrapper around apply_unitary_dilation_densitypoly. It constructs a UnitaryDilation object from the supplied modes, unitary matrix, and traced modes, and then applies the resulting channel.

The induced channel is

\[\Phi(\rho) = \operatorname{Tr}_{T}\!\left[ U \rho U^\dagger \right],\]

where the ordering of the matrix \(U\) matches the ordering of modes.

Parameters:

rho (DensityPoly) – Input symbolic density polynomial.
modes (tuple[ModeOp, ...]) – Ordered tuple of modes on which the dilation unitary acts.
U (ndarray) – Square matrix representing the passive linear transformation in the ordered basis given by modes.
trace_out_modes (tuple[ModeOp, ...]) – Modes to trace out after applying the unitary action.
normalize_trace (bool) – If True, normalize the reduced output state to unit trace after tracing out the selected modes.
eps (float) – Threshold used by the trace-normalization routine when normalize_trace is enabled.
check_unitary (bool) – If True, validate that U is unitary within the tolerance specified by atol.
atol (float) – Absolute tolerance used when validating unitarity.

Returns:

Reduced symbolic density polynomial obtained after the unitary action and partial trace.

Return type:

DensityPolyProtocol

Notes

This function is useful when the caller does not need to reuse a UnitaryDilation object and wants to specify the dilation data directly at the call site.

`bogoliubov`	Bogoliubov rewrites for CCR polynomial representations.
`linear_mode_unitary`	Linear mode-map rewrites for CCR polynomial representations.
`unitary_dilation`	Generic unitary-dilation channels for symbolic density polynomials.