{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "7306415b",
   "metadata": {},
   "source": [
    "# Photonic QGAN with `PhotonicGenerator`\n",
    "\n",
    "This notebook demonstrates a compact Adam-trained photonic QGAN workflow using MerLin's `PhotonicGenerator`. It follows the structure of the photonic QGAN model at documentation scale: repeated quantum generator heads produce image patches, `ImageAdapter` assembles them into images, and a classical discriminator trains against Optdigits samples.\n",
    "\n",
    "The run below reproduces the results obtained in the [reproduction in MerLin](https://github.com/merlinquantum/reproduced_papers/tree/main/papers/photonic_QGAN) of the original [photonic QGAN paper](https://opg.optica.org/opticaq/fulltext.cfm?uri=opticaq-2-6-458) by Sedrakyan and Salavrakos."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1b546a24",
   "metadata": {},
   "source": [
    "## Introduction to Classical Generative Adversarial Networks (GAN)\n",
    "\n",
    "A Generative Adversarial Network (GAN) is a classical neural network that tries to create a generative model that generates new samples from a given distribution. \n",
    "\n",
    "The model is composed of two different submodules: a generator G and a discriminator D which are competing against one another in an adversarial zero-sum game. The generator wants to fool the discriminator with fake images and the discriminator wants to correctly identify fake images versus real images from the dataset. The generator receives random noise values as input and transforms them to fake images of the dataset. The model can be identified in the next figure where we can just consider the generator as a whole classical model without the quantum sub generators.\n",
    "\n",
    "![Photonic QGAN overview](../../_static/reproduced_papers/photonicQGAN.png)\n",
    "\n",
    "\n",
    "The GAN has a specific training routine. Here are the main steps.\n",
    "\n",
    "1. For a number of ``iterations``:\n",
    "    1. For a number of discriminator iterations ``d_steps``:\n",
    "        1. Train the discriminator parameters with the batches fake and real images. The labels of the real values are ``real_labels`` and the fake images' labels are ``fake_labels``. Here, after the hyper parameter optimization done in the reproduction, we will choose ``real_labels=0.9`` and ``fake_labels=0.0``.\n",
    "    2. For a number of generator iterations ``g_steps``:\n",
    "        1. Train the generator parameters with only its fake generated images that have been classified by the discriminator. The associated labels are ``generator_labels``. Here, after the hyper parameter optimization done in the reproduction, we will choose ``generator_labels=0.9``.\n",
    "\n",
    "The loss calculations for both steps are:\n",
    "1. For the discriminator training $$\\mathcal{L}_D=\\frac{1}{n}\\sum_{i=1}^n Loss(D(x_i),\\text{real labels})+\\frac{1}{n}\\sum_{i=1}^n Loss(D(G(z_i)),\\text{fake labels})$$ where $x_i$ is the real images of the batch and $z_i$ are the noises generated for the batch.\n",
    "2. For the generator training $$\\mathcal{L}_G=\\frac{1}{n}\\sum_{i=1}^n Loss(D(G(z_i)),\\text{generator labels})$$ where $z_i$ are the noises generated for the batch.\n",
    "\n",
    "For the photonic QGAN, the preferred loss is ``PyTorch``'s ``BCEWithLogitsLoss``. \n",
    "\n",
    "### The photonic QGAN\n",
    "\n",
    "The photonic implementation of the QGAN is similar. Just like it is illustrated in the picture, the generator will be composed of multiple photonic circuits that will be run together to generate brand new images. The concept and training of the GAN model stays the same."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "026a574f",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-06-03T12:07:31.666282Z",
     "iopub.status.busy": "2026-06-03T12:07:31.666282Z",
     "iopub.status.idle": "2026-06-03T12:07:40.713806Z",
     "shell.execute_reply": "2026-06-03T12:07:40.712800Z"
    }
   },
   "outputs": [],
   "source": [
    "from __future__ import annotations\n",
    "\n",
    "import copy\n",
    "import math\n",
    "import random\n",
    "\n",
    "import matplotlib.pyplot as plt\n",
    "import numpy as np\n",
    "import perceval as pcvl\n",
    "import torch\n",
    "from sklearn.datasets import load_digits\n",
    "from torch import nn\n",
    "\n",
    "import merlin as ML"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "813981d3",
   "metadata": {},
   "source": [
    "## Configuration\n",
    "\n",
    "We will use the same experiment setup as the setup d of the reproduction. We will also use all of the optimized hyperparameters identified in the study of the photonic QGAN's MerLin reproduction.\n",
    "\n",
    "The demo uses four patch heads, two latent features, an 8 by 8 digit target (UCI Optdigits 0th digit), and one discriminator update followed by three generator updates. So, the dataset chosen here is 8x8 images of hand-drawn zeros."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "483a9dbd",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-06-03T12:07:40.715806Z",
     "iopub.status.busy": "2026-06-03T12:07:40.715806Z",
     "iopub.status.idle": "2026-06-03T12:07:40.725183Z",
     "shell.execute_reply": "2026-06-03T12:07:40.724176Z"
    }
   },
   "outputs": [],
   "source": [
    "seed = 0\n",
    "digit = 0\n",
    "training_iterations = 1400\n",
    "batch_size = 4\n",
    "image_size = 8\n",
    "latent_dim = 2\n",
    "generator_heads = 4\n",
    "\n",
    "input_state = (0, 1, 0, 1, 0)\n",
    "\n",
    "lr_d = 0.0002\n",
    "lr_g = 0.004\n",
    "adam_betas = (0.5, 0.99)\n",
    "d_steps = 1\n",
    "g_steps = 3\n",
    "\n",
    "random.seed(seed)\n",
    "np.random.seed(seed)\n",
    "_ = torch.manual_seed(seed)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b75720bd",
   "metadata": {},
   "source": [
    "## Load Optdigits Samples\n",
    "\n",
    "The notebook uses `sklearn.datasets.load_digits`, so it can run without a separate data checkout. Pixel values are normalized to `[0, 1]`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "b55a0a8f",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-06-03T12:07:40.727182Z",
     "iopub.status.busy": "2026-06-03T12:07:40.727182Z",
     "iopub.status.idle": "2026-06-03T12:07:40.791611Z",
     "shell.execute_reply": "2026-06-03T12:07:40.790444Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "digit samples: 178\n",
      "training batches: 1400\n"
     ]
    }
   ],
   "source": [
    "digits = load_digits()\n",
    "mask = digits.target == digit\n",
    "real_images = torch.tensor(digits.images[mask], dtype=torch.float32).unsqueeze(1) / 16.0\n",
    "real_vectors = real_images.reshape(real_images.shape[0], -1)\n",
    "\n",
    "sample_generator = torch.Generator().manual_seed(seed + 17)\n",
    "batch_indices = torch.randint(\n",
    "    real_vectors.shape[0],\n",
    "    (training_iterations, batch_size),\n",
    "    generator=sample_generator,\n",
    ")\n",
    "real_batches = [real_vectors[indices] for indices in batch_indices]\n",
    "real_preview = real_images[batch_indices[0]]\n",
    "\n",
    "print(f\"digit samples: {real_vectors.shape[0]}\")\n",
    "print(f\"training batches: {len(real_batches)}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f4792bfa",
   "metadata": {},
   "source": [
    "## Build the MerLin Photonic Generator\n",
    "\n",
    "In order to get similar results as the one identified in the [photonic QGAN paper](https://opg.optica.org/opticaq/fulltext.cfm?uri=opticaq-2-6-458) and in the [photonic QGAN reproduction with MerLin](https://github.com/merlinquantum/reproduced_papers/tree/main/papers/photonic_QGAN), we will use the same circuit unitaries as presented in the paper. Below is the photonic circuit implementation.\n",
    "\n",
    "![Photonic QGAN unitaries](../../_static/reproduced_papers/fig3_pqgan.png)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "e6fbd2a2",
   "metadata": {},
   "outputs": [],
   "source": [
    "def var_circuit(n_modes: int, param_start_index: int = 0) -> pcvl.Circuit:\n",
    "    \"\"\"Create a trainable photonic circuit block for the generator.\n",
    "\n",
    "    Parameters\n",
    "    ----------\n",
    "    n_modes : int\n",
    "        Number of modes in the circuit.\n",
    "    param_start_index : int\n",
    "        Starting index for the trainable phase parameters.\n",
    "        Default is 0.\n",
    "\n",
    "    Returns\n",
    "    -------\n",
    "    pcvl.Circuit\n",
    "        A Perceval circuit containing phase shifters and beam\n",
    "        splitters with trainable parameters.\n",
    "    \"\"\"\n",
    "    trainable_params = [pcvl.Parameter(f\"phi{i+param_start_index}\") for i in range((2 * n_modes) - 1)]\n",
    "    circ = pcvl.Circuit(m=n_modes)\n",
    "    for i in range(n_modes):\n",
    "        circ.add([i], component=pcvl.PS(trainable_params[i]))\n",
    "    for i, j in enumerate(range(0, n_modes - 1, 2)):\n",
    "        circ.add([j, j + 1], component=pcvl.BS(trainable_params[i + n_modes]))\n",
    "    for i, j in enumerate(range(1, n_modes - 1, 2)):\n",
    "        circ.add([j, j + 1], component=pcvl.BS(trainable_params[i + n_modes + (n_modes // 2)]))\n",
    "\n",
    "    return circ\n",
    "\n",
    "\n",
    "def encoding_circuit(n_modes: int, mode_to_target: int, param_index: int = 0) -> pcvl.Circuit:\n",
    "    \"\"\"Create an encoding circuit that applies a phase to one mode.\n",
    "\n",
    "    Parameters\n",
    "    ----------\n",
    "    n_modes : int\n",
    "        Number of modes in the circuit.\n",
    "    mode_to_target : int\n",
    "        Mode index to apply the encoding phase shift.\n",
    "    param_index : int\n",
    "        Index for the encoding parameter.\n",
    "        Default is 0.\n",
    "\n",
    "    Returns\n",
    "    -------\n",
    "    pcvl.Circuit\n",
    "        A Perceval circuit containing a single trainable phase shift.\n",
    "    \"\"\"\n",
    "    encoding_param = pcvl.Parameter(f\"theta{param_index}\")\n",
    "    circ = pcvl.Circuit(m=n_modes)\n",
    "    circ.add([mode_to_target], component=pcvl.PS(encoding_param))\n",
    "\n",
    "    return circ"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b9476dea",
   "metadata": {},
   "source": [
    "We will then use those base bricks to create the subgenerator pattern d in the paper.\n",
    "\n",
    "![Photonic QGAN circuit](../../_static/reproduced_papers/fig4d_pqgan.png)\n",
    "\n",
    "We will create a ``QuantumLayer`` out of these Perceval circuits created earlier. \n",
    "\n",
    "In the original paper, the photonic generator can have or not photon-number-resolving detectors. Here, like on current Quandela hardware, we will suppose that the photon number cannot be resolved by the detectors."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "f626633f",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-06-03T12:07:40.793106Z",
     "iopub.status.busy": "2026-06-03T12:07:40.793106Z",
     "iopub.status.idle": "2026-06-03T12:07:41.018569Z",
     "shell.execute_reply": "2026-06-03T12:07:41.017564Z"
    }
   },
   "outputs": [],
   "source": [
    "def create_subgenerator(use_pnr_detectors:bool=False) -> ML.QuantumLayer:\n",
    "    #Define the complete Perceval Circuit\n",
    "    m=len(input_state)\n",
    "    circuit=pcvl.Circuit(m=m)\n",
    "    circuit.add(port_range=[i for i in range(m)],component=var_circuit(n_modes=m,param_start_index=0))\n",
    "    circuit.add(port_range=[i for i in range(m)],component=encoding_circuit(n_modes=m,mode_to_target=1,param_index=0))\n",
    "    circuit.add(port_range=[i for i in range(m)],component=var_circuit(n_modes=m,param_start_index=(2*m)-1))\n",
    "    circuit.add(port_range=[i for i in range(m)],component=encoding_circuit(n_modes=m,mode_to_target=3,param_index=1))\n",
    "    circuit.add(port_range=[i for i in range(m)],component=var_circuit(n_modes=m,param_start_index=(4*m)-2))\n",
    "\n",
    "    #Define the Perceval experiment\n",
    "    exp=pcvl.Experiment(circuit)\n",
    "    \n",
    "    #If the user does not want PNR detectors, remove them.\n",
    "    if not use_pnr_detectors:\n",
    "        for i in range(m):\n",
    "            exp.detectors[i]=pcvl.Detector.threshold()\n",
    "\n",
    "    #Create the corresponding QuantumLayer\n",
    "    return ML.QuantumLayer(\n",
    "        input_size=latent_dim,\n",
    "        experiment=exp,\n",
    "        input_state=input_state,\n",
    "        trainable_parameters=[\"phi\"],\n",
    "        input_parameters=[\"theta\"],\n",
    "        measurement_strategy=ML.MeasurementStrategy.probs(\n",
    "            computation_space=ML.ComputationSpace.FOCK,\n",
    "            occupancy_readout=True,\n",
    "        ),\n",
    "    )"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d20440b4",
   "metadata": {},
   "source": [
    "Let's now define the ``PhotonicGenerator`` with this ``QuantumLayer``.\n",
    "\n",
    "We will use `count=4` that creates four independent heads with the same circuit structure. Each head returns Fock-space probabilities with binary occupancy readout, then the image adapter maps each head to one patch of the generated image. \n",
    "\n",
    "This is the same idea as presented in the paper to use multiple photonic circuits as patches to create one image."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "f9155572",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "heads: 4\n",
      "trainable parameters: 108\n",
      "per-head output widths: [15, 15, 15, 15]\n",
      "image batch shape: (4, 1, 8, 8)\n"
     ]
    }
   ],
   "source": [
    "generator = ML.PhotonicGenerator(\n",
    "    layers=create_subgenerator(use_pnr_detectors=False),\n",
    "    count=generator_heads,\n",
    "    output_adapter=ML.ImageAdapter(\n",
    "        shape=(1, image_size, image_size),\n",
    "        headwise=True,\n",
    "        normalize_patches=True,\n",
    "    ),\n",
    ")\n",
    "\n",
    "fixed_noise = torch.normal(0.0, 2 * math.pi, (batch_size, latent_dim))\n",
    "with torch.no_grad():\n",
    "    generated_before = generator(fixed_noise).detach()\n",
    "\n",
    "measurements = generator.measure(fixed_noise)\n",
    "print(f\"heads: {len(generator)}\")\n",
    "print(f\"trainable parameters: {sum(p.numel() for p in generator.parameters())}\")\n",
    "print(f\"per-head output widths: {[output.shape[1] for output in measurements.outputs]}\")\n",
    "print(f\"image batch shape: {tuple(generated_before.shape)}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "348d984a",
   "metadata": {},
   "source": [
    "## Defining the Classical Discriminator\n",
    "\n",
    "The classical discriminator is just a regular ``pytorch`` module. We will use the same one as in the paper reproduction."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "060fe612",
   "metadata": {},
   "outputs": [],
   "source": [
    "discriminator = nn.Sequential(\n",
    "    nn.Linear(image_size * image_size, 32),\n",
    "    nn.LeakyReLU(0.2),\n",
    "    nn.Linear(32, 16),\n",
    "    nn.LeakyReLU(0.2),\n",
    "    nn.Linear(16, 1),\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7a4345c4",
   "metadata": {},
   "source": [
    "## Train with Adam\n",
    "\n",
    "In order to train the Photonic QGAN, we need to follow the specific training structure of the classical GAN. We will use the ADAM optimizer as it is the most fitted for MerLin use even though the original paper used SPSA. A study on the optimization of ADAM's parameter is also available in the MerLin reproduction. It will be presented later. First, we need to define the performance metrics."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fcf0e509",
   "metadata": {},
   "source": [
    "### Defining the Metrics\n",
    "\n",
    "We will use different metrics to analyze the training and performance of the photonic QGAN. We will define a batch similarity which determines how close the fake generated images of the current batch are close to the real images. This metric is basically the average of the structural similarity (ssim) over the full image (not exactly like ``skimage.metrics.structural_similarity``) between all pairs of fake and real images on the batch."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "76e6b84e",
   "metadata": {},
   "outputs": [],
   "source": [
    "def global_ssim(x: np.ndarray, y: np.ndarray) -> float:\n",
    "    c1 = 0.01**2\n",
    "    c2 = 0.03**2\n",
    "    x = x.astype(np.float64, copy=False)\n",
    "    y = y.astype(np.float64, copy=False)\n",
    "    mu_x = float(x.mean())\n",
    "    mu_y = float(y.mean())\n",
    "    var_x = float(((x - mu_x) ** 2).mean())\n",
    "    var_y = float(((y - mu_y) ** 2).mean())\n",
    "    cov_xy = float(((x - mu_x) * (y - mu_y)).mean())\n",
    "    numerator = (2 * mu_x * mu_y + c1) * (2 * cov_xy + c2)\n",
    "    denominator = (mu_x**2 + mu_y**2 + c1) * (var_x + var_y + c2)\n",
    "    return numerator / denominator\n",
    "\n",
    "\n",
    "def batch_similarity(real: torch.Tensor, fake: torch.Tensor) -> float:\n",
    "    real_batch = real.detach().cpu().numpy().reshape(batch_size, image_size, image_size)\n",
    "    fake_batch = fake.detach().cpu().numpy().reshape(batch_size, image_size, image_size)\n",
    "    total = 0.0\n",
    "    for real_image in real_batch:\n",
    "        for fake_image in fake_batch:\n",
    "            total += global_ssim(\n",
    "                np.clip(real_image, 0.0, 1.0),\n",
    "                np.clip(fake_image, 0.0, 1.0),\n",
    "            )\n",
    "    return total / (batch_size * batch_size)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c82e0433",
   "metadata": {},
   "source": [
    "### Training the Photonic QGAN\n",
    "\n",
    "We will use the same training steps as the classical GAN to train our photonic QGAN. Since the generator and discriminator are ordinary PyTorch modules. `loss.backward()` populates gradients for the MerLin quantum layers, and the user-selected Adam optimizers own the parameter updates."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "ec7120bd",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-06-03T12:07:41.020569Z",
     "iopub.status.busy": "2026-06-03T12:07:41.020569Z",
     "iopub.status.idle": "2026-06-03T12:08:20.140524Z",
     "shell.execute_reply": "2026-06-03T12:08:20.139518Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "training iterations: 1400\n",
      "best iteration: 500\n",
      "best batch similarity: 0.712\n",
      "generator gradients populated: True\n"
     ]
    }
   ],
   "source": [
    "#Optimization objects\n",
    "criterion = nn.BCEWithLogitsLoss()\n",
    "optimizer_d = torch.optim.Adam(discriminator.parameters(), lr=lr_d, betas=adam_betas)\n",
    "optimizer_g = torch.optim.Adam(generator.parameters(), lr=lr_g, betas=adam_betas)\n",
    "\n",
    "#Generator's noise sampler\n",
    "noise_generator = torch.Generator().manual_seed(seed + 31)\n",
    "\n",
    "# Training results\n",
    "d_losses: list[float] = []\n",
    "g_losses: list[float] = []\n",
    "similarity_scores: list[float] = []\n",
    "best_similarity = float(\"-inf\")\n",
    "best_state = copy.deepcopy(generator.state_dict())\n",
    "best_iteration = 0\n",
    "\n",
    "#Labels used for the training\n",
    "real_labels = torch.full((batch_size,), 0.9)\n",
    "fake_labels = torch.zeros(batch_size)\n",
    "generator_labels = torch.full((batch_size,), 0.9)\n",
    "\n",
    "\n",
    "for iteration, real_data in enumerate(real_batches, start=1):\n",
    "    \n",
    "    # Discriminator training\n",
    "    d_step_losses = []\n",
    "    for _ in range(d_steps):\n",
    "        noise_d = torch.normal(\n",
    "            0.0,\n",
    "            2 * math.pi,\n",
    "            (batch_size, latent_dim),\n",
    "            generator=noise_generator,\n",
    "        )\n",
    "        fake_for_d = generator(noise_d).reshape(batch_size, -1).detach()\n",
    "\n",
    "        optimizer_d.zero_grad()\n",
    "        d_loss = criterion(discriminator(real_data).view(-1), real_labels)\n",
    "        d_loss = d_loss + criterion(discriminator(fake_for_d).view(-1), fake_labels)\n",
    "        d_loss.backward()\n",
    "        optimizer_d.step()\n",
    "        d_step_losses.append(float(d_loss.detach()))\n",
    "\n",
    "\n",
    "    # Freezing the discriminator for the generator training\n",
    "    for parameter in discriminator.parameters():\n",
    "        parameter.requires_grad_(False)\n",
    "    \n",
    "    # Generator training\n",
    "    g_step_losses = []\n",
    "    fake_for_metrics = None\n",
    "    for _ in range(g_steps):\n",
    "        noise_g = torch.normal(\n",
    "            0.0,\n",
    "            2 * math.pi,\n",
    "            (batch_size, latent_dim),\n",
    "            generator=noise_generator,\n",
    "        )\n",
    "        optimizer_g.zero_grad()\n",
    "        fake_for_g = generator(noise_g).reshape(batch_size, -1)\n",
    "        g_loss = criterion(discriminator(fake_for_g).view(-1), generator_labels)\n",
    "        g_loss.backward()\n",
    "        optimizer_g.step()\n",
    "        g_step_losses.append(float(g_loss.detach()))\n",
    "        fake_for_metrics = fake_for_g\n",
    "\n",
    "\n",
    "    # Defreezing the discriminator for the discriminator training\n",
    "    for parameter in discriminator.parameters():\n",
    "        parameter.requires_grad_(True)\n",
    "\n",
    "    if fake_for_metrics is None:\n",
    "        raise RuntimeError(\"Generator update did not produce samples.\")\n",
    "    \n",
    "\n",
    "    # Get the performance of the iteration\n",
    "    similarity = batch_similarity(real_data, fake_for_metrics)\n",
    "    if similarity > best_similarity:\n",
    "        best_similarity = similarity\n",
    "        best_iteration = iteration\n",
    "        best_state = copy.deepcopy(generator.state_dict())\n",
    "\n",
    "    d_losses.append(float(np.mean(d_step_losses)))\n",
    "    g_losses.append(float(np.mean(g_step_losses)))\n",
    "    similarity_scores.append(similarity)\n",
    "\n",
    "#Checking the gradient\n",
    "has_generator_gradient = any(\n",
    "    parameter.grad is not None and parameter.grad.abs().sum() > 0\n",
    "    for parameter in generator.parameters()\n",
    ")\n",
    "\n",
    "# Best result of the training\n",
    "generator.load_state_dict(best_state)\n",
    "with torch.no_grad():\n",
    "    generated_best = generator(fixed_noise).detach()\n",
    "\n",
    "print(f\"training iterations: {training_iterations}\")\n",
    "print(f\"best iteration: {best_iteration}\")\n",
    "print(f\"best batch similarity: {best_similarity:.3f}\")\n",
    "print(f\"generator gradients populated: {has_generator_gradient}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "df6dc85c",
   "metadata": {},
   "source": [
    "## Results\n",
    "\n",
    "The first row shows real digit-0 samples. The second row shows the generated digits before training. The third row shows the best checkpoint selected during the Adam run.\n",
    "\n",
    "We then plot the losses and batch similarity scores per epoch."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "4c757a07",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-06-03T12:08:20.144524Z",
     "iopub.status.busy": "2026-06-03T12:08:20.144524Z",
     "iopub.status.idle": "2026-06-03T12:08:20.644340Z",
     "shell.execute_reply": "2026-06-03T12:08:20.643309Z"
    }
   },
   "outputs": [
    {
     "data": {
      "image/png": "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7rrrStQvf/nL0K7Nj3vOGxoaCu1OnToV2u3fv79ErVixIrQ7ffp0aLd169bQ7vDhwyXqySef7OrzeMHnPve50G7VqlWh3VNPPVWi+vr6Qrt33nkntLvmmmtCuxtuuKFE/eAHP+jqMxl9z1evXh3ajY6OlqgPfOADod2ZM2dCuy984Quh3ec///kS9dOf/vSinUdP5AAAkhJyAABJCTkAgKSEHABAUkIOACApIQcAkJSQAwBISsgBACQl5AAAkhJyAABJCTkAgKSEHABAUkIOACCpRlVVVTsvvPzyy0MX2Lx5c2h37ty5EvXwww+Hdvfff39od+zYsdDu97//fYlatGhRaHf69OnSCXp6ekK76667LrT7xz/+UaKuvfba0O5rX/taaHfnnXeGdo1Go0T19vbW/u98rpk3L/b/4qVLl4Z2b7/9dolasmRJaPejH/0otBsZGan9TEa309PTpRNE//59fX2h3cmTJ0vd5/FPf/pTaHfTTTfVfh6j94epqan3/rNDfzIAALNOyAEAJCXkAACSEnIAAEkJOQCApIQcAEBSQg4AICkhBwCQlJADAEhKyAEAJCXkAACSEnIAAEkJOQCApIQcAEBSjaqqqnZeuGLFitAFjh8/Xuq2bt260K63tze0azabod3BgwdLVJsf2/u2m2uWLl0a2p06darU7WMf+1hod+mll4Z2hw4dSvPedMp5nMn9Y2pqqvb37sMf/nCtuwMHDpQsOuVMzp8/P7SbnJwsWe6Ry5cvr/V372ycjXau6YkcAEBSQg4AICkhBwCQlJADAEhKyAEAJCXkAACSEnIAAEkJOQCApIQcAEBSQg4AICkhBwCQlJADAEhKyAEAJNWoqqqa7R8CAID/nydyAABJCTkAgKSEHABAUkIOACApIQcAkJSQAwBISsgBACQl5AAAkhJyAABJCTkAgKSEHABAUkIOACApIQcAkJSQAwBIqtnuCxuNRsni4YcfDu327NkT2i1cuDC0+/vf/17qVlVV6QTO47tzHmeHM/nunMn6OY/dcx49kQMASErIAQAkJeQAAJIScgAASQk5AICkhBwAQFJCDgAgKSEHAJCUkAMASErIAQAkJeQAAJIScgAASTWqNr9FPfoFvNHdQw89VKJuuumm0O6Tn/xkrV9EH/3i3gvOnTtX688612Q6j7fccktod9VVV5U6LViwILzt9vN4gTP5/pvJPfLs2bNdfSadx+45j57IAQAkJeQAAJIScgAASQk5AICkhBwAQFJCDgAgKSEHAJCUkAMASErIAQAkJeQAAJIScgAASQk5AICkhBwAQFKNqqqqdl64Zs2a0AW++c1vhnbNZrNE/eUvfwnt7r333tDuzjvvDO2++MUvlqhXXnkltGvz457zLrvsstDuO9/5TqnbU089Fdp9//vfr/Xv6DzOzpn89re/Xer29NNP13qPvOuuu0I7ZzLOeeye8+iJHABAUkIOACApIQcAkJSQAwBISsgBACQl5AAAkhJyAABJCTkAgKSEHABAUkIOACApIQcAkJSQAwBISsgBACQl5AAAkmq2+8KjR4+GLrB69erQ7p577ilRv/jFL0K74eHh0O6f//xnaPfyyy+XqEajUbpZq9UK7VauXBnabdu2rUT96le/Cu22bNkS2h0+fDi0e/7550vU/PnzS7eLnsmPfOQjod3WrVtL1COPPBLa3X333bXeI1966aUSNW9edz+nqPs8zuR3dt3n8V//+ldHncfuPukAAIkJOQCApIQcAEBSQg4AICkhBwCQlJADAEhKyAEAJCXkAACSEnIAAEkJOQCApIQcAEBSQg4AICkhBwCQVKOqqqqtFzYaoQv09/eHdidPnixRCxYsCO0mJydDu6985Suh3W9+85sSdfnll4d2U1NTpRM4j+//eXzkkUfCn8cVV1wR2p0/f750Cmfy3TmT9XMeu+c8eiIHAJCUkAMASErIAQAkJeQAAJIScgAASQk5AICkhBwAQFJCDgAgKSEHAJCUkAMASErIAQAkJeQAAJIScgAASTXbfWFvb2/oAg899FBo9+yzz5aoV155JbTbsGFDaPfMM8+EduvXry9R09PTpZvVfR6fe+650unn8TOf+UyJmpqaKt3OmXx3zmSe87h9+/ba75F79+4N7dwj/8sTOQCApIQcAEBSQg4AICkhBwCQlJADAEhKyAEAJCXkAACSEnIAAEkJOQCApIQcAEBSQg4AICkhBwCQlJADAEiqUVVV1c4Lly1bVuq0dOnS8ParX/1qaDc8PBzatfkW/o+hoaFSt+jPOtdcc801tf79o9e74Iorrqj1Z43u7rvvvlK3TjmPF9x+++2h3fT0dK3Xu2DFihWh3WOPPVbr57x79+5St045k3Wfx1tvvbVELV++PLR74oknav2Md+3aVerWzs/qiRwAQFJCDgAgKSEHAJCUkAMASErIAQAkJeQAAJIScgAASQk5AICkhBwAQFJCDgAgKSEHAJCUkAMASErIAQAkJeQAAJJqVFVVtfXCRqPUaeXKleHtW2+9Vep02WWXhXb//ve/3/ef5b20+XHPeXWfx1WrVoW3R44cCe2mp6dDuwceeCC0+/GPf1zq1inncTbO5OrVq8Pb6L0neiYPHjwY2n36058udeuUM1n3efzoRz8a3h4+fLjW8/i3v/0ttFu/fn2Zi+fREzkAgKSEHABAUkIOACApIQcAkJSQAwBISsgBACQl5AAAkhJyAABJCTkAgKSEHABAUkIOACApIQcAkJSQAwBIqlFVVTXbPwQAAP8/T+QAAJIScgAASQk5AICkhBwAQFJCDgAgKSEHAJCUkAMASErIAQAkJeQAAEpO/wHQ9jlT79sYRAAAAABJRU5ErkJggg==",
      "text/plain": [
       "<Figure size 700x400 with 12 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "image/png": "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",
      "text/plain": [
       "<Figure size 900x300 with 2 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "def show_grid(images: torch.Tensor, title: str, axes: np.ndarray) -> None:\n",
    "    flat_axes = axes.reshape(-1)\n",
    "    for axis, image in zip(flat_axes, images, strict=False):\n",
    "        axis.imshow(image.squeeze().cpu(), cmap=\"gray\", vmin=0.0, vmax=1.0)\n",
    "        axis.axis(\"off\")\n",
    "    for axis in flat_axes[len(images):]:\n",
    "        axis.axis(\"off\")\n",
    "    axes[0].set_ylabel(title, rotation=0, labelpad=35, va=\"center\")\n",
    "\n",
    "\n",
    "fig, axes = plt.subplots(3, batch_size, figsize=(7, 4))\n",
    "show_grid(real_preview, \"real\", axes[0])\n",
    "show_grid(generated_before, \"before\", axes[1])\n",
    "show_grid(generated_best, \"best\", axes[2])\n",
    "fig.tight_layout()\n",
    "plt.show()\n",
    "\n",
    "fig, axes = plt.subplots(1, 2, figsize=(9, 3))\n",
    "axes[0].plot(d_losses, label=\"D loss\")\n",
    "axes[0].plot(g_losses, label=\"G loss\")\n",
    "axes[0].set_xlabel(\"training iteration\")\n",
    "axes[0].set_ylabel(\"BCE loss\")\n",
    "axes[0].legend()\n",
    "\n",
    "axes[1].plot(similarity_scores)\n",
    "axes[1].axvline(best_iteration - 1, color=\"black\", linestyle=\"--\", linewidth=1)\n",
    "axes[1].set_xlabel(\"training iteration\")\n",
    "axes[1].set_ylabel(\"batch similarity\")\n",
    "fig.tight_layout()\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6ee32e98",
   "metadata": {},
   "source": [
    "We observe the expected tendencies of the losses identified in the original paper. The generator loss increases as the discriminator ones decreases. Here, the best iteration is the 500th but the batch selection is chosen form 4 images: that means that this selection is dominated by batch noise. A more revealing metric would be to average it over multiple batches or iterations. The metric is a noisy per-batch proxy which is just to identify some good results."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9037c9f2",
   "metadata": {},
   "source": [
    "## What this demonstrates\n",
    "\n",
    "This notebook exercises the public MerLin path needed by the photonic QGAN model: repeated independent generator heads via `PhotonicGenerator(..., count=...)`, Fock-space occupancy readout, headwise image adaptation, a classical discriminator, and standard PyTorch Adam updates. The example is intentionally small; paper-scale experiments should use longer runs and checkpoint selection."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "MerLin_dev",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.12.12"
  },
  "nbsphinx": {
   "execute": "never"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}