PML-282 Photonic Generator by ben9871 · Pull Request #220 · merlinquantum/merlin

ben9871 · 2026-05-21T15:03:43Z

PML-282 Add QuantumLayer-backed PhotonicGenerator

Summary

This PR adds a PhotonicGenerator model that composes one or more existing QuantumLayer objects into a latent-to-sample generator. It keeps quantum execution inside QuantumLayer, exposes raw per-layer measurements for inspection, and uses output adapters to map measurements to vectors or images.

Related Issue

Related Jira: PML-282

Type of change

Proposed changes

Add merlin.models.PhotonicGenerator.
Add GeneratorMeasurements to carry raw per-layer outputs and output-key metadata.
Add latent distribution helpers:
- LatentDistribution
- NormalLatent
Add output adapter API:
- OutputAdapter
- VectorAdapter
- ImageAdapter
Export the new public objects from merlin.models and top-level merlin.
Add tests covering construction, validation, latent sampling, generation, adapter behaviour, parameter registration, and gradient flow.
Add the new API page under docs/source/api_reference/api/merlin.models.photonic_generator.rst.

API shape:

generator = ml.PhotonicGenerator(
    layers=[layer_0, layer_1],
    output_adapter=ml.ImageAdapter(shape=(1, 8, 8)),
)

z = generator.sample_latent(batch_size=16)
samples = generator(z)
measurements = generator.measure(z)
first_layer = generator[0]

How to test / How to run

Run pre-commit on the touched Python files:

python -m pre_commit run --files merlin/models/photonic_generator.py merlin/models/__init__.py merlin/__init__.py tests/models/test_photonic_generator.py

Run the focused test file:

python -m pytest tests/models/test_photonic_generator.py -q

Run the strict docs build:

python -m sphinx -b html -W --keep-going -n docs/source docs/build/html

Observed locally:

ruff (legacy alias)......................................................Passed
ruff format..............................................................Passed
mypy.....................................................................Passed

16 passed

build succeeded.

Screenshots / Logs (optional)

N/A.

Performance considerations (optional)

The generator evaluates its underlying QuantumLayer heads sequentially and then adapts the collected outputs. Runtime is therefore approximately the sum of the runtimes of the configured quantum layers. No cross-layer batching or caching is introduced in this PR.

This is intentional for the first version because different generator heads may use different circuits, input states, output spaces, measurement strategies, and noise models.

Documentation

User docs updated (Sphinx)
Examples / notebooks updated
Docstrings updated
Updated the API

Checklist

PR title includes Jira issue key (e.g., PML-126)
"Related Jira ticket" section includes the Jira issue key (no URL)
Code formatted (ruff format)
Lint passes (ruff)
Static typing passes (mypy) if applicable
Unit tests added/updated (pytest)
Tests pass locally (pytest)
Tests pass on GPU (pytest)
Test coverage not decreased significantly
Docs build locally if affected (sphinx)
With this command:
```
  > SPHINXOPTS="-W --keep-going -n" make -C docs clean html
```
the docs are built without any warning or errors.
New public classes/methods/packages are added in the API following the methodology presented in other files.
Dependencies updated (if needed) and pinned appropriately
PR description explains what changed and how to validate it

LF-Vigneux

The form and structure of the code seems fine to me. This is not a complete review pending the remaining functions to implement.

CassNot

There are some discrepancy with the orignal code

(orignal perceval) https://github.com/Quandela/photonic-qgan
(new MerLin) https://github.com/merlinquantum/reproduced_papers/tree/main/papers/photonic_QGAN
I am describing these discrepancies in review comments

More of a product question: What happens if the subgenerators are all the same ? Do we need to create multiple times the same one or should there be a shortcut to have to only define it once, then through the API, we precise the circuit/layer structure and N ones would be initiated ? (as in the original one)

