notebooks/07_mask_labels.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "d64a4568",
   "metadata": {},
   "source": [
    "# Die assembly with labels (deprecated)\n",
    "\n",
    "You can add a label per automated alignment structure.\n",
    "\n",
    "However this only works well for fiber array only or electrical probing only, so we don't recommend it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "22256427",
   "metadata": {},
   "outputs": [],
   "source": [
    "from functools import partial\n",
    "\n",
    "import json\n",
    "import gdsfactory as gf\n",
    "from gdsfactory.generic_tech import get_generic_pdk\n",
    "from gdsfactory.labels import add_label_ehva, add_label_json"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b88604fa",
   "metadata": {},
   "source": [
    "## Automated testing using labels\n",
    "\n",
    "This is deprecated, we recommend exposing all ports and writing the test manifest directly.\n",
    "However you can also do automatic testing by adding labels the devices that you want to test.\n",
    "GDS labels are not fabricated and are only visible in the GDS file.\n",
    "\n",
    "Lets review some different automatic labeling schemas:\n",
    "\n",
    "1. One label per test alignment that includes settings, electrical ports and optical ports.\n",
    "2. SiEPIC labels: only the laser input grating coupler from the fiber array has a label, which is the second port from left to right.\n",
    "3. EHVA automatic testers, include a Label component declaration as described in this [doc](https://drive.google.com/file/d/1kbQNrVLzPbefh3by7g2s865bcsA2vl5l/view)\n",
    "\n",
    "Most gdsfactory examples add south grating couplers on the south and RF or DC signals to the north. However if you need RF and DC pads, you have to make sure RF pads are orthogonal to the DC Pads. For example, you can use EAST/WEST for RF and NORTH for DC.\n",
    "\n",
    "\n",
    "### 1. Test Sites Labels\n",
    "\n",
    "Each alignment site includes a label with the measurement and analysis settings:\n",
    "\n",
    "- Optical and electrical port locations for each alignment.\n",
    "- measurement settings.\n",
    "- Component settings for the analysis and test and data analysis information. Such as Design of Experiment (DOE) id.\n",
    "\n",
    "\n",
    "The default settings can be stored in a separate [CSV file](https://docs.google.com/spreadsheets/d/1845m-XZM8tZ1tNd8GIvAaq7ZE-iha00XNWa0XrEOabc/edit#gid=0)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "34a1ed71",
   "metadata": {},
   "outputs": [],
   "source": [
    "info = dict(\n",
    "    doe=\"mzis\",\n",
    "    analysis=\"mzi_phase_shifter\",\n",
    "    measurement=\"optical_loopback2_heater_sweep\",\n",
    "    measurement_settings=json.dumps(dict(v_max=5)),\n",
    ")\n",
    "\n",
    "c = gf.components.mzi_phase_shifter()\n",
    "c = gf.components.add_fiber_array_optical_south_electrical_north(c)\n",
    "c.info.update(info)\n",
    "c = add_label_json(c)\n",
    "c.plot()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "24fdce37",
   "metadata": {},
   "outputs": [],
   "source": [
    "c.labels"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b9068471",
   "metadata": {},
   "outputs": [],
   "source": [
    "json.loads(c.labels[0].text)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a2bbd791",
   "metadata": {},
   "outputs": [],
   "source": [
    "c = gf.components.spiral_inner_io_fiber_array(\n",
    "    length=20e3,\n",
    ")\n",
    "c = gf.labels.add_label_json(c)\n",
    "info = dict(\n",
    "    measurement=\"optical_loopback2\",\n",
    "    doe=\"spiral_sc\",\n",
    "    measurement_settings=json.dumps(dict(wavelength_alignment=1560)),\n",
    ")\n",
    "c.info.update(info)\n",
    "c.plot()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c50b7f68",
   "metadata": {},
   "outputs": [],
   "source": [
    "json.loads(c.labels[0].text)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d47a0438",
   "metadata": {},
   "source": [
    "### 2. SiEPIC labels\n",
    "\n",
    "Labels follow format `opt_in_{polarization}_{wavelength}_device_{username}_({component_name})-{gc_index}-{port.name}` and you only need to label the laser input port of the fiber array.\n",
    "This also includes one label per test site."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d5a42d5b",
   "metadata": {},
   "outputs": [],
   "source": [
    "mmi = gf.components.mmi2x2()\n",
    "mmi_te_siepic = gf.labels.add_fiber_array_siepic(component=mmi)\n",
    "mmi_te_siepic.plot()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "302e67bf",
   "metadata": {},
   "outputs": [],
   "source": [
    "mmi_te_siepic.ports"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f8bd7164",
   "metadata": {},
   "outputs": [],
   "source": [
    "labels = mmi_te_siepic.get_labels()\n",
    "\n",
    "for label in labels:\n",
    "    print(label.text)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4c14b653",
   "metadata": {},
   "source": [
    "### 3. EHVA labels"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c6fae10d",
   "metadata": {},
   "outputs": [],
   "source": [
    "add_label_ehva_demo = partial(add_label_ehva, die=\"demo_die\")\n",
    "mmi = gf.c.mmi2x2(length_mmi=2.2)\n",
    "mmi_te_ehva = gf.routing.add_fiber_array(mmi)\n",
    "mmi_te_ehva = add_label_ehva_demo(mmi_te_ehva)\n",
    "mmi_te_ehva.plot()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ed8824f9",
   "metadata": {},
   "outputs": [],
   "source": [
    "labels = mmi_te_ehva.get_labels(depth=0)\n",
    "\n",
    "for label in labels:\n",
    "    print(label.text)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ff63baf6",
   "metadata": {},
   "source": [
    "One advantage of the EHVA formats is that you can track any changes on the components directly from the GDS label, as the label already stores any changes of the child device, as well as any settings that you specify.\n",
    "\n",
    "Settings can have many levels of hierarchy, but you can still access any children setting with `:` notation.\n",
    "\n",
    "```\n",
    "grating_coupler:\n",
    "    function: grating_coupler_elliptical_trenches\n",
    "    settings:\n",
    "        polarization: te\n",
    "        taper_angle: 35\n",
    "\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d2df3865",
   "metadata": {},
   "outputs": [],
   "source": [
    "add_label_ehva_demo = partial(\n",
    "    add_label_ehva,\n",
    "    die=\"demo_die\",\n",
    ")\n",
    "mmi = gf.components.mmi2x2(length_mmi=10)\n",
    "mmi_te_ehva = gf.routing.add_fiber_array(\n",
    "    mmi,\n",
    "    get_input_labels_function=None,\n",
    ")\n",
    "mmi_te_ehva = add_label_ehva_demo(mmi_te_ehva)\n",
    "mmi_te_ehva.plot()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "976be138",
   "metadata": {},
   "outputs": [],
   "source": [
    "labels = mmi_te_ehva.get_labels(depth=0)\n",
    "\n",
    "for label in labels:\n",
    "    print(label.text)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f5422be8",
   "metadata": {},
   "source": [
    "## Metadata\n",
    "\n",
    "When saving GDS files is also convenient to store the metadata settings that you used to generate the GDS file.\n",
    "\n",
    "We recommend storing all the device metadata in GDS labels but you can also store it in a separate YAML file.\n",
    "\n",
    "### Metadata in separate YAML file"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c0bb6e51",
   "metadata": {
    "lines_to_next_cell": 2
   },
   "outputs": [],
   "source": [
    "import gdsfactory as gf\n",
    "\n",
    "\n",
    "@gf.cell\n",
    "def wg():\n",
    "    c = gf.Component()\n",
    "    c.info[\"doe\"] = \"phase_shifter_rings_te\"\n",
    "    c.info[\"test_sequence\"] = \"optical_loopback_electrical_sweep\"\n",
    "    c.info[\"data_analysis\"] = \"extract_vpi\"\n",
    "    return c\n",
    "\n",
    "\n",
    "c = wg()\n",
    "c.pprint()\n",
    "gdspath = c.write_gds(\"demo.gds\", with_metadata=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a3f222e6",
   "metadata": {},
   "source": [
    "### Metadata in the GDS file\n",
    "\n",
    "You can use GDS labels to store device information such as settings and port locations.\n",
    "\n",
    "The advantage of GDS labels is that they are all stored in the same file.\n",
    "\n",
    "We define a single label for each test site (Device Under Test), and the label contains all the measurement and data analysis information."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "04d93e6d",
   "metadata": {},
   "outputs": [],
   "source": [
    "test_info_mzi_heaters = dict(\n",
    "    doe=\"mzis_heaters\",\n",
    "    analysis=\"mzi_heater_phase_shifter_length\",\n",
    "    measurement=\"optical_loopback4_heater_sweep\",\n",
    ")\n",
    "test_info_ring_heaters = dict(\n",
    "    doe=\"ring_heaters_coupling_length\",\n",
    "    analysis=\"ring_heater\",\n",
    "    measurement=\"optical_loopback2_heater_sweep\",\n",
    ")\n",
    "\n",
    "mzis = [\n",
    "    gf.components.mzi2x2_2x2_phase_shifter(length_x=lengths)\n",
    "    for lengths in [100, 200, 300]\n",
    "]\n",
    "\n",
    "rings = [\n",
    "    gf.components.ring_single_heater(length_x=length_x) for length_x in [10, 20, 30]\n",
    "]\n",
    "\n",
    "mzis_te = []\n",
    "for mzi in mzis:\n",
    "    mzi_te = gf.components.add_fiber_array_optical_south_electrical_north(\n",
    "        mzi,\n",
    "        electrical_port_names=[\"top_l_e2\", \"top_r_e2\"],\n",
    "    )\n",
    "    mzi_te.info.update(test_info_mzi_heaters)\n",
    "    mzi_te = gf.labels.add_label_json(mzi_te)\n",
    "    mzis_te.append(mzi_te)\n",
    "\n",
    "rings_te = []\n",
    "for ring in rings:\n",
    "    ring_te = gf.components.add_fiber_array_optical_south_electrical_north(\n",
    "        ring,\n",
    "        electrical_port_names=[\"l_e2\", \"r_e2\"],\n",
    "    )\n",
    "    ring_te.info.update(test_info_ring_heaters)\n",
    "    ring_te = gf.labels.add_label_json(ring_te)\n",
    "    rings_te.append(ring_te)\n",
    "\n",
    "c = gf.pack(mzis_te + rings_te)[0]\n",
    "c.plot()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cd62b28b",
   "metadata": {},
   "source": [
    "## Test manifest from labels\n",
    "\n",
    "Each Device Under Test (test site) has a JSON test label with all the settings.\n",
    "\n",
    "You can define a [Test manifest](https://docs.google.com/spreadsheets/d/1845m-XZM8tZ1tNd8GIvAaq7ZE-iha00XNWa0XrEOabc/edit#gid=0) (also known as Test sequence) in CSV automatically from the labels."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d37416ab",
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandas as pd\n",
    "\n",
    "gdspath = c.write_gds()\n",
    "csvpath = gf.labels.write_labels.write_labels_gdstk(\n",
    "    gdspath, debug=True, prefixes=[\"{\"], layer_label=\"TEXT\"\n",
    ")\n",
    "df = pd.read_csv(csvpath)\n",
    "df"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "af600231",
   "metadata": {},
   "source": [
    "As you can see there are 6 devices with optical and electrical ports.\n",
    "\n",
    "You can turn each label into a test manifest CSV file to interface with your lab instrumentation functions.\n",
    "\n",
    "Each measurement will use a different `measurement` procedure and settings `measurement_settings`\n",
    "\n",
    "The default measurement settings for each functions can also be defined in a separate [CSV file](https://docs.google.com/spreadsheets/d/1845m-XZM8tZ1tNd8GIvAaq7ZE-iha00XNWa0XrEOabc/edit#gid=138229318) and easily editable with Excel or LibreOffice."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "16f4e6a2",
   "metadata": {},
   "outputs": [],
   "source": [
    "from gdsfactory.labels.write_test_manifest import write_test_manifest\n",
    "\n",
    "dm = write_test_manifest(csvpath)\n",
    "dm"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "69a923bd",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "jupytext": {
   "cell_metadata_filter": "-all",
   "custom_cell_magics": "kql"
  },
  "kernelspec": {
   "display_name": "base",
   "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.11.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}