symop.polynomial.kernels.devices.beamsplitter

Polynomial kernels for beamsplitter-style two-mode devices.

This module implements backend kernels for applying one or more two-mode beamsplitter transformations to polynomial ket and density states.

The semantic planning stage provides the input mode signatures, output paths, and beamsplitter parameters through action.params. The backend uses the package Heisenberg convention, where creation operators transform as

\[\hat a^\dagger_{\mathrm{out},k} = \sum_j U_{k j}\,\hat a^\dagger_{\mathrm{in},j}.\]

For the angle parameter theta used by the high-level beamsplitter device, the transmission and reflection amplitudes are

\[t = \cos(\theta), \qquad r = \sin(\theta).\]

The corresponding two-mode unitary is

\[\begin{split}U = \begin{pmatrix} t e^{i\phi_t} & r e^{i\phi_r} \\ -r e^{-i\phi_r} & t e^{-i\phi_t} \end{pmatrix}.\end{split}\]

Thus theta = pi / 4 gives a 50/50 beamsplitter.

Notes

The kernel performs the full representation-specific beamsplitter rewrite, including construction of output-path modes. No additional label-edit phase is required for the physical beamsplitter action.

Functions

beamsplitter_poly_density(*, state, action, ctx)

Apply one or more beamsplitters to a polynomial density state.

beamsplitter_poly_ket(*, state, action, ctx)

Apply one or more beamsplitters to a polynomial ket state.
class _BeamSplitterKernelParams(pairs: tuple[_BeamSplitterSpec, ...]) → None

Bases: object

Parsed kernel parameters for one or more beamsplitter applications.

Parameters:

pairs (tuple[_BeamSplitterSpec, ...])

pairs

Tuple of parsed beamsplitter application specifications.

pairs: tuple[_BeamSplitterSpec, ...]
class _BeamSplitterSpec(mode0_sig: Any, mode1_sig: Any, theta: float, phi_t: float = 0.0, phi_r: float = 0.0, check_unitary: bool = False, atol: float = 1e-10, in0: Any | None = None, in1: Any | None = None, out0: Any | None = None, out1: Any | None = None) → None

Bases: object

Parsed specification for one beamsplitter application.

Parameters:
mode0_sig

Signature of the first input mode, or None if the first input arm is vacuum and must be synthesized.

mode1_sig

Signature of the second input mode, or None if the second input arm is vacuum and must be synthesized.

theta

Mixing angle.

phi_t

Transmission phase.

phi_r

Reflection phase.

check_unitary

Whether to validate the resulting 2x2 unitary.

atol

Tolerance for optional unitary validation.

in0, in1

Input paths used when a vacuum partner mode must be synthesized.

out0, out1

Output paths used by the beamsplitter rewrite.

atol: float = 1e-10
check_unitary: bool = False
in0: Any | None = None
in1: Any | None = None
mode0_sig: Any
mode1_sig: Any
out0: Any | None = None
out1: Any | None = None
phi_r: float = 0.0
phi_t: float = 0.0
theta: float
_make_vacuum_partner_mode(*, existing_mode: ModeOp, input_path: Path) → Any

Create a matching partner mode on a missing beamsplitter input path.

The new mode matches the existing mode in all semantic degrees of freedom except for the path label, which is replaced by input_path.

Parameters:

  • existing_mode (ModeOp)

  • input_path (Path)

Return type:

Any

_parse_beamsplitter_params(action: DeviceAction) → _BeamSplitterKernelParams

Extract and validate kernel parameters from a device action.

Parameters:

action (DeviceAction) – Semantic device action produced during planning.

Returns:

Parsed beamsplitter parameters.

Return type:

_BeamSplitterKernelParams

Raises:

TypeError – If action.params does not have the expected mapping shape.

_parse_single_pair(obj: object) → _BeamSplitterSpec

Parse one beamsplitter pair specification.

Parameters:

obj (object) – Mapping-like specification for one beamsplitter action.

Returns:

Parsed beamsplitter specification.

Return type:

_BeamSplitterSpec

Raises:

  • TypeError – If the input does not have the expected mapping structure.

  • KeyError – If required keys are missing.

_require_output_paths(spec: _BeamSplitterSpec) → tuple[Path, Path]

Return validated output paths for one beamsplitter specification.

Parameters:

spec (_BeamSplitterSpec) – Parsed beamsplitter specification.

Returns:

Pair (out0, out1) of validated output paths.

Return type:

tuple[Path, Path]

Raises:

ValueError – If either output path is missing.

beamsplitter_poly_density(*, state: DensityPolyState, action: DeviceAction, ctx: ApplyContext) → DensityPolyState

Apply one or more beamsplitters to a polynomial density state.

Parameters:

  • state (DensityPolyState) – Input polynomial density state.

  • action (DeviceAction) – Semantic device action containing beamsplitter parameters.

  • ctx (ApplyContext) – Unused for direct beamsplitter application. Included for API consistency with other kernels.

Returns:

Output density state after all requested beamsplitter operations.

Return type:

DensityPolyState

Notes

This kernel performs the full backend-specific beamsplitter rewrite, including construction of output-path modes.

beamsplitter_poly_ket(*, state: KetPolyState, action: DeviceAction, ctx: ApplyContext) → KetPolyState

Apply one or more beamsplitters to a polynomial ket state.

Parameters:

  • state (KetPolyState) – Input polynomial ket state.

  • action (DeviceAction) – Semantic device action containing beamsplitter parameters.

  • ctx (ApplyContext) – Unused for direct beamsplitter application. Included for API consistency with other kernels.

Returns:

Output ket state after all requested beamsplitter operations.

Return type:

KetPolyState

Notes

This kernel performs the full backend-specific beamsplitter rewrite, including construction of output-path modes.