paramrf 0.35.3__tar.gz → 0.36.0__tar.gz

{paramrf-0.35.3 → paramrf-0.36.0}/.github/workflows/docs.yml

@@ -3,6 +3,7 @@ name: Deploy Sphinx Docs
 on:
   push:
     branches: [main]
+    tags: [ "v*" ]
 
 permissions:
   contents: write
@@ -27,7 +28,6 @@ jobs:
     - name: Install dependencies
       run: |
         pip install -e ".[docs]"
-        pip install "git+https://github.com/gvcallen/distreqx.git"
 
     - name: Build docs
       run: |

paramrf-0.36.0/.github/workflows/tests.yml

@@ -0,0 +1,62 @@
+name: Run Tests
+
+on:
+  push:
+    branches: [main]
+    tags: [ "v*" ]
+    paths-ignore:
+      - "docs/**"
+      - "paper/**"
+      - "**.md"
+      - "**.rst"
+  pull_request:
+    branches: [main]
+    paths-ignore:
+      - "docs/**"
+      - "paper/**"
+      - "**.md"
+      - "**.rst"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout repo
+      uses: actions/checkout@v4
+
+    - name: Install Compilers and MPI
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y gfortran libopenmpi-dev openmpi-bin
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+        cache: pip
+        cache-dependency-path: pyproject.toml
+
+    - name: Install dependencies and smoke test package import
+      run: scripts/install-test-deps.sh
+
+    # Each run saves under its own key and restores the newest earlier one, so the cache
+    # follows the code. conftest.py caps its size.
+    - name: Restore JAX compilation cache
+      uses: actions/cache@v4
+      with:
+        path: .jax_cache
+        key: jax-${{ runner.os }}-${{ hashFiles('pyproject.toml') }}-${{ github.sha }}
+        restore-keys: |
+          jax-${{ runner.os }}-${{ hashFiles('pyproject.toml') }}-
+          jax-${{ runner.os }}-
+
+    - name: Run Pytest
+      run: |
+        python -m pytest -rs -n auto
+      env:
+        PMRF_TESTS_NO_SKIPS: "1"

{paramrf-0.35.3 → paramrf-0.36.0}/.gitignore

@@ -190,3 +190,6 @@ skills-lock.json
 .secrets/
 *.token
 .env.local
+
+# JAX persistent compilation cache (tests/conftest.py)
+.jax_cache/

paramrf-0.36.0/AGENTS.md

@@ -0,0 +1,90 @@
+# AGENTS.md
+
+**ParamRF** (`pmrf`) is a JAX-native RF modelling framework: frequency-domain circuit
+simulation, optimisation, fitting, and inference. Models are Equinox modules — immutable
+dataclasses that are also JAX PyTrees. Built on `jax`, `equinox`, and
+[`parax`](https://gvcallen.github.io/parax) (the parameter/constraint layer).
+
+## Breaking changes are fine
+
+Pre-1.0. No backwards-compatibility shims, deprecation aliases or legacy code paths
+unless asked. Prefer the clean design, within the issue's seam.
+
+## Seams
+
+Each issue names one seam: a file, a set of files, or a folder. If the work needs a
+change outside it, stop and ask.
+
+`CONTEXT.md` and ADRs (architecture decision records, `docs/adr/`) are edited only by
+the reviewer, in their own commit. If you need a domain term that isn't in the issue,
+an ADR or `CONTEXT.md`, that's a design decision: stop and ask.
+
+Start every PR body with `## Cross-seam`, listing each file changed outside the issue's
+seam with the ADR or issue line that allows it, or `DECISION NEEDED`. Write `none` if
+there are none.
+
+## Commands
+
+```bash
+.venv/bin/python -m pytest tests/test_x.py  # the tests covering a change, while working
+.venv/bin/python -m pytest -n 4            # local test command: full suite, once before committing
+.venv/bin/python -c "import pmrf"          # import smoke check
+```
+
+CI runs the full suite on every PR. Compilation dominates test time, so `tests/conftest.py`
+keeps JAX's persistent compilation cache in `.jax_cache/`: the first run fills it (about 4 min
+with `-n 4`) and later runs take about 2 min. Deleting it is always safe.
+
+No linter or formatter is configured. Match the style of surrounding code.
+
+## Commits
+
+Do not add yourself as an author. No `Co-Authored-By` trailer, no session link, no
+tool attribution.
+
+## Source layout
+
+Real code lives in `pmrf/`. `build/` and `dist/` hold stale copies of it — searches will
+hit them, but never read or edit them as source.
+
+## Naming
+
+- `Solver` — reserved for classes that actually solve a system (`GlobalMNACircuitSolver`).
+- `Formulation` — closed-form physics strategy objects.
+- `Abstract` — prefixes an ABC unless it is domain terminology. `Model` is the exception.
+
+## Documentation
+
+Numpydoc docstrings. Maths is written `$$...$$` and rendered by `sphinx-math-dollar`.
+Physics classes carry a `**Mathematical Formulation**` section stating the equations they
+implement and a `References` section citing the source paper; match that. Fields are
+documented with `#:` comments directly above them.
+
+## Tests
+
+`tests/` mirrors the package. When touching physics, validate against `scikit-rf` rather
+than against recorded ParamRF output, which only locks in current behaviour. Record
+tolerances per case; do not loosen a global tolerance to make one case pass.
+
+**scikit-rf is guidance, not ground truth.** It makes its own approximations and
+modelling choices, and it has been wrong before. When a comparison disagrees, read the
+scikit-rf source (not just its docstring) and check both implementations against the
+cited paper. If ParamRF is wrong, fix it; if scikit-rf is, or the two deliberately model
+different things, say so in the test with the reason. Never widen a tolerance until the
+difference is explained.
+
+## Issues and docs
+
+### Issue tracker
+
+Issues live as GitHub issues on `gvcallen/paramrf`, managed with the `gh` CLI. See
+`docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+One `CONTEXT.md` and one `docs/adr/` at the repo root; either may not exist yet. See
+`docs/agents/domain.md`.

paramrf-0.36.0/CLAUDE.md

@@ -0,0 +1,90 @@
+# AGENTS.md
+
+**ParamRF** (`pmrf`) is a JAX-native RF modelling framework: frequency-domain circuit
+simulation, optimisation, fitting, and inference. Models are Equinox modules — immutable
+dataclasses that are also JAX PyTrees. Built on `jax`, `equinox`, and
+[`parax`](https://gvcallen.github.io/parax) (the parameter/constraint layer).
+
+## Breaking changes are fine
+
+Pre-1.0. No backwards-compatibility shims, deprecation aliases or legacy code paths
+unless asked. Prefer the clean design, within the issue's seam.
+
+## Seams
+
+Each issue names one seam: a file, a set of files, or a folder. If the work needs a
+change outside it, stop and ask.
+
+`CONTEXT.md` and ADRs (architecture decision records, `docs/adr/`) are edited only by
+the reviewer, in their own commit. If you need a domain term that isn't in the issue,
+an ADR or `CONTEXT.md`, that's a design decision: stop and ask.
+
+Start every PR body with `## Cross-seam`, listing each file changed outside the issue's
+seam with the ADR or issue line that allows it, or `DECISION NEEDED`. Write `none` if
+there are none.
+
+## Commands
+
+```bash
+.venv/bin/python -m pytest tests/test_x.py  # the tests covering a change, while working
+.venv/bin/python -m pytest -n 4            # local test command: full suite, once before committing
+.venv/bin/python -c "import pmrf"          # import smoke check
+```
+
+CI runs the full suite on every PR. Compilation dominates test time, so `tests/conftest.py`
+keeps JAX's persistent compilation cache in `.jax_cache/`: the first run fills it (about 4 min
+with `-n 4`) and later runs take about 2 min. Deleting it is always safe.
+
+No linter or formatter is configured. Match the style of surrounding code.
+
+## Commits
+
+Do not add yourself as an author. No `Co-Authored-By` trailer, no session link, no
+tool attribution.
+
+## Source layout
+
+Real code lives in `pmrf/`. `build/` and `dist/` hold stale copies of it — searches will
+hit them, but never read or edit them as source.
+
+## Naming
+
+- `Solver` — reserved for classes that actually solve a system (`GlobalMNACircuitSolver`).
+- `Formulation` — closed-form physics strategy objects.
+- `Abstract` — prefixes an ABC unless it is domain terminology. `Model` is the exception.
+
+## Documentation
+
+Numpydoc docstrings. Maths is written `$$...$$` and rendered by `sphinx-math-dollar`.
+Physics classes carry a `**Mathematical Formulation**` section stating the equations they
+implement and a `References` section citing the source paper; match that. Fields are
+documented with `#:` comments directly above them.
+
+## Tests
+
+`tests/` mirrors the package. When touching physics, validate against `scikit-rf` rather
+than against recorded ParamRF output, which only locks in current behaviour. Record
+tolerances per case; do not loosen a global tolerance to make one case pass.
+
+**scikit-rf is guidance, not ground truth.** It makes its own approximations and
+modelling choices, and it has been wrong before. When a comparison disagrees, read the
+scikit-rf source (not just its docstring) and check both implementations against the
+cited paper. If ParamRF is wrong, fix it; if scikit-rf is, or the two deliberately model
+different things, say so in the test with the reason. Never widen a tolerance until the
+difference is explained.
+
+## Issues and docs
+
+### Issue tracker
+
+Issues live as GitHub issues on `gvcallen/paramrf`, managed with the `gh` CLI. See
+`docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+One `CONTEXT.md` and one `docs/adr/` at the repo root; either may not exist yet. See
+`docs/agents/domain.md`.

{paramrf-0.35.3 → paramrf-0.36.0}/CONTEXT.md

@@ -20,6 +20,8 @@ for saved results, ties and selectors.
 Where a parameter's number lives. Every surface defaults to **declared**.
 
 - **raw**: the latent, unbounded array optimisers and samplers move through.
+  ParamRF defines it: a parameter's prior whitens it, and attaching a joint
+  prior redefines it for the parameters under that prior (ADR-0005).
 - **declared**: the number as written, in the units the parameter's scale
   declares (2.0 for 2 pF). Construction, bounds, priors and `Param.value` are
   in declared space.
@@ -54,6 +56,44 @@ dataclass field replace, not an update.
 
 *Avoid:* "set values", "with values"; "update" for an optimiser step.
 
+### Tie and resolve
+
+`prf.tie` derives one part of a tree from another: the **target** is removed from
+the parameters and recomputed as `fn(source)` whenever the tree is resolved, so
+it follows the source through `prf.update`, optimisation and sampling. Target
+and source are selected by name, on either side, and a name that picks a
+sub-model ties the parameters beneath it, pairing by suffix.
+
+Two operations read a tied tree back, and they are not the same thing.
+
+- **Resolve** (`prf.resolve`): structural. Ties are applied and every wrapper
+  that only describes structure is discharged; parameters stay parameters. A
+  container resolves to its own shape, so a `dict` of components comes back a
+  `dict`, still parameterised.
+- **Evaluation** (`prf.unwrap`): every parameter becomes its physical value.
+  The result is numbers, not priors, and nothing rebuilt from it is
+  parameterised. A joint prior is dropped the same way and for the same
+  reason, so resolve leaves it standing.
+
+Resolve is the one ordinary modelling code wants; `prf.unwrap` is a low-level
+evaluation primitive. A tie's target resolves to a plain value either way — it
+is derived, so it has no prior of its own.
+
+*Avoid:* "unwrap" for reading a tied container; "apply the ties" for evaluation.
+
+### Prior and joint prior
+
+`prf.prior` attaches a prior to the parameters a selector picks (ADR-0005). A
+scalar distribution gives each of them its own prior. A distribution whose
+event size equals the number of parameters is a **joint prior** over them: a
+wrapper (`prf.modules.Probabilistic`) around the unchanged tree, so every
+parameter keeps its name. A joint prior replaces its parameters' own priors,
+and its `space` says which space its distribution is over. Raw space for its
+parameters becomes the distribution's whitened space.
+
+*Avoid:* "covered parameters" (say "the parameters under a joint prior");
+"joint target" (the old collapsing node).
+
 ### Derived model
 
 A model computed from a **base** model and **new parameters** by a function,
@@ -66,7 +106,7 @@ named by its keyword. Used to derive a more complete model from a nominal one
 
 ### Parameter values
 
-`prf.param_values`: a name-keyed dict of arrays in one space, the form values
+`prf.values`: a name-keyed dict of arrays in one space, the form values
 take when crossing ParamRF's boundary. Not flattened; a 1-D vector exists only
 inside adapters that need one.
 
@@ -142,4 +182,6 @@ paper with no ParamRF objects in sight.
 `docs/adr/` records the decisions behind these layers. Read
 `docs/adr/0001-line-modelling-architecture.md` before changing a strategy
 interface or a default, and `docs/adr/0002-parameter-api.md` before adding a
-method, a public function or a value space.
+method, a public function or a value space. Read
+`docs/adr/0005-priors-by-name.md` before changing how priors are attached or
+scored.

{paramrf-0.35.3 → paramrf-0.36.0}/CONTRIBUTING.md

@@ -8,7 +8,7 @@ ParamRF builds on top of JAX and Equinox's functional style. If you are coming f
 
 1. **Fork and Clone:** Fork the repository on GitHub and clone it locally.
 2. **Virtual Environment:** Set up a virtual environment using Python 3.11+.
-3. **Install Dependencies:** Install the package in editable mode with the same test environment CI uses, including the pinned `distreqx` fork, PolyChord and blackjax. PolyChord needs Fortran and MPI compilers (like `mpifort` and `mpicxx`):
+3. **Install Dependencies:** Install the package in editable mode with the same test environment CI uses, including PolyChord and blackjax. PolyChord needs Fortran and MPI compilers (like `mpifort` and `mpicxx`):
 
     scripts/install-test-deps.sh
     pip install -e .[docs]

{paramrf-0.35.3 → paramrf-0.36.0}/PKG-INFO

@@ -1,19 +1,18 @@
 Metadata-Version: 2.4
 Name: paramrf
-Version: 0.35.3
+Version: 0.36.0
 Summary: Parametric radio frequency modeling
 Author-email: Gary Allen <gvcallen@gmail.com>
 Project-URL: homepage, https://github.com/gvcallen/paramrf
 Description-Content-Type: text/x-rst
 License-File: LICENSE
 License-File: NOTICE
-Requires-Dist: parax>=0.10.8
+Requires-Dist: parax>=0.11.1
 Requires-Dist: threadpoolctl
 Requires-Dist: eqxpress
 Requires-Dist: jax
 Requires-Dist: jaxtyping
 Requires-Dist: equinox
-Requires-Dist: distreqx
 Requires-Dist: optimistix
 Requires-Dist: lineax
 Requires-Dist: jaxopt
@@ -35,11 +34,14 @@ Requires-Dist: matplotlib; extra == "docs"
 Requires-Dist: jupyter-sphinx; extra == "docs"
 Provides-Extra: tests
 Requires-Dist: pytest; extra == "tests"
+Requires-Dist: pytest-xdist; extra == "tests"
+Requires-Dist: filelock; extra == "tests"
 Requires-Dist: ipython; extra == "tests"
 Requires-Dist: scikit-rf; extra == "tests"
 Requires-Dist: anesthetic; extra == "tests"
 Requires-Dist: mpi4py; extra == "tests"
 Requires-Dist: blackjax; extra == "tests"
+Requires-Dist: fleqx; extra == "tests"
 Dynamic: license-file
 
 .. title:: Home
@@ -113,7 +115,7 @@ The code below demonstrate how to define and optimize an RLC model to satisfy a
   model.plot_s_db(plot_freq, m=0, n=0, label='initial')
   result.model.plot_s_db(plot_freq, m=0, n=0, label='optimized')
 
-  print(prf.param_values(result.model))
+  print(prf.values(result.model))
 
 Next steps
 ----------
@@ -125,12 +127,6 @@ Optional dependencies
 ---------------------
 Several additional dependencies are required/recommended for more advanced use-cases.
 
-For Bayesian inference, you may need this fork of *distreqx*:
-
-.. code-block:: bash
-
-   $ pip install git+https://github.com/gvcallen/distreqx
-
 For *BlackJAX*'s Bayesian solvers:
 
 .. code-block:: bash

{paramrf-0.35.3 → paramrf-0.36.0}/README.rst

@@ -69,7 +69,7 @@ The code below demonstrate how to define and optimize an RLC model to satisfy a
   model.plot_s_db(plot_freq, m=0, n=0, label='initial')
   result.model.plot_s_db(plot_freq, m=0, n=0, label='optimized')
 
-  print(prf.param_values(result.model))
+  print(prf.values(result.model))
 
 Next steps
 ----------
@@ -81,12 +81,6 @@ Optional dependencies
 ---------------------
 Several additional dependencies are required/recommended for more advanced use-cases.
 
-For Bayesian inference, you may need this fork of *distreqx*:
-
-.. code-block:: bash
-
-   $ pip install git+https://github.com/gvcallen/distreqx
-
 For *BlackJAX*'s Bayesian solvers:
 
 .. code-block:: bash

{paramrf-0.35.3 → paramrf-0.36.0}/docs/adr/0002-parameter-api.md

@@ -133,16 +133,16 @@ not a replacement: its target is recomputed from its source every time the
 model is unwrapped. A relation that needs a quantity the model does not yet hold
 is a derived model (`prf.derived`, ADR-0003), not a tie.
 
-### 4. Reading: `prf.params` and `prf.param_values`
+### 4. Reading: `prf.params` and `prf.values`
 
 ```python
 prf.params(model, where='*', *, free_only=False)                          # dict[str, Param]
-prf.param_values(model, where='*', *, free_only=False, space='declared')  # dict[str, Array]
+prf.values(model, where='*', *, free_only=False, space='declared')  # dict[str, Array]
 prf.log_prior(model, *, space='declared')                                 # scalar
 ```
 
 A user thinks "the parameters of my model", so `params` returns `Param`
-objects, whose `repr` shows value, bounds and prior. `param_values` is what
+objects, whose `repr` shows value, bounds and prior. `values` is what
 `update` accepts and what optimisers use; a bare `values` was rejected as too
 vague at top level, where it could mean S-parameter data. `named_params`'
 `full_params` and `namespace_separator` are dropped.
@@ -150,7 +150,7 @@ vague at top level, where it could mean S-parameter data. `named_params`'
 The documented identity, which is also the regression test of decision 10:
 
 ```python
-prf.update(m, prf.param_values(m, space=s), space=s)   # same structure, same cache key
+prf.update(m, prf.values(m, space=s), space=s)   # same structure, same cache key
 ```
 
 All functions are defined in `pmrf.parameters` and re-exported at top level.
@@ -165,7 +165,7 @@ All functions are defined in `pmrf.parameters` and re-exported at top level.
 
 `declared` is the default everywhere, and every user-facing surface agrees with
 construction: `Param(value=...)`, bounds, priors, `repr`, `Param.value`,
-`param_values` and `update`. Distributions and bounds are authored in declared
+`values` and `update`. Distributions and bounds are authored in declared
 space.
 
 `Param` gets one property per space: `value` (declared), `physical_value` and
@@ -218,7 +218,7 @@ Raveling to a 1-D vector stays inside the adapters that need it, such as the
 SciPy solver (`pmrf/optimize/solvers/scipy.py`) and non-JAX samplers.
 `prf.flatten` and `FlatParams` (#142) are not added. A public ravel helper, with
 one name per array element, can be added when a non-JAX consumer needs it; it
-would sit on top of `param_values`, not replace it.
+would sit on top of `values`, not replace it.
 
 The substance of #142 is kept: the raw-space log prior with the Jacobian and
 scale terms, name alignment, and a single implementation behind the minimiser