socklight 0.2.0__tar.gz

socklight-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,81 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ !startsWith(github.ref, 'refs/tags/') }}
+
+# VACASK and openvaf-r (with the wasm32-unknown-emscripten target) come from
+# PyPI: vacask is a dependency, vacask-bin a build requirement (pyproject.toml).
+# cibuildwheel builds each wheel and runs the tests against the installed wheel,
+# natively and in Pyodide.
+jobs:
+  wheels-linux:
+    name: Wheels (${{ matrix.os }})
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-24.04, ubuntu-24.04-arm]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v6
+      - uses: pypa/cibuildwheel@v4.3.5
+      - uses: actions/upload-artifact@v6
+        with:
+          name: wheels-${{ matrix.os }}
+          path: wheelhouse/*.whl
+
+  wheels-pyodide:
+    # Pyodide 314 (Python 3.14, Emscripten 5.0.3), the Pyodide marimo ships.
+    name: Wheels (Pyodide)
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v6
+      - uses: pypa/cibuildwheel@v4.3.5
+        env:
+          CIBW_PLATFORM: pyodide
+          CIBW_BUILD: cp314-pyodide_wasm32
+      # PyPI accepts the PEP 783 tag only: fail here rather than mid-release.
+      - name: Check the platform tag
+        run: |
+          ls wheelhouse
+          ls wheelhouse/*-cp314-cp314-pyemscripten_2026_0_wasm32.whl
+      - uses: actions/upload-artifact@v6
+        with:
+          name: wheels-pyodide
+          path: wheelhouse/*.whl
+
+  sdist:
+    name: sdist
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v6
+      - run: pipx run build --sdist
+      - uses: actions/upload-artifact@v6
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  # Publishes on a v* tag. pypi.org must list this repository, this workflow
+  # file (ci.yml) and the environment "pypi" as a trusted publisher of socklight.
+  pypi:
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: [wheels-linux, wheels-pyodide, sdist]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/socklight
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v6
+        with:
+          path: dist
+          merge-multiple: true
+      - uses: pypa/gh-action-pypi-publish@release/v1

socklight-0.2.0/.gitignore

@@ -0,0 +1,21 @@
+.venv/
+__pycache__/
+*.pyc
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+# scikit-build-core editable.mode = "inplace" configures and builds in the source tree
+/.cmake/
+/.ninja_deps
+/.ninja_log
+/.skbuild-info.json
+/CMakeCache.txt
+/CMakeFiles/
+/CMakeInit.txt
+/build.ninja
+/cmake_install.cmake
+/src/socklight/socklight.osdi
+/src/socklight/va/
+/wheelhouse/
+/.pyodide_build/

socklight-0.2.0/CMakeLists.txt

@@ -0,0 +1,120 @@
+cmake_minimum_required(VERSION 3.18)
+project(socklight LANGUAGES C)
+
+# socklight.osdi: one OSDI device per model in socklight's Python registry.
+# Built against the Python headers only; the Py* symbols resolve from the
+# process that loads it (VACASK's Python extension), so libpython is not linked.
+find_package(Python 3.10 REQUIRED COMPONENTS Interpreter Development.Module)
+
+set(SOCKLIGHT_MAX_MODELS 1024 CACHE STRING "Descriptor slots in socklight.osdi (the most models one process can register)")
+if(NOT SOCKLIGHT_MAX_MODELS MATCHES "^[1-9][0-9]*$")
+  message(FATAL_ERROR "SOCKLIGHT_MAX_MODELS must be a positive integer, got '${SOCKLIGHT_MAX_MODELS}'")
+endif()
+
+# One SL_SLOT(k) line per descriptor slot; socklight_osdi.c expands it into the
+# slot's trampolines and their table.
+set(_slots "")
+math(EXPR _last "${SOCKLIGHT_MAX_MODELS} - 1")
+foreach(k RANGE 0 ${_last})
+  string(APPEND _slots "SL_SLOT(${k})\n")
+endforeach()
+set(_gen "${CMAKE_CURRENT_BINARY_DIR}/CMakeFiles/socklight_generated")
+file(CONFIGURE OUTPUT "${_gen}/sl_slots.inc" CONTENT "${_slots}")
+
+add_library(socklight_osdi MODULE
+  csrc/socklight_osdi.c
+  csrc/device.c
+  csrc/bridge.c
+)
+target_include_directories(socklight_osdi PRIVATE csrc "${_gen}")
+target_link_libraries(socklight_osdi PRIVATE Python::Module)
+target_compile_definitions(socklight_osdi PRIVATE SOCKLIGHT_MAX_MODELS=${SOCKLIGHT_MAX_MODELS})
+target_link_libraries(socklight_osdi PRIVATE m)
+set_target_properties(socklight_osdi PROPERTIES
+  OUTPUT_NAME socklight
+  PREFIX ""
+  SUFFIX ".osdi"
+  C_STANDARD 11
+  C_EXTENSIONS ON
+  C_VISIBILITY_PRESET hidden
+)
+if(CMAKE_C_COMPILER_ID MATCHES "GNU|Clang")
+  target_compile_options(socklight_osdi PRIVATE -Wall -Wextra)
+endif()
+if(CMAKE_SYSTEM_NAME STREQUAL "Emscripten")
+  # Pyodide: a WebAssembly side module, loaded by VACASK's dlopen like the native
+  # library. The Py* symbols stay undefined and resolve against the Pyodide main
+  # module, like any extension module's.
+  target_link_options(socklight_osdi PRIVATE -sSIDE_MODULE=1)
+endif()
+
+# scikit-build-core's editable.mode = "inplace" configures in the source
+# directory: put the library next to the package sources.
+if(CMAKE_BINARY_DIR STREQUAL CMAKE_SOURCE_DIR)
+  set_target_properties(socklight_osdi PROPERTIES
+    LIBRARY_OUTPUT_DIRECTORY "${CMAKE_SOURCE_DIR}/src/socklight")
+endif()
+
+install(TARGETS socklight_osdi LIBRARY DESTINATION socklight)
+
+# Verilog-A helpers (va/*.va), compiled with OpenVAF-reloaded into socklight/va/<name>.osdi.
+# Default: the openvaf-r that vacask-bin ships (a build requirement, see
+# pyproject.toml; since 0.3.4.dev5 it has the wasm32-unknown-emscripten target),
+# else openvaf-r on PATH.
+set(OPENVAF_COMPILER "" CACHE STRING "openvaf-r, the OpenVAF compiler used for va/*.va (name on PATH or full path; default: vacask-bin's)")
+if(NOT OPENVAF_COMPILER)
+  execute_process(
+    COMMAND "${Python_EXECUTABLE}" -c "import vacask_bin; print(vacask_bin.OPENVAF_CMD)"
+    OUTPUT_VARIABLE _vacask_bin_openvaf OUTPUT_STRIP_TRAILING_WHITESPACE
+    RESULT_VARIABLE _res ERROR_QUIET)
+  if(_res EQUAL 0 AND EXISTS "${_vacask_bin_openvaf}")
+    set(OPENVAF_COMPILER "${_vacask_bin_openvaf}")
+  else()
+    set(OPENVAF_COMPILER "openvaf-r")
+  endif()
+endif()
+message(STATUS "OpenVAF compiler: ${OPENVAF_COMPILER}")
+find_program(_openvaf NAMES "${OPENVAF_COMPILER}" REQUIRED NO_CMAKE_FIND_ROOT_PATH)
+# Extra openvaf-r arguments for the target, and the environment it runs in.
+# openvaf-r defaults to --target_cpu native: models built on one machine can then
+# die with "Illegal instruction" on another. Wheels must run anywhere.
+set(OPENVAF_TARGET_CPU "generic" CACHE STRING "CPU the va/*.va models are compiled for (openvaf-r --target_cpu; 'native' for local builds)")
+set(_openvaf_target --target_cpu "${OPENVAF_TARGET_CPU}")
+set(_openvaf_launcher "")
+if(CMAKE_SYSTEM_NAME STREQUAL "Emscripten")
+  # As VACASK's Pyodide build: the models become WebAssembly side modules,
+  # compiled for wasm32-unknown-emscripten and linked by the wasm-ld of the
+  # Emscripten SDK that builds socklight.osdi.
+  execute_process(COMMAND "${_openvaf}" --supported-targets
+    OUTPUT_VARIABLE _targets RESULT_VARIABLE _res)
+  if(NOT _res EQUAL 0 OR NOT _targets MATCHES "wasm32-unknown-emscripten")
+    message(FATAL_ERROR "${_openvaf} cannot compile for WebAssembly (no wasm32-unknown-emscripten target)")
+  endif()
+  get_filename_component(_cc_dir "${CMAKE_C_COMPILER}" DIRECTORY)
+  find_program(WASM_LD wasm-ld
+    HINTS "${EMSCRIPTEN_ROOT_PATH}/../bin" "$ENV{EMSDK}/upstream/bin" "${_cc_dir}/../bin"
+    NO_CMAKE_FIND_ROOT_PATH REQUIRED)
+  message(STATUS "WebAssembly linker for va/*.va: ${WASM_LD}")
+  set(_openvaf_target --target wasm32-unknown-emscripten)
+  set(_openvaf_launcher "${CMAKE_COMMAND}" -E env "OPENVAF_WASM_LD=${WASM_LD}")
+endif()
+if(CMAKE_BINARY_DIR STREQUAL CMAKE_SOURCE_DIR)
+  set(_va_out "${CMAKE_SOURCE_DIR}/src/socklight/va")
+else()
+  set(_va_out "${CMAKE_CURRENT_BINARY_DIR}/va")
+endif()
+file(MAKE_DIRECTORY "${_va_out}")
+set(_va_osdi "")
+foreach(_name optical_source optical_term photodetector heater)
+  set(_src "${CMAKE_CURRENT_SOURCE_DIR}/va/${_name}.va")
+  set(_dst "${_va_out}/${_name}.osdi")
+  add_custom_command(
+    OUTPUT "${_dst}"
+    COMMAND ${_openvaf_launcher} "${_openvaf}" ${_openvaf_target} "${_src}" -o "${_dst}"
+    DEPENDS "${_src}"
+    COMMENT "OpenVAF ${_name}.va"
+    VERBATIM)
+  list(APPEND _va_osdi "${_dst}")
+endforeach()
+add_custom_target(socklight_va ALL DEPENDS ${_va_osdi})
+install(FILES ${_va_osdi} DESTINATION socklight/va)

socklight-0.2.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2025 Floris Laporte
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

socklight-0.2.0/NOTICE

@@ -0,0 +1,7 @@
+socklight
+Copyright (c) socklight contributors
+
+This product includes software derived from sax (https://github.com/flaport/sax,
+as developed at gdsfactory/sax), commit c22ed91, licensed under the Apache License,
+Version 2.0. See LICENSE and VENDORED.md. Vendored files are modified: jax is replaced
+by numpy.

socklight-0.2.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.2
+Name: socklight
+Version: 0.2.0
+Summary: sax's optical model library on numpy, exposed to VACASK as OSDI devices
+License: Apache-2.0
+Requires-Python: >=3.10
+Requires-Dist: numpy
+Requires-Dist: vacask>=0.3.4.dev6
+

socklight-0.2.0/README.md

@@ -0,0 +1,216 @@
+# socklight
+
+sax's optical models on numpy, exposed to the VACASK circuit simulator as OSDI devices. Every
+model in socklight's Python registry becomes one device of `socklight.osdi`, which VACASK's
+Python extension loads like any other OSDI file. The design is in `docs/design.md`; the optical
+port convention is in `docs/iq-convention.md`.
+
+## Install
+
+```sh
+pip install socklight
+```
+
+Wheels exist for Linux (x86_64, aarch64; CPython 3.10–3.14) and for Pyodide 314
+(Python 3.14, the Pyodide marimo ships), where `micropip.install("socklight")` works the same.
+They pull in VACASK's Python extension (`vacask`).
+
+Building from source needs a C compiler and CMake. The Verilog-A helpers are compiled with
+the `openvaf-r` that `vacask-bin` (a build requirement) ships; pass `-DOPENVAF_COMPILER=...`
+through `CMAKE_ARGS` to use another one. For a development install:
+
+```sh
+pip install vacask-bin scikit-build-core pytest
+pip install -e . --no-build-isolation
+```
+
+`socklight.osdi` is built against the Python headers only and does not link libpython. It
+works only inside a Python process that has `vacask` imported. The standalone `vacask` binary
+cannot load it.
+
+## A minimal deck
+
+```python
+import socklight  # registers the standard library (socklight.models)
+
+netlist = f"""mmi demo
+ground 0
+load "{socklight.osdi_path()}"
+load "{socklight.va_path("optical_source")}"
+load "{socklight.va_path("optical_term")}"
+model src optical_source
+model term optical_term
+model mmi 'socklight.models:mmi2x2' loss_db=0.3
+s1 (o1_i o1_q) src p=1
+x1 (o1_i o1_q o2_i o2_q o3_i o3_q o4_i o4_q) mmi wl=1.55
+t2 (o2_i o2_q) term
+t3 (o3_i o3_q) term
+t4 (o4_i o4_q) term
+"""
+```
+
+Run it with the `vacask` Python API (parse, elaborate, run an `op` analysis); `tests/conftest.py`
+shows how.
+
+- The device name is the model's resource path, `package.module:callable`. VACASK identifiers
+  cannot contain `.` or `:`, so put it in single quotes on the `model` line.
+- Each optical port `p` has two terminals, `p_i p_q`. Ports are listed in `sorted()` order.
+  For `mmi2x2` that is `o1 o2 o3 o4`.
+- Every model parameter can be set on the `model` line or on an instance; the instance wins.
+  A parameter you don't set takes the Python signature default. A parameter whose default is
+  `None` is not passed to the model unless you set it.
+- Every numeric parameter is a real in the deck. One whose Python default is an `int` or `bool`
+  (e.g. `loss_dB_cm=3`) still accepts any real: the model gets an `int` when the value is
+  integral (`loss_db_cm=2` gives `2`) and a `float` otherwise (`loss_db_cm=2.5` gives `2.5`).
+- `socklight.va_path(name)` gives the Verilog-A helpers: `optical_source`, `optical_term`,
+  `photodetector` and `heater` (see `docs/iq-convention.md`).
+
+### Parameter names are lowercase
+
+VACASK lowercases device and parameter names when it loads an OSDI file. Netlists must
+write them in lowercase, including in sweeps. So sax's `loss_dB` is `loss_db` in a deck,
+as is `parameter="loss_db"` in a sweep. socklight still calls the model with the original
+`loss_dB`.
+
+## Your own models
+
+```python
+import socklight
+
+def ring(wl=1.55, kappa=0.1, loss_dB=0.0):
+    ...  # return a sax SDict at scalar wl
+
+socklight.register("mypdk.models:ring", ring)
+socklight.register_models("mypdk.models", {"ring": ring, "taper": taper})  # register() for each
+```
+
+Register every model **before** the first netlist loads `socklight.osdi`. Its constructor
+snapshots the registry once per process.
+
+- After that, registering a new name, or a model whose ports or parameters (names, kinds,
+  defaults) differ, raises `RuntimeError` naming what changed.
+- Registering the same signature again replaces the function. The next circuit setup uses
+  the new function, so a notebook can edit a model body without restarting.
+- `register()` validates up front. It raises on a malformed name, a parameter without a
+  default, two names or parameters that collide case-insensitively, and a probe call that
+  fails.
+
+## From a gdsfactory netlist
+
+`socklight.netlist.netlist_to_deck` turns a flat netlist, as `Component.get_netlist()` returns it,
+into a deck. It imports neither gdsfactory nor sax.
+
+```python
+from socklight.netlist import netlist_to_deck
+
+socklight.register_models("cspdk.si220", PDK.models)  # before any deck loads socklight.osdi
+deck = netlist_to_deck(c.get_netlist(), "cspdk.si220", params={"wl": 1.31})
+i, q = deck.external["o1"]  # nodes of external port o1: append a source here
+netlist = deck.text + f'load "{socklight.va_path("optical_source")}"\nmodel src optical_source\n' \
+    + f"s1 ({i} {q}) src p=1\n"  # ...and terms or photodetectors on the other external ports
+```
+
+- `models` is a prefix (component `coupler` uses `"cspdk.si220:coupler"`) or a mapping from
+  component to registered name. A component without a registered model raises `KeyError`.
+- An instance's parameters are its `settings` with `info` merged over them, as `sax.circuit`
+  does. Keys that are not parameters of the model are left out and listed in `deck.dropped`
+  (layout-only settings such as `width` or `npoints` are normal there). `None` means "use the
+  model's default".
+- `params` go to every instance whose model has that parameter, unless the instance sets it
+  itself: the instance wins.
+- `variables=("wl",)` is `params` by reference: each instance whose model has `wl` (and does not
+  set it) gets `wl=wl`, a VACASK circuit variable, so a single sweep moves every instance. A name
+  in both `params` and `variables` raises `ValueError`. `deck.variables` lists them; declare each
+  one before elaboration or VACASK will not resolve it:
+
+  socklight runs inside a Python process, and VACASK's Python API ignores a deck's `control`
+  block, so declare and sweep the variable through the API:
+
+  ```python
+  from vacask import (Circuit, OpenvafCompiler, Parser, ParserTables, Status, Value,
+                      Analysis, PTAnalysis, PTSave, PTSweep, PV, simulator)
+
+  deck = netlist_to_deck(c.get_netlist(), "cspdk.si220", variables=("wl",))
+  text = deck.text + "..."  # append sources and detectors
+
+  simulator.setup()
+  s = Status()
+  tab = ParserTables("models")
+  Parser(tab).parseNetlistString(text)
+  tab.verify(s)
+  compiler = OpenvafCompiler()
+  cir = Circuit(tab, compiler, s)
+  cir.setVariable("wl", Value(1.55))           # before elaborate
+  cir.elaborate([], "__topdef__", "__topinst__", status=s)
+
+  desc = PTAnalysis("op1", "op")
+  sweep = PTSweep("s")
+  sweep.add(PV("variable", "wl"))
+  sweep.add(PV("values", [1.50, 1.52, 1.55, 1.58, 1.60]))
+  desc.add(sweep)
+  analysis = Analysis.create(desc, cir, s)
+  analysis.add(PTSave("default"))
+  analysis.run(s)                               # writes op1.raw, one point per wavelength
+  ```
+
+  Keep `tab`, `compiler` and `desc` referenced until the run is done: with vacask 0.3.4.dev6 the
+  circuit and the analysis do not keep them alive themselves.
+- Each net is one node pair `n<k>_i n<k>_q`. An external port `p` is `p_i p_q` (sanitized if `p`
+  is not a VACASK identifier). An instance port that is on no net and not external is
+  terminated with `optical_term`. The deck always loads it as model `optical_term`, so appended
+  lines can use it.
+- The deck has no sources, detectors or analysis. Append them.
+
+## Errors
+
+VACASK reports only error codes for OSDI failures, so socklight records the details on the
+Python side:
+
+- `socklight.load_error()`: why `socklight.osdi` exported no devices (a registry over capacity
+  or a failed snapshot), else `None`.
+- `socklight.last_error()`: the last setup failure, as a dict with `model`, `params` and
+  `traceback`. Possible causes:
+  - the model raised;
+  - it returned a non-finite entry;
+  - its ports changed;
+  - `I + S` is singular;
+  - the instance connects too few terminals ("connected k of 2n terminals").
+
+  The simulation fails with "Fatal error during setup".
+
+## Sweeping wavelength
+
+`wl` is an ordinary parameter, so VACASK's own sweep works, whether `wl` is given on the
+instance, on the model line, or not at all:
+
+```
+control
+  sweep wl_sweep instance="x1" parameter="wl" values=[1.50, 1.52, 1.54, 1.55, 1.56]
+  analysis op1 op
+endc
+```
+
+Each point re-runs the device's setup, where the model is evaluated. `eval` and `load` never
+call Python. When the sweep finishes, VACASK restores the original value.
+`tests/test_native_sweep.py` builds such sweeps from Python. You can also re-elaborate one
+circuit per point, as `tests/test_sweep.py` does.
+
+## Examples and cross-checks
+
+- `examples/mzi_tia.py`: a heater-tuned MZI feeding a photodetector and a TIA built from VACASK's
+  bundled `opamp`. Sweeping the heater voltage from 0 to 4 V swings the TIA output between
+  about 0 V and -4.9 V.
+- `tools/circulax_heater.py`, run in a venv with jax, sax, circulax and cspdk (not socklight):
+  - It builds the same heater MZI in circulax with cspdk's `ThermalPhaseShifter` and writes
+    `tests/data/circulax_heater.json`. `tests/test_circulax.py` compares that file with the
+    VACASK run of the socklight heater.
+  - Over an 11-point sweep from 0 to 2 V, the two detector powers differ by at most 4.3e-9.
+    circulax against a closed-form numpy MZI also differs by 4.3e-9.
+  - Agreement is expected for the forward configuration only. circulax's heater is a VCVS and
+    is non-reciprocal at `o2`, so reverse drive is not compared.
+- Why the two ranges differ: the heater has R = 0.375 ohm/um × 320 um = 120 ohm, and its phase
+  is `dphi = pi × 12.5 × V^2 / 120`.
+  - 0 to 2 V gives up to 0.42 pi, part of one fringe. That is enough for a point-by-point
+    numerical comparison and keeps the circulax run small.
+  - 0 to 4 V gives up to 1.67 pi, so the demo passes through full extinction and shows the
+    TIA's whole output swing.