quapp-merlin 0.0.1.dev1__tar.gz

quapp_merlin-0.0.1.dev1/LICENSE

@@ -0,0 +1,8 @@
+The MIT License (MIT)
+Copyright © CITYNOW Co. Ltd. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

quapp_merlin-0.0.1.dev1/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: quapp-merlin
+Version: 0.0.1.dev1
+Summary: Quapp common library supporting Quapp Platform for Quantum Computing
+Author-email: "CITYNOW Co. Ltd. " <corp@citynow.vn>
+License: The MIT License (MIT)
+        Copyright © CITYNOW Co. Ltd. All rights reserved.
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+Project-URL: Homepage, https://quapp.cloud/
+Keywords: quapp,quapp-merlin,quantum,photonic,pytorch
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Requires-Python: <3.15,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: quapp-common==0.0.15.dev5
+Requires-Dist: merlinquantum==0.4.1
+Provides-Extra: dev
+Requires-Dist: black; extra == "dev"
+Requires-Dist: bumpver; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+Requires-Dist: pip-tools; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# quapp-merlin
+
+Quapp provider lib for [MerLin](https://merlinquantum.ai/), 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.
+
+```python
+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:
+
+| Axis | What it does | Rule here |
+|---|---|---|
+| Backend | one `MerlinProcessor` binds one backend, but a handler can build a second one and route layers to it | **refused** -- the machine comes from DeviceSelection |
+| Chunks | `len(X) > microbatch_size` splits a batch into several cloud jobs | `chunk_concurrency=1`, batch must fit one microbatch |
+| Leaves | several `QuantumLayer`s in one model, each its own remote job | one layer per invocation |
+
+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
+
+| | local (`QUAO_QUANTUM_SIMULATOR`) | remote (`QUANDELA`) |
+|---|---|---|
+| Runs on | SLOS simulation in the container, **CPU only** | Quandela Cloud, `sim:*` or `qpu:*` |
+| Training | yes, `MerlinJobSpec(training=TrainingSpec(...))` | **no** -- no gradient flows through the MerLin processor |
+| Phases | COMPILATION, EXECUTION, ANALYSIS | plus POLLING while waiting on the cloud |
+| Job id | none | one, from `future.job_ids` |
+
+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:
+
+```python
+{'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
+
+| | |
+|---|---|
+| `merlinquantum` | `==0.4.1` -- 0.4 renamed the `QuantumLayer` arguments 0.3 used (`output_mapping_strategy` -> `measurement_strategy`, `ansatz` -> `builder`), so `>=` would break every handler |
+| `quapp-common` | `==0.0.15.dev5` -- first release carrying `Sdk.MERLIN` |
+| Python | `>=3.10` (merlinquantum), `<3.15` (perceval-quandela) |
+
+`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.

quapp_merlin-0.0.1.dev1/README.md

@@ -0,0 +1,107 @@
+# quapp-merlin
+
+Quapp provider lib for [MerLin](https://merlinquantum.ai/), 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.
+
+```python
+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:
+
+| Axis | What it does | Rule here |
+|---|---|---|
+| Backend | one `MerlinProcessor` binds one backend, but a handler can build a second one and route layers to it | **refused** -- the machine comes from DeviceSelection |
+| Chunks | `len(X) > microbatch_size` splits a batch into several cloud jobs | `chunk_concurrency=1`, batch must fit one microbatch |
+| Leaves | several `QuantumLayer`s in one model, each its own remote job | one layer per invocation |
+
+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
+
+| | local (`QUAO_QUANTUM_SIMULATOR`) | remote (`QUANDELA`) |
+|---|---|---|
+| Runs on | SLOS simulation in the container, **CPU only** | Quandela Cloud, `sim:*` or `qpu:*` |
+| Training | yes, `MerlinJobSpec(training=TrainingSpec(...))` | **no** -- no gradient flows through the MerLin processor |
+| Phases | COMPILATION, EXECUTION, ANALYSIS | plus POLLING while waiting on the cloud |
+| Job id | none | one, from `future.job_ids` |
+
+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:
+
+```python
+{'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
+
+| | |
+|---|---|
+| `merlinquantum` | `==0.4.1` -- 0.4 renamed the `QuantumLayer` arguments 0.3 used (`output_mapping_strategy` -> `measurement_strategy`, `ansatz` -> `builder`), so `>=` would break every handler |
+| `quapp-common` | `==0.0.15.dev5` -- first release carrying `Sdk.MERLIN` |
+| Python | `>=3.10` (merlinquantum), `<3.15` (perceval-quandela) |
+
+`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.

quapp_merlin-0.0.1.dev1/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=61.0.0", "wheel==0.45.1"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "quapp-merlin"
+version = "0.0.1.dev1"
+description = "Quapp common library supporting Quapp Platform for Quantum Computing"
+readme = "README.md"
+authors = [{ name = "CITYNOW Co. Ltd. ", email = "corp@citynow.vn" }]
+license = { file = "LICENSE" }
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+]
+keywords = ["quapp", "quapp-merlin", "quantum", "photonic", "pytorch"]
+# merlinquantum 0.4 renamed the QuantumLayer arguments that 0.3 used
+# (output_mapping_strategy -> measurement_strategy, ansatz -> builder), so `>=`
+# would silently break every handler. Exact pin, same policy as the other libs.
+#
+# torch is NOT listed here on purpose: the base image installs the CPU wheel
+# from download.pytorch.org, and naming it here would let pip pull the default
+# wheel instead, which drags in the whole CUDA runtime (~2.5 GB) for a photonic
+# QPU that never touches a GPU. merlinquantum already declares torch, so the
+# constraint is still enforced -- it is just satisfied by what the image
+# installed first.
+dependencies = [
+    # 0.0.15.dev5 is the first release carrying Sdk.MERLIN.
+    "quapp-common==0.0.15.dev5",
+    "merlinquantum==0.4.1"
+]
+# merlinquantum requires >=3.10; perceval-quandela caps at <3.15.
+requires-python = ">=3.10,<3.15"
+
+[project.optional-dependencies]
+dev = ["black", "bumpver", "isort", "pip-tools", "pytest"]
+
+[project.urls]
+Homepage = "https://quapp.cloud/"
+
+[tool.setuptools.packages.find]
+include = ["quapp_merlin*"]

quapp_merlin-0.0.1.dev1/quapp_merlin/__init__.py

@@ -0,0 +1,8 @@
+from .data.merlin_job_spec import MerlinJobSpec, TrainingSpec
+from .factory.merlin_handler_factory import MerlinHandlerFactory
+
+# Imported for the side effect: register_rules() has to run before the
+# first job fails, so this import cannot be made lazy.
+from . import error_rules as _error_rules  # noqa: E402,F401
+
+__all__ = ['MerlinJobSpec', 'TrainingSpec', 'MerlinHandlerFactory']

quapp_merlin-0.0.1.dev1/quapp_merlin/component/backend/merlin_invocation.py

@@ -0,0 +1,82 @@
+#  Quapp Platform Project
+#  merlin_invocation.py
+#  Copyright © CITYNOW Co. Ltd. All rights reserved.
+
+"""Wiring MerLin into the invocation pipeline.
+
+The pipeline carries whatever ``processing()`` returned without looking at it --
+except in one place, ``_get_qubit_amount``, which DeviceSelection uses to pick a
+machine. That is the only spot where a MerLin job has to explain itself, and the
+answer is a **mode count**, not a qubit count: see the note on the method.
+"""
+
+from quapp_common.component.backend.invocation import Invocation
+from quapp_common.data.request.invocation_request import InvocationRequest
+from quapp_common.model.provider.provider import Provider
+
+from ...factory.merlin_device_factory import MerlinDeviceFactory
+from ...factory.merlin_provider_factory import MerlinProviderFactory
+from ...util.single_machine import quantum_leaves
+
+
+class MerlinInvocation(Invocation):
+
+    def __init__(self, request_data: InvocationRequest):
+        super().__init__(request_data)
+
+    def _export_circuit(self, circuit):
+        # Only QISKIT and BRAKET export circuits (EXPORT_CIRCUIT_SDK in
+        # quapp-common). A MerLin job is a torch module, not a drawable circuit.
+        return None
+
+    def _create_provider(self):
+        self.logger.debug(
+                f'Creating provider: '
+                f'provider_tag={getattr(self.backend_information, "provider_tag", None)}')
+        provider = MerlinProviderFactory.create_provider(
+                provider_type=self.backend_information.provider_tag,
+                sdk=self.sdk,
+                authentication=self.backend_information.authentication)
+        self.logger.info(f'Provider created: {type(provider).__name__}')
+        return provider
+
+    def _create_device(self, provider: Provider):
+        device_specification = getattr(self.backend_information, 'device_name',
+                                       None)
+        self.logger.debug(f'Creating device: {device_specification}')
+        device = MerlinDeviceFactory.create_device(
+                provider=provider,
+                device_specification=device_specification,
+                authentication=self.backend_information.authentication,
+                sdk=self.sdk)
+        self.logger.info(f'Device created: {type(device).__name__}')
+        return device
+
+    def _get_qubit_amount(self, circuit):
+        """How many optical **modes** the job needs.
+
+        DeviceSelection asks for a qubit count because every other SDK is
+        gate-based. Photonic hardware is sized in modes, and MerLin's layers
+        carry a Perceval circuit whose ``m`` is exactly that. Reporting modes
+        here is the closest true answer; a device catalogue that stores qubits
+        for a Quandela machine has to be read the same way.
+
+        Returns 0 rather than raising when the model hides its circuit: failing
+        device selection over a metric nobody uses downstream would turn a
+        runnable job into a failed one.
+        """
+        for _, leaf in quantum_leaves(getattr(circuit, 'model', circuit)):
+            for attribute in ('m', 'n_modes', 'modes'):
+                modes = getattr(leaf, attribute, None)
+                if isinstance(modes, int) and modes > 0:
+                    return modes
+
+            inner = getattr(leaf, 'circuit', None)
+            modes = getattr(inner, 'm', None)
+            if isinstance(modes, int) and modes > 0:
+                return modes
+
+        self.logger.warning(
+                'Could not read a mode count from the model; reporting 0 to '
+                'device selection.')
+        return 0

quapp_merlin-0.0.1.dev1/quapp_merlin/data/merlin_job_spec.py

@@ -0,0 +1,93 @@
+#  Quapp Platform Project
+#  merlin_job_spec.py
+#  Copyright © CITYNOW Co. Ltd. All rights reserved.
+
+"""What a MerLin handler returns instead of a circuit.
+
+Every other SDK in the platform has ``processing()`` return a circuit, and the
+whole pipeline carries that object around opaquely. MerLin has no circuit to
+return: the unit of work is a ``torch.nn.Module`` (normally one holding an
+``merlin.QuantumLayer``) plus the input tensor to run it on.
+
+Returning a bare Module would not be enough -- the model alone says nothing about
+WHAT to run it on, and the device would have to guess which key of
+``invocation_input`` holds the data. A spec makes the contract explicit and lets
+the device reject a malformed job with a specific error code instead of a
+``TypeError`` deep inside torch.
+
+A bare Module is still accepted as shorthand; see ``coerce()``.
+"""
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class TrainingSpec:
+    """Local-only training.
+
+    MerLin's remote processor cannot backpropagate -- the documentation is
+    explicit: *"No gradient can flow through the MerLin processor."* So a spec
+    carrying ``training`` is refused on a remote device and only runs on the
+    local simulator.
+    """
+
+    targets: object
+    epochs: int = 10
+    learning_rate: float = 0.01
+    loss: str = 'mse'
+
+
+@dataclass
+class MerlinJobSpec:
+    """One MerLin job: one model, one input batch, one machine.
+
+    @param model: the torch Module to run. Must contain exactly one quantum
+                  layer -- see the single-machine rules in
+                  ``model/device/merlin_remote_device.py``.
+    @param inputs: the input batch, shape ``[batch, input_size]``. Anything
+                   ``torch.as_tensor`` accepts is fine (list, ndarray, tensor).
+    @param shots: sample count. ``None`` or ``0`` means exact probabilities --
+                  MerLin does not invent a default, and neither do we.
+    @param sampling_method: e.g. ``'multinomial'``; ``None`` leaves MerLin's
+                            default alone.
+    @param training: present only for local training runs.
+    @param metadata: free-form, copied into the job result for the handler's own
+                     post_processing().
+    """
+
+    model: object
+    inputs: object
+    shots: int = None
+    sampling_method: str = None
+    training: TrainingSpec = None
+    metadata: dict = field(default_factory=dict)
+
+
+SPEC_HELP = (
+    'processing() must return a MerlinJobSpec, or a torch.nn.Module when the '
+    'input batch is in invocation_input["inputs"].')
+
+
+def coerce(prepared, invocation_input: dict = None) -> MerlinJobSpec:
+    """Turn what ``processing()`` returned into a MerlinJobSpec.
+
+    A bare Module is accepted because the common case -- one layer, data already
+    in the request -- should not need the import. The data then has to be in
+    ``invocation_input["inputs"]``; anything else is rejected here rather than
+    surfacing later as a shape error inside torch.
+    """
+    if isinstance(prepared, MerlinJobSpec):
+        return prepared
+
+    if hasattr(prepared, 'forward') and callable(prepared):
+        inputs = (invocation_input or {}).get('inputs')
+        if inputs is None:
+            raise ValueError(
+                    'processing() returned a model but no input batch: put it '
+                    'in invocation_input["inputs"], or return a MerlinJobSpec '
+                    'with inputs=... instead.')
+        return MerlinJobSpec(model=prepared, inputs=inputs,
+                             shots=(invocation_input or {}).get('shots'))
+
+    raise ValueError(
+            f'processing() returned {type(prepared).__name__}. {SPEC_HELP}')