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, no_bunching=None, output_map_func=None)

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) – Deprecated legacy parameter.

  • output_map_func (Any) – Optional output mapping function.

compute(parameters)

Compute output amplitudes for the configured input state.

Parameters:

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

Returns:

Output amplitudes produced by the simulation graph.

Return type:

torch.Tensor

compute_ebs_simultaneously(parameters, simultaneous_processes=1)

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.

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.They 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, *, return_keys=False)
Return type:

Union[Tensor, tuple[list[tuple[int, ...]], Tensor]]

compute_with_keys(parameters)

Compute output amplitudes and return them with basis keys.

Parameters:

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

Returns:

Simulation-graph keys and corresponding amplitudes.

Return type:

tuple[Any, torch.Tensor]

class merlin.core.process.ComputationProcessFactory

Bases: object

Factory for creating computation processes.

static create(circuit, input_state, trainable_parameters, input_parameters, computation_space=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.

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

Returns:

Created computation process.

Return type:

ComputationProcess