Merge pull request #217 from angelPappas/models_documentation

Models documentation

Author: joamatab

.github/write_models.py

@@ -0,0 +1,52 @@
+"""Write model documentation."""
+
+from jinja2 import Environment, FileSystemLoader
+
+import qpdk
+from qpdk.config import PATH
+
+filepath_models = PATH.docs / "models.rst"
+template_dir = PATH.docs / "templates"
+
+# Models that should NOT be plotted
+skip_plots = {
+    "gamma_0_load",
+    "launcher",
+    "resonator_frequency",
+    "single_admittance_element",
+    "single_impedance_element",
+}
+
+# Collect all public functions/classes in qpdk.models
+models = {
+    name: obj
+    for name, obj in qpdk.models.__dict__.items()
+    if callable(obj) and not name.startswith("_")
+}
+
+# Prepare items for the template
+items = [
+    {
+        "title": "Models",
+        "automodule": "qpdk.models",
+        "synopsis": "Code for S-parameter and other modelling",
+        "members": True,
+        "undoc_members": True,
+        "show_inheritance": True,
+        "functions": sorted(models.keys()),  # preserves order
+        "skip_plots": skip_plots,
+    },
+    {
+        "title": "References",
+        "bibliography_filter": "docname in docnames",
+    },
+]
+
+# Setup Jinja2
+env = Environment(loader=FileSystemLoader(template_dir), autoescape=False)
+template = env.get_template("models_static.rst.j2")
+
+rendered = template.render(items=items)
+
+with filepath_models.open("w") as f:
+    f.write(rendered)

.gitignore

@@ -156,6 +156,7 @@ cython_debug/
 
 # Documentation
 docs/cells.rst
+docs/models.rst
 docs/samples.rst
 docs/notebooks/
 docs/makefile_help.txt

Makefile

@@ -1,4 +1,4 @@
-.PHONY: all build clean convert-notebooks copy-sample-notebooks docs docs-latex docs-pdf git-rm-merged help install rm-samples run-pre setup-ipython-config test test-fail-fast test-force test-gds test-gds-fail-fast test-gds-force update-pre write-cells write-makefile-help
+.PHONY: all build clean convert-notebooks copy-sample-notebooks docs docs-latex docs-pdf git-rm-merged help install rm-samples run-pre setup-ipython-config test test-fail-fast test-force test-gds test-gds-fail-fast test-gds-force update-pre write-cells write-makefile-help write-models
 
 # Based on https://gist.github.com/prwhite/8168133?permalink_comment_id=4718682#gistcomment-4718682
 help: ##@ (Default) Print listing of key targets with their descriptions
@@ -61,6 +61,9 @@ build: ##@ Build the Python package (install build tool and create dist)
 write-cells: ##@ Write cell outputs into documentation notebooks (used when building docs)
 	uv run --group docs .github/write_cells.py
 
+write-models: ##@ Write model outputs into documentation notebooks (used when building docs)
+	uv run --group docs .github/write_models.py
+
 write-makefile-help: ##@ Write Makefile help output to documentation
 	uv run --group docs .github/write_makefile_help.py
 
@@ -77,10 +80,10 @@ setup-ipython-config: ##@ Setup IPython configuration for documentation build
 	mkdir -p ~/.config/matplotlib/stylelib/
 	cp docs/qpdk.mplstyle ~/.config/matplotlib/stylelib/qpdk.mplstyle
 
-docs: write-cells write-makefile-help copy-sample-notebooks ##@ Build the HTML documentation
+docs: write-cells write-models write-makefile-help copy-sample-notebooks ##@ Build the HTML documentation
 	uv run --group docs jb build docs
 
-docs-latex: write-cells write-makefile-help copy-sample-notebooks ##@ Setup LaTeX for PDF documentation
+docs-latex: write-cells write-models write-makefile-help copy-sample-notebooks ##@ Setup LaTeX for PDF documentation
 	uv run --group docs jb build docs --builder latex
 
 docs-pdf: docs-latex ##@ Build PDF documentation (requires a TeXLive installation)

docs/models.rst

@@ -0,0 +1,46 @@
+{{ items[0].title }}
+{{ "=" * items[0].title | length }}
+
+{% for func_name in items[0].functions %}
+
+{{ func_name }}
+{{ "-" * func_name | length }}
+
+.. autofunction:: qpdk.models.{{ func_name }}
+
+{% if func_name not in items[0].skip_plots %}
+.. plot::
+   :include-source:
+
+   import jax.numpy as jnp
+   import matplotlib.pyplot as plt
+   from qpdk.models import {{ func_name }}
+   from qpdk import PDK
+
+   PDK.activate()
+
+   freq = jnp.linspace(2e9, 8e9, 501)
+   freq_ghz = freq / 1e9
+   s_model = {{ func_name }}(f=freq)
+
+   plt.figure()
+   plt.title("{{ func_name }}", fontsize=14)
+
+   for (pout, pin), sij in s_model.items():
+    i = int(pout[-1])  # "o2" -> 2
+    j = int(pin[-1])   # "o1" -> 1
+
+    if i >= j:
+        plt.plot(
+            freq_ghz,
+            20 * jnp.log10(jnp.abs(sij)),
+            label = "$S_{" + str(i) + str(j) + "}$"
+        )
+   plt.xlabel("Frequency [GHz]", fontsize=12)
+   plt.ylabel("Magnitude [dB]", fontsize=12)
+   plt.grid(True)
+   plt.legend()
+   plt.show()
+{% endif %}
+
+{% endfor %}

docs/templates/models_static.rst.j2

@@ -56,7 +56,14 @@ def short(
 
 
 def short_2_port(f: ArrayLike = jnp.array([5e9])) -> sax.SType:
-    """Electrical short 2-port connection Sax model."""
+    """Electrical short 2-port connection Sax model.
+
+    Args:
+        f: Array of frequency points in Hz
+
+    Returns:
+        sax.SType: S-parameters dictionary
+    """
     return short(f=f, n_ports=2)
 
 

qpdk/models/generic.py

@@ -66,6 +66,14 @@ def straight_shorted(
     Note:
         The port ``o2`` is internally shorted and should not be used.
         It seems to be a Sax limitation that we need to define at least two ports.
+
+    Args:
+        **kwargs
+            Keyword arguments forwarded to :func:`qpdk.models.straight`.
+            See :class:`StraightModelKwargs` for the supported parameters.
+
+    Returns:
+        sax.SType: S-parameters dictionary
     """
     circuit, _ = sax.circuit(
         netlist={
@@ -97,23 +105,59 @@ def bend_circular(
     *args: Any,
     **kwargs: Unpack[StraightModelKwargs],
 ) -> sax.SType:
-    """S-parameter model for a circular bend, wrapped to to :func:`~straight`."""
+    """S-parameter model for a circular bend, wrapped to to :func:`~straight`.
+
+    Args:
+        *args:
+            Positional arguments forwarded directly to :func:`straight`.
+
+        **kwargs:
+            Keyword arguments forwarded directly to :func:`straight`.
+            See :class:`StraightModelKwargs` for the supported parameters.
+
+    Returns:
+        sax.SType: S-parameters dictionary
+    """
     return straight(*args, **kwargs)  # pyrefly: ignore[bad-keyword-argument]
 
 
 def bend_euler(
     *args: Any,
     **kwargs: Unpack[StraightModelKwargs],
 ) -> sax.SType:
-    """S-parameter model for an Euler bend, wrapped to to :func:`~straight`."""
+    """S-parameter model for an Euler bend, wrapped to to :func:`~straight`.
+
+    Args:
+        *args:
+            Positional arguments forwarded directly to :func:`straight`.
+
+        **kwargs:
+            Keyword arguments forwarded directly to :func:`straight`.
+            See :class:`StraightModelKwargs` for the supported parameters.
+
+    Returns:
+        sax.SType: S-parameters dictionary
+    """
     return straight(*args, **kwargs)  # pyrefly: ignore[bad-keyword-argument]
 
 
 def bend_s(
     *args: Any,
     **kwargs: Unpack[StraightModelKwargs],
 ) -> sax.SType:
-    """S-parameter model for an S-bend, wrapped to to :func:`~straight`."""
+    """S-parameter model for an S-bend, wrapped to to :func:`~straight`.
+
+    Args:
+        *args:
+            Positional arguments forwarded directly to :func:`straight`.
+
+        **kwargs:
+            Keyword arguments forwarded directly to :func:`straight`.
+            See :class:`StraightModelKwargs` for the supported parameters.
+
+    Returns:
+        sax.SType: S-parameters dictionary
+    """
     return straight(*args, **kwargs)  # pyrefly: ignore[bad-keyword-argument]
 
 
@@ -135,6 +179,9 @@ def taper_cross_section(
         cross_section_1: Cross-section for the start of the taper.
         cross_section_2: Cross-section for the end of the taper.
         n_points: Number of segments to divide the taper into for simulation.
+
+    Returns:
+        sax.SType: S-parameters dictionary
     """
     # Ensure n_points is a concrete Python int
 
@@ -212,7 +259,19 @@ def rectangle(
     *args: Any,
     **kwargs: Unpack[StraightModelKwargs],
 ) -> sax.SType:
-    """S-parameter model for a rectangular section, wrapped to to :func:`~straight`."""
+    """S-parameter model for a rectangular section, wrapped to to :func:`~straight`.
+
+    Args:
+        *args:
+            Positional arguments forwarded directly to :func:`straight`.
+
+        **kwargs:
+            Keyword arguments forwarded directly to :func:`straight`.
+            See :class:`StraightModelKwargs` for the supported parameters.
+
+    Returns:
+        sax.SType: S-parameters dictionary
+    """
     return straight(*args, **kwargs)  # pyrefly: ignore[bad-keyword-argument]