paramrf 0.35.2__tar.gz → 0.35.4__tar.gz

{paramrf-0.35.2 → paramrf-0.35.4}/AGENTS.md

@@ -8,7 +8,20 @@ dataclasses that are also JAX PyTrees. Built on `jax`, `equinox`, and
 ## Breaking changes are acceptable
 
 The library is pre-1.0 and moves quickly. Do not add backwards-compatibility shims,
-deprecation aliases, or legacy code paths unless explicitly asked. Prefer the clean design.
+deprecation aliases, or legacy code paths unless explicitly asked. Prefer the clean design,
+within the seam the ticket names.
+
+## Seams
+
+A ticket names one seam, either a file, a set of files or a folder. If a cross-seam change is needed, implmentation should be stopped and decision left to the human.
+
+`docs/adr/` and `CONTEXT.md` change in their own commit, by the reviewer. An
+implementation reaching for a word absent from the ticket, the ADR and `CONTEXT.md` has
+reached a decision it does not have: ask.
+
+Open every PR body with `## Cross-seam`: each file touched outside the ticket's seam,
+with the ADR or issue line sanctioning it, or `DECISION NEEDED`. Write `none` when there
+are none.
 
 ## Commands
 

{paramrf-0.35.2 → paramrf-0.35.4}/CLAUDE.md

@@ -8,7 +8,20 @@ dataclasses that are also JAX PyTrees. Built on `jax`, `equinox`, and
 ## Breaking changes are acceptable
 
 The library is pre-1.0 and moves quickly. Do not add backwards-compatibility shims,
-deprecation aliases, or legacy code paths unless explicitly asked. Prefer the clean design.
+deprecation aliases, or legacy code paths unless explicitly asked. Prefer the clean design,
+within the seam the ticket names.
+
+## Seams
+
+A ticket names one seam, either a file, a set of files or a folder. If a cross-seam change is needed, implmentation should be stopped and decision left to the human.
+
+`docs/adr/` and `CONTEXT.md` change in their own commit, by the reviewer. An
+implementation reaching for a word absent from the ticket, the ADR and `CONTEXT.md` has
+reached a decision it does not have: ask.
+
+Open every PR body with `## Cross-seam`: each file touched outside the ticket's seam,
+with the ADR or issue line sanctioning it, or `DECISION NEEDED`. Write `none` when there
+are none.
 
 ## Commands
 

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

@@ -45,13 +45,50 @@ on a value overrides a field's default; scales never multiply.
 
 `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
+names, or a callable. A **validated update** (a name → value mapping
+entry, `value=`, `fixed=`) goes through each parameter's constructor; a
+**structural update** (a new node, `fn=`, or a mapping entry whose value is a
+`Model`, keyed by sub-model name) bypasses validation. In a mapping the tier is
+decided per entry by the value's type. `prf.replace` is the plain
 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 (`prf.modules.Probabilistic`) is discharged 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.
+
+### Derived model
+
+A model computed from a **base** model and **new parameters** by a function,
+`f(base, **new)`, built with `prf.derived` (ADR-0003). The base and the new
+parameters are held once; the base keeps its names and each new parameter is
+named by its keyword. Used to derive a more complete model from a nominal one
+(a wet section, a cut) and, by nesting, to share a parameter across parts.
+
+*Avoid:* "tie with new parameters", "shared parameter" as a separate concept.
+
 ### Parameter values
 
 `prf.param_values`: a name-keyed dict of arrays in one space, the form values

{paramrf-0.35.2 → paramrf-0.35.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: paramrf
-Version: 0.35.2
+Version: 0.35.4
 Summary: Parametric radio frequency modeling
 Author-email: Gary Allen <gvcallen@gmail.com>
 Project-URL: homepage, https://github.com/gvcallen/paramrf

{paramrf-0.35.2 → paramrf-0.35.4}/docs/adr/0002-parameter-api.md

@@ -85,6 +85,7 @@ 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, {'east': wet(model.east), 'west': wet(model.west)})  # sub-models 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
@@ -98,19 +99,26 @@ It replaces `with_values`, `with_free`, `with_fixed`, `Module.map`,
 
 - **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
+- **Two tiers, set by the form, or per entry in a mapping.** The `value=` and
+  `fixed=` forms, and mapping entries whose value is an array or `Param`, 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.
+  constraint, scale, name and metadata. The node and `fn=` forms, and mapping
+  entries whose value is a `Model`, 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
+  with every key a string. A value that is an array or `Param` is keyed by a
+  parameter name, and `space=` applies to it. A value that is a `Model` is keyed
+  by a sub-model name (`'cascade[1]'`, a named module's name) and replaces that
+  sub-model as the node form does (amended by #168, so several sub-models can be
+  replaced in one call). One mapping may mix both; a model for a parameter name,
+  or a value for a sub-model name, raises. 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`
+- **Value forms keep the jit cache key.** Mappings of values only, and the
+  `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
@@ -122,7 +130,8 @@ 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.
+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`
 

paramrf-0.35.4/docs/adr/0003-derived-models.md

@@ -0,0 +1,80 @@
+# ADR-0003: Derived models add parameters by deriving from a whole base
+
+Status: accepted (2026-09)
+
+## Context
+
+Users constrain parameters by relations such as "this part is computed from
+those". `prf.tie` (ADR-0002) covers this only when every source already exists
+in the model. It fails when the relation needs a quantity that has no home.
+
+The driving case (#167): a coaxial cable of total length L is wet for its first
+w and dry for the rest. The model is `wet ** dry`, but neither section can hold
+L. L must stay a parameter with its own prior, possibly a joint lab prior with
+the cable's geometry and material, and must not drift as w changes. w is a new
+parameter with its own prior. Several parts may share one such parameter (one
+water level on both arms of a balun).
+
+## Decision
+
+`prf.derived` turns a function `f(base, **new)` returning a model into a
+constructor of a **derived model**: a `pmrf.Model` (`pmrf.models.Derived`, an
+`AbstractBuilder`) that holds the base and the new parameters once and calls
+`f` on their unwrapped values whenever the model is used. `f` is a static field,
+so models derived with one function share a jit cache entry.
+
+### The base stays whole
+
+The derived model holds the base model itself, not parameters extracted from
+it. This is what makes two things work with no extra machinery:
+
+- **Joint priors.** A `Probabilistic` prior over the base (length with
+  geometry) is still in the tree, over the same parameters, under the same
+  names, and scores unchanged.
+- **Sharing with no ties.** `f` uses the base's geometry in both sections; it
+  is one parameter because it is stored once. No tie is needed to keep the wet
+  and dry sections consistent.
+
+### Naming rule
+
+- The base's parameters keep exactly the names they have on the base. The
+  wrapper is transparent to the name resolver, and the base's own name moves to
+  the derived model (unless `name=` is given), so a container prefixes as usual.
+- Each new parameter is named by its keyword; a keyword that clashes with a
+  base name raises.
+- Nothing produced inside `f` is named: it is not in the tree.
+
+A values dict saved from a fit of the base therefore applies unchanged to the
+derived model.
+
+### Sharing by nesting
+
+A parameter shared by several parts is a new parameter of a derived model at
+the level that owns them. Its `f` derives each part, passing the same value,
+and puts them back with the multi-model `prf.update` mapping form (#168). A
+derived model can be the base of another; names accumulate flat. There is no
+separate "shared parameter" concept.
+
+## Rejected options
+
+- **A tie with new parameters** (`tie(..., new={...})` and other tie-centric
+  designs). L ends up separate from the geometry and material, so no joint prior
+  covers them, and the dry section needs extra ties to share the geometry.
+- **A separate "add parameters" function** followed by a tie. Two steps for one
+  idea, and the added parameters have no relation to the model until tied, with
+  the same joint-prior problem.
+- **Reparametrising a parameter in place** (replace L by a function of new
+  parameters). The relation is not a function of one parameter: it replaces
+  part of the model's structure (one section becomes two), and L loses its prior.
+- **Builder classes.** They work, but an engineer should not need a class for
+  a one-off constraint, and topology code had to reach into the class.
+  `prf.derived` is a builder whose class is generated from a function.
+
+## Consequences
+
+- `tie` is unchanged.
+- `f` must be pure and its output's structure must not depend on parameter
+  values, as for `AbstractBuilder.build`. It should be defined once at module
+  level; a lambda made on every call recompiles.
+- A non-model return is only detected when the model is used, since calling
+  `f` eagerly at construction would repeat the work at every nesting level.

paramrf-0.35.4/docs/adr/0004-profiled-lines.md

@@ -0,0 +1,214 @@
+# ADR-0004: Profiled lines vary parameters along a line through target-agnostic profiles
+
+Status: accepted (2026-09)
+
+## Context
+
+ParamRF's line models (ADR-0001) are uniform: a `MicrostripLine` has one width,
+one substrate, one conductor, and its `zc_and_gammaL` holds everywhere along it.
+Real structures are not. A taper's width varies along z, a cable's permittivity
+drifts with a moisture gradient, a deposited conductor's conductivity varies with
+position. The quantity that varies is always an existing parameter of an existing
+line, and it must keep taking part in fitting: its shape is described by a few
+new parameters with their own priors, and those are what the user fits.
+
+The repository already held a commented-out `ProfiledLine` from an earlier API:
+a `line_fn` plus parallel `profile_fns` (static callables) and `profile_params`
+dicts, a constructor that sniffed keyword types to decide what was a profile, and
+a `method='stepped'|'riccati'` switch whose Riccati branch raised
+`NotImplementedError`. It predates the parameter API (ADR-0002) and derived
+models (ADR-0003).
+
+Two further pressures shaped this. First (#45), a cascade of ten microstrip lines
+with independent widths is built by a Python list comprehension, which traces
+once per member and gives every member its own name set — the same batching
+problem a profiled line has, at a different level. Second, users do not know what
+section count a given taper needs for an accurate answer, and an under-resolved
+line is not merely inaccurate: an optimiser will exploit it.
+
+## Decision
+
+`pmrf.models.ProfiledLine` takes a uniform line and a mapping from parameter
+targets to **profiles**, and evaluates as a cascade of `n` uniform sections whose
+parameters are sampled at the section midpoints.
+
+### A profile is a shape, not a line
+
+`AbstractProfile` is a `pmrf.Module` — parameter-aware, named, validated, but not
+a `Model`, exactly as materials and the line strategy objects are. It declares one
+method, `evaluate(t)`, on normalised `t`, documented as elementwise so the
+container passes the whole midpoint array in one call. Its coefficients are
+ordinary `prf.param` fields carrying physical units and their own constraints, so
+`ExponentialProfile(start=2e-3, end=8e-3)` and
+`ExponentialProfile(start=Bounded(...), end=Bounded(...))` both work with no
+profile-specific machinery.
+
+A profile knows nothing about the line, the parameter, or the family. This is the
+central constraint: an exponential taper must apply to microstrip width, stripline
+width or coaxial inner diameter without being rewritten. `evaluate` returns a
+plain physical value, in the units of whatever it is attached to.
+
+`t = 0` is at port 1 and `t = 1` at port 2, fixed on `AbstractProfile` and
+restated on `ProfiledLine`. Reversing a taper swaps coefficients through
+`prf.update`; there is no orientation flag, because a flag that silently mirrors
+geometry inside a cascade is a debugging hazard.
+
+The library ships `LinearProfile`, `ExponentialProfile` and `KlopfensteinProfile`.
+Klopfenstein is the linearised-Riccati *design* solution: it defines a shape worth
+simulating and is not a reference the simulator is checked against.
+
+### Targets are dotted paths; the base tree is untouched
+
+`ProfiledLine` holds the base line and a mapping from a **dotted path** naming a
+`Param` on that base to the profile driving it. The base tree is left exactly as
+built. Profiles are not substituted into it, and not declared as model fields.
+
+Targets are exact dotted paths only — `w`, `substrate.dielectric.ep_r` — not
+globs, sequences or callables. A glob matching three parameters would silently
+create three independent profiles that happen to share a shape object, which is
+never what the user meant.
+
+`length` is not profilable and is rejected. It is the base's own parameter and it
+is the **total** length; `ProfiledLine` divides by `n` internally and the user
+never sees a per-section length. `ProfiledLine` has no `length` field, exposing
+the base's as a read-only forwarding property.
+
+A profiled target's value on the base is discarded, and the parameter is removed
+from the profiled line's parameter set, replaced by the profile's coefficients.
+Passing a value explicitly for a target that is also profiled raises: silently
+discarded input is how an afternoon is lost. A field default that is discarded
+does not raise, because the user did not type it.
+
+Coefficients are named under the target: `w.start`, `w.end`,
+`substrate.dielectric.ep_r.start` — the name the parameter would have had, with
+the coefficient below it. `ProfiledLine` names them itself rather than letting
+the mapping's keys be named as dict keys, so a non-identifier path does not leak
+a bracket form into parameter names. Globs such as `'w.*'` and `'*.start'` then
+both do the obvious thing, and the container's internal field layout never
+appears in a parameter name.
+
+### Two ways in, one representation
+
+The base may be given as a constructed line or as a class. A class is constructed
+from the plain keywords, with a small reserved set (`n`, `extrapolate`, `name`,
+`metadata`) always belonging to the container and a clear error on collision. A
+user usually thinks "I want to profile a microstrip line", not "I want to profile
+this particular line", and the class form lets them say so without constructing a
+line whose width they are about to throw away. A base built this way is
+deliberately unnamed, so parameter paths flatten to the container root.
+
+Whichever form is used, one representation is stored: a base model plus the
+target-to-profile mapping.
+
+### Evaluation: midpoint sections, extrapolated
+
+`ProfiledLine` is a `TransmissionLine` and an `AbstractBuilder`. `build` returns a
+`pmrf.models.RepeatedCascade`, so every representation delegates for free and no
+line-specific evaluation code is written twice.
+
+`RepeatedCascade` is public in its own right: one model, a mapping from dotted
+names to arrays whose leading axis is the repeat axis, and everything else shared.
+`n` is static by construction, from that leading axis. It is what `ProfiledLine`
+produces after evaluating profiles at the midpoints, and it is also the answer to
+#45's cascade of independently-parametrised lines. The reduction itself moves into
+`pmrf.rf` and is shared with `Cascade`: the ABCD domain by default, reduced with a
+sequential `lax.scan`.
+
+Sampling each profile at the section midpoints and building exact hyperbolic ABCD
+sections is the exponential midpoint rule, an order-2 Magnus integrator. It is
+time-symmetric, so its error expands in **even** powers of `h`, and Richardson
+extrapolation of `T(n)` and `T(2n)` as `(4·T(2n) − T(n))/3` is **O(h⁴)**, not
+O(h³). Extrapolation is on by default (`extrapolate=True`), costing `3n` section
+builds, all vmapped. `n` defaults to 64, which holds the per-section electrical
+length inside the guard below well past any realistic taper. `extrapolate=False`
+is the escape for users who want the plain midpoint result.
+
+Extrapolation is applied to the complex ABCD entries, and the per-frequency error
+estimate is exposed.
+
+### The guard is on by default and hard-errors
+
+Two conditions are checked at evaluation: the Richardson error estimate against a
+tolerance, and per-section electrical length against `βh ≲ 0.2 rad`. Both are
+traced, so both use `eqx.error_if`, as the degenerate-DC guards in the line base
+already do. A static `check=True` field turns them off.
+
+The error estimate is taken relative to a matrix norm, never to `|S11|`:
+normalising by a reflection coefficient makes the guard fire spuriously at every
+reflection null.
+
+Erroring rather than warning is deliberate. Silently wrong S-parameters feeding a
+likelihood is the worst outcome available, and an under-resolved taper is exactly
+the kind of numerical slack an optimiser finds and exploits. The accepted cost is
+that a fit whose trial point wanders past the guard dies mid-run rather than being
+penalised; `check=False` is the lever.
+
+### Introspection
+
+`ProfiledLine.at(t)` returns the base model with the profiled targets substituted
+at that `t` — the same substitution the evaluator performs at the midpoints,
+exposed for one position. It composes: `line.at(0.5).zc_and_gammaL(f)`, and `t`
+as an array vmaps to give the whole profile at once.
+
+## Rejected options
+
+- **Profiles declared as model fields** (`w: Param | Profile`). A `prf.param`
+  field runs an `as_param` converter, so a profile node is coerced or rejected;
+  and where a foreign node is stored untouched (ADR-0003), the field's constraint
+  and scale deliberately do not apply. A `MicrostripLine` whose width validation
+  is silently bypassed by an intermediate shape object is worse than no feature.
+- **Substituting the profile into the base tree in place**, replacing the `Param`
+  at the target. Naming would fall out for free, but it is the same validation
+  bypass at a different entry point.
+- **A section function returning a concrete line** (`lambda t: MicrostripLine(w=...)`).
+  It couples the taper definition to the line family: an exponential taper for
+  microstrip width would have to be rewritten for stripline width and again for
+  coaxial diameter. This is what forced profiles to be plain `f(t) -> value`.
+- **Authoring through `prf.update`** — construct a line, then update targets with
+  profile nodes. Unintuitive as the primary interface, and it reintroduces
+  in-tree substitution.
+- **A profile as a `Model`.** It has no ports and no S-parameters. `pmrf.Module`
+  is the base for parameter-aware objects that are not models.
+- **`ProfiledLine` as an `AbstractUniformLine`**, with `zc_and_gammaL` returning
+  the midpoint value. A characteristic impedance that is silently the value at
+  one position invites exactly the misuse the guard exists to prevent.
+- **Relative profiles** (`w(t) = w_base × profile(t)`). It keeps the base value
+  meaningful, but requires a reference value at every target and makes a
+  dimensionless profile of permittivity mean something odd. Profiles are absolute.
+- **A per-section `length`.** The base's `length` already carries a name, a prior
+  and possibly a joint lab prior with the geometry; dividing it internally keeps
+  all three and keeps a values dict from an earlier fit applicable.
+- **`BatchedCascade` as the name.** "Batch" in ParamRF already means the
+  parameter batch dimension (`prf.batch_axes`, `prf.sweep`), and a
+  `RepeatedCascade` can itself be batched in that sense.
+- **A `method` field and the Riccati path.** The old Riccati branch never ran. A
+  field with one legal value is an API promise bought before it is needed, and a
+  higher-order integrator would change `n` and `extrapolate` semantics too, so it
+  deserves its own design rather than a pre-cut slot.
+- **Automatic `n` selection.** `n` must be static under `jit` — it is a vmap axis
+  and a scan length — while `Frequency.f` is a dynamic array leaf, so no rule that
+  reads the frequency band can run inside `jit`. A manual `refine()` for power
+  users is deferred to its own ticket.
+- **Arbitrary-shape profiles** (polynomial, spline). They raise the smoothness
+  question the extrapolation depends on and belong in a later ticket.
+
+## Consequences
+
+- The even-power error expansion, and therefore the O(h⁴) claim, requires the
+  profile to be C² in `t`. This is documented on `AbstractProfile`. A deliberate
+  kink is expressed by cascading two `ProfiledLine`s with `**`, not by a
+  discontinuous profile.
+- Periodic uniform sections have an artificial Bragg stopband at `βh = π`. The
+  `βh ≲ 0.2` guard keeps evaluation far from it, but the mechanism is why the
+  guard is always on rather than advisory.
+- Richardson measures the *discretisation* error only. It is blind to the model
+  error floor — mode conversion, radiation, quasi-TEM breakdown — so a small
+  estimate is not a statement that the answer is physically right.
+- The convergence-order test is the slow one in the suite: it measures O(h²)
+  without extrapolation and O(h⁴) with it. Validation otherwise uses the
+  exponential taper's closed form, a diffrax RK reference, and exactness at
+  `n = 1`.
+- `Cascade` and `RepeatedCascade` share one reduction in `pmrf.rf`; changes to the
+  cascade numerics now affect both.
+- The commented-out `nonuniform.py` is deleted rather than ported. Per `AGENTS.md`
+  there is no back-compatibility obligation.

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

@@ -31,6 +31,8 @@ Working with Parameters
    pmrf.log_prior
    pmrf.update
    pmrf.tie
+   pmrf.resolve
+   pmrf.derived
 
 
 Main Modules

{paramrf-0.35.2 → paramrf-0.35.4}/docs/core_concepts/parameter_names.rst

@@ -40,9 +40,49 @@ Models are immutable, so :func:`pmrf.update` returns a changed copy rather than
 
 **Structural changes** replace a part of the model outright, either with a new sub-model or parameter, or with the result of a function applied to the old part. These put exactly what they are given in place, without validation. An exact name can select a whole sub-model here, whereas a glob only ever matches parameters.
 
+A dictionary passed to :func:`pmrf.update` can hold both kinds. Each entry is decided by its value: a :class:`pmrf.Model` keyed by a sub-model name is a structural change, unvalidated, while an array or parameter keyed by a parameter name is a value change. For example, ``prf.update(system, {'east_coax': new_east, 'west_coax': new_west})`` replaces two sub-models in one call. A model given for a parameter name, or a value given for a sub-model name, raises an error.
+
 The distinction matters for performance. RF methods such as :meth:`pmrf.Model.s` are compiled just-in-time, and the compiled code is only reused while the model's structure is unchanged. Changing a parameter's value keeps that structure, so it never triggers a recompile. Fixing or freeing a parameter, making a structural change, or swapping in a parameter with a different constraint or scale all change the structure, and so recompile. On a large circuit this can take noticeably longer than an evaluation, so value changes should be preferred inside loops.
 
 Tied Parameters
 ~~~~~~~~~~~~~~~
 
 Rather than setting a parameter once, :func:`pmrf.tie` derives it from another parameter. The target is removed from the model's parameters and is recomputed from its source every time the model is evaluated, so it follows the source through updates, optimization and sampling. Because it is no longer a parameter, it also no longer has a name. The tie function receives and returns physical values, and derivatives with respect to the source include the path through the tie.
+
+Derived Models
+~~~~~~~~~~~~~~
+
+A tie can only relate parameters that already exist. Sometimes a relation needs a quantity the model has no place for. Take a coaxial cable of total length ``L`` that is wet for its first ``w``: the model is a wet section cascaded with a dry one, but neither section can hold ``L``, and ``L`` should keep its own prior (perhaps a joint lab prior with the cable's geometry) rather than drift as ``w`` changes.
+
+:func:`pmrf.derived` handles this by starting from the nominal model and deriving a more complete one. It turns a function ``f(base, **new)`` into a constructor: the base model and the new parameters are held once, and ``f`` is called on them whenever the model is used.
+
+.. code-block:: python
+
+    @prf.derived
+    def wet(cable, wet_length, wet_ep_r):
+        wet = prf.replace(cable, length=wet_length,
+                          dielectric=prf.replace(cable.dielectric, ep_r=wet_ep_r))
+        dry = prf.replace(cable, length=cable.length - wet_length)
+        return wet ** dry
+
+    coax = wet(coax, wet_length=prf.Random(Uniform(0, 20), scale=1e-3),
+               wet_ep_r=prf.Random(Uniform(1, 80)))
+
+The result is an ordinary :class:`pmrf.Model` with the same port count, so it can be cascaded, wrapped, tied and fitted like any other. Its parameters are the base's, under exactly the names they had on the base, plus one per keyword (``wet_length`` and ``wet_ep_r``). The cable's geometry is used by both sections but is still one parameter, and a values dictionary saved from a fit of the dry cable applies unchanged. Nothing built inside ``f`` is named, and the derived model takes the base's name, so inside a named container everything is prefixed as usual.
+
+Like a tie function, ``f`` receives physical values. Inside it, use :func:`pmrf.replace` to change fields of the object in hand, and :func:`pmrf.update` to change parts reached by name. ``f`` must be pure and must return a model whose structure does not depend on parameter values. It is part of the model's static structure, so define it once at module level: a lambda created anew on every call recompiles.
+
+A parameter shared by several parts is expressed by deriving at the level that owns it. A derived model can be the base of another, and names accumulate flat, so one water level for both arms of a balun is:
+
+.. code-block:: python
+
+    @prf.derived
+    def wet_balun(system, wet_length):
+        return prf.update(system, {
+            'east_coax': wet(system.east_coax, wet_length=wet_length, wet_ep_r=80.0),
+            'west_coax': wet(system.west_coax, wet_length=wet_length, wet_ep_r=80.0),
+        })
+
+    balun = wet_balun(balun, wet_length=prf.Random(Uniform(0, 20), scale=1e-3))
+
+Here ``prf.params(balun)`` holds a single ``wet_length``, and changing it changes both cables. The reasoning behind this design is recorded in ADR-0003.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: paramrf
-Version: 0.35.2
+Version: 0.35.4
 Summary: Parametric radio frequency modeling
 Author-email: Gary Allen <gvcallen@gmail.com>
 Project-URL: homepage, https://github.com/gvcallen/paramrf

{paramrf-0.35.2 → paramrf-0.35.4}/paramrf.egg-info/SOURCES.txt

@@ -25,6 +25,8 @@ docs/_templates/autosummary/function.rst
 docs/_templates/autosummary/module.rst
 docs/adr/0001-line-modelling-architecture.md
 docs/adr/0002-parameter-api.md
+docs/adr/0003-derived-models.md
+docs/adr/0004-profiled-lines.md
 docs/agents/domain.md
 docs/agents/issue-tracker.md
 docs/agents/triage-labels.md
@@ -115,6 +117,7 @@ pmrf/models/adapters/base.py
 pmrf/models/adapters/bridge.py
 pmrf/models/adapters/callable.py
 pmrf/models/adapters/delegated.py
+pmrf/models/adapters/derived.py
 pmrf/models/adapters/static.py
 pmrf/models/adapters/wrapped.py
 pmrf/models/components/__init__.py
@@ -130,6 +133,7 @@ pmrf/models/components/lines/microstrip.py
 pmrf/models/components/lines/nodal.py
 pmrf/models/components/lines/nonuniform.py
 pmrf/models/components/lines/planar.py
+pmrf/models/components/lines/profiles.py
 pmrf/models/components/lines/stripline.py
 pmrf/models/composite/__init__.py
 pmrf/models/composite/nodal.py
@@ -159,6 +163,7 @@ pmrf/optimize/solvers/jaxopt.py
 pmrf/optimize/solvers/optimistix.py
 pmrf/optimize/solvers/scipy.py
 pmrf/rf/__init__.py
+pmrf/rf/cascade.py
 pmrf/rf/conversions.py
 pmrf/rf/mna.py
 pmrf/utils/__init__.py
@@ -214,11 +219,14 @@ tests/test_models/test_circuit_nodal.py
 tests/test_models/test_circuit_port_order.py
 tests/test_models/test_circuit_scattering.py
 tests/test_models/test_current_distribution.py
+tests/test_models/test_derived.py
 tests/test_models/test_interconnected.py
 tests/test_models/test_lines.py
 tests/test_models/test_lines_skrf_matrix.py
 tests/test_models/test_lumped.py
 tests/test_models/test_nodal.py
+tests/test_models/test_profiles.py
+tests/test_models/test_repeated_cascade.py
 tests/test_models/test_sections.py
 tests/test_models/test_transformed.py
 tests/test_models/test_transformers.py

{paramrf-0.35.2 → paramrf-0.35.4}/pmrf/__init__.py

@@ -46,6 +46,7 @@ except PackageNotFoundError:
 from pmrf.models import (
     Model as Model,
     is_model as is_model,
+    derived as derived,
 )
 from pmrf.modules.base import Module as Module, is_module as is_module
 from pmrf.frequency import Frequency as Frequency
@@ -68,6 +69,7 @@ from pmrf.parameters import (
     log_prior as log_prior,
     update as update,
     tie as tie,
+    resolve as resolve,
 )
 
 from pmrf.serialization import (
@@ -125,6 +127,7 @@ __all__ = [
     # Base/Core
     "Model",
     "is_model",
+    "derived",
     "Module",
     "is_module",
     "Frequency",
@@ -158,6 +161,7 @@ __all__ = [
     "log_prior",
     "update",
     "tie",
+    "resolve",
     "unwrap",
     "unwrap_self",
     "derivative",

{paramrf-0.35.2 → paramrf-0.35.4}/pmrf/models/__init__.py

@@ -70,6 +70,13 @@ from pmrf.models.components.lines.base import (
     ImmittanceResult as ImmittanceResult,
 )
 
+from pmrf.models.components.lines.profiles import (
+    AbstractProfile as AbstractProfile,
+    LinearProfile as LinearProfile,
+    ExponentialProfile as ExponentialProfile,
+    KlopfensteinProfile as KlopfensteinProfile,
+)
+
 from pmrf.models.components.lines.nodal import (
     FloatingLine as FloatingLine,
 )
@@ -170,7 +177,10 @@ from pmrf.models.composite.interconnected.circuit.solvers.nodal import (
 )
 
 from pmrf.models.composite.interconnected.circuit.circuit import Circuit as Circuit
-from pmrf.models.composite.interconnected.cascade import Cascade as Cascade
+from pmrf.models.composite.interconnected.cascade import (
+    Cascade as Cascade,
+    RepeatedCascade as RepeatedCascade,
+)
 from pmrf.models.composite.interconnected.terminated import Terminated as Terminated
 
 
@@ -198,6 +208,11 @@ from pmrf.models.adapters.wrapped import (
     Wrapped as Wrapped,
 )
 
+from pmrf.models.adapters.derived import (
+    Derived as Derived,
+    derived as derived,
+)
+
 # Compatibility re-exports. Parameter-aware wrappers live under ``pmrf.modules``.
 from pmrf.modules import Tied as Tied, Probabilistic as Probabilistic
 

{paramrf-0.35.2 → paramrf-0.35.4}/pmrf/models/adapters/__init__.py

@@ -7,7 +7,7 @@ This includes scikit-rf Networks, EM simulation software, and generic Equinox mo
 """
 
 from pmrf.models.adapters import base
-from pmrf.models.adapters import bridge, static, callable, delegated, wrapped
+from pmrf.models.adapters import bridge, static, callable, delegated, derived, wrapped
 
 __all__ = [
     "base",
@@ -15,6 +15,7 @@ __all__ = [
     "static",
     "callable",
     "delegated",
+    "derived",
     "wrapped",
 ]