Lack of validation: to validate this implementation, I would test it in the same settings as the original work (implementation here https://github.com/merlinquantum/reproduced_papers/tree/main/papers/photonic_QGAN) in a dedicated notebook

CassNot · 2026-05-25T12:42:56Z

+        raise NotImplementedError
+
+
+class VectorAdapter(OutputAdapter):


Both classes VectorAdapter and ImageAdapter do not preserve the original QGAN mapping
Here: they flatten the outputs and crop/pad them directly, ignoring the output_keys
In the original work: the orignal PatchGenerator regroups Fock states through output_map and sums collision with index_add_ (filters lossy/non-PNR states + renormalizes) then maps to pixels -> see method dist_to_image in https://github.com/merlinquantum/reproduced_papers/blob/main/papers/photonic_QGAN/lib/generators.py

Therefore, in this implementation, the mapping depends on the MerLin's combinadics and not the paper mapping (for which the code is the same in the reproduced_papers repo as in the original work, in utils/mappings.py)

will be changed in next commit

CassNot · 2026-05-25T12:51:39Z

+    return flattened
+
+
+def _center_crop_or_pad(x: torch.Tensor, size: int) -> torch.Tensor:


Here, you apply cropping and padding after concatenating all heads
But the orignal work applied it per batch before concatenation (line 173 in https://github.com/merlinquantum/reproduced_papers/blob/main/papers/photonic_QGAN/lib/generators.py)

CassNot · 2026-05-25T12:53:33Z

+        If ``std`` is not positive.
+    """
+
+    def __init__(self, dim: int, mean: float = 0.0, std: float = 1.0) -> None:


Default latent sampling does not match the reproduction training loop (line 142 https://github.com/merlinquantum/reproduced_papers/blob/main/papers/photonic_QGAN/lib/qgan.py)
PhotonicGenerator.generate() defaults to NormalLatent(..., std=1.0), while the original QGAN samples latent inputs with std 2 * pi

CassNot · 2026-05-25T12:54:02Z

A regression test should also compare a fixed set of output_keys and synthetic probability tensors against the original regroup/crop/normalize behavior

correct, will do in next commit

CassNot · 2026-05-25T13:01:44Z

@codex review with respect to original implementation https://github.com/merlinquantum/reproduced_papers/tree/main/papers/photonic_QGAN

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9c529552be

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-05-25T13:06:25Z

+        flattened = _flatten_tensor_outputs(measurements.outputs)
+        combined = torch.cat(flattened, dim=1)
+        return _center_crop_or_pad(combined, self.size)


Reintroduce output-key remapping before image/vector adaptation

The new adapters flatten and crop raw tensor columns directly, but the original photonic_QGAN PatchGenerator path explicitly remaps probabilities with output_map (index_add_) before resizing each patch. In non-PNR/lossy settings, multiple Fock keys must be merged (and some keys filtered) to represent the same classical bin; skipping that remap changes the generated sample distribution rather than just reshaping it, so outputs are no longer faithful to the original implementation behavior.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-05-25T13:06:25Z

+        if latent is None:
+            latent = NormalLatent(inferred_dim)


Match default latent scale used by original photonic QGAN

When latent=None, the generator defaults to NormalLatent(..., std=1.0), but the original photonic_QGAN training code samples generator noise with torch.normal(0, 2 * torch.pi, ...). Any workflow using sample_latent()/generate() with defaults will therefore feed a much narrower latent distribution than the reference implementation, which can materially change training dynamics and reproduction results.

Useful? React with 👍 / 👎.

correct, will be changed soon

CassNot

We still miss:

a demo notebook illustrating that this model works as in https://github.com/merlinquantum/reproduced_papers/tree/main/papers/photonic_QGAN with Adam optimizer
maybe you could add the original image from the paper in the documentation to illustrate how the model works (it is quite clear with it)

CassNot · 2026-05-29T20:40:40Z

This grouping strategy requires the keys and therefore breaks the nn.Sequential pipeline we can have with the other ones
Maybe you can move it to models/photonic_generator.py for now as we know it works for the GAN but we have not tested it on other models
This way, we can use it externally but it does not surprise users if it breaks nn.Sequential pipeline

Copilot

Pull request overview

This PR introduces a new PhotonicGenerator model under merlin.models that composes one or more QuantumLayer heads into a latent-to-sample generator, and adds an OccupancyGrouping policy used by photonic QGAN-style image pipelines. It also wires up the necessary plumbing in QuantumLayer to bind key-aware groupings to layer output keys.

Changes:

Add PhotonicGenerator, GeneratorMeasurements, LatentDistribution/NormalLatent, and OutputAdapter/VectorAdapter/ImageAdapter in a new merlin/models/photonic_generator.py.
Add OccupancyGrouping in merlin/utils/grouping.py plus _bind_grouping_to_output_keys, and integrate output-key binding into QuantumLayer so probability groupings can refine output_keys/output_size.
Export new public APIs from merlin and merlin.models, and add Sphinx pages for the new grouping and generator modules.

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
merlin/models/photonic_generator.py	New generator model, latent/output-adapter abstractions, and concrete vector/image adapters.
merlin/utils/grouping.py	New `OccupancyGrouping` plus shared key-binding helper.
merlin/utils/init.py	Exports `OccupancyGrouping`.
merlin/measurement/strategies.py	Accepts `OccupancyGrouping` in probability/partial strategies.
merlin/algorithms/layer.py	Binds key-aware groupings and uses the bound grouping in `forward`/`output_keys`.
merlin/models/init.py	Re-exports new generator-related symbols.
merlin/init.py	Top-level exports for new public API.
tests/models/test_photonic_generator.py	New comprehensive test suite for the generator pipeline.
tests/utils/test_grouping.py	Adds `OccupancyGrouping` test class covering binding, filtering, collapsing, gradients, dtype.
tests/measurement/test_measurement_strategy.py	Adds an integration test verifying `OccupancyGrouping` binds to layer output keys.
docs/source/api_reference/api/merlin.utils.grouping.rst	Adds `OccupancyGrouping` autoclass entry.
docs/source/api_reference/api/merlin.models.rst	Adds toctree entry for the new generator page.
docs/source/api_reference/api/merlin.models.photonic_generator.rst	New API reference page for the generator and adapters.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

ben9871 added 5 commits May 21, 2026 15:54

Add PhotonicGenerator model primitives

fba1a83

Add PhotonicGenerator tests

ae572ba

Document PhotonicGenerator API

9da1fc0

Apply pre-commit formatting to PhotonicGenerator

c9fb871

Fix PhotonicGenerator mypy casts

9c52955

LF-Vigneux requested changes May 22, 2026

View reviewed changes

Comment thread merlin/models/photonic_generator.py

Comment thread merlin/models/photonic_generator.py

Clarify PhotonicGenerator extension interfaces

1cc869b

CassNot requested changes May 25, 2026

View reviewed changes

chatgpt-codex-connector Bot reviewed May 25, 2026

View reviewed changes

ben9871 added 2 commits May 25, 2026 17:37

Add occupancy grouping for photonic generator

9436652

Match photonic QGAN occupancy collapse

684752d

CassNot added this to the v0.4 milestone May 28, 2026

CassNot added the new feature label May 28, 2026

CassNot requested changes May 29, 2026

View reviewed changes

CassNot requested a review from Copilot May 29, 2026 20:44

Copilot started reviewing on behalf of CassNot May 29, 2026 20:44 View session

Copilot AI reviewed May 29, 2026

View reviewed changes

		raise NotImplementedError


		class VectorAdapter(OutputAdapter):

		return flattened


		def _center_crop_or_pad(x: torch.Tensor, size: int) -> torch.Tensor:

Conversation

ben9871 commented May 21, 2026

PML-282 Add QuantumLayer-backed PhotonicGenerator

Summary

Related Issue

Type of change

Proposed changes

How to test / How to run

Screenshots / Logs (optional)

Performance considerations (optional)

Documentation

Checklist

Uh oh!

LF-Vigneux left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

CassNot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

CassNot commented May 25, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot May 25, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot May 25, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

CassNot left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants