update docs

flaport · Jun 17, 2024 · 9109023 · 9109023
1 parent 33e4676
commit 9109023
Show file tree

Hide file tree

Showing 13 changed files with 51 additions and 88 deletions.
diff --git a/Makefile b/Makefile
@@ -17,8 +17,7 @@ dockerpush:
 
 .PHONY: docs
 docs:
-	sphinx-apidoc --force --no-toc --no-headings --implicit-namespaces --module-first --maxdepth 1 --output-dir docs/source sax
-	cd docs && make html
+	cd docs/source/ && make && cd .. && make html
 
 clean:
 	find . -name "modes" | xargs rm -rf

diff --git a/docs/source/index.md b/docs/source/index.md
@@ -18,13 +18,13 @@ examples/04_multimode_simulations.ipynb
 examples/05_thinfilm.ipynb
 examples/06_additive_backend.ipynb
 examples/07_layout_aware.ipynb
+examples/08_sparse_coo.ipynb
 ```
 
 ```{toctree}
 :caption: 'Library Internals'
 :maxdepth: 2
 
-internals/00_typing.ipynb
 internals/01_models.ipynb
 internals/02_circuit.ipynb
 internals/03_backends.ipynb

diff --git a/docs/source/sax.loss.rst b/docs/source/sax.loss.rst
@@ -0,0 +1,7 @@
+sax.loss module
+===============
+
+.. automodule:: sax.loss
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/sax.nn.core.rst b/docs/source/sax.nn.core.rst
diff --git a/docs/source/sax.nn.io.rst b/docs/source/sax.nn.io.rst
diff --git a/docs/source/sax.nn.loss.rst b/docs/source/sax.nn.loss.rst
diff --git a/docs/source/sax.nn.rst b/docs/source/sax.nn.rst
diff --git a/docs/source/sax.nn.utils.rst b/docs/source/sax.nn.utils.rst
diff --git a/docs/source/sax.patched.rst b/docs/source/sax.patched.rst
diff --git a/docs/source/sax.rst b/docs/source/sax.rst
@@ -8,7 +8,6 @@ Subpackages
    :maxdepth: 4
 
    sax.backends
-   sax.nn
 
 Submodules
 ----------
@@ -17,10 +16,10 @@ Submodules
    :maxdepth: 4
 
    sax.circuit
+   sax.loss
    sax.models
    sax.multimode
    sax.netlist
-   sax.patched
    sax.saxtypes
    sax.utils
 

diff --git a/examples/07_layout_aware.ipynb b/examples/07_layout_aware.ipynb
@@ -18,6 +18,16 @@
     "> Towards layout-aware optimization and monte-carlo simulations"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "a217989b-2a54-4c23-a9d9-a998cbab43d9",
+   "metadata": {},
+   "source": [
+    ":::{note}\n",
+    "This notebook is currently broken. It should run normally again when [this GDSFactory issue](https://github.com/gdsfactory/gdsfactory/issues/2881) is resolved.\n",
+    ":::"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,

diff --git a/examples/08_sparse_coo.ipynb b/examples/08_sparse_coo.ipynb
@@ -14,7 +14,7 @@
     "tags": []
    },
    "source": [
-    "## Sparse COO"
+    "# Sparse COO"
    ]
   },
   {

diff --git a/internals/03_backends.ipynb b/internals/03_backends.ipynb
@@ -75,17 +75,17 @@
    "source": [
     "SAX allows to easily interchange the backend of a circuit. A SAX backend consists of two static analysis steps and an evaluation step:\n",
     "\n",
-    ":::{eval-rst}\n",
+    "```{eval-rst}\n",
     ".. autofunction:: sax.backends.analyze_instances\n",
-    ":::\n",
+    "```\n",
     "\n",
-    ":::{eval-rst}\n",
+    "```{eval-rst}\n",
     ".. autofunction:: sax.backends.analyze_circuit\n",
-    ":::\n",
+    "```\n",
     "\n",
-    ":::{eval-rst}\n",
+    "```{eval-rst}\n",
     ".. autofunction:: sax.backends.evaluate_circuit\n",
-    ":::"
+    "```"
    ]
   },
   {
@@ -104,11 +104,15 @@
    "source": [
     "The `analyze_instances` step analyzes the 'shape' of the instances by running each model with default parameters. By shape we mean which port-combinations are present in the sparse S-matrix.\n",
     "\n",
-    "> QUESTION: can we do this more efficiently in a functional way?\n",
+    ":::{warning}\n",
+    "QUESTION: can we do this more efficiently in a functional way?\n",
+    ":::\n",
     "\n",
     "After analyzing the instances, it is assumed that the shape of the instance won't change any more. **It is therefore important that you write your model functions in such a way that the port combinations present in your s-matrix *never* changes!**\n",
     "\n",
-    "> NOTE: we used to do this analysis step in `analyze_circuit` by just looking at the connections present. However, this inherently assumed dense connectivity within the model. This is pretty inefficient for large sparse models with many ports. Ideally, however, we should be able to analyze the shape of our instances without running their models with default parameters..."
+    ":::{note}\n",
+    "we used to do this analysis step in `analyze_circuit` by just looking at the connections present. However, this inherently assumed dense connectivity within the model. This is pretty inefficient for large sparse models with many ports. Ideally, however, we should be able to analyze the shape of our instances without running their models with default parameters...\n",
+    ":::"
    ]
   },
   {
@@ -125,7 +129,7 @@
     "tags": []
    },
    "source": [
-    "The `analyze_circuit` step should statically analyze the connections and ports and should return an `analyzed` object. This object contains all the static objects that are needed for circuit computation but won't be recalculated when any parameters of the circuit change. See [KLU backend](#klu-backend) for a non-trivial implementation of the circuit analyzation.\n",
+    "The `analyze_circuit` step should statically analyze the connections and ports and should return an `analyzed` object. This object contains all the static objects that are needed for circuit computation but won't be recalculated when any parameters of the circuit change. See KLU Backend (below) for a non-trivial implementation of the circuit analyzation.\n",
     "\n",
     "The `evaluate_circuit` step evaluates the circuit for given `SType` instances, given whatever analysis object was returned from the `analyze_circuit` step and the instance `SType`s."
    ]
@@ -259,13 +263,13 @@
     "\n",
     "> Filipsson, Gunnar. \"*A new general computer algorithm for S-matrix calculation of interconnected multiports.*\" 11th European Microwave Conference. IEEE, 1981.\n",
     "\n",
-    ":::{eval-rst}\n",
+    "```{eval-rst}\n",
     ".. autofunction:: sax.backends.analyze_circuit_fg\n",
-    ":::\n",
+    "```\n",
     "\n",
-    ":::{eval-rst}\n",
+    "```{eval-rst}\n",
     ".. autofunction:: sax.backends.evaluate_circuit_fg\n",
-    ":::"
+    "```"
    ]
   },
   {
@@ -772,7 +776,7 @@
     "tags": []
    },
    "source": [
-    "Now the [Gunnar Algorithm](#citation) is used. Given a (block-diagonal) 'S-matrix' `block_diag` and a 'connection matrix' `current_ports` we can interconnect port `k` and `l` as follows:\n",
+    "Now the Gunnar Algorithm is used. Given a (block-diagonal) 'S-matrix' `block_diag` and a 'connection matrix' `current_ports` we can interconnect port `k` and `l` as follows:\n",
     "\n",
     "> Note: some creative freedom is used here. In SAX, the matrices we're talking about are in fact represented by a sparse dictionary (an `SDict`), i.e. similar to a COO sparse matrix for which the indices are the port names."
    ]
@@ -1105,13 +1109,13 @@
     "\n",
     "> Ekanathan Palamadai Natariajan. \"*KLU - A high performance sparse linear solver for circuit simulation problems.*\"\n",
     "\n",
-    ":::{eval-rst}\n",
+    "```{eval-rst}\n",
     ".. autofunction:: sax.backends.analyze_circuit_klu\n",
-    ":::\n",
+    "```\n",
     "\n",
-    ":::{eval-rst}\n",
+    "```{eval-rst}\n",
     ".. autofunction:: sax.backends.evaluate_circuit_klu\n",
-    ":::"
+    "```"
    ]
   },
   {
@@ -1333,13 +1337,13 @@
    "source": [
     "### Sparse Helper Functions\n",
     "\n",
-    ":::{eval-rst}\n",
+    "```{eval-rst}\n",
     ".. autofunction:: klujax.solve\n",
-    ":::\n",
+    "```\n",
     "\n",
-    ":::{eval-rst}\n",
+    "```{eval-rst}\n",
     ".. autofunction:: klujax.coo_mul_vec\n",
-    ":::"
+    "```"
    ]
   },
   {
@@ -2842,13 +2846,13 @@
    "source": [
     "## Additive Backend\n",
     "\n",
-    ":::{eval-rst}\n",
+    "```{eval-rst}\n",
     ".. autofunction:: sax.backends.analyze_circuit_additive\n",
-    ":::\n",
+    "```\n",
     "\n",
-    ":::{eval-rst}\n",
+    "```{eval-rst}\n",
     ".. autofunction:: sax.backends.evaluate_circuit_additive\n",
-    ":::\n",
+    "```\n",
     "\n",
     "Sometimes we would like to calculate circuit path lengths or time delays within a circuit. We could obviously simulate these things with a time domain simulator, but in many cases a simple additive backend (as opposed to the default multiplicative backend) can suffice."
    ]