{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "2f585ef9",
   "metadata": {},
   "source": [
    "# First Quantum Layers: Classifying Iris with MerLin\n",
    "\n",
    "This notebook walks through three complementary ways to instantiate `QuantumLayer` objects and trains each on the classic Iris classification task."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "134fcc8e",
   "metadata": {},
   "source": [
    "We will reuse a common data pipeline and optimisation loop while switching between the following APIs:\n",
    "\n",
    "1. `QuantumLayer.simple` quickstart factory.\n",
    "2. Declarative `CircuitBuilder` pipeline.\n",
    "3. A fully manual `perceval.Circuit`.\n",
    "\n",
    "You can run the cells top-to-bottom to reproduce the reported metrics !"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "a5016e4d",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-11-10T09:13:09.887064600Z",
     "start_time": "2025-11-10T09:13:09.840373500Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Train size: 112 samples\n",
      "Test size: 38 samples\n"
     ]
    }
   ],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "import numpy as np\n",
    "import perceval as pcvl\n",
    "import torch\n",
    "import torch.nn as nn\n",
    "import torch.nn.functional as F\n",
    "from sklearn.datasets import load_iris\n",
    "from sklearn.model_selection import train_test_split\n",
    "\n",
    "from merlin import LexGrouping, QuantumLayer\n",
    "from merlin.builder import CircuitBuilder\n",
    "\n",
    "torch.manual_seed(0)\n",
    "np.random.seed(0)\n",
    "\n",
    "iris = load_iris()\n",
    "X = iris.data.astype(\"float32\")\n",
    "y = iris.target.astype(\"int64\")\n",
    "\n",
    "X_train, X_test, y_train, y_test = train_test_split(\n",
    "    X,\n",
    "    y,\n",
    "    test_size=0.25,\n",
    "    stratify=y,\n",
    "    random_state=42,\n",
    ")\n",
    "\n",
    "X_train = torch.tensor(X_train, dtype=torch.float32)\n",
    "X_test = torch.tensor(X_test, dtype=torch.float32)\n",
    "y_train = torch.tensor(y_train, dtype=torch.long)\n",
    "y_test = torch.tensor(y_test, dtype=torch.long)\n",
    "\n",
    "mean = X_train.mean(dim=0, keepdim=True)\n",
    "std = X_train.std(dim=0, keepdim=True).clamp_min(1e-6)\n",
    "X_train = (X_train - mean) / std\n",
    "X_test = (X_test - mean) / std\n",
    "\n",
    "print(f\"Train size: {X_train.shape[0]} samples\")\n",
    "print(f\"Test size: {X_test.shape[0]} samples\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "ea1972d2",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-11-10T09:13:09.887064600Z",
     "start_time": "2025-11-10T09:13:09.864622100Z"
    }
   },
   "outputs": [],
   "source": [
    "# here is a function to run an experiment : train and evaluate a QuantumLayer\n",
    "\n",
    "\n",
    "def run_experiment(layer: torch.nn.Module, epochs: int = 60, lr: float = 0.05):\n",
    "    optimizer = torch.optim.Adam(layer.parameters(), lr=lr)\n",
    "    losses = []\n",
    "    for _ in range(epochs):\n",
    "        layer.train()\n",
    "        optimizer.zero_grad()\n",
    "        logits = layer(X_train)\n",
    "        loss = F.cross_entropy(logits, y_train)\n",
    "        loss.backward()\n",
    "        optimizer.step()\n",
    "        losses.append(loss.item())\n",
    "\n",
    "    layer.eval()\n",
    "    with torch.no_grad():\n",
    "        train_preds = layer(X_train).argmax(dim=1)\n",
    "        test_preds = layer(X_test).argmax(dim=1)\n",
    "        train_acc = (train_preds == y_train).float().mean().item()\n",
    "        test_acc = (test_preds == y_test).float().mean().item()\n",
    "    return losses, train_acc, test_acc\n",
    "\n",
    "\n",
    "def describe(name: str, losses, train_acc: float, test_acc: float):\n",
    "    print(name)\n",
    "    print(f\"  epochs: {len(losses)}\")\n",
    "    print(f\"  final loss: {losses[-1]:.4f}\")\n",
    "    print(f\"  train accuracy: {train_acc:.3f}\")\n",
    "    print(f\"  test accuracy: {test_acc:.3f}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a7b72ea1",
   "metadata": {},
   "source": [
    "## 1. Quickstart factory: `QuantumLayer.simple`\n",
    "\n",
    "The quickstart helper allocates a ready-to-train (input_size+1)-mode, (ceil((input_size+1)/2))-photon circuit."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "8f402df2",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-11-10T09:13:15.346136600Z",
     "start_time": "2025-11-10T09:13:09.866644400Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "QuantumLayer.simple\n",
      "  epochs: 80\n",
      "  final loss: 0.8519\n",
      "  train accuracy: 0.732\n",
      "  test accuracy: 0.658\n",
      "  trainable parameters: 40\n"
     ]
    }
   ],
   "source": [
    "base_simple = QuantumLayer.simple(\n",
    "    input_size=X_train.shape[1],\n",
    "    dtype=X_train.dtype,\n",
    ")\n",
    "\n",
    "simple_layer = nn.Sequential(\n",
    "    base_simple,\n",
    "    LexGrouping(base_simple.output_size, 3),\n",
    ")\n",
    "\n",
    "losses, train_acc, test_acc = run_experiment(simple_layer, epochs=80, lr=0.01)\n",
    "trainable = sum(p.numel() for p in simple_layer.parameters() if p.requires_grad)\n",
    "describe(\"QuantumLayer.simple\", losses, train_acc, test_acc)\n",
    "print(\n",
    "    f\"  trainable parameters: {trainable}\"\n",
    ")  # this will also print the number of trainable parameters in the last Linear layer\n",
    "\n",
    "# this circuit does not work well on this dataset, let us try another circuit !"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "da3a7fad",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-11-10T09:13:15.378085500Z",
     "start_time": "2025-11-10T09:13:15.346136600Z"
    }
   },
   "outputs": [
    {
     "data": {
      "image/svg+xml": [
       "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n",
       "<svg xmlns=\"http://www.w3.org/2000/svg\" xmlns:xlink=\"http://www.w3.org/1999/xlink\"\n",
       "     width=\"445.0\" height=\"343.75\" viewBox=\"-28.0 0 356.0 275.0\">\n",
       "<defs>\n",
       "</defs>\n",
       "<path d=\"M10,25.0 L25,25.0\" stroke-width=\"3\" stroke=\"darkred\" stroke-linejoin=\"miter\" fill=\"none\" />\n",
       "<path d=\"M10,75.0 L25,75.0\" stroke-width=\"3\" stroke=\"darkred\" stroke-linejoin=\"miter\" fill=\"none\" />\n",
       "<path d=\"M10,125.0 L25,125.0\" stroke-width=\"3\" stroke=\"darkred\" stroke-linejoin=\"miter\" fill=\"none\" />\n",
       "<path d=\"M10,175.0 L25,175.0\" stroke-width=\"3\" stroke=\"darkred\" stroke-linejoin=\"miter\" fill=\"none\" />\n",
       "<path d=\"M10,225.0 L25,225.0\" stroke-width=\"3\" stroke=\"darkred\" stroke-linejoin=\"miter\" fill=\"none\" />\n",
       "<path d=\"M25,25 L125,25\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M25,75 L125,75\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M25,125 L125,125\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M25,175 L125,175\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M25,225 L125,225\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M27.5,2.5 L122.5,2.5 L122.5,247.5 L27.5,247.5 Z\" stroke=\"darkred\" fill=\"lightpink\" stroke-linejoin=\"miter\" />\n",
       "<text x=\"35\" y=\"16\" font-size=\"8\" text-anchor=\"start\" font-weight=\"bold\">CPLX</text>\n",
       "<path d=\"M125,25 L175,25\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M130,40 L139,40 L153,10 L144,10 L130,40 L139,40 Z\" stroke=\"black\" fill=\"gray\" stroke-linejoin=\"miter\" />\n",
       "<text x=\"147\" y=\"38\" font-size=\"7\" text-anchor=\"start\">Φ=input1</text>\n",
       "<path d=\"M125,75 L175,75\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M130,90 L139,90 L153,60 L144,60 L130,90 L139,90 Z\" stroke=\"black\" fill=\"gray\" stroke-linejoin=\"miter\" />\n",
       "<text x=\"147\" y=\"88\" font-size=\"7\" text-anchor=\"start\">Φ=input2</text>\n",
       "<path d=\"M125,125 L175,125\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M130,140 L139,140 L153,110 L144,110 L130,140 L139,140 Z\" stroke=\"black\" fill=\"gray\" stroke-linejoin=\"miter\" />\n",
       "<text x=\"147\" y=\"138\" font-size=\"7\" text-anchor=\"start\">Φ=input3</text>\n",
       "<path d=\"M125,175 L175,175\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M130,190 L139,190 L153,160 L144,160 L130,190 L139,190 Z\" stroke=\"black\" fill=\"gray\" stroke-linejoin=\"miter\" />\n",
       "<text x=\"147\" y=\"188\" font-size=\"7\" text-anchor=\"start\">Φ=input4</text>\n",
       "<path d=\"M125,225.0 L175,225.0\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M175,25 L275,25\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M175,75 L275,75\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M175,125 L275,125\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M175,175 L275,175\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M175,225 L275,225\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M177.5,2.5 L272.5,2.5 L272.5,247.5 L177.5,247.5 Z\" stroke=\"darkred\" fill=\"lightpink\" stroke-linejoin=\"miter\" />\n",
       "<text x=\"185\" y=\"16\" font-size=\"8\" text-anchor=\"start\" font-weight=\"bold\">CPLX</text>\n",
       "<path d=\"M275,25.0 L290,25.0\" stroke-width=\"3\" stroke=\"darkred\" stroke-linejoin=\"miter\" fill=\"none\" />\n",
       "<path d=\"M275,75.0 L290,75.0\" stroke-width=\"3\" stroke=\"darkred\" stroke-linejoin=\"miter\" fill=\"none\" />\n",
       "<path d=\"M275,125.0 L290,125.0\" stroke-width=\"3\" stroke=\"darkred\" stroke-linejoin=\"miter\" fill=\"none\" />\n",
       "<path d=\"M275,175.0 L290,175.0\" stroke-width=\"3\" stroke=\"darkred\" stroke-linejoin=\"miter\" fill=\"none\" />\n",
       "<path d=\"M275,225.0 L290,225.0\" stroke-width=\"3\" stroke=\"darkred\" stroke-linejoin=\"miter\" fill=\"none\" />\n",
       "<text x=\"300\" y=\"28.0\" font-size=\"6\" text-anchor=\"end\">0</text>\n",
       "<text x=\"300\" y=\"78.0\" font-size=\"6\" text-anchor=\"end\">1</text>\n",
       "<text x=\"300\" y=\"128.0\" font-size=\"6\" text-anchor=\"end\">2</text>\n",
       "<text x=\"300\" y=\"178.0\" font-size=\"6\" text-anchor=\"end\">3</text>\n",
       "<text x=\"300\" y=\"228.0\" font-size=\"6\" text-anchor=\"end\">4</text>\n",
       "<text x=\"0\" y=\"28.0\" font-size=\"6\" text-anchor=\"start\">0</text>\n",
       "<text x=\"0\" y=\"78.0\" font-size=\"6\" text-anchor=\"start\">1</text>\n",
       "<text x=\"0\" y=\"128.0\" font-size=\"6\" text-anchor=\"start\">2</text>\n",
       "<text x=\"0\" y=\"178.0\" font-size=\"6\" text-anchor=\"start\">3</text>\n",
       "<text x=\"0\" y=\"228.0\" font-size=\"6\" text-anchor=\"start\">4</text>\n",
       "</svg>"
      ],
      "text/plain": [
       "<drawsvg.drawing.Drawing at 0x16914bf20>"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# you can visualize the circuit generated by QuantumLayer.simple\n",
    "pcvl.pdisplay(base_simple.circuit)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "5a04f401",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-11-10T09:13:31.430651400Z",
     "start_time": "2025-11-10T09:13:15.366028900Z"
    }
   },
   "outputs": [
    {
     "data": {
      "image/png": "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uuuuu6o9Z/jw4Ya7775brX/00UeGVq1aGQoKCkz3//LLLwZvb29DWlqaup6QkGB48skn69wGeY+nnnrKdF1eS25bvHixuj516lTDzJkz+bckxAVhzQ0hxCGcd955KhpiTlRUlGl95MiR1e6T69u3b1frEkkZMGAAQkJCTPePHj0alZWVOHDggEprnTp1ChMnTqx3G/r3729al9cKDw9HRkaGun733XeryNHWrVsxefJkTJ8+HaNGjWrhXhNC7AHFDSHEIYiYqJkmshZSI9MY/Pz8ql0XUSQCSZB6n6SkJCxatAhLly5VQknSXP/6179sss2EEOvBmhtCiFPy559/1rreq1cvtS6XUosjtTc6f/zxB7y9vdGjRw+EhYWhY8eOWL58eYu2QYqJb775Znz++ed488038dFHH7Xo9Qgh9oGRG0KIQygpKUFaWlq123x9fU1Fu1IkPHToUIwZMwb//e9/sXHjRnzyySfqPin8feaZZ5TwePbZZ5GZmYm//vWvuPHGGxEXF6ceI7ffddddiI2NVVGY/Px8JYDkcY1h1qxZGDJkiOq2km39+eefTeKKEOLcUNwQQhzCkiVLVHu2ORJ12b9/v6mT6auvvsI999yjHvfll1+id+/e6j5p3f7111/xwAMP4JxzzlHXpT5mzpw5ptcS4VNcXIw33ngDf//735VouuKKKxq9ff7+/nj88cdx/PhxleYaO3as2h5CiPPjJVXFjt4IQgipWfuycOFCVcRLCCFNhTU3hBBCCHErKG4IIYQQ4law5oYQ4nQwW04IaQmM3BBCCCHEraC4IYQQQohbQXFDCCGEELeC4oYQQgghbgXFDSGEEELcCoobQgghhLgVFDeEEEIIcSsobgghhBACd+L/Acoh6oUS0oW4AAAAAElFTkSuQmCC",
      "text/plain": [
       "<Figure size 640x480 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "test_accs, train_accs = [], []\n",
    "epochs = [10 * i for i in range(1, 26)]\n",
    "for epoch in epochs:\n",
    "    base_layer = QuantumLayer.simple(\n",
    "        input_size=X_train.shape[1],\n",
    "        dtype=X_train.dtype,\n",
    "    )\n",
    "    simple_layer = nn.Sequential(\n",
    "        base_layer,\n",
    "        LexGrouping(base_layer.output_size, 3),\n",
    "    )\n",
    "    losses, train_acc, test_acc = run_experiment(simple_layer, epochs=epoch, lr=0.01)\n",
    "    test_accs.append(test_acc)\n",
    "    train_accs.append(train_acc)\n",
    "plt.plot(epochs, train_accs, label=\"train\")\n",
    "plt.plot(epochs, test_accs, label=\"test\")\n",
    "ticks = epochs\n",
    "indexes_to_pop = []\n",
    "index = 0\n",
    "for i in range(len(epochs)):\n",
    "    if i % 3 > 0:\n",
    "        ticks.pop(index)\n",
    "    else:\n",
    "        index += 1\n",
    "\n",
    "plt.xticks(ticks=ticks, labels=[str(p) for p in ticks])\n",
    "plt.xlabel(\"Epochs\")\n",
    "plt.ylabel(\"Accuracy\")\n",
    "plt.legend()\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "41fd459a",
   "metadata": {},
   "source": [
    "## 2. Declarative builder API\n",
    "\n",
    "`CircuitBuilder` offers a fluent interface to assemble interferometers, encoders, and trainable blocks before handing the result to `QuantumLayer`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "01c9efa8",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-11-10T09:13:33.155301100Z",
     "start_time": "2025-11-10T09:13:31.430651400Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "CircuitBuilder pipeline\n",
      "  epochs: 80\n",
      "  final loss: 0.7887\n",
      "  train accuracy: 0.848\n",
      "  test accuracy: 0.789\n",
      "  trainable parameters: 36\n"
     ]
    }
   ],
   "source": [
    "builder = CircuitBuilder(n_modes=6)\n",
    "builder.add_entangling_layer(trainable=True, name=\"U1\")\n",
    "builder.add_angle_encoding(modes=list(range(X_train.shape[1])), name=\"input\")\n",
    "builder.add_rotations(trainable=True, name=\"theta\")\n",
    "builder.add_superpositions(depth=1)\n",
    "builder_core = QuantumLayer(\n",
    "    input_size=X_train.shape[1],\n",
    "    builder=builder,\n",
    "    n_photons=3,  # equivalent to input_state = [1,1,1,0,0,0]\n",
    "    dtype=X_train.dtype,\n",
    ")\n",
    "builder_layer = nn.Sequential(\n",
    "    builder_core,\n",
    "    LexGrouping(builder_core.output_size, 3),\n",
    ")\n",
    "losses, train_acc, test_acc = run_experiment(builder_layer, epochs=80, lr=0.05)\n",
    "trainable = sum(p.numel() for p in builder_layer.parameters() if p.requires_grad)\n",
    "describe(\"CircuitBuilder pipeline\", losses, train_acc, test_acc)\n",
    "print(f\"  trainable parameters: {trainable}\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "e6a99bbd",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-11-10T09:13:33.207579Z",
     "start_time": "2025-11-10T09:13:33.155301100Z"
    }
   },
   "outputs": [
    {
     "data": {
      "image/svg+xml": [
       "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n",
       "<svg xmlns=\"http://www.w3.org/2000/svg\" xmlns:xlink=\"http://www.w3.org/1999/xlink\"\n",
       "     width=\"1008.75\" height=\"406.25\" viewBox=\"-28.5 0 807.0 325.0\">\n",
       "<defs>\n",
       "</defs>\n",
       "<path d=\"M10,25.0 L25,25.0\" stroke-width=\"3\" stroke=\"darkred\" stroke-linejoin=\"miter\" fill=\"none\" />\n",
       "<path d=\"M10,75.0 L25,75.0\" stroke-width=\"3\" stroke=\"darkred\" stroke-linejoin=\"miter\" fill=\"none\" />\n",
       "<path d=\"M10,125.0 L25,125.0\" stroke-width=\"3\" stroke=\"darkred\" stroke-linejoin=\"miter\" fill=\"none\" />\n",
       "<path d=\"M10,175.0 L25,175.0\" stroke-width=\"3\" stroke=\"darkred\" stroke-linejoin=\"miter\" fill=\"none\" />\n",
       "<path d=\"M10,225.0 L25,225.0\" stroke-width=\"3\" stroke=\"darkred\" stroke-linejoin=\"miter\" fill=\"none\" />\n",
       "<path d=\"M10,275.0 L25,275.0\" stroke-width=\"3\" stroke=\"darkred\" stroke-linejoin=\"miter\" fill=\"none\" />\n",
       "<path d=\"M25,25 L125,25\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M25,75 L125,75\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M25,125 L125,125\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M25,175 L125,175\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M25,225 L125,225\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M25,275 L125,275\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M27.5,2.5 L122.5,2.5 L122.5,297.5 L27.5,297.5 Z\" stroke=\"darkred\" fill=\"lightpink\" stroke-linejoin=\"miter\" />\n",
       "<text x=\"35\" y=\"16\" font-size=\"8\" text-anchor=\"start\" font-weight=\"bold\">CPLX</text>\n",
       "<path d=\"M125,25 L175,25\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M130,40 L139,40 L153,10 L144,10 L130,40 L139,40 Z\" stroke=\"black\" fill=\"gray\" stroke-linejoin=\"miter\" />\n",
       "<text x=\"147\" y=\"38\" font-size=\"7\" text-anchor=\"start\">Φ=input1</text>\n",
       "<path d=\"M125,75 L175,75\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M130,90 L139,90 L153,60 L144,60 L130,90 L139,90 Z\" stroke=\"black\" fill=\"gray\" stroke-linejoin=\"miter\" />\n",
       "<text x=\"147\" y=\"88\" font-size=\"7\" text-anchor=\"start\">Φ=input2</text>\n",
       "<path d=\"M125,125 L175,125\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M130,140 L139,140 L153,110 L144,110 L130,140 L139,140 Z\" stroke=\"black\" fill=\"gray\" stroke-linejoin=\"miter\" />\n",
       "<text x=\"147\" y=\"138\" font-size=\"7\" text-anchor=\"start\">Φ=input3</text>\n",
       "<path d=\"M125,175 L175,175\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M130,190 L139,190 L153,160 L144,160 L130,190 L139,190 Z\" stroke=\"black\" fill=\"gray\" stroke-linejoin=\"miter\" />\n",
       "<text x=\"147\" y=\"188\" font-size=\"7\" text-anchor=\"start\">Φ=input4</text>\n",
       "<path d=\"M175,25 L225,25\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M180,40 L189,40 L203,10 L194,10 L180,40 L189,40 Z\" stroke=\"black\" fill=\"gray\" stroke-linejoin=\"miter\" />\n",
       "<text x=\"197\" y=\"38\" font-size=\"7\" text-anchor=\"start\">Φ=theta_0</text>\n",
       "<path d=\"M175,75 L225,75\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M180,90 L189,90 L203,60 L194,60 L180,90 L189,90 Z\" stroke=\"black\" fill=\"gray\" stroke-linejoin=\"miter\" />\n",
       "<text x=\"197\" y=\"88\" font-size=\"7\" text-anchor=\"start\">Φ=theta_1</text>\n",
       "<path d=\"M175,125 L225,125\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M180,140 L189,140 L203,110 L194,110 L180,140 L189,140 Z\" stroke=\"black\" fill=\"gray\" stroke-linejoin=\"miter\" />\n",
       "<text x=\"197\" y=\"138\" font-size=\"7\" text-anchor=\"start\">Φ=theta_2</text>\n",
       "<path d=\"M175,175 L225,175\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M180,190 L189,190 L203,160 L194,160 L180,190 L189,190 Z\" stroke=\"black\" fill=\"gray\" stroke-linejoin=\"miter\" />\n",
       "<text x=\"197\" y=\"188\" font-size=\"7\" text-anchor=\"start\">Φ=theta_3</text>\n",
       "<path d=\"M125,225 L175,225\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M130,240 L139,240 L153,210 L144,210 L130,240 L139,240 Z\" stroke=\"black\" fill=\"gray\" stroke-linejoin=\"miter\" />\n",
       "<text x=\"147\" y=\"238\" font-size=\"7\" text-anchor=\"start\">Φ=theta_4</text>\n",
       "<path d=\"M125,275 L175,275\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M130,290 L139,290 L153,260 L144,260 L130,290 L139,290 Z\" stroke=\"black\" fill=\"gray\" stroke-linejoin=\"miter\" />\n",
       "<text x=\"147\" y=\"288\" font-size=\"7\" text-anchor=\"start\">Φ=theta_5</text>\n",
       "<path d=\"M225,25 L253,25 L272,44\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M278,44 L297,25 L325,25\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M225,75 L253,75 L272,56\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M278,56 L297,75 L325,75\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M250,43 L300,43 L300,57 L250,57 Z\" stroke=\"black\" fill=\"black\" stroke-linejoin=\"miter\" />\n",
       "<text x=\"275\" y=\"85\" font-size=\"7\" text-anchor=\"middle\"></text>\n",
       "<text x=\"275\" y=\"26\" font-size=\"7\" text-anchor=\"middle\"></text>\n",
       "<path d=\"M250,43 L300,43 L300,47 L250,47 Z\" stroke=\"black\" fill=\"lightgray\" stroke-linejoin=\"miter\" />\n",
       "<path d=\"M293,50 L303,50 L303,60 L293,60 Z\" stroke=\"black\" fill=\"thistle\" stroke-linejoin=\"miter\" />\n",
       "<text x=\"298\" y=\"57\" font-size=\"6\" text-anchor=\"middle\">Rx</text>\n",
       "<path d=\"M225,125.0 L325,125.0\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M325,75 L353,75 L372,94\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M378,94 L397,75 L425,75\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M325,125 L353,125 L372,106\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M378,106 L397,125 L425,125\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M350,93 L400,93 L400,107 L350,107 Z\" stroke=\"black\" fill=\"black\" stroke-linejoin=\"miter\" />\n",
       "<text x=\"375\" y=\"135\" font-size=\"7\" text-anchor=\"middle\"></text>\n",
       "<text x=\"375\" y=\"76\" font-size=\"7\" text-anchor=\"middle\"></text>\n",
       "<path d=\"M350,93 L400,93 L400,97 L350,97 Z\" stroke=\"black\" fill=\"lightgray\" stroke-linejoin=\"miter\" />\n",
       "<path d=\"M393,100 L403,100 L403,110 L393,110 Z\" stroke=\"black\" fill=\"thistle\" stroke-linejoin=\"miter\" />\n",
       "<text x=\"398\" y=\"107\" font-size=\"6\" text-anchor=\"middle\">Rx</text>\n",
       "<path d=\"M225,175.0 L425,175.0\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M425,125 L453,125 L472,144\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M478,144 L497,125 L525,125\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M425,175 L453,175 L472,156\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M478,156 L497,175 L525,175\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M450,143 L500,143 L500,157 L450,157 Z\" stroke=\"black\" fill=\"black\" stroke-linejoin=\"miter\" />\n",
       "<text x=\"475\" y=\"185\" font-size=\"7\" text-anchor=\"middle\"></text>\n",
       "<text x=\"475\" y=\"126\" font-size=\"7\" text-anchor=\"middle\"></text>\n",
       "<path d=\"M450,143 L500,143 L500,147 L450,147 Z\" stroke=\"black\" fill=\"lightgray\" stroke-linejoin=\"miter\" />\n",
       "<path d=\"M493,150 L503,150 L503,160 L493,160 Z\" stroke=\"black\" fill=\"thistle\" stroke-linejoin=\"miter\" />\n",
       "<text x=\"498\" y=\"157\" font-size=\"6\" text-anchor=\"middle\">Rx</text>\n",
       "<path d=\"M175,225.0 L525,225.0\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M525,175 L553,175 L572,194\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M578,194 L597,175 L625,175\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M525,225 L553,225 L572,206\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M578,206 L597,225 L625,225\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M550,193 L600,193 L600,207 L550,207 Z\" stroke=\"black\" fill=\"black\" stroke-linejoin=\"miter\" />\n",
       "<text x=\"575\" y=\"235\" font-size=\"7\" text-anchor=\"middle\"></text>\n",
       "<text x=\"575\" y=\"176\" font-size=\"7\" text-anchor=\"middle\"></text>\n",
       "<path d=\"M550,193 L600,193 L600,197 L550,197 Z\" stroke=\"black\" fill=\"lightgray\" stroke-linejoin=\"miter\" />\n",
       "<path d=\"M593,200 L603,200 L603,210 L593,210 Z\" stroke=\"black\" fill=\"thistle\" stroke-linejoin=\"miter\" />\n",
       "<text x=\"598\" y=\"207\" font-size=\"6\" text-anchor=\"middle\">Rx</text>\n",
       "<path d=\"M175,275.0 L625,275.0\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M625,225 L653,225 L672,244\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M678,244 L697,225 L725,225\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M625,275 L653,275 L672,256\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M678,256 L697,275 L725,275\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M650,243 L700,243 L700,257 L650,257 Z\" stroke=\"black\" fill=\"black\" stroke-linejoin=\"miter\" />\n",
       "<text x=\"675\" y=\"285\" font-size=\"7\" text-anchor=\"middle\"></text>\n",
       "<text x=\"675\" y=\"226\" font-size=\"7\" text-anchor=\"middle\"></text>\n",
       "<path d=\"M650,243 L700,243 L700,247 L650,247 Z\" stroke=\"black\" fill=\"lightgray\" stroke-linejoin=\"miter\" />\n",
       "<path d=\"M693,250 L703,250 L703,260 L693,260 Z\" stroke=\"black\" fill=\"thistle\" stroke-linejoin=\"miter\" />\n",
       "<text x=\"698\" y=\"257\" font-size=\"6\" text-anchor=\"middle\">Rx</text>\n",
       "<path d=\"M325,25.0 L725,25.0\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M425,75.0 L725,75.0\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M525,125.0 L725,125.0\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M625,175.0 L725,175.0\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M725,25.0 L740,25.0\" stroke-width=\"3\" stroke=\"darkred\" stroke-linejoin=\"miter\" fill=\"none\" />\n",
       "<path d=\"M725,75.0 L740,75.0\" stroke-width=\"3\" stroke=\"darkred\" stroke-linejoin=\"miter\" fill=\"none\" />\n",
       "<path d=\"M725,125.0 L740,125.0\" stroke-width=\"3\" stroke=\"darkred\" stroke-linejoin=\"miter\" fill=\"none\" />\n",
       "<path d=\"M725,175.0 L740,175.0\" stroke-width=\"3\" stroke=\"darkred\" stroke-linejoin=\"miter\" fill=\"none\" />\n",
       "<path d=\"M725,225.0 L740,225.0\" stroke-width=\"3\" stroke=\"darkred\" stroke-linejoin=\"miter\" fill=\"none\" />\n",
       "<path d=\"M725,275.0 L740,275.0\" stroke-width=\"3\" stroke=\"darkred\" stroke-linejoin=\"miter\" fill=\"none\" />\n",
       "<text x=\"750\" y=\"28.0\" font-size=\"7\" text-anchor=\"end\">0</text>\n",
       "<text x=\"750\" y=\"78.0\" font-size=\"7\" text-anchor=\"end\">1</text>\n",
       "<text x=\"750\" y=\"128.0\" font-size=\"7\" text-anchor=\"end\">2</text>\n",
       "<text x=\"750\" y=\"178.0\" font-size=\"7\" text-anchor=\"end\">3</text>\n",
       "<text x=\"750\" y=\"228.0\" font-size=\"7\" text-anchor=\"end\">4</text>\n",
       "<text x=\"750\" y=\"278.0\" font-size=\"7\" text-anchor=\"end\">5</text>\n",
       "<text x=\"0\" y=\"28.0\" font-size=\"7\" text-anchor=\"start\">0</text>\n",
       "<text x=\"0\" y=\"78.0\" font-size=\"7\" text-anchor=\"start\">1</text>\n",
       "<text x=\"0\" y=\"128.0\" font-size=\"7\" text-anchor=\"start\">2</text>\n",
       "<text x=\"0\" y=\"178.0\" font-size=\"7\" text-anchor=\"start\">3</text>\n",
       "<text x=\"0\" y=\"228.0\" font-size=\"7\" text-anchor=\"start\">4</text>\n",
       "<text x=\"0\" y=\"278.0\" font-size=\"7\" text-anchor=\"start\">5</text>\n",
       "</svg>"
      ],
      "text/plain": [
       "<drawsvg.drawing.Drawing at 0x16a4b5700>"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# you can observe your circuit\n",
    "pcvl.pdisplay(builder_core.circuit)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ba326ccd",
   "metadata": {},
   "source": [
    "## 3. Hand-crafted Perceval circuit\n",
    "\n",
    "When full control is required, build a `perceval.Circuit` manually and pass it to `QuantumLayer` alongside the parameter prefixes to train and encode."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "680842d0",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-11-10T09:13:35.653789100Z",
     "start_time": "2025-11-10T09:13:33.175465800Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Manual Perceval circuit\n",
      "  epochs: 120\n",
      "  final loss: 0.7080\n",
      "  train accuracy: 0.973\n",
      "  test accuracy: 0.921\n",
      "  trainable parameters: 60\n"
     ]
    }
   ],
   "source": [
    "modes = 6\n",
    "\n",
    "wl = pcvl.GenericInterferometer(\n",
    "    modes,\n",
    "    lambda i: (\n",
    "        pcvl.BS()\n",
    "        // pcvl.PS(pcvl.P(f\"theta_li{i}\"))\n",
    "        // pcvl.BS()\n",
    "        // pcvl.PS(pcvl.P(f\"theta_lo{i}\"))\n",
    "    ),\n",
    "    shape=pcvl.InterferometerShape.RECTANGLE,\n",
    ")\n",
    "circuit = pcvl.Circuit(modes)\n",
    "circuit.add(0, wl)\n",
    "for mode in range(len(iris.feature_names)):\n",
    "    circuit.add(mode, pcvl.PS(pcvl.P(f\"input{mode}\")))\n",
    "wr = pcvl.GenericInterferometer(\n",
    "    modes,\n",
    "    lambda i: (\n",
    "        pcvl.BS()\n",
    "        // pcvl.PS(pcvl.P(f\"theta_ri{i}\"))\n",
    "        // pcvl.BS()\n",
    "        // pcvl.PS(pcvl.P(f\"theta_ro{i}\"))\n",
    "    ),\n",
    "    shape=pcvl.InterferometerShape.RECTANGLE,\n",
    ")\n",
    "circuit.add(0, wr)\n",
    "\n",
    "manual_core = QuantumLayer(\n",
    "    input_size=X_train.shape[1],\n",
    "    circuit=circuit,\n",
    "    input_state=[\n",
    "        1,\n",
    "        0,\n",
    "        1,\n",
    "        0,\n",
    "        1,\n",
    "        0,\n",
    "    ],  # here, you can just precise the n_photons -> input_state = [1,1,1,0,0,0]\n",
    "    trainable_parameters=[\"theta\"],\n",
    "    input_parameters=[\"input\"],\n",
    "    dtype=X_train.dtype,\n",
    ")\n",
    "\n",
    "manual_layer = nn.Sequential(\n",
    "    manual_core,\n",
    "    LexGrouping(manual_core.output_size, 3),\n",
    ")\n",
    "\n",
    "losses, train_acc, test_acc = run_experiment(manual_layer, epochs=120, lr=0.05)\n",
    "trainable = sum(p.numel() for p in manual_layer.parameters() if p.requires_grad)\n",
    "describe(\"Manual Perceval circuit\", losses, train_acc, test_acc)\n",
    "print(f\"  trainable parameters: {trainable}\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "d43797b2",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-11-10T09:13:35.708099500Z",
     "start_time": "2025-11-10T09:13:35.653789100Z"
    }
   },
   "outputs": [
    {
     "data": {
      "image/svg+xml": [
       "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n",
       "<svg xmlns=\"http://www.w3.org/2000/svg\" xmlns:xlink=\"http://www.w3.org/1999/xlink\"\n",
       "     width=\"446.25\" height=\"406.25\" viewBox=\"-28.5 0 357.0 325.0\">\n",
       "<defs>\n",
       "</defs>\n",
       "<path d=\"M10,25.0 L25,25.0\" stroke-width=\"3\" stroke=\"darkred\" stroke-linejoin=\"miter\" fill=\"none\" />\n",
       "<path d=\"M10,75.0 L25,75.0\" stroke-width=\"3\" stroke=\"darkred\" stroke-linejoin=\"miter\" fill=\"none\" />\n",
       "<path d=\"M10,125.0 L25,125.0\" stroke-width=\"3\" stroke=\"darkred\" stroke-linejoin=\"miter\" fill=\"none\" />\n",
       "<path d=\"M10,175.0 L25,175.0\" stroke-width=\"3\" stroke=\"darkred\" stroke-linejoin=\"miter\" fill=\"none\" />\n",
       "<path d=\"M10,225.0 L25,225.0\" stroke-width=\"3\" stroke=\"darkred\" stroke-linejoin=\"miter\" fill=\"none\" />\n",
       "<path d=\"M10,275.0 L25,275.0\" stroke-width=\"3\" stroke=\"darkred\" stroke-linejoin=\"miter\" fill=\"none\" />\n",
       "<path d=\"M25,25 L125,25\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M25,75 L125,75\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M25,125 L125,125\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M25,175 L125,175\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M25,225 L125,225\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M25,275 L125,275\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M27.5,2.5 L122.5,2.5 L122.5,297.5 L27.5,297.5 Z\" stroke=\"darkred\" fill=\"lightpink\" stroke-linejoin=\"miter\" />\n",
       "<text x=\"35\" y=\"16\" font-size=\"8\" text-anchor=\"start\" font-weight=\"bold\">CPLX</text>\n",
       "<path d=\"M125,25 L175,25\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M130,40 L139,40 L153,10 L144,10 L130,40 L139,40 Z\" stroke=\"black\" fill=\"gray\" stroke-linejoin=\"miter\" />\n",
       "<text x=\"147\" y=\"38\" font-size=\"7\" text-anchor=\"start\">Φ=input0</text>\n",
       "<path d=\"M125,75 L175,75\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M130,90 L139,90 L153,60 L144,60 L130,90 L139,90 Z\" stroke=\"black\" fill=\"gray\" stroke-linejoin=\"miter\" />\n",
       "<text x=\"147\" y=\"88\" font-size=\"7\" text-anchor=\"start\">Φ=input1</text>\n",
       "<path d=\"M125,125 L175,125\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M130,140 L139,140 L153,110 L144,110 L130,140 L139,140 Z\" stroke=\"black\" fill=\"gray\" stroke-linejoin=\"miter\" />\n",
       "<text x=\"147\" y=\"138\" font-size=\"7\" text-anchor=\"start\">Φ=input2</text>\n",
       "<path d=\"M125,175 L175,175\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M130,190 L139,190 L153,160 L144,160 L130,190 L139,190 Z\" stroke=\"black\" fill=\"gray\" stroke-linejoin=\"miter\" />\n",
       "<text x=\"147\" y=\"188\" font-size=\"7\" text-anchor=\"start\">Φ=input3</text>\n",
       "<path d=\"M125,225.0 L175,225.0\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M125,275.0 L175,275.0\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M175,25 L275,25\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M175,75 L275,75\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M175,125 L275,125\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M175,175 L275,175\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M175,225 L275,225\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M175,275 L275,275\" stroke=\"darkred\" stroke-width=\"3\" fill=\"none\" />\n",
       "<path d=\"M177.5,2.5 L272.5,2.5 L272.5,297.5 L177.5,297.5 Z\" stroke=\"darkred\" fill=\"lightpink\" stroke-linejoin=\"miter\" />\n",
       "<text x=\"185\" y=\"16\" font-size=\"8\" text-anchor=\"start\" font-weight=\"bold\">CPLX</text>\n",
       "<path d=\"M275,25.0 L290,25.0\" stroke-width=\"3\" stroke=\"darkred\" stroke-linejoin=\"miter\" fill=\"none\" />\n",
       "<path d=\"M275,75.0 L290,75.0\" stroke-width=\"3\" stroke=\"darkred\" stroke-linejoin=\"miter\" fill=\"none\" />\n",
       "<path d=\"M275,125.0 L290,125.0\" stroke-width=\"3\" stroke=\"darkred\" stroke-linejoin=\"miter\" fill=\"none\" />\n",
       "<path d=\"M275,175.0 L290,175.0\" stroke-width=\"3\" stroke=\"darkred\" stroke-linejoin=\"miter\" fill=\"none\" />\n",
       "<path d=\"M275,225.0 L290,225.0\" stroke-width=\"3\" stroke=\"darkred\" stroke-linejoin=\"miter\" fill=\"none\" />\n",
       "<path d=\"M275,275.0 L290,275.0\" stroke-width=\"3\" stroke=\"darkred\" stroke-linejoin=\"miter\" fill=\"none\" />\n",
       "<text x=\"300\" y=\"28.0\" font-size=\"7\" text-anchor=\"end\">0</text>\n",
       "<text x=\"300\" y=\"78.0\" font-size=\"7\" text-anchor=\"end\">1</text>\n",
       "<text x=\"300\" y=\"128.0\" font-size=\"7\" text-anchor=\"end\">2</text>\n",
       "<text x=\"300\" y=\"178.0\" font-size=\"7\" text-anchor=\"end\">3</text>\n",
       "<text x=\"300\" y=\"228.0\" font-size=\"7\" text-anchor=\"end\">4</text>\n",
       "<text x=\"300\" y=\"278.0\" font-size=\"7\" text-anchor=\"end\">5</text>\n",
       "<text x=\"0\" y=\"28.0\" font-size=\"7\" text-anchor=\"start\">0</text>\n",
       "<text x=\"0\" y=\"78.0\" font-size=\"7\" text-anchor=\"start\">1</text>\n",
       "<text x=\"0\" y=\"128.0\" font-size=\"7\" text-anchor=\"start\">2</text>\n",
       "<text x=\"0\" y=\"178.0\" font-size=\"7\" text-anchor=\"start\">3</text>\n",
       "<text x=\"0\" y=\"228.0\" font-size=\"7\" text-anchor=\"start\">4</text>\n",
       "<text x=\"0\" y=\"278.0\" font-size=\"7\" text-anchor=\"start\">5</text>\n",
       "</svg>"
      ],
      "text/plain": [
       "<drawsvg.drawing.Drawing at 0x16001c0b0>"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# you can visualize the circuit\n",
    "pcvl.pdisplay(manual_core.circuit)"
   ]
  }
 ],
 "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"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}