quapp-merlin

Quapp provider lib for MerLin, Quandela's photonic quantum machine learning framework. MerLin wraps Perceval but is a separate SDK here: a MerLin handler returns a PyTorch model, not a circuit.

SDK tag: MERLIN · providers: QUAO_QUANTUM_SIMULATOR (local), QUANDELA (cloud)

What a handler returns

Every other SDK on the platform has processing() return a circuit. MerLin has no circuit to return -- the unit of work is a torch.nn.Module holding a merlin.QuantumLayer, plus the batch to run it on.

import merlin as ML
import torch

from quapp_merlin import MerlinJobSpec


def processing(invocation_input: dict) -> MerlinJobSpec:
    layer = ML.QuantumLayer.simple(
            input_size=4,
            measurement_strategy=ML.MeasurementStrategy.probs())

    return MerlinJobSpec(model=layer,
                         inputs=torch.tensor(invocation_input['inputs']),
                         shots=invocation_input.get('shots'))


def post_processing(job_result: dict) -> dict:
    return {'probabilities': job_result['result']['values']}

Returning a bare torch.nn.Module also works, and the batch is then read from invocation_input["inputs"].

shots=None (the default) means exact probabilities: MerLin does not invent a shot count, and neither does this lib.

One invocation, one machine

MerLin fans out along three axes, and the first one can put a job on a machine nobody selected:

Together these keep future.job_ids a single id, so provider_job_id stays one value the backend can store as-is. The rules live in quapp_merlin/util/single_machine.py and are locked by tests/test_single_machine.py.

Local vs remote

The image ships the CPU build of torch on purpose: the default wheel drags in the whole CUDA runtime (~2.5 GB) for a photonic simulator that never touches a GPU. A job asking for ProcessingUnit.GPU runs on CPU with a warning.

Result shape

_create_job returns a dict that is already JSON-safe -- no tensor ever reaches json.dumps in a callback:

{'result': {'values': [[0.24, 0.76]], 'truncated': False, 'elements': 2},
 'shape': [1, 2],
 'batch_size': 1,
 'shots': None,
 'measurement': 'probs',
 'execution_time': 0.184,
 'provider_job_id': None,
 'histogram': {'state_0': 0.24, 'state_1': 0.76},
 'metadata': {}}

histogram is only produced for a probability measurement of a single row: with a batch there are as many distributions as rows, and with mode_expectations() / amplitudes() there is no distribution over states to bin. It is None in those cases, and the full output stays in result.

Large outputs are truncated with truncated: True and the real element count, rather than silently sending the first rows as if they were everything.

Versions

import quapp_merlin needs none of torch, merlin or perceval: every SDK import sits inside the function that uses it, so the error classifier still works in an image where the SDK failed to install. tests/test_lazy_sdk_imports.py enforces it.