merlin.core.process module

Quantum computation processes and factories.

class merlin.core.process.ComputationProcess(circuit, input_state, trainable_parameters, input_parameters, n_photons=None, dtype=torch.float32, device=None, computation_space=None, memristive_metadata=None, no_bunching=None, output_map_func=None, noise_groups=None, n_phase_error_samples=1)

Bases: AbstractComputationProcess

Handle quantum circuit computation and state evolution.

Parameters:

  • circuit (pcvl.Circuit) – Circuit used to build the unitary and simulation graphs.

  • input_state (list[int] | torch.Tensor) – Input Fock state or superposition tensor.

  • trainable_parameters (list[str]) – Prefixes of trainable circuit parameters.

  • input_parameters (list[str]) – Prefixes of input-driven circuit parameters.

  • n_photons (int | None) – Number of photons represented by the process.

  • dtype (torch.dtype) – Real dtype used for internal tensor conversions.

  • device (torch.device | None) – Device on which computation graphs are materialized.

  • computation_space (ComputationSpace | None) – Computation space used for basis enumeration.

  • no_bunching (bool | None) – Removed legacy parameter.

  • output_map_func (Any) – Optional output mapping function.

  • noise_groups (NoiseGroups | None) – The noise groups applied to the circuit to be ran.

  • n_phase_error_samples (int) – Number of Monte Carlo unitary samples used when active phase_error is present. For each sample, the converter draws fresh perturbations around the commanded phases after any phase_imprecision quantization, computes probabilities for that sampled unitary, and averages probabilities. Amplitudes are not averaged.

compute(parameters, amplitude_encoding=False, memristive_current_state=None)

Compute output amplitudes or probabilities for the configured input state.

Parameters:

  • parameters (list[torch.Tensor]) – Circuit parameters passed to the converter.

  • amplitude_encoding (bool) – If True and input_state is a tensor, use tensor-superposition handling. Source-noise simulations mix probabilities over Fock basis states weighted by \(|c_i|^2\); phase-error simulations without source noise compute coherent probabilities per sampled unitary. Default is False.

  • memristive_current_state (list[torch.Tensor] | None) – The memristive phase shifters current states. Defaults to None and will be treated as an empty list.

Returns:

Output probabilities if source noise or stochastic phase error is active (a SectoredDistribution when g2 noise is present) and amplitudes otherwise.

Return type:

torch.Tensor | SectoredDistribution

compute_ebs_simultaneously(parameters, simultaneous_processes=1, memristive_current_state=None)

Evaluate a single circuit parametrisation against all superposed input states by chunking them in groups and delegating the heavy work to the TorchScript-enabled batch kernel.

The method converts the trainable parameters into a unitary matrix, normalises the input state (if it is not already normalised), filters out components with zero amplitude, and then queries the simulation graph for batches of Fock states. Each batch feeds compute_batch(), producing a tensor that contains the amplitudes of all reachable output states for the selected input components. The partial results are accumulated into a preallocated tensor and finally weighted by the complex coefficients of self.input_state to produce the global output amplitudes.

Parameters:

  • parameters (list[torch.Tensor]) – Differentiable parameters that encode the photonic circuit.

  • simultaneous_processes (int) – Maximum number of non-zero input components propagated in a single call to compute_batch.

  • memristive_current_state (list[torch.Tensor] | None) – The memristive phase shifters current states. Defaults to None and will be treated as an empty list.

Returns:

Superposed output amplitudes with shape [batch_size, num_output_states].

Return type:

torch.Tensor

Raises:

TypeError – If self.input_state is not a torch.Tensor.

Notes

  • self.input_state is normalized in place to avoid an extra allocation. Parameters are forwarded to self.converter to build the unitary matrix used during the simulation.

  • Zero-amplitude components are skipped to minimise the number of calls to compute_batch.

  • The method is agnostic to the device: tensors remain on the device they already occupy, so callers should ensure parameters and self.input_state live on the same device.

compute_superposition_state(parameters, *, simultaneous_processes=None, return_keys=False, memristive_current_state=None)

Compute amplitudes for a tensor superposition input state.

Parameters:

  • parameters (list[torch.Tensor]) – Circuit parameters passed to the converter.

  • simultaneous_processes (int | None) – Maximum number of active input components propagated in one chunk. If omitted, an internal default chunk size is used.

  • return_keys (bool) – Whether to return the output basis keys with the amplitudes. Default value is False.

  • memristive_current_state (list[torch.Tensor] | None) – The memristive phase shifters current states. Defaults to None and will be treated as an empty list.

Returns:

Output amplitudes, optionally paired with their basis keys.

Return type:

torch.Tensor | tuple[list[tuple[int, …]], torch.Tensor]

Raises:

RuntimeError – If phase error or source noise is active, because those paths return probabilities rather than amplitudes.

compute_with_keys(parameters, *, use_input_state_superposition=False, memristive_current_state=None)

Compute output values and return them with basis keys.

Parameters:

  • parameters (list[torch.Tensor]) – Circuit parameters passed to the converter.

  • use_input_state_superposition (bool) – If True and input_state is a tensor, use tensor-superposition handling when phase error is active. If omitted, tensor input_state follows the same default fixed-Fock-state behavior as compute(). Default is False.

  • memristive_current_state (list[torch.Tensor] | None) – The memristive phase shifters current states. Defaults to None and will be treated as an empty list.

Returns:

Simulation-graph keys and corresponding probabilities if source noise or phase error is active, and amplitudes otherwise.

Return type:

tuple[Any, torch.Tensor | SectoredDistribution]

to(*, dtype, device)

Move runtime computation state to a new dtype or device.

Parameters:

  • dtype (torch.dtype) – Target real tensor dtype used by the unitary converter and SLOS simulation graph.

  • device (torch.device | None) – Target tensor device. If omitted, runtime tensors keep PyTorch’s implicit CPU placement.

Returns:

Updated computation process instance.

Return type:

ComputationProcess

Raises:

  • TypeError – If the converter rejects the target dtype or device.

  • ValueError – If the SLOS simulation graph cannot be rebuilt for the target dtype.

class merlin.core.process.ComputationProcessFactory

Bases: object

Factory for creating computation processes.

static create(circuit, input_state, trainable_parameters, input_parameters, computation_space=None, noise_groups=None, n_phase_error_samples=1, memristive_metadata=None, **kwargs)

Create a computation process.

Parameters:

  • circuit (pcvl.Circuit) – Circuit used to build the process.

  • input_state (list[int] | torch.Tensor) – Input Fock state or superposition tensor.

  • trainable_parameters (list[str]) – Prefixes of trainable circuit parameters.

  • input_parameters (list[str]) – Prefixes of input-driven circuit parameters.

  • computation_space (ComputationSpace | None) – Computation space used for basis enumeration.

  • noise_groups (NoiseGroups | None) – The noise groups applied to the circuit to be ran.

  • n_phase_error_samples (int) – Number of Monte Carlo unitary samples used when active phase_error is present. Default value is 1.

  • memristive_metadata (list[dict] | None) – The memristive phase shifter metadata. If None, it will be stored as an empty list.

  • **kwargs – Additional keyword arguments forwarded to ComputationProcess.

Returns:

Created computation process.

Return type:

ComputationProcess