update

pmrf.parameters.update(tree, selection: ~typing.Any = <object object>, node: ~typing.Any = <object object>, /, *, value: ~typing.Any = <object object>, fixed: bool | None = None, space: ~typing.Literal['raw', 'declared', 'physical'] | None = None, on_invalid: str = 'raise', fn: ~typing.Callable[[~typing.Any], ~typing.Any] | None = None)

Returns a copy of a model with the parts a selector picks replaced.

Exactly one form says what replaces them:

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
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(model, {'R': trial}, on_invalid='nan') # reject an invalid trial
prf.update(param, value=3.0)                    # the parameter itself

The mapping, value and fixed forms go through each parameter’s constructor: values are checked against the bounds, and the prior, constraint, scale, name and metadata are kept. Value forms keep the model’s structure, and every leaf’s dtype, shape and weak_type, so RF methods such as pmrf.Model.s() do not recompile. Changing fixed changes the structure, and recompiling is expected.

The node and fn forms are structural: they bypass converters and validation, 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 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 pmrf.freeze() sub-tree stays frozen. To leave only some parameters free, fix everything, then free those: update(update(m, '*', fixed=True), names, fixed=False).

update is not an optimiser step. For replacing a field of one object without validation, use pmrf.replace(). To derive one parameter from another, use tie().

By default, an invalid numerical value raises. Set on_invalid='nan' to make a numerical trial non-raising: if a candidate is nonfinite or outside a parameter’s effective constraint, the entire updated value leaf becomes NaN. Other requested values are still written. This option applies only to numerical value updates; it cannot be combined with fixed-state changes or structural replacements. Candidate values are checked after conversion from space to declared space, including after the joint-prior whitening map for raw updates.

Parameters:

  • tree (PyTree) – A model, any collection of models and parameters, or a single parameter.

  • selection (Mapping[str, ArrayLike | Param] or selector, optional) – 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, 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 the nodes it returns rather than the parameters below them.

  • node (Any, optional) – The part to put in place of each selected part.

  • value (ArrayLike, optional) – The value to give every selected parameter.

  • fixed (bool, optional) – The fixed state to give every selected parameter.

  • space ({'declared', 'physical', 'raw'}, optional) – The space of the values, by default 'declared'. Only used with values. A raw value of a parameter under a joint prior is its slice of the prior’s whitened vector, in its own shape: the entries not given keep their raw values, and every parameter under the prior may move.

  • on_invalid ({'raise', 'nan'}, optional) – How numerical value updates handle nonfinite values and values outside the effective constraint. The default 'raise' preserves strict validation. 'nan' writes NaN to the entire invalid parameter leaf and is only available for floating-point or complex numerical value updates.

  • fn (Callable, optional) – Called on each selected part; its result replaces the part.

Returns:

The updated copy.

Return type:

PyTree

Raises:

  • ValueError – If a name is unknown, a value is outside its parameter’s constraint, structurally selected parts overlap, or fixed=True selects a parameter under a joint prior. Under jax.jit the bounds check raises at runtime.

  • TypeError – 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, or on_invalid='nan' is used with a structural update or a non-floating-point value leaf.