paramrf 0.35.2__tar.gz → 0.35.3__tar.gz

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

@@ -45,13 +45,25 @@ 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.
 
+### 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.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: paramrf
-Version: 0.35.2
+Version: 0.35.3
 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.3}/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.3/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.2 → paramrf-0.35.3}/docs/api/index.rst

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

{paramrf-0.35.2 → paramrf-0.35.3}/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.3}/paramrf.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: paramrf
-Version: 0.35.2
+Version: 0.35.3
 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.3}/paramrf.egg-info/SOURCES.txt

@@ -25,6 +25,7 @@ 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/agents/domain.md
 docs/agents/issue-tracker.md
 docs/agents/triage-labels.md
@@ -115,6 +116,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
@@ -214,6 +216,7 @@ 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

{paramrf-0.35.2 → paramrf-0.35.3}/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
@@ -125,6 +126,7 @@ __all__ = [
     # Base/Core
     "Model",
     "is_model",
+    "derived",
     "Module",
     "is_module",
     "Frequency",

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

@@ -198,6 +198,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.3}/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",
 ]
 

paramrf-0.35.3/pmrf/models/adapters/derived.py

@@ -0,0 +1,144 @@
+"""Models derived from an existing model with new parameters."""
+
+import copy
+import functools
+from typing import Any, Callable
+
+from pmrf.models.base import Model
+from pmrf.models.adapters.delegated import AbstractBuilder
+from pmrf.utils import field
+
+
+class Derived(AbstractBuilder):
+    """A model computed by a function from a base and new named parameters.
+
+    Built by :func:`derived`, which documents the contract. The base and the new
+    parameters are held once, as ``operands = (base, new)``, and ``fn(base, **new)``
+    is called on their unwrapped values whenever the model is used. Parameter names
+    see through this wrapper: the base's names are unchanged and each new parameter
+    is named by its keyword.
+    """
+
+    #: The base, and the new parameters keyed by keyword.
+    operands: tuple[Any, dict[str, Any]]
+
+    #: The function building the model from the base and the new parameters.
+    fn: Callable[..., Model] = field(static=True, kw_only=True)
+
+    def build(self) -> Model:
+        base, new = self.operands
+        model = self.fn(base, **new)
+        if not isinstance(model, Model):
+            raise TypeError(
+                f"The derived function {getattr(self.fn, '__qualname__', self.fn)!r} must "
+                f"return a pmrf.Model; got {type(model).__name__}."
+            )
+        return model
+
+
+def _unnamed(node: Any) -> Any:
+    """Returns `node` without its own name, so its parameters keep their names below it."""
+    if getattr(node, 'name', None) is None:
+        return node
+    node = copy.copy(node)
+    object.__setattr__(node, 'name', None)
+    return node
+
+
+def derived(fn: Callable[..., Model]) -> Callable[..., Derived]:
+    """
+    Turns a function of a base model and new parameters into a derived model constructor.
+
+    A derived model starts from a nominal model and derives a more complete one that
+    captures some artifact (a wet section, degraded copper, a cut). The decorated
+    function is called as ``f(base, **new)``: exactly one positional base (a model,
+    or any collection of models and parameters) and keyword arguments that are the
+    new parameters (a :class:`pmrf.Param`, or anything :func:`pmrf.as_param`
+    accepts). It returns a :class:`pmrf.Model` that holds the base and the new
+    parameters once, and calls `fn` on them whenever the model is used.
+
+    `fn` receives the base and the new parameters as the model is unwrapped, so
+    parameters arrive as physical values, as for :func:`pmrf.tie`. It must return a
+    :class:`pmrf.Model`, must be pure, and its output's structure and port count must
+    not depend on parameter values. Inside `fn`, use :func:`pmrf.replace` for fields
+    of the object in hand and :func:`pmrf.update` for parts reached by name.
+
+    **Names.** The base's parameters keep the names they have on the base, and each
+    new parameter is named by its keyword. Nothing produced inside `fn` is named. The
+    derived model takes the base's name unless ``name=`` is passed, so a container
+    prefixes both as usual. A derived model can be the base of another, and names
+    accumulate flat; a parameter shared by several parts is expressed by deriving at
+    the level that owns it.
+
+    `fn` is a static part of the model: two models derived with the same function
+    share a jit cache entry. Define it once at module level; a lambda created on every
+    call recompiles.
+
+    Parameters
+    ----------
+    fn : Callable
+        ``fn(base, **new) -> Model``.
+
+    Returns
+    -------
+    Callable
+        ``constructor(base, *, name=None, **new) -> Derived``.
+
+    Raises
+    ------
+    TypeError
+        On a call with other than one positional base or with no new parameters, or
+        (when the model is used) if `fn` does not return a model.
+    ValueError
+        If a keyword clashes with a parameter name of the base.
+
+    Examples
+    --------
+    A coaxial cable of total length ``L`` that is wet for its first ``wet_length``:
+
+    .. 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)))
+        prf.params(coax)   # the cable's names, plus 'wet_length' and 'wet_ep_r'
+    """
+    from pmrf.parameters import as_param, params
+
+    @functools.wraps(fn)
+    def constructor(*args, name: str | None = None, **new) -> Derived:
+        if len(args) != 1:
+            raise TypeError(
+                f"{fn.__name__}() takes exactly one positional base and new parameters as "
+                f"keywords, e.g. {fn.__name__}(model, wet_length=...); got {len(args)} "
+                "positional arguments."
+            )
+        if not new:
+            raise TypeError(f"{fn.__name__}() needs at least one new parameter as a keyword.")
+        base = args[0]
+        clashes = sorted(set(new) & set(params(base)))
+        if clashes:
+            raise ValueError(
+                f"{fn.__name__}(): new parameter names {clashes} clash with parameters of "
+                "the base. Choose different keywords."
+            )
+        coerced = {}
+        for key, value in new.items():
+            value = as_param(value)
+            if value.name is not None:
+                value = _unnamed(value)
+            coerced[key] = value
+        if name is None:
+            name = getattr(base, 'name', None)
+        return Derived((_unnamed(base), coerced), fn=fn, name=name)
+
+    return constructor
+
+
+__all__ = ["Derived", "derived"]

{paramrf-0.35.2 → paramrf-0.35.3}/pmrf/parameters.py

@@ -955,11 +955,12 @@ def _is_name_leaf(x: Any) -> bool:
 
 def _is_name_transparent(x: Any) -> bool:
     """Wrappers whose own path parts are omitted from parameter names."""
+    from pmrf.models.adapters.derived import Derived
     from pmrf.models.adapters.wrapped import Wrapped
     from pmrf.modules.base import Module
     from pmrf.modules.wrapped import Probabilistic, Tied
 
-    if isinstance(x, (Tied, Probabilistic, Wrapped)):
+    if isinstance(x, (Tied, Probabilistic, Wrapped, Derived)):
         return True
     return isinstance(x, prx.AbstractUnwrappable) and not isinstance(x, Module) and not is_param(x)
 
@@ -1378,15 +1379,20 @@ def _select_parts(tree, where: Selector) -> list[tuple[Any, ...]]:
         paths.extend(resolved[name][0] for name in hits)
 
     unique = list(dict.fromkeys(paths))
-    for a in unique:
-        for b in unique:
+    _check_no_overlap(unique)
+    return unique
+
+
+def _check_no_overlap(paths: list[tuple[Any, ...]]):
+    """Raises if one of the selected paths contains another."""
+    for a in paths:
+        for b in paths:
             if a != b and b[:len(a)] == a:
                 raise ValueError("The selected parts overlap: one contains another.")
-    return unique
 
 
 _UPDATE_FORMS = """prf.update takes one of these forms:
-    update(model, {'name': value, ...}, space=...)   values by name
+    update(model, {'name': value, ...}, space=...)   values by name, or sub-models by name
     update(model, where, value=..., space=...)       one value for the selected parameters
     update(model, where, fixed=True or False)        fixed state of the selected parameters
     update(model, where, node)                       replace the selected parts with `node`
@@ -1417,6 +1423,7 @@ def update(
     .. code-block:: python
 
         prf.update(model, {'L1.L': 3.0, 'C1.C': 2.0})   # values by name
+        prf.update(model, {'load': Short(), 'L1.L': 3.0})  # sub-models and values by name
         prf.update(model, 'L1.*', value=3.0)            # one value for a selection
         prf.update(model, 'cable.*', fixed=True)        # fixed state
         prf.update(model, 'cascade[1]', Short())        # a new sub-model or node
@@ -1434,6 +1441,13 @@ def update(
     and put exactly what they are given in place of each selected part, so the caller
     keeps field invariants. They usually change the structure, and recompile.
 
+    In the mapping form the tier is decided per entry by the value's type. A
+    :class:`pmrf.Model` value is a structural replacement of the sub-model its key
+    names, as in ``update(model, key, node)``: it is unvalidated and usually
+    recompiles, and `space` does not apply to it. Any other value is a validated
+    value update of the parameter its key names. A mapping of values only keeps the
+    jit cache key.
+
     ``fixed=`` is additive: parameters the selector does not match are untouched,
     and ``fixed=False`` frees a parameter even if it was created fixed. It does not
     unfreeze: a parameter inside a :func:`pmrf.freeze` sub-tree stays frozen. To
@@ -1452,7 +1466,9 @@ def update(
         Either a mapping from names to values, or a selector: a name, an `fnmatch`
         glob over names, a sequence of them, or a callable returning nodes of
         `tree`. A mapping is recognised only when every key is a string. Its values
-        may be arrays, or parameters, whose value in `space` is used. Omit it to
+        may be arrays, or parameters, whose value in `space` is used, keyed by
+        parameter name; or models, keyed by sub-model name, which replace that
+        sub-model structurally. Omit it to
         update `tree` itself, which must then be a parameter. In the structural
         forms, an exact name may also name a sub-model (``'cascade[1]'``, or a named
         module's name), a glob matches parameter names only, and a callable selects
@@ -1480,7 +1496,8 @@ def update(
         structurally selected parts overlap. Under `jax.jit` the bounds check raises
         at runtime.
     TypeError
-        If the arguments match none of the forms.
+        If the arguments match none of the forms, or a mapping gives a model for a
+        parameter name or a non-model for a sub-model name.
     """
     has_value = value is not _MISSING
     has_fixed = fixed is not None
@@ -1517,12 +1534,39 @@ def update(
     if isinstance(selection, Mapping):
         if has_value or has_fixed or not all(isinstance(k, str) for k in selection):
             raise form_error()
+        from pmrf.models.base import Model
+
         resolved = tree_param_paths(tree)
-        unknown = [name for name in selection if name not in resolved]
+        submodels = None
+        paths, nodes, unknown = [], [], []
+        for name, v in selection.items():
+            # A joint target is named like a parameter, and its value may itself be a model.
+            if isinstance(v, Model) and not (name in resolved and _is_joint_target(resolved[name][1])):
+                if name in resolved:
+                    raise TypeError(f"'{name}' is a parameter name, but its value is a model; "
+                                    "a model can only replace a sub-model.")
+                if submodels is None:
+                    submodels = _tree_submodel_paths(tree)
+                if name not in submodels:
+                    raise ValueError(f"Unknown sub-model name: '{name}'")
+                if len(submodels[name]) > 1:
+                    raise ValueError(f"Sub-model name '{name}' is ambiguous: several sub-models have it.")
+                paths.append(submodels[name][0])
+                nodes.append(v)
+            elif name in resolved:
+                paths.append(resolved[name][0])
+                nodes.append(_write(resolved[name][1], v, space))
+            else:
+                if submodels is None:
+                    submodels = _tree_submodel_paths(tree)
+                if name in submodels:
+                    raise TypeError(f"'{name}' names a sub-model, but its value is not a model; "
+                                    "only a pmrf.Model can replace a sub-model.")
+                unknown.append(name)
         if unknown:
             raise ValueError(f"Unknown parameter names: {unknown}")
-        paths = [resolved[name][0] for name in selection]
-        nodes = [_write(resolved[name][1], v, space) for name, v in selection.items()]
+        if submodels is not None:
+            _check_no_overlap(paths)
         return _set_paths(tree, paths, nodes)
 
     if not _is_selector(selection) or has_value == has_fixed:

{paramrf-0.35.2 → paramrf-0.35.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "paramrf"
-version = "0.35.2"
+version = "0.35.3"
 description = "Parametric radio frequency modeling"
 readme = "README.rst"
 authors = [