merlin.core.components module

The merlin.core.components module defines the fundamental building blocks for photonic quantum circuits in Merlin. These components are platform-agnostic, descriptive objects that specify what should be present in a circuit (such as rotations, beam splitters, interferometers, and measurements), rather than how they are implemented on a specific backend.

Why use components?

  • Components provide a clear, modular, and backend-independent way to describe quantum circuits.

  • They enable high-level circuit construction, parameter management (fixed, trainable, or input-driven), and facilitate translation to various simulation or hardware platforms.

  • By separating intent from implementation, components make it easy to prototype, optimize, and analyze quantum circuits in a flexible and extensible manner.

Main components include:

  • Rotation: Describes a phase shifter (single-mode rotation), with configurable axis, value, and parameter role (fixed, trainable, or input).

  • BeamSplitter: Represents a two-mode mixing operation, with tunable mixing angle (theta) and phase (phi), both of which can be fixed or trainable.

  • EntanglingBlock: Specifies a block of entangling operations (e.g., nearest-neighbor beam splitters) to increase circuit expressivity.

  • GenericInterferometer: Encodes a universal linear optical transformation over multiple modes, optionally trainable.

These components are used by higher-level tools (like CircuitBuilder) to assemble, manipulate, and compile quantum circuits for simulation or execution.

Pure descriptive components that describe WHAT we want, not HOW to implement it. Components are platform-agnostic and focus on intent rather than implementation.

class merlin.core.components.ParameterRole(*values)

Bases: Enum

Role definition for circuit parameters.

FIXED = 'fixed'
INPUT = 'input'
TRAINABLE = 'trainable'
class merlin.core.components.Rotation(target, role=ParameterRole.FIXED, value=0.0, axis='z', custom_name=None)

Bases: object

Rotation gate description. The actual parameter name will be generated by the backend based on role.

Parameters:

  • target (int) – Target mode of the rotation.

  • role (ParameterRole) – Parameter role of the rotation.

  • value (float) – Fixed rotation value when role is ParameterRole.FIXED.

  • axis (str) – Rotation axis.

  • custom_name (str | None) – Optional custom parameter name.

axis: str = 'z'
custom_name: Optional[str] = None
get_params()

Return declared parameter placeholders for the rotation.

Non-fixed rotations expose either their custom name or the automatically generated identifier so that downstream tooling can bind data or trainable tensors to the gate.

Returns:

Mapping from parameter name to placeholder value.

Return type:

dict[str, Any]

role: ParameterRole = 'fixed'
target: int
value: float = 0.0
class merlin.core.components.BeamSplitter(targets, theta_role=ParameterRole.FIXED, theta_value=0.7854, phi_role=ParameterRole.FIXED, phi_value=0.0, theta_name=None, phi_name=None)

Bases: object

Beam splitter description.

Parameters:

  • targets (tuple) – Pair of target modes.

  • theta_role (ParameterRole) – Role of the mixing-angle parameter.

  • theta_value (float) – Fixed value of the mixing angle when theta_role is fixed.

  • phi_role (ParameterRole) – Role of the relative-phase parameter.

  • phi_value (float) – Fixed value of the relative phase when phi_role is fixed.

  • theta_name (str | None) – Optional symbolic name for the mixing-angle parameter.

  • phi_name (str | None) – Optional symbolic name for the relative-phase parameter.

get_params()

Describe which phase shifter angles should be exposed as parameters.

Returns:

Parameter placeholders keyed by their symbolic names.

Return type:

dict[str, Any]

phi_name: Optional[str] = None
phi_role: ParameterRole = 'fixed'
phi_value: float = 0.0
targets: tuple
theta_name: Optional[str] = None
theta_role: ParameterRole = 'fixed'
theta_value: float = 0.7854
class merlin.core.components.EntanglingBlock(targets='all', pattern='nearest_neighbor', depth=1, trainable=True, name_prefix=None)

Bases: object

Entangling block description.

Parameters:

  • targets (str | list[int]) – Target modes or "all" for every mode.

  • pattern (str) – Connectivity pattern for the entangling block.

  • depth (int) – Number of repeated entangling passes.

  • trainable (bool) – Whether the block should expose trainable parameters.

  • name_prefix (str | None) – Optional prefix used when generating parameter names.

depth: int = 1
get_params()

Entangling blocks themselves carry no direct parameters.

Returns:

Always empty because entangling blocks are metadata-only.

Return type:

dict[str, Any]

name_prefix: Optional[str] = None
pattern: str = 'nearest_neighbor'
targets: Union[str, list[int]] = 'all'
trainable: bool = True
class merlin.core.components.GenericInterferometer(start_mode, span, trainable=True, name_prefix=None, model='mzi', trainable_inner=None, trainable_outer=None)

Bases: object

Generic interferometer block spanning multiple modes.

Parameters:

  • start_mode (int) – First mode covered by the interferometer.

  • span (int) – Number of modes covered by the interferometer.

  • trainable (bool) – Whether the interferometer exposes trainable parameters.

  • name_prefix (str | None) – Optional prefix used when generating parameter names.

  • model (str) – Interferometer model, either "mzi" or "bell".

  • trainable_inner (bool | None) – Whether inner phase shifters are trainable.

  • trainable_outer (bool | None) – Whether outer phase shifters are trainable.

get_params()

Return placeholder names for every internal interferometer parameter.

Returns:

Mapping of generated parameter names to None placeholders.

Return type:

dict[str, Any]

model: str = 'mzi'
name_prefix: Optional[str] = None
span: int
start_mode: int
trainable: bool = True
trainable_inner: Optional[bool] = None
trainable_outer: Optional[bool] = None
class merlin.core.components.Component

Bases: object

Backward-compatible component base class.