merlin.core package

Core quantum layer components.

class merlin.core.AbstractComputationProcess

Bases: ABC

Abstract base class for quantum computation processes.

abstract compute(*args, **kwargs)

Perform the computation.

Args:

*args: Positional arguments for the computation. **kwargs: Keyword arguments for the computation.`

class merlin.core.Ansatz(PhotonicBackend, input_size, output_size=None, output_mapping_strategy=OutputMappingStrategy.LINEAR, device=None, dtype=None)

Bases: object

Complete configuration for a quantum neural network layer.

class merlin.core.AnsatzFactory

Bases: object

Factory for creating quantum layer ansatzes (complete configurations).

static create(PhotonicBackend, input_size, output_size=None, output_mapping_strategy=OutputMappingStrategy.LINEAR, device=None, dtype=None)

Create a complete ansatz configuration.

Return type:

Ansatz

Args:

PhotonicBackend (PhotonicBackend): The backend configuration to use. input_size (int): Size of the input feature vector. output_size (int | None): Size of the output vector. If None, it is defined by the backend. output_mapping_strategy (OutputMappingStrategy): Strategy for mapping outputs. device (torch.device | None): Device to run computations on. dtype (torch.dtype | None): Data type for computations.

Returns:

Ansatz: A complete ansatz configuration for the quantum layer.

class merlin.core.CircuitGenerator

Bases: object

Utility class for generating quantum photonic circuits.

static generate_circuit(circuit_type, n_modes, n_features)

Generate a quantum circuit based on specified type.

enum merlin.core.CircuitType(value)

Bases: Enum

Quantum circuit topology types.

Valid values are as follows:

PARALLEL_COLUMNS = <CircuitType.PARALLEL_COLUMNS: 'parallel_columns'>

SERIES = <CircuitType.SERIES: 'series'>

PARALLEL = <CircuitType.PARALLEL: 'parallel'>

class merlin.core.ComputationProcess(circuit, input_state, trainable_parameters, input_parameters, reservoir_mode=False, dtype=torch.float32, device=None, no_bunching=None, output_map_func=None, index_photons=None)

Bases: AbstractComputationProcess

Handles quantum circuit computation and state evolution.

compute(parameters)

Compute quantum output distribution.

Return type:

Tensor

compute_with_keys(parameters)

Compute quantum output distribution and return both keys and probabilities.

class merlin.core.ComputationProcessFactory

Bases: object

Factory for creating computation processes.

static create(circuit, input_state, trainable_parameters, input_parameters, reservoir_mode=False, no_bunching=None, output_map_func=None, index_photons=None, **kwargs)

Create a computation process.

Return type:

ComputationProcess

class merlin.core.PhotonicBackend(circuit_type, n_modes, n_photons, state_pattern=StatePattern.PERIODIC, use_bandwidth_tuning=False, reservoir_mode=False)

Bases: object

Configuration container for quantum layer experiments.

class merlin.core.QuantumLayer(input_size, output_size=None, ansatz=None, circuit=None, input_state=None, n_photons=None, trainable_parameters=(), input_parameters=(), output_mapping_strategy=OutputMappingStrategy.LINEAR, device=None, dtype=None, shots=0, sampling_method='multinomial', no_bunching=True, index_photons=None)

Bases: Module

Enhanced Quantum Neural Network Layer with factory-based architecture.

This layer can be created either from: 1. An Ansatz object (from AnsatzFactory) - for auto-generated circuits 2. Direct parameters - for custom circuits (backward compatible)

Args:

index_photons (List[Tuple[int, int]], optional): List of tuples (min_mode, max_mode)

constraining where each photon can be placed. The first_integer is the lowest index layer a photon can take and the second_integer is the highest index. If None, photons can be placed in any mode from 0 to m-1.

forward(*input_parameters, apply_sampling=None, shots=None)

Forward pass through the quantum layer.

Return type:

Tensor

get_index_photons_info()

Get information about index_photons constraints.

Return type:

dict

Returns:

dict: Information about photon placement constraints

prepare_parameters(input_parameters)

Prepare parameter list for circuit evaluation.

Return type:

list[Tensor]

set_sampling_config(shots=None, method=None)

Update sampling configuration.

classmethod simple(input_size, n_params=100, shots=0, reservoir_mode=False, output_size=None, output_mapping_strategy=OutputMappingStrategy.NONE, device=None, dtype=None, no_bunching=True)

Simplified interface for creating a QuantumLayer.

Uses SERIES circuit type with PERIODIC state pattern as defaults. Automatically calculates the number of modes based on n_params.

Args:

input_size (int): Size of the input vector n_params (int): Total number of parameters desired (default: 100). Formula: n_params = 2 * n_modes^2 shots (int): Number of shots for sampling (default: 0) reservoir_mode (bool): Whether to use reservoir mode (default: False) output_size (int, optional): Output dimension. If None, uses distribution size output_mapping_strategy: How to map quantum output to classical output device: PyTorch device dtype: PyTorch dtype no_bunching: Whether to exclude states with multiple photons per mode

Returns:

QuantumLayer: Configured quantum layer instance

to(*args, **kwargs)

Move and/or cast the parameters and buffers.

This can be called as

to(device=None, dtype=None, non_blocking=False)

to(dtype, non_blocking=False)

to(tensor, non_blocking=False)

to(memory_format=torch.channels_last)

Its signature is similar to torch.Tensor.to(), but only accepts floating point or complex dtypes. In addition, this method will only cast the floating point or complex parameters and buffers to dtype (if given). The integral parameters and buffers will be moved device, if that is given, but with dtypes unchanged. When non_blocking is set, it tries to convert/move asynchronously with respect to the host if possible, e.g., moving CPU Tensors with pinned memory to CUDA devices.

See below for examples.

Note

This method modifies the module in-place.

Args:

device (torch.device): the desired device of the parameters

and buffers in this module

dtype (torch.dtype): the desired floating point or complex dtype of

the parameters and buffers in this module

tensor (torch.Tensor): Tensor whose dtype and device are the desired

dtype and device for all parameters and buffers in this module

memory_format (torch.memory_format): the desired memory

format for 4D parameters and buffers in this module (keyword only argument)

Returns:

Module: self

Examples:

>>> # xdoctest: +IGNORE_WANT("non-deterministic")
>>> linear = nn.Linear(2, 2)
>>> linear.weight
Parameter containing:
tensor([[ 0.1913, -0.3420],
        [-0.5113, -0.2325]])
>>> linear.to(torch.double)
Linear(in_features=2, out_features=2, bias=True)
>>> linear.weight
Parameter containing:
tensor([[ 0.1913, -0.3420],
        [-0.5113, -0.2325]], dtype=torch.float64)
>>> # xdoctest: +REQUIRES(env:TORCH_DOCTEST_CUDA1)
>>> gpu1 = torch.device("cuda:1")
>>> linear.to(gpu1, dtype=torch.half, non_blocking=True)
Linear(in_features=2, out_features=2, bias=True)
>>> linear.weight
Parameter containing:
tensor([[ 0.1914, -0.3420],
        [-0.5112, -0.2324]], dtype=torch.float16, device='cuda:1')
>>> cpu = torch.device("cpu")
>>> linear.to(cpu)
Linear(in_features=2, out_features=2, bias=True)
>>> linear.weight
Parameter containing:
tensor([[ 0.1914, -0.3420],
        [-0.5112, -0.2324]], dtype=torch.float16)

>>> linear = nn.Linear(2, 2, bias=None).to(torch.cdouble)
>>> linear.weight
Parameter containing:
tensor([[ 0.3741+0.j,  0.2382+0.j],
        [ 0.5593+0.j, -0.4443+0.j]], dtype=torch.complex128)
>>> linear(torch.ones(3, 2, dtype=torch.cdouble))
tensor([[0.6122+0.j, 0.1150+0.j],
        [0.6122+0.j, 0.1150+0.j],
        [0.6122+0.j, 0.1150+0.j]], dtype=torch.complex128)

class merlin.core.StateGenerator

Bases: object

Utility class for generating photonic input states.

static generate_state(n_modes, n_photons, state_pattern)

Generate an input state based on specified pattern.

enum merlin.core.StatePattern(value)

Bases: Enum

Input photon state patterns.

Valid values are as follows:

DEFAULT = <StatePattern.DEFAULT: 'default'>

SPACED = <StatePattern.SPACED: 'spaced'>

SEQUENTIAL = <StatePattern.SEQUENTIAL: 'sequential'>

PERIODIC = <StatePattern.PERIODIC: 'periodic'>

Submodules

• merlin.core.ansatz module
  • Ansatz
  • AnsatzFactory
    • AnsatzFactory.create()
  • CircuitGenerator
    • CircuitGenerator.generate_circuit()
  • ComputationProcessFactory
    • ComputationProcessFactory.create()
  • FeatureEncoder
    • FeatureEncoder.encode()
  • OutputMappingStrategy
    • OutputMappingStrategy.LINEAR
    • OutputMappingStrategy.GROUPING
    • OutputMappingStrategy.LEXGROUPING
    • OutputMappingStrategy.MODGROUPING
    • OutputMappingStrategy.NONE
  • PhotonicBackend
  • StateGenerator
    • StateGenerator.generate_state()
• merlin.core.base module
  • ABC
  • AbstractComputationProcess
    • AbstractComputationProcess.compute()
  • abstractmethod()
• merlin.core.generators module
  • CircuitGenerator
    • CircuitGenerator.generate_circuit()
  • CircuitType
    • CircuitType.PARALLEL_COLUMNS
    • CircuitType.SERIES
    • CircuitType.PARALLEL
  • Enum
    • Enum.name
    • Enum.value
  • StateGenerator
    • StateGenerator.generate_state()
  • StatePattern
    • StatePattern.DEFAULT
    • StatePattern.SPACED
    • StatePattern.SEQUENTIAL
    • StatePattern.PERIODIC
• merlin.core.layer module
  • Ansatz
  • AnsatzFactory
    • AnsatzFactory.create()
  • AutoDiffProcess
    • AutoDiffProcess.autodiff_backend()
  • CircuitType
    • CircuitType.PARALLEL_COLUMNS
    • CircuitType.SERIES
    • CircuitType.PARALLEL
  • ComputationProcessFactory
    • ComputationProcessFactory.create()
  • Experiment
  • OutputMapper
    • OutputMapper.create_mapping()
  • OutputMappingStrategy
    • OutputMappingStrategy.LINEAR
    • OutputMappingStrategy.GROUPING
    • OutputMappingStrategy.LEXGROUPING
    • OutputMappingStrategy.MODGROUPING
    • OutputMappingStrategy.NONE
  • QuantumLayer
    • QuantumLayer.forward()
    • QuantumLayer.get_index_photons_info()
    • QuantumLayer.prepare_parameters()
    • QuantumLayer.set_sampling_config()
    • QuantumLayer.simple()
    • QuantumLayer.to()
  • StatePattern
    • StatePattern.DEFAULT
    • StatePattern.SPACED
    • StatePattern.SEQUENTIAL
    • StatePattern.PERIODIC
• merlin.core.photonicbackend module
  • CircuitType
    • CircuitType.PARALLEL_COLUMNS
    • CircuitType.SERIES
    • CircuitType.PARALLEL
  • PhotonicBackend
  • StatePattern
    • StatePattern.DEFAULT
    • StatePattern.SPACED
    • StatePattern.SEQUENTIAL
    • StatePattern.PERIODIC
• merlin.core.process module
  • AbstractComputationProcess
    • AbstractComputationProcess.compute()
  • CircuitConverter
    • CircuitConverter.set_dtype()
    • CircuitConverter.to()
    • CircuitConverter.to_tensor()
  • ComputationProcess
    • ComputationProcess.compute()
    • ComputationProcess.compute_with_keys()
  • ComputationProcessFactory
    • ComputationProcessFactory.create()
  • build_slos_distribution_computegraph()