Merge pull request #136 from invrs-io/docs2

Reorganize docs
invrs-io · Jul 16, 2024 · 69c21f0 · 69c21f0
2 parents c17b459 + eddd551
commit 69c21f0
Show file tree

Hide file tree

Showing 11 changed files with 433 additions and 749 deletions.
diff --git a/docs/_toc.yml b/docs/_toc.yml
@@ -4,12 +4,18 @@
 format: jb-book
 root: readme
 parts:
+  - caption: Introduction
+    chapters:
+    - file: notebooks/intro/gym_basics
   - caption: Challenges
     chapters:
-    - file: notebooks/bayer_sorter
-    - file: notebooks/ceviche_challenges
-    - file: notebooks/diffractive_splitter
-    - file: notebooks/meta_atom_library
-    - file: notebooks/metagrating
-    - file: notebooks/metalens
-    - file: notebooks/photon_extractor
+    - file: notebooks/challenges/bayer_sorter
+    - file: notebooks/challenges/ceviche_challenges
+    - file: notebooks/challenges/diffractive_splitter
+    - file: notebooks/challenges/meta_atom_library
+    - file: notebooks/challenges/metagrating
+    - file: notebooks/challenges/metalens
+    - file: notebooks/challenges/photon_extractor
+  - caption: Optimization
+    chapters:
+    - file: notebooks/optimization/basic_optimization
diff --git a/docs/notebooks/bayer_sorter.ipynb → docs/notebooks/challenges/bayer_sorter.ipynb b/docs/notebooks/bayer_sorter.ipynb → docs/notebooks/challenges/bayer_sorter.ipynb
@@ -28,7 +28,7 @@
     "import numpy as onp\n",
     "from skimage import measure\n",
     "\n",
-    "design = onp.genfromtxt(\"../../reference_designs/bayer/zou.csv\", delimiter=\",\")\n",
+    "design = onp.genfromtxt(\"../../../reference_designs/bayer/zou.csv\", delimiter=\",\")\n",
     "\n",
     "plt.figure(figsize=(3, 3))\n",
     "ax = plt.subplot(111)\n",

diff --git a/docs/notebooks/ceviche_challenges.ipynb → ...books/challenges/ceviche_challenges.ipynb b/docs/notebooks/ceviche_challenges.ipynb → ...books/challenges/ceviche_challenges.ipynb
@@ -36,7 +36,7 @@
     "from skimage import measure\n",
     "\n",
     "design = onp.genfromtxt(\n",
-    "    \"../../reference_designs/ceviche/mode_converter/converter_generator_circle_10_x47530832_w19_s483.csv\",\n",
+    "    \"../../../reference_designs/ceviche/mode_converter/converter_generator_circle_10_x47530832_w19_s483.csv\",\n",
     "    delimiter=\",\",\n",
     ")\n",
     "\n",
@@ -185,135 +185,6 @@
     "\n",
     "plot_mode_converter(component, params, response, aux)"
    ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "93874528",
-   "metadata": {},
-   "source": [
-    "## Mode converter optimization\n",
-    "\n",
-    "Now let's optimize a mode converter. To make things run quickly, we'll use the _lightweight_ version, which uses 40 nm grid spacing (rather than 10 nm) and only considers 1270 nm and 1290 nm wavelengths. We also obtain the initial parameters and define our loss function; here, we'll simply use the standard loss function defined by the challenge."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "5df7a111",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "challenge = challenges.ceviche_lightweight_mode_converter()\n",
-    "\n",
-    "params = challenge.component.init(jax.random.PRNGKey(0))\n",
-    "\n",
-    "\n",
-    "def loss_fn(params):\n",
-    "    response, aux = challenge.component.response(params)\n",
-    "    loss = challenge.loss(response)\n",
-    "    return loss, (response, aux)"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "f7ddb410",
-   "metadata": {},
-   "source": [
-    "To design the mode converter we'll use the `density_lbfgsb` optimizer from the [invrs-opt](https://github.com/invrs-io/opt) package. Initialize the optimizer state, and then define the `step_fn` which is called at each optimization step, and then simply call it repeatedly to obtain an optimized design."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "a844af25",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import invrs_opt\n",
-    "\n",
-    "opt = invrs_opt.density_lbfgsb(beta=4)\n",
-    "state = opt.init(params)  # Initialize optimizer state using the initial parameters.\n",
-    "\n",
-    "\n",
-    "@jax.jit\n",
-    "def step_fn(state):\n",
-    "    params = opt.params(state)\n",
-    "    (value, (response, aux)), grad = jax.value_and_grad(loss_fn, has_aux=True)(params)\n",
-    "    state = opt.update(grad=grad, value=value, params=params, state=state)\n",
-    "    return state, (params, value, response, aux)\n",
-    "\n",
-    "\n",
-    "# Call `step_fn` repeatedly to optimize, and store the results of each evaluation.\n",
-    "step_outputs = []\n",
-    "for _ in range(20):\n",
-    "    state, (params, value, response, aux) = step_fn(state)\n",
-    "    step_outputs.append((params, response, aux))"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "60ec4212",
-   "metadata": {},
-   "source": [
-    "Now let's visualize the results. At the first step, the design is roughly uniform and gray, corresponding to an intermediate material with permittivity between that of silicon and silicon oxide. This corresponds to a poor mode converter, with strong reflection and radiation losses."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "6040c30d",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "plot_mode_converter(challenge.component, *step_outputs[0])"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "b4492d0a",
-   "metadata": {},
-   "source": [
-    "After 20 optimization steps, the performance has become quite good, with low radiation loss and reflection. Note that the design is not fully binary and does contain some sharp features. In order to find high-quality designs that are also manufacturable, we'd need to use more sophisticated schemes such as in the papers referenced above."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "bd84d443",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "plot_mode_converter(challenge.component, *step_outputs[-1])"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "3d667cf0",
-   "metadata": {},
-   "source": [
-    "Now, let's plot the loss value and evaluation metric versus the optimization step. The evaluation metric is an independent measure of the quality of a solution, with larger values corresponding to better devices."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "e3b0c088",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "plt.figure(figsize=(11, 4))\n",
-    "ax = plt.subplot(121)\n",
-    "ax.semilogy([challenge.loss(s[1]) for s in step_outputs])\n",
-    "ax.grid(True)\n",
-    "ax.set_xlabel(\"step\")\n",
-    "ax.set_ylabel(\"loss\")\n",
-    "\n",
-    "ax = plt.subplot(122)\n",
-    "ax.plot([challenge.eval_metric(s[1]) for s in step_outputs])\n",
-    "ax.grid(True)\n",
-    "ax.set_xlabel(\"step\")\n",
-    "ax.set_ylabel(\"eval_metric\")"
-   ]
   }
  ],
  "metadata": {