paramrf 0.34.4__tar.gz → 0.35.2__tar.gz

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

@@ -0,0 +1,34 @@
+name: Run Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+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'
+
+    - name: Install dependencies and smoke test package import
+      run: scripts/install-test-deps.sh
+
+    - name: Run Pytest
+      run: |
+        python -m pytest -rs
+      env:
+        PMRF_TESTS_NO_SKIPS: "1"

paramrf-0.35.2/CHANGELOG.md

@@ -0,0 +1,126 @@
+# Changelog
+
+## 0.35.0
+
+Parameter names, values and serialisation (#138), and the parameter API of
+ADR-0002 (#146). Downstream users pinning an exact version: every breaking
+change below ships in **0.35.0**.
+
+Name-keyed operations are now free functions rather than methods, values are
+read and written in the units they were declared in, and changing a value no
+longer recompiles a model's RF methods.
+
+### Breaking changes (0.35.0)
+
+- **Parameter API (#146):** name-keyed operations are free functions, so they
+  also work on a collection such as `(model, noise_model)`. Removed:
+  `Module.named_params`, `values`, `with_values`, `with_free`, `with_fixed`,
+  `map` and `at`; `Module.tied` and `Model.tied`; `Param.as_fixed`, `as_free`
+  and `at`; and the public `Param.wrap`. Use `prf.params`, `prf.param_values`,
+  `prf.update` and `prf.tie`. There are no aliases or deprecation shims.
+- **Parameter API (#146):** `Module` has no public methods. `Model` keeps its RF
+  methods, which are now fixed by a checked-in allowlist.
+- **Values (#146):** `Param.value`, `prf.param_values` and `prf.update` use the
+  **declared** value, the number as written in the units the parameter's scale
+  declares, so `prf.update(m, {'C': 3.0})` on a pF parameter sets 3 pF, not 3 F.
+  This reverses the physical-value behaviour `prf.replace(p, value=...)` had
+  earlier in this release.
+- **Values (#146):** a scale on a value overrides the field's scale instead of
+  multiplying with it, so a `Param` with `scale=1e-9` passed into a pF field is
+  nF. `Param.scale` is `None` when the parameter declares none.
+- **Values (#146):** `Param.unscaled_value` is removed; the three spaces are
+  `Param.value` (declared), `physical_value` and `raw_value`.
+- **Values (#146):** the `Param` field holding the Parax variable is renamed
+  from `raw_value` to `variable`, and the bijector properties are now
+  `raw_to_declared_bijector` and `declared_to_physical_bijector`.
+- **Values (#146):** a model's `repr` shows declared values, not scaled ones.
+- **Inference (#146):** the minimiser and samplers run on raw-space values, over
+  a name-keyed dict rather than a flat vector. `pmrf.utils.optix`'s lens is
+  internal; nothing public returns a `Lens`.
+- **Inference (#146):** `prf.log_prior` is a density in the space asked for, so
+  a raw-space prior carries the constraint's Jacobian and scale terms. Saved
+  results that stored physical values need re-reading in declared space.
+- **Inference (#151):** `run_minimizer`'s `use_bounds` argument is removed. A
+  bounded solver is given infinite raw bounds, because raw space is the whole
+  real line and each parameter's bijector keeps its constraints.
+- **Inference (#151):** a parameter starting exactly on one of its bounds
+  raises for the minimiser and for joint and split samplers: its raw value is
+  infinite and cannot move. Hypercube samplers work in declared space and
+  accept it.
+- **Values (#146):** `prf.derivative` differentiates each parameter with
+  respect to its declared value, so the derivative for a pF parameter is per pF;
+  `space='physical'` gives the old per-SI-unit result. Each result keeps its
+  argument's structure, wrappers included, instead of the unwrapped one. A fixed
+  parameter gets its sensitivity rather than zero, and a tie's source includes
+  the path through the tie.
+- **Names (#133):** parameter names no longer include tied targets; a tie's
+  target is derived, not stored.
+- **Names (#133):** wrapper path parts (`Tied`, `Probabilistic`, `Wrapped`) are
+  dropped from parameter names.
+- **Names (#133):** a name collision raises.
+- **Names (#133):** `prf.unfreeze` also unfreezes frozen parameters inside the
+  value.
+- **Names (#133):** string dict keys that are valid identifiers give dotted
+  names (`components.cable.length`) instead of the bracket form.
+- **Names (#146):** a named model held in a dict drops its key, and top-level
+  dict keys do not add a namespace layer.
+- **Values (#134):** the `Param` constructor rejects a raw value together with
+  `distribution` or `constraint`.
+- **Save format (#136):** prf files carry a header
+  (`{"format": "prf", "schema_version": 1, "paramrf_version": ..., "tree": ...}`).
+  `prf.load` rejects files without it, or with a `schema_version`
+  other than 1, so files saved by earlier versions
+  cannot be loaded.
+- **Save format (#136):** `prf.save` writes every field, defaults included.
+
+### Added
+
+- `prf.params` and `prf.param_values` read a model's parameters by name, and
+  `prf.log_prior` scores them, each over a selector and one of the three value
+  spaces (#146).
+- `prf.update`, one verb for changing a model: values by name, a value or fixed
+  state over a selector, a new sub-model, or a function of the old part (#146).
+- `prf.tie` as a free function (#146).
+- One name resolver behind every name-based operation; names resolve through
+  frozen parameters and after evaluating a `Touchstone`-backed model (#133).
+- `prf.replace` works on `Param`, keeping prior, constraint, fixed state, scale,
+  name and metadata (#134).
+- `pmrf.serialization.SCHEMA_VERSION` and `FORMAT` constants, and a clearer
+  `ImportError` when a saved class cannot be imported (#136).
+
+### Fixed
+
+- Changing a parameter's value no longer recompiles a model's RF methods. The
+  value forms of `prf.update` keep the tree structure and every leaf's dtype,
+  shape and weak type (#130, #146).
+- Compiling `model.s(freq)` for a Touchstone-backed model no longer takes
+  minutes: interpolation is vectorised over port pairs rather than looped. At
+  50 ports with linear interpolation, the first call drops from 70 s to 0.4 s;
+  100 ports no longer times out. S-parameter data stays static, which keeps
+  per-call evaluation fast (#130, #152).
+- `pmrf.__version__` is now set; it was looked up under the wrong
+  distribution name (#136).
+- The `Model.build` deprecation warning is emitted once per class, and now
+  points to plain functions for composites with no parameters of their own
+  (#137).
+- `pmrf.__all__` no longer lists `Topology` and `Initvar`, which do not exist
+  (#146).
+
+### Documentation
+
+- New "Working with parameter names" page in core concepts: how names are
+  formed, the three value spaces, selectors, the forms of `prf.update`, ties,
+  and what recompiles. The "Parameter naming and model manipulation" example
+  walks through the same operations on the new API (#146).
+- `Module` and `Substrate` explain that passing the same instance to two
+  sibling fields gives independent parameters, and how to share one (#137).
+
+## Unreleased
+
+- Complete Tesche coaxial conductor physics across the low-frequency regime,
+  and pass evaluated material properties to pure coaxial formulations.
+- Correct microstrip results by enabling Kirschning--Jansen modal dispersion by
+  default. Set `dispersion=None` on `MicrostripLine` to retain the quasi-static
+  pipeline explicitly.
+- Add the Hammerstad--Jensen microstrip formulation and selectable complex
+  (ADS-like) and real (QUCS-like) permittivity conventions.

paramrf-0.35.2/CITATION.cff

@@ -0,0 +1,14 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+type: software
+title: "ParamRF: A Modern Framework for Parametric Radio Frequency Modeling"
+authors:
+  - family-names: "Allen"
+    given-names: "Gary"
+    orcid: "https://orcid.org/0009-0005-6572-598X"
+  - family-names: "De Villiers"
+    given-names: "Dirk"
+    orcid: "https://orcid.org/0000-0003-1273-5365"
+repository-code: "https://github.com/gvcallen/paramrf"
+license: "Apache-2.0"
+version: "0.34.4"

{paramrf-0.34.4 → paramrf-0.35.2}/CONTEXT.md

@@ -1,8 +1,62 @@
 # ParamRF domain context
 
-Vocabulary for the transmission-line modelling layer. Terms here are the ones
-the code uses; prefer them over synonyms. Each entry points at the class that
-owns the maths rather than repeating it.
+Vocabulary for ParamRF's domain layers. Terms here are the ones the code uses;
+prefer them over synonyms. Each entry points at the class that owns the maths
+rather than repeating it.
+
+## Parameters
+
+Vocabulary from ADR-0002.
+
+### Param
+
+A named, possibly bounded or probabilistic value in a model: `pmrf.Param`,
+wrapping a Parax **variable** (the field `variable`). A **parameter name** is
+the dotted path #133's resolver gives it (`feed_coax.dielectric.ep_r`), the key
+for saved results, ties and selectors.
+
+### Space
+
+Where a parameter's number lives. Every surface defaults to **declared**.
+
+- **raw**: the latent, unbounded array optimisers and samplers move through.
+- **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.
+- **physical**: the scaled, SI value (2e-12).
+
+*Avoid:* "unconstrained space" (reads as a parameter without bounds; that is
+`prf.Unconstrained`), "unscaled" and "constrained" for declared space, "unit
+space" (the unit hypercube).
+
+### Scale
+
+The units a value is written in: physical = declared × scale. An explicit scale
+on a value overrides a field's default; scales never multiply.
+
+### Fixed and frozen
+
+- **Fixed**: a parameter state. The parameter keeps its name and prior and is
+  excluded from optimisation. Toggled with `prf.update(..., fixed=)`.
+- **Frozen**: an opaque subtree (`prf.freeze`), for constant data. Name-based
+  operations never act on it.
+
+### Update
+
+`prf.update` returns a copy of a model with the parts a **selector** picks
+replaced. A selector is a parameter name, a glob over names, a sequence of
+names, or a callable. A **validated update** (a name → value mapping,
+`value=`, `fixed=`) goes through each parameter's constructor; a **structural
+update** (a new node, `fn=`) bypasses validation. `prf.replace` is the plain
+dataclass field replace, not an update.
+
+*Avoid:* "set values", "with values"; "update" for an optimiser step.
+
+### Parameter values
+
+`prf.param_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.
 
 ## Line modelling
 
@@ -73,6 +127,7 @@ paper with no ParamRF objects in sight.
 
 ## Decisions
 
-`docs/adr/` records the decisions behind this layering. Read
+`docs/adr/` records the decisions behind these layers. Read
 `docs/adr/0001-line-modelling-architecture.md` before changing a strategy
-interface or a default.
+interface or a default, and `docs/adr/0002-parameter-api.md` before adding a
+method, a public function or a value space.

{paramrf-0.34.4 → paramrf-0.35.2}/CONTRIBUTING.md

@@ -8,25 +8,18 @@ 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 along with the test and documentation dependencies:
+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`):
 
-    pip install -e .[tests,docs]
-
-4. **External Inference Dependencies (Optional):** If you plan on working on the Bayesian inference module (`pmrf.infer`), you may need to install our custom `distreqx` fork and PolyChord. Note that PolyChord requires C++ and Fortran compilers (like `mpicxx` and `mpifort`) to be installed on your system:
-
-    ```bash
-    pip install git+https://github.com/gvcallen/distreqx.git
-    ```
-
-    ```bash
-    pip install git+https://github.com/PolyChord/PolyChordLite.git
-    ```
+    scripts/install-test-deps.sh
+    pip install -e .[docs]
 
 ## Building docs/running tests
 
 We use `pytest` for all unit testing. Simply run:
 
-    pytest
+    pytest -rs
+
+Tests for optional backends skip when a backend is missing. CI sets `PMRF_TESTS_NO_SKIPS=1`, which turns any skip into a failure, so run with it locally too before opening a PR.
 
 When writing new tests, especially for fitting and inference routines, try to use synthetic, in-memory S-parameter data (identity fits) rather than committing `.s2p` files to the repository. This keeps the test suite fast and the repository size small.
 

{paramrf-0.34.4/paramrf.egg-info → paramrf-0.35.2}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: paramrf
-Version: 0.34.4
+Version: 0.35.2
 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
+Requires-Dist: parax>=0.10.8
 Requires-Dist: threadpoolctl
 Requires-Dist: eqxpress
 Requires-Dist: jax
@@ -113,7 +113,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(result.model.named_params())
+  print(prf.param_values(result.model))
 
 Next steps
 ----------

{paramrf-0.34.4 → paramrf-0.35.2}/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(result.model.named_params())
+  print(prf.param_values(result.model))
 
 Next steps
 ----------

paramrf-0.35.2/docs/adr/0002-parameter-api.md

@@ -0,0 +1,255 @@
+# ADR-0002: Parameter API: free functions, one update verb, three value spaces
+
+Status: accepted (2026-09)
+
+## Context
+
+0.35.0 (#138) made parameter names the key for saved results, ties, free sets
+and external tooling, and added name-keyed operations as `Module` methods:
+`values`, `with_values`, `with_free` and `with_fixed`, next to the existing
+`named_params`, `at`, `map` and `tied`. An older ParamRF had `with_*` methods
+and deprecated them because they inflated the API and cut against a move to a
+functional style. There was no rule for which operations get a method, so the
+surface grew case by case.
+
+Four problems forced a decision:
+
+- **Joint trees.** Fitting and inference increasingly work on collections such
+  as `(model, noise_model)`. A method on `Module` cannot reach them, so every
+  method-only operation needs a function as well, and the API grows two
+  spellings.
+- **Scale.** Construction takes the declared value (`prf.param(scale=1e-12)`
+  then `RC(1.0, 2.0)` stores 2 pF), but `Param.value`, `values()`,
+  `with_values()` and `prf.replace(p, value=...)` use the physical, scaled
+  value. `with_values({'C': 3.0})` on that model silently sets 3 F. A `Param`
+  with its own scale passed into a scaled field multiplies the two scales
+  (`1e-9 × 1e-12`).
+- **Recompilation (#130).** RF methods are wrapped in `eqx.filter_jit`, so any
+  change to a model's static structure recompiles. Rebuilding a parameter with
+  `model.at(name).set(prf.Unconstrained(v))`, as the docs showed, changes its
+  scale and constraint and recompiles; for a large circuit that is a minute per
+  change. `_replace_raw_value` also flips `weak_type` on the value leaf, so
+  `with_values` and `prf.replace` recompile once even though the treedef is
+  unchanged.
+- **Flattening (#135, #142).** A proposed `prf.flatten` returned a
+  `FlatParams` object over a 1-D vector. Flattening that prominent is unusual
+  in the JAX ecosystem.
+
+Precedent from other JAX libraries: Equinox's `Module` has no public methods;
+Flax NNX deprecated `Module.iter_modules` and `iter_children` in favour of free
+functions; Penzai keeps a single `.select()` gateway; NumPyro's
+`initialize_model` exposes a potential function over a **name-keyed dict** of
+unconstrained values and ravels only inside samplers. scikit-rf, which most
+ParamRF users know, puts RF operations on `Network` as methods.
+
+## Decisions
+
+### 1. A method belongs to the class that gives it meaning
+
+If an operation would make equal sense on a plain collection of models and
+parameters, such as a `(model, noise_model)` tuple, it is a free function and
+never a method. There are no exceptions.
+
+- **`Model`** keeps RF methods: `s`, `a`, `z`, `y`, `mna`, `nports`,
+  `port_tuples`, `primary_matrix`, `build`, `expand`, `cascaded`, `flipped`,
+  `renumbered`, `terminated`, `**`, `@`, `to_skrf` and `export_touchstone`.
+  `tied` leaves; tying is parameterisation, not circuit algebra.
+- **`Module`** has no public methods (decision 2).
+- **`Param`** keeps read-only properties that describe it (`value`, `bounds`,
+  `distribution`, ...). `as_fixed`, `as_free` and `at` are removed; `wrap`
+  becomes private.
+
+A test asserts that `Module` has no public methods and that `Model`'s public
+methods equal a checked-in allowlist, so adding one is a reviewed decision. The
+methods `__init_subclass__` generates (`s_db`, `s_mn_mag`, ...) and the plotting
+names `__getattr__` serves are RF and allowed; the test skips them by pattern
+and says so. Replacing them is out of scope.
+
+This matches what scikit-rf users expect, where RF operations are methods, and
+what JAX users expect, where tree operations are functions.
+
+### 2. `Module` is a contract, not a toolbox
+
+Without methods, `Module` still does work nothing else does. Its `name` is what
+makes a named module collapse the path to its left into a namespace, which name
+resolution depends on. `pmrf.modules.validate` rejects raw float JAX arrays in
+its fields, which are ambiguous between free and fixed parameters. It carries
+`metadata`, gives the unwrapped `repr`, and is the base of `Model`, losses,
+likelihoods, kernels, materials and evaluators. Subclassing it says the object
+takes part in naming and validation. Its docstring says so.
+
+### 3. One verb for changing a model: `prf.update`
+
+`prf.update` returns a copy of a model in which the parts a selector picks are
+replaced. Exactly one form says what with:
+
+```python
+prf.update(model, {'L1.L': 3.0, 'C1.C': 2.0})      # parameter values by name
+prf.update(model, 'L1.L', value=3.0)               # parameter fields on a selection
+prf.update(model, 'cable.*', fixed=True)           # fixed state
+prf.update(model, 'cascade[1]', Short())           # a new sub-model or node
+prf.update(model, 'load.*', fn=lambda p: ...)      # a function of the old part
+prf.update(model, v, space='raw')                  # write-back from an optimiser or sampler
+prf.update(param, value=3.0)                       # selector omitted: the root itself
+```
+
+It replaces `with_values`, `with_free`, `with_fixed`, `Module.map`,
+`Module.at`, `Param.as_fixed`, `Param.as_free` and `Param.wrap`.
+
+- **Selectors** are parameter names, `fnmatch` globs over them, sequences of
+  names, or callables, resolved by the #133 resolver.
+- **Two tiers, set by the form.** The mapping, `value=` and `fixed=` forms go
+  through each parameter's constructor: they validate bounds and keep the prior,
+  constraint, scale, name and metadata. The node and `fn=` forms are
+  structural: they bypass converters and validation, and the docstring says so.
+- **The mapping form** is recognised only as the second positional argument
+  with every key a string. Its values may be arrays or `Param` objects. Any
+  other second argument is a selector, and a form mismatch raises an error that
+  lists the forms.
+- **`fixed=`** is additive. `fixed=False` frees a parameter even if it was
+  created fixed, and parameters the selector does not match are untouched.
+  "Only these free" is `update(update(m, '*', fixed=True), names, fixed=False)`.
+- **Value forms keep the jit cache key.** The mapping, `value=` and `space=`
+  forms never change the treedef, or any leaf's dtype, shape or `weak_type`
+  (decision 10). Changing `fixed=`, or any structural form, changes the model's
+  structure, and recompiling is expected.
+- **Not an optimiser step.** In fitting, "updates" also means Optax gradient
+  steps; the docstring says `update` is neither.
+
+`prf.replace` stays as the plain `dataclasses.replace`: fields of one object,
+unvalidated, able to break a type. Its docstring points to `update` for
+anything name-based.
+
+`prf.tie(model, target, source, fn=identity)` stays a separate verb. A tie is
+not a replacement: its target is recomputed from its source every time the
+model is unwrapped.
+
+### 4. Reading: `prf.params` and `prf.param_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.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
+`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.
+
+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
+```
+
+All functions are defined in `pmrf.parameters` and re-exported at top level.
+
+### 5. Three value spaces: `raw`, `declared`, `physical`
+
+| Space | Meaning | Example (2 pF, `scale=1e-12`) |
+|---|---|---|
+| `raw` | the latent, unbounded array an optimiser or sampler moves through | constraint bijector inverse of 2.0 |
+| `declared` | the number as written, in the units the parameter's scale declares | `2.0` |
+| `physical` | the scaled, SI value | `2e-12` |
+
+`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
+space.
+
+`Param` gets one property per space: `value` (declared), `physical_value` and
+`raw_value` (the latent array). `unscaled_value` is removed. The field
+currently named `raw_value`, which holds the Parax variable, is renamed
+`variable`. The bijector properties become `raw_to_declared_bijector` and
+`declared_to_physical_bijector`; "constrained" and "unscaled" are no longer
+used as space names.
+
+`log_prior` supports all three spaces: declared is the density as written,
+physical adds −log|scale| per parameter, and raw adds the constraint bijector's
+log|det J| as well. Each docstring states its measure.
+
+**Why `raw`, not `unconstrained`.** ParamRF's users are mostly RF engineers,
+who read "unconstrained" as "a parameter without bounds", which is what
+`prf.Unconstrained` creates. The code already used "raw" for this reason.
+**Why not `unit`.** In fitting, "unit space" is the unit hypercube nested
+samplers work in, which ParamRF's hypercube sampler maps to.
+**Why not `unscaled`, `normalized`, `per_unit` or `engineering`.** `declared`
+says what the value is rather than what has not happened to it; `normalized`
+means z = Z/Z₀ in RF and [0, 1] in optimisation; `per_unit` is power-systems
+jargon; "engineering units" means the scaled value in instrumentation.
+
+### 6. Scale is the units a value is written in
+
+A field's scale is a default unit. An explicit scale on the value overrides it;
+the two are never multiplied. The factories and `as_param` take `scale=None`,
+meaning "inherit the field's", so `prf.Unconstrained(2.0)` passed into a pF
+field is 2 pF, and `prf.Unconstrained(2.0, scale=1e-9)` is 2 nF.
+
+This reverses 0.35.0's `prf.replace(p, value=...)`, which took the physical
+value; `update(p, value=...)` takes the declared one.
+
+### 7. Fixed and frozen are different things
+
+- **Fixed** is a parameter state. The parameter is still a `Param`, still named
+  and still carries its prior; it is excluded from optimisation.
+  `update(..., fixed=)` toggles it.
+- **Frozen** (`prf.freeze`, `prf.unfreeze`) makes a subtree opaque. It is for
+  constant data, such as `field(converter=prf.freeze)`, and for hiding whole
+  subtrees.
+
+The name-based operations act on fixed, never on frozen.
+
+### 8. No public flattening
+
+Parameter values cross ParamRF's boundary as name-keyed dicts, which are
+pytrees that Optax, Optimistix, BlackJAX and `jax.grad` take directly.
+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.
+
+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
+and samplers.
+
+### 9. Public names describe the domain, not the data structure
+
+Public functions have no `tree_` prefix; most users do not know what a pytree
+is and should not need to. `tree_*` names are for private helpers. Docs say "a
+model, or any collection of models and parameters", and reserve "pytree" for
+an advanced page.
+
+### 10. Recompilation is prevented by keeping structure, not by changing the cache
+
+The automatic `eqx.filter_jit` on RF methods and its cache key stay as they
+are. Dropping the automatic jit would make `model.s(freq)` slow for the users
+decision 1 keeps methods for; removing `name` and `metadata` from the treedef
+would complicate name resolution for a rare case.
+
+Instead, the structure-preserving forms of `update` guarantee an unchanged
+cache key, and a test enforces it for every such form: treedef, dtype, shape and
+`weak_type` of every leaf. The docs say plainly that changing a parameter's
+value never recompiles and rebuilding it does.
+
+## Consequences
+
+- **Breaking, in one minor release.** Removed: `Module.named_params`, `values`,
+  `with_values`, `with_free`, `with_fixed`, `map`, `at`, `tied`; `Model.tied`;
+  `Param.as_fixed`, `as_free`, `at`, `unscaled_value`; public `Param.wrap`.
+  Renamed: the `Param.raw_value` field to `variable`, and the bijector
+  properties. Changed: `Param.value` returns the declared value; scales
+  override instead of multiplying. No aliases or deprecation shims.
+- `pmrf.utils.optix`'s lens becomes internal or is deleted; nothing public
+  returns a `Lens`.
+- Joint-tree names keep #133's rules. A named model inside a dict drops its key,
+  and a collision raises; top-level dict keys do not become a namespace layer.
+- Saved results keyed by name keep working; results that stored physical
+  values need re-reading in declared space.
+- Deferred to their own issues: reducing the top-level and submodule surface
+  (including `__all__` listing `Topology` and `Initvar`, which do not exist);
+  compile duration for large S-parameter blocks (#130, the per-port
+  interpolation loop); the generated `s_db`-style methods; flat vectors for
+  non-JAX tools.

{paramrf-0.34.4 → paramrf-0.35.2}/docs/api/index.rst

@@ -20,6 +20,19 @@ Core Primitives
    pmrf.Random
 
 
+Working with Parameters
+-----------------------
+
+.. autosummary::
+   :toctree: generated/
+
+   pmrf.params
+   pmrf.param_values
+   pmrf.log_prior
+   pmrf.update
+   pmrf.tie
+
+
 Main Modules
 ------------
 

{paramrf-0.34.4 → paramrf-0.35.2}/docs/core_concepts/core_primitives.rst

@@ -9,7 +9,7 @@ The Model
 
 Under the hood, ParamRF uses the `Equinox <https://docs.kidger.site/equinox/api/module/module/>`_ library to interoperate with JAX. This means that :class:`pmrf.Model` is an `Equinox Module <https://docs.kidger.site/equinox/api/module/module/>`_, a `JAX PyTree <https://docs.jax.dev/en/latest/pytrees.html>`_ and a Python `dataclass <https://docs.python.org/3/library/dataclasses.html>`_. If these concepts are completely foreign to you, do not worry. The practical consequences of this are:
 
-  * **Models are immutable**. Models cannot be mutated (``model.x = 5.0`` will throw an error). Rather, they represent "pure functions" which store their parameters alongside. This means that models should *never* contain any fields that can be derived from other fields (state should be "pure"), and should also not reference other objects in the model (using the same parameter object twice will result in two separate parameters!). Instead, :meth:`pmrf.Model.at` can be used to manipulate a model. Although this approach may feel new to some, the end result is improved optimization performance, differentiation capabilities, and added flexibility.
+  * **Models are immutable**. Models cannot be mutated (``model.x = 5.0`` will throw an error). Rather, they represent "pure functions" which store their parameters alongside. This means that models should *never* contain any fields that can be derived from other fields (state should be "pure"), and should also not reference other objects in the model (using the same parameter object twice will result in two separate parameters!). Instead, :func:`pmrf.update` returns a copy of a model with the parts you select replaced; see :doc:`parameter_names`. Although this approach may feel new to some, the end result is improved optimization performance and differentiation capabilities.
   * **Models are lazy**. Since models only store their parameters (and not their S-matrix or frequency), they do not perform any computation at initialization. Rather, their response is only evaluated when one of their methods (e.g. :meth:`pmrf.Model.s`) is passed a :class:`~pmrf.Frequency` object *as input*. This is in contrast to other, purely object-oriented libraries (such as :mod:`scikit-rf`).
   * **Models are JAX-native**. Models are simply JAX `PyTrees <https://docs.jax.dev/en/latest/pytrees.html>`_, meaning they can be passed around in any JAX context. This means that they can be compiled *just-in-time* (JIT) for enhanced performance and simulation on other platforms (GPUs, TPUs etc) and also used for many advanced JAX features (such as for vectorization via :func:`jax.vmap` and differentiation via :func:`jax.jacfwd`). See the :doc:`jax_overview` section for more details.
 

{paramrf-0.34.4 → paramrf-0.35.2}/docs/core_concepts/index.rst

@@ -7,5 +7,6 @@ This chapter provides an in-depth description of the most important concepts in
    :maxdepth: 2
 
    core_primitives
+   parameter_names
    optimization_and_inference
    jax_overview

{paramrf-0.34.4 → paramrf-0.35.2}/docs/core_concepts/jax_overview.rst

@@ -11,7 +11,7 @@ Standard Python is interpreted, which can introduce significant overhead. JAX by
 
 When a JIT-compiled function is called, it is not immediately executed. Instead, JAX "traces" the function's execution using abstract values. This trace builds a static computation graph in an intermediate representation called **XLA** (Accelerated Linear Algebra). The XLA compiler then optimizes this graph by merging operations, reducing memory allocation, and compiling it to a specific hardware architecture (CPU, GPU, or TPU).
 
-In ParamRF, all models and evaluators are designed to be JIT-compatible. Because JAX relies on this static tracing mechanism, functions passed to the JIT compiler must be *pure* (stateless and lacking side-effects). This functional paradigm is the underlying reason why ParamRF models are immutable; rather than modifying a model's attributes in-place, methods like :meth:`pmrf.Model.at` should be used.
+In ParamRF, all models and evaluators are designed to be JIT-compatible. Because JAX relies on this static tracing mechanism, functions passed to the JIT compiler must be *pure* (stateless and lacking side-effects). This functional paradigm is the underlying reason why ParamRF models are immutable; rather than modifying a model's attributes in-place, :func:`pmrf.update` returns a modified copy.
 
 Differentiability and Autodifferentiation
 -----------------------------------------
@@ -64,7 +64,7 @@ This allows you to easily create and evaluate entire batches of models simultane
 
 Parax and Unwrapping
 --------------------
-ParamRF builds on top of the JAX library `Parax <https://github.com/gvcallen/parax>`_ for parameters and constraints. Parax allows parameters (and entire models) to be manipulated in powerful ways, such as being fixed, scaled, constrained, or tied together. To accomplish this, Parax makes use of a concept known as *unwrapping*. To initialize a *wrapper*, the relevant parameter or object is *wrapped* in the desired class (for example, a "scale" wrapper). Then, to apply the wrapper, the object is *unwrapped*. This mechanism is what allows parameters to be tied together using :meth:`pmrf.Model.tied`, or for parameters to remain bounded, *even* when using an unbounded optimization algorithm.
+ParamRF builds on top of the JAX library `Parax <https://github.com/gvcallen/parax>`_ for parameters and constraints. Parax allows parameters (and entire models) to be fixed, scaled, constrained, or tied together. To accomplish this, Parax makes use of a concept known as *unwrapping*. To initialize a *wrapper*, the relevant parameter or object is *wrapped* in the desired class (for example, a "scale" wrapper). Then, to apply the wrapper, the object is *unwrapped*. This mechanism is what allows parameters to be tied together using :func:`pmrf.tie`, or for parameters to remain bounded, *even* when using an unbounded optimization algorithm.
 
 In ParamRF, unwrapping can be done manually using :func:`pmrf.unwrap` (which is an alias to :func:`parax.unwrap`). It is also automatically applied in ParamRF for RF response methods such as :meth:`pmrf.Model.s` via the :func:`pmrf.unwrap_self` annotation, as well as internally during optimization and inference. However, if you are using non-standard methods on your models and simply want to evaluate them (for example in a Jupyter notebook), then you should manually unwrap using :func:`pmrf.unwrap`, or annotate your method using :func:`pmrf.unwrap_self` where relevant.