paramrf 0.36.1__tar.gz → 0.36.2__tar.gz

{paramrf-0.36.1 → paramrf-0.36.2}/CONTEXT.md

@@ -26,10 +26,23 @@ Where a parameter's number lives. Every surface defaults to **declared**.
   declares (2.0 for 2 pF). Construction, bounds, priors and `Param.value` are
   in declared space.
 - **physical**: the scaled, SI value (2e-12).
+- **box**: the box a bounded minimiser searches, built from a parameter's
+  bounds, not its prior: the unit box when both bounds are finite, declared
+  space otherwise (ADR-0007).
 
 *Avoid:* "unconstrained space" (reads as a parameter without bounds; that is
 `prf.Unconstrained`), "unscaled" and "constrained" for declared space, "unit
-space" (the unit hypercube).
+space" (the unit hypercube; box space is the unit box only when both bounds are
+finite), "base space" for box space (Parax's name for it, but ADR-0005's "base"
+is a flow's latent, which is raw).
+
+### Open and closed bounds
+
+Each bound of a parameter is **closed** (the bound is a valid value, and a
+model must evaluate there) or **open** (the bound is excluded, and a value on
+it is rejected at construction). Closedness belongs to the constraint:
+`pmrf.Bounded` and a `Uniform` support are closed, `Positive()` is open, and
+where two constraints meet at one bound, open wins (ADR-0007).
 
 ### Scale
 
@@ -184,4 +197,6 @@ paper with no ParamRF objects in sight.
 interface or a default, and `docs/adr/0002-parameter-api.md` before adding a
 method, a public function or a value space. Read
 `docs/adr/0005-priors-by-name.md` before changing how priors are attached or
-scored.
+scored, and `docs/adr/0007-edge-values.md` before changing how a
+circuit solver produces S, how bounds are validated, or which space a solver
+moves through.

{paramrf-0.36.1/paramrf.egg-info → paramrf-0.36.2}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: paramrf
-Version: 0.36.1
+Version: 0.36.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>=0.11.1
+Requires-Dist: parax>=0.11.5
 Requires-Dist: threadpoolctl
 Requires-Dist: eqxpress
 Requires-Dist: jax

paramrf-0.36.2/docs/adr/0007-edge-values.md

@@ -0,0 +1,130 @@
+# ADR-0007: Values at the edge of a domain: zero impedance and parameters on bounds
+
+Status: accepted (2026-09)
+
+## Context
+
+#215 reported zero inductance breaking the default `GlobalMNACircuitSolver`, and
+parameters that start exactly on a bound being unable to move. Both are values
+at the edge of a domain, and both failed quietly:
+
+- `Inductor.y()` is `1/(jωL)`, which is not finite at L = 0. `Model.mna()`
+  stamps from `y()`, so the MNA solve returns NaN.
+- With a finite stamp (`PiSectionCLC` goes through ABCD), the MNA solver still
+  returns Y, and two ports joined by a short have no finite Y. The solver
+  regularises it to about 1e12, and `y2s` of that Y has a condition number
+  around 1e14: |S21|² came out 0.7% wrong and dL wrong by ten orders of
+  magnitude, without a warning. Removing the regularisation from the auxiliary
+  rows made it worse: the singular block went to a least-squares solve, and
+  the short came out as an open.
+- `BoxSectionCLCC` substitutes eps for L = 0, which fixes the value and zeroes
+  the gradient.
+- Parax documents `Interval` and `GreaterThan` as exclusive, but validates them
+  as inclusive, and maps them onto open raw spaces. So `Bounded(0, 10, value=0)`
+  is accepted, has raw value −∞, and cannot move. `minimize` rejects it.
+  `Random(Uniform(0, 10), value=0)` is silently moved to 2.2e-15 by a clip in
+  parax. `minimize` gives even bounded solvers raw space with infinite bounds,
+  so no solver ever sees the box the user wrote.
+
+Engineers expect both to work: an inductor fitted down to 0, and a parameter
+started on, or converging to, the bound they gave it.
+
+## Decision
+
+### Circuit solvers return S at the probe reference
+
+A circuit solver that assembles a nodal system loads each external port with
+the probe reference impedance $Z_r$ (ADR-0006) and drives it through $Z_r$. With
+$H$ the port-voltage response to the drive, it returns power-wave S directly:
+
+$$H = (Y + Z_r^{-1})^{-1} Z_r^{-1}, \qquad
+S = F\,\big(2\,\mathrm{Re}(Z_r)\,Z_r^{-1} H - Z_r^{*} Z_r^{-1}\big)\,F^{-1}, \qquad
+F = \mathrm{diag}\big(1 / (2\sqrt{\mathrm{Re}\,Z_r})\big)$$
+
+where $Y + Z_r^{-1}$ is eliminated inside the full MNA system, never formed.
+Loaded ports keep the system non-singular when ports are shorted together, so
+the result is exact there. $Z_r$ may be complex and per-port. For real $Z_r$
+this reduces to $S = 2\sqrt{G}\,(Y+G)^{-1}\sqrt{G} - I$; that short form is
+wrong for complex $Z_r$.
+
+- **One implementation.** `pmrf.rf.mna2s(stamp, z0)` holds the formula. The
+  MNA solver uses it, and so does `Model.s()` for a model whose primary domain
+  is MNA.
+- **The solve depends on the probe.** `Circuit.s(z0=...)` passes its probe into
+  the solve rather than renormalising a probe-free Y afterwards.
+- **Regularisation is physical.** GMIN is a conductance from every node to
+  ground. Each auxiliary branch gets a +eps Ω series resistance, which resolves
+  loops of zero-impedance branches. The system is therefore never singular,
+  and the default linear solver is LU (`well_posed=True`): a singular system is
+  a bug and shows up as NaN, not as a least-squares answer.
+- **Y stays honest.** `Circuit.y()` is `s2y` of S at the native reference, and
+  is non-finite for shorted ports. `Circuit.mna()` is `s2mna` of S at the hub
+  reference, which stays finite, so nested circuits are exact.
+- **Series elements that can short stamp as branches.** An element whose
+  impedance can be zero (`Inductor`, `InductorQ`, the inductor in
+  `BoxSectionCLCC`) stamps with an auxiliary branch current,
+  $V_1 - V_2 - Z I = 0$, not from `y()`. Its `y()` is undefined at zero and may
+  be non-finite there. No model substitutes eps for a zero value.
+- **The nodal solver stays Y-only.** `GlobalNodalCircuitSolver` cannot
+  represent a zero impedance and documents it.
+
+### Bounds are open or closed, and solvers see the box
+
+- **Each bound is open or closed**, declared by its Parax constraint.
+  `Positive` and `Negative` are open; `NonNegative` and `NonPositive` are
+  closed; `Interval`, `GreaterThan` and `LessThan` take `closed` and default to
+  closed. `pmrf.Bounded` and a `Uniform` support are closed. Where two
+  constraints meet at one bound, open wins. Validation respects closedness, so
+  a value on an open bound is rejected at construction.
+- **A closed bound is part of the model's domain.** A model evaluates, with a
+  finite value and gradient, at every closed bound of its parameters and at
+  zero where zero is valid. A value it cannot evaluate gets an open validity
+  constraint instead: a line width is `Positive()`, a quality factor is
+  `Positive()`. Lumped L, C and R stay unconstrained, because fitted
+  equivalent circuits use negative values.
+- **Box space** is a fourth space: the box a bounded minimiser searches. It is
+  built from a parameter's bounds, not its prior: the unit box when both bounds
+  are finite, declared space otherwise. A closed edge of the box is the bound
+  itself; an open edge is inset by δ = 1e-6.
+- **Minimisers say whether they honour bounds**, through the minimiser
+  interface. `SolverView` hands box space to one that does and raw space to one
+  that does not. Nothing in `SolverView` knows about a specific backend.
+- **A start on a closed bound is nudged for raw space.** For raw-space
+  consumers (unbounded minimisers and samplers), `SolverView` moves a start on a
+  closed bound δ = 1e-6 inward in box space before mapping it to raw. The nudge
+  is silent: it is the kind of difference engineers expect between optimisers.
+- **Raw space is unchanged.** It stays whitened by the prior (ADR-0005).
+
+## Rejected options
+
+- **Keep Y from the MNA solver and detect ill-conditioning.** Wrong answers get
+  louder but stay wrong.
+- **Substitute eps for zero in models.** It is what `BoxSectionCLCC` did, and
+  it zeroes the gradient at exactly the value being fitted.
+- **A tanh map for `Interval`.** Any map ending in `lower + width·u` has an
+  absolute precision of about eps·width. tanh only moves the exact point from
+  the lower bound to the midpoint, and loses it at a lower bound of 0, the
+  common case.
+- **Reject every start on a bound.** Correct, but engineers write bounds they
+  mean to include.
+- **Nudge by a fixed raw value.** A raw value of −14 is 1e-6 of a sigmoid's
+  width, but 1e-43 of a prior-whitened parameter's slope. The nudge has to be
+  in box space to mean the same thing for every parameter.
+- **Track whether a bound came from a range or a validity constraint.**
+  Closedness is a property of the constraint; recording it there needs no
+  bookkeeping when constraints are intersected.
+- **Box space whitened by the prior**, as Parax does for `Random`. A prior is a
+  belief, not the shape of the search; a `Normal` prior made the box edges ±∞,
+  kept finite only by a clip.
+
+## Consequences
+
+- Circuits with shorted ports, and every component at L, C or R = 0, give the
+  same S and gradient under MNA and scattering solvers.
+- `value=0` on a `Positive` field now raises at construction.
+- A `Random` parameter on a bound has raw value ±∞ once Parax drops its clip,
+  and is nudged like any other.
+- Fits run through a minimiser that honours bounds now evaluate the objective
+  exactly on closed bounds. A test sweep evaluates every component at its
+  closed bounds and at zero so this is safe.
+- A fit that started on a bound gives slightly different results than before.

{paramrf-0.36.1 → paramrf-0.36.2/paramrf.egg-info}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: paramrf
-Version: 0.36.1
+Version: 0.36.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>=0.11.1
+Requires-Dist: parax>=0.11.5
 Requires-Dist: threadpoolctl
 Requires-Dist: eqxpress
 Requires-Dist: jax

{paramrf-0.36.1 → paramrf-0.36.2}/paramrf.egg-info/SOURCES.txt

@@ -29,6 +29,7 @@ docs/adr/0003-derived-models.md
 docs/adr/0004-profiled-lines.md
 docs/adr/0005-priors-by-name.md
 docs/adr/0006-reference-impedance.md
+docs/adr/0007-edge-values.md
 docs/agents/domain.md
 docs/agents/issue-tracker.md
 docs/agents/triage-labels.md
@@ -184,6 +185,7 @@ tests/__init__.py
 tests/_jit.py
 tests/conftest.py
 tests/test_autodiff.py
+tests/test_box_space_solving.py
 tests/test_conversions.py
 tests/test_covariance_kernels.py
 tests/test_dc_limits.py
@@ -224,10 +226,12 @@ tests/test_models/test_circuit_native_z0.py
 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_circuit_shorted_ports.py
 tests/test_models/test_circuit_skrf_port_names.py
 tests/test_models/test_circuit_z0.py
 tests/test_models/test_current_distribution.py
 tests/test_models/test_derived.py
+tests/test_models/test_edge_values.py
 tests/test_models/test_interconnected.py
 tests/test_models/test_lines.py
 tests/test_models/test_lines_skrf_matrix.py

{paramrf-0.36.1 → paramrf-0.36.2}/paramrf.egg-info/requires.txt

@@ -1,4 +1,4 @@
-parax>=0.11.1
+parax>=0.11.5
 threadpoolctl
 eqxpress
 jax

paramrf-0.36.2/pmrf/_solver_view.py

@@ -0,0 +1,284 @@
+"""
+The view of a model a solver moves through, shared by the minimiser and every sampler.
+
+A solver never sees the model itself: it sees the free parameters as a name-keyed dict
+of values: in box space for a minimiser that honours bounds, in raw space for one that
+does not and for the joint and split samplers, and in declared space for the hypercube
+samplers. Values are read and written through the public :func:`pmrf.values`,
+:func:`pmrf.update` and :func:`pmrf.log_prior`, so a solver sees exactly what a user
+would with those functions.
+
+Box space is the box a bounded minimiser searches (ADR-0007). Along each parameter it is
+built from the constraint's bounds, not its prior (Parax's ``base_bounds`` and
+``base_bijector``): the unit box between two finite bounds, declared space otherwise. A closed edge of the box is the
+bound itself; an open edge is inset by 1e-6.
+"""
+
+import dataclasses
+from typing import Any, Callable
+
+from jaxtyping import Array, PyTree, Scalar
+
+import equinox as eqx
+import jax
+import jax.numpy as jnp
+import parax as prx
+
+from pmrf.parameters import (
+    Param, is_param, log_prior as _log_prior, params, tree_param_paths, values as _values, update,
+)
+from pmrf.utils import unwrap
+from pmrf.utils.tree import Pathgetter
+
+
+# How far a start on a closed bound is moved inward, and an open edge of the box is
+# inset, in box space (ADR-0007).
+_NUDGE = 1e-6
+
+
+def _box_constraint(node: Param | Array) -> prx.constraints.AbstractConstraint | None:
+    """Returns the constraint whose bounds give the box of `node`, or None if `node` is
+    a raw array or an unconstrained parameter, whose box is its declared space."""
+    return prx.unwrap(node.constraint) if is_param(node) else None
+
+
+def _box_edges(node: Param | Array) -> tuple[Array, Array]:
+    """Returns the lower and upper edges of the box of `node`, shaped like its value."""
+    value = jnp.asarray(node.value if is_param(node) else node)
+    constraint = _box_constraint(node)
+    if constraint is None:
+        return jnp.full_like(value, -jnp.inf), jnp.full_like(value, jnp.inf)
+
+    def _like_value(x):
+        return jnp.broadcast_to(jnp.asarray(x), value.shape).astype(value.dtype)
+
+    lower, upper = (_like_value(b) for b in constraint.base_bounds)
+    lower_closed, upper_closed = (jnp.broadcast_to(jnp.asarray(c), value.shape) for c in constraint.closed)
+    return jnp.where(lower_closed, lower, lower + _NUDGE), jnp.where(upper_closed, upper, upper - _NUDGE)
+
+
+def _to_box(node: Param | Array) -> Array:
+    """Returns the declared value of `node` in its box space."""
+    value = jnp.asarray(node.value if is_param(node) else node)
+    constraint = _box_constraint(node)
+    if constraint is None:
+        return value
+    return jnp.broadcast_to(constraint.base_bijector.inverse(value), value.shape).astype(value.dtype)
+
+
+def _from_box(node: Param | Array, box: Array) -> Array:
+    """Returns the box-space value `box` of `node` in declared space.
+
+    The result is kept inside the bounds, which rounding at a closed edge could
+    otherwise step past. The comparison leaves the gradient at the edge intact.
+    """
+    constraint = _box_constraint(node)
+    if constraint is None:
+        return box
+    declared = constraint.base_bijector.forward(box)
+    lower, upper = constraint.bounds
+    return jnp.where(declared < lower, lower, jnp.where(declared > upper, upper, declared))
+
+
+def _node_from_box(node: Param | Array, box: Array) -> Param | Array:
+    """Returns `node` holding the box-space value `box`, for evaluating the objective.
+
+    A parameter stays a parameter, with its scale, name and validity, so a derived
+    model's builder sees what it would otherwise. It holds its declared value directly,
+    not through its raw value, which is infinite on a closed bound, so the value and
+    its gradient are finite there.
+    """
+    declared = _from_box(node, box)
+    if not is_param(node):
+        return declared
+    return dataclasses.replace(node, variable=prx.Real(declared))
+
+
+def _nudged(param: Param) -> Array | None:
+    """Returns the declared value of `param` with each element on a closed bound moved
+    1e-6 inward in box space, or None if no element is on one.
+
+    Box space is built from the constraint's bounds: the unit box between two finite
+    bounds, declared space otherwise. An element also counts as on a bound when it is
+    no further from it, in box space, than twice the bound's image through the
+    raw-to-declared bijector. A Parax prior whitening clips on the way out of raw
+    space, so a prior's value set on its bound reads back slightly inside it, with a
+    raw value too far out to move.
+    """
+    constraint = prx.unwrap(param.constraint)
+    if constraint is None:
+        return None
+    value = param.value
+    to_declared = constraint.base_bijector
+
+    def _like_value(x):
+        return jnp.broadcast_to(jnp.asarray(x), value.shape)
+
+    box = _like_value(to_declared.inverse(value))
+    lower, upper = (_like_value(b).astype(value.dtype) for b in constraint.base_bounds)
+    lower_closed, upper_closed = (_like_value(c) for c in constraint.closed)
+    ends = [
+        _like_value(to_declared.inverse(constraint.bijector.forward(jnp.full(value.shape, x, value.dtype))))
+        for x in (-jnp.inf, jnp.inf)
+    ]
+    unknown = jnp.isnan(ends[0]) | jnp.isnan(ends[1])
+    lower_image = jnp.where(unknown, lower, jnp.minimum(*ends))
+    upper_image = jnp.where(unknown, upper, jnp.maximum(*ends))
+
+    at_lower = lower_closed & jnp.isfinite(lower) & (box - lower <= 2 * (lower_image - lower))
+    at_upper = upper_closed & jnp.isfinite(upper) & ~at_lower & (upper - box <= 2 * (upper - upper_image))
+    if not bool(jnp.any(at_lower | at_upper)):
+        return None
+
+    nudged = to_declared.forward(jnp.where(at_lower, lower + _NUDGE, upper - _NUDGE))
+    return jnp.where(at_lower | at_upper, nudged, value).astype(value.dtype)
+
+
+class SolverView:
+    """
+    The free parameters of a model, as the dict of values a solver moves through.
+
+    The starting values :attr:`y0` are raw, and :meth:`updated` and :meth:`objective`
+    take a ``space`` so a solver working in declared space, such as a hypercube
+    sampler, or in box space, such as a minimiser that honours bounds, can use the
+    same view. :meth:`box` gives the start and edges in box space.
+
+    A parameter starting on a closed bound has an infinite raw value, so :attr:`y0`
+    starts it 1e-6 inward in box space instead (ADR-0007). The model keeps
+    the value it was given.
+
+    Parameters
+    ----------
+    model : PyTree
+        A model, or any collection of models and parameters.
+    action : str
+        What the solver does, such as ``'optimize'``, for the error raised when there
+        is nothing to move.
+
+    Raises
+    ------
+    ValueError
+        If `model` has no free parameters.
+    """
+
+    def __init__(self, model: PyTree, action: str):
+        #: The model the values are written into.
+        self.model = model
+        #: What the solver does, used in error messages.
+        self.action = action
+        raw = _values(model, free_only=True, space='raw')
+        if not raw:
+            raise ValueError(
+                f"Nothing to {action}: the tree has no free parameters. Every parameter is "
+                "either fixed or a plain value."
+            )
+        nudged = {}
+        for name, param in params(model, free_only=True).items():
+            if is_param(param) and (value := _nudged(param)) is not None:
+                nudged[name] = value
+        if nudged:
+            raw = _values(update(model, nudged), free_only=True, space='raw')
+        #: The starting raw values of the free parameters, by name, with each start on
+        #: a closed bound nudged inward.
+        self.y0 = raw
+        # The free parameters' paths and nodes, by name, for box space.
+        self._free = tree_param_paths(model, free_only=True)
+
+    def box(self) -> tuple[dict, tuple[dict, dict]]:
+        """Returns the start and the box a bounded minimiser searches, in box space.
+
+        A start on a closed bound stays on it. A start outside the box, which can only
+        be within 1e-6 of an open bound, is moved onto its edge.
+
+        Returns
+        -------
+        tuple
+            ``(y0, (lower, upper))``: the starting box values of the free parameters
+            and the lower and upper edges of the box, each a dict by name.
+        """
+        lower, upper, y0 = {}, {}, {}
+        for name, (_, node) in self._free.items():
+            lower[name], upper[name] = _box_edges(node)
+            y0[name] = jnp.clip(_to_box(node), lower[name], upper[name])
+        return y0, (lower, upper)
+
+    def check_finite(self) -> None:
+        """Checks that no starting raw value is NaN, so a solver can move it.
+
+        Only for solvers that move raw values.
+
+        Raises
+        ------
+        ValueError
+            If a starting raw value is NaN.
+        """
+        def _leaves(v):
+            return [jnp.asarray(x) for x in jax.tree.leaves(v)]
+
+        nan = [name for name, v in self.y0.items() if any(bool(jnp.any(jnp.isnan(x))) for x in _leaves(v))]
+        if nan:
+            raise ValueError(
+                f"Cannot {self.action}: {', '.join(repr(name) for name in nan)} start at NaN, "
+                "which no solver can move. Give them a finite starting value."
+            )
+
+    def updated(self, values: dict, space: str = 'raw') -> PyTree:
+        """Returns the model with `values`, by name and in `space`, written into it.
+
+        `space` is ``'box'`` or any space :func:`pmrf.update` takes. Batched values give
+        a batched model; fixed parameters stay unbatched.
+        """
+        if space == 'box':
+            declared = {name: _from_box(self._free[name][1], v) for name, v in values.items()}
+            return update(self.model, declared, space='declared')
+        return update(self.model, values, space=space)
+
+    def read(self, batch: PyTree) -> dict:
+        """Returns the raw values of the free parameters of `batch`, a model like this one.
+
+        Raises
+        ------
+        ValueError
+            If a free parameter of this model is missing from `batch`, or is fixed there.
+        """
+        values = _values(batch, free_only=True, space='raw')
+        missing = [name for name in self.y0 if name not in values]
+        if missing:
+            raise ValueError(
+                f"Cannot {self.action}: {', '.join(repr(name) for name in missing)} "
+                f"{'is' if len(missing) == 1 else 'are'} free in the model but missing or "
+                "fixed in the given tree. It must have the same free parameters as the model."
+            )
+        return {name: values[name] for name in self.y0}
+
+    def objective(self, fn: Callable[[PyTree, Any], Scalar], space: str = 'raw') -> Callable[[dict, Any], Scalar]:
+        """Returns `fn`, which takes the unwrapped model, as a function of values in `space`.
+
+        In box space each free parameter holds its declared value directly, rather than
+        through its raw value, which is infinite on a closed bound. So the objective and
+        its gradient are finite there.
+        """
+        if space == 'box':
+            names = list(self._free)
+            getter = Pathgetter(*(path for path, _ in self._free.values()))
+
+            def box_value_fn(values: dict, args: Any) -> Scalar:
+                nodes = [_node_from_box(self._free[name][1], values[name]) for name in names]
+                model = eqx.tree_at(getter, self.model, nodes[0] if len(nodes) == 1 else tuple(nodes))
+                return fn(unwrap(model), args)
+            return box_value_fn
+
+        def value_fn(values: dict, args: Any) -> Scalar:
+            return fn(unwrap(self.updated(values, space)), args)
+        return value_fn
+
+    def log_prior(self, values: dict, _args: Any = None) -> Scalar:
+        """Returns the raw-space log prior of the model at `values`."""
+        return _log_prior(self.updated(values), space='raw')
+
+    def log_posterior(self, loglikelihood_fn: Callable[[PyTree, Any], Scalar]) -> Callable[[dict, Any], Scalar]:
+        """Returns the raw-space log posterior: `loglikelihood_fn` plus the raw log prior."""
+        def value_fn(values: dict, args: Any) -> Scalar:
+            model = self.updated(values)
+            return loglikelihood_fn(unwrap(model), args) + _log_prior(model, space='raw')
+        return value_fn

{paramrf-0.36.1 → paramrf-0.36.2}/pmrf/constraints.py

@@ -12,6 +12,8 @@ from parax.constraints import (
     RealLine as RealLine,
     Positive as Positive,
     Negative as Negative,
+    NonNegative as NonNegative,
+    NonPositive as NonPositive,
     Interval as Interval,
     GreaterThan as GreaterThan,
     LessThan as LessThan,
@@ -25,6 +27,8 @@ __all__ = [
     'RealLine',
     'Positive',
     'Negative',
+    'NonNegative',
+    'NonPositive',
     'Interval',
     'GreaterThan',
     'LessThan',

{paramrf-0.36.1 → paramrf-0.36.2}/pmrf/infer/base.py

@@ -237,9 +237,10 @@ def run_sampler(
     :func:`pmrf.update`, so fixed parameters, names, scales and priors are unchanged,
     and only free parameters are batched.
 
-    A parameter starting exactly on one of its bounds has an infinite raw value and
-    could not move, so a joint or split sampler raises; start it inside its bounds.
-    A hypercube sampler works in declared space and accepts it.
+    A parameter starting exactly on a closed bound has an infinite raw value, so a
+    joint or split sampler starts it just inside: by 1e-6 of the width between two
+    finite bounds, or 1e-6 in declared units otherwise. A hypercube sampler works in
+    declared space and starts it on the bound.
 
     Parameters
     ----------
@@ -271,7 +272,7 @@ def run_sampler(
     ------
     ValueError
         If `model` has no free parameters, a joint or split sampler is given a
-        parameter starting on a bound, `init_samples` is missing a free parameter, or
+        parameter starting at NaN, `init_samples` is missing a free parameter, or
         a hypercube sampler is given a free parameter without a prior, a prior with no
         inverse CDF, or a joint prior with no independent normal base.
     """

{paramrf-0.36.1 → paramrf-0.36.2}/pmrf/materials/dielectric.py

@@ -10,7 +10,7 @@ from __future__ import annotations
 from abc import abstractmethod
 
 import jax.numpy as jnp
-from pmrf.constraints import Positive, GreaterThan, Interval
+from pmrf.constraints import Positive, NonNegative, GreaterThan, Interval
 from pmrf.frequency import Frequency
 from pmrf.modules.base import Module
 from pmrf.parameters import Param, param
@@ -89,10 +89,10 @@ class ConstantDielectric(AbstractDielectric):
     ep_r: Param = param(default=1.0, constraint=GreaterThan(1.0))
 
     #: Dielectric loss tangent
-    tand: Param = param(default=0.0, constraint=Positive())
+    tand: Param = param(default=0.0, constraint=NonNegative())
 
     #: Static bulk conductivity in S/m
-    sigma: Param = param(default=0.0, constraint=Positive())
+    sigma: Param = param(default=0.0, constraint=NonNegative())
 
     #: Relative permeability of the medium
     mu_r: Param = param(default=1.0, constraint=Positive())
@@ -155,7 +155,7 @@ class DjordjevicSarkarDielectric(AbstractDielectric):
     ep_r: Param = param(default=1.0, constraint=GreaterThan(1.0))
 
     #: Dielectric loss tangent at `f_ref`
-    tand: Param = param(default=0.0, constraint=Positive())
+    tand: Param = param(default=0.0, constraint=NonNegative())
 
     #: Lower bound of the relaxation-time distribution
     f_low: Param = param(default=1e3, constraint=Positive())
@@ -167,7 +167,7 @@ class DjordjevicSarkarDielectric(AbstractDielectric):
     f_ref: Param = param(default=1e9, constraint=Positive())
 
     #: Static bulk conductivity in S/m
-    sigma: Param = param(default=0.0, constraint=Positive())
+    sigma: Param = param(default=0.0, constraint=NonNegative())
 
     def properties(self, freq: Frequency) -> DielectricProperties:
         f = freq.f
@@ -201,7 +201,7 @@ class DebyePole(Module):
         Relaxation frequency of the pole in Hz.
     """
     #: Permittivity increment of the pole
-    dep_r: Param = param(default=0.0, constraint=Positive())
+    dep_r: Param = param(default=0.0, constraint=NonNegative())
 
     #: Relaxation frequency of the pole
     f_relax: Param = param(default=1e9, constraint=Positive())
@@ -256,7 +256,7 @@ class MultipoleDebyeDielectric(AbstractDielectric):
     poles: tuple[DebyePole, ...] = field(default=(), converter=_as_poles)
 
     #: Static bulk conductivity in S/m
-    sigma: Param = param(default=0.0, constraint=Positive())
+    sigma: Param = param(default=0.0, constraint=NonNegative())
 
     def properties(self, freq: Frequency) -> DielectricProperties:
         eps = self.ep_inf * jnp.ones(freq.npoints, dtype=complex)
@@ -300,7 +300,7 @@ class ColeColeDielectric(AbstractDielectric):
     ep_inf: Param = param(default=1.0, constraint=GreaterThan(1.0))
 
     #: Permittivity increment
-    dep_r: Param = param(default=0.0, constraint=Positive())
+    dep_r: Param = param(default=0.0, constraint=NonNegative())
 
     #: Relaxation frequency
     f_relax: Param = param(default=1e9, constraint=Positive())
@@ -309,7 +309,7 @@ class ColeColeDielectric(AbstractDielectric):
     alpha: Param = param(default=0.0, constraint=Interval(0.0, 1.0))
 
     #: Static bulk conductivity in S/m
-    sigma: Param = param(default=0.0, constraint=Positive())
+    sigma: Param = param(default=0.0, constraint=NonNegative())
 
     def properties(self, freq: Frequency) -> DielectricProperties:
         # Guard f = 0, where (jf/f_r)**(1-alpha) is a branch point.
@@ -355,7 +355,7 @@ class TabulatedDielectric(AbstractDielectric):
     ep_r: jnp.ndarray = field(converter=lambda x: jnp.asarray(x, dtype=complex))
 
     #: Static bulk conductivity in S/m
-    sigma: Param = param(default=0.0, constraint=Positive())
+    sigma: Param = param(default=0.0, constraint=NonNegative())
 
     def __check_init__(self):
         if self.f.ndim != 1 or self.ep_r.ndim != 1:

{paramrf-0.36.1 → paramrf-0.36.2}/pmrf/materials/roughness.py

@@ -4,7 +4,7 @@ from abc import abstractmethod
 import jax.numpy as jnp
 from scipy.constants import mu_0
 
-from pmrf.constraints import Positive
+from pmrf.constraints import NonNegative
 from pmrf.frequency import Frequency
 from pmrf.modules.base import Module
 from pmrf.parameters import Param, param
@@ -55,7 +55,7 @@ class HammerstadRoughness(AbstractRoughness):
         RMS surface roughness in meters.
     """
     #: RMS surface roughness in meters
-    rms: Param = param(default=0.0, constraint=Positive())
+    rms: Param = param(default=0.0, constraint=NonNegative())
 
     def factor(self, freq: Frequency, sigma, mu_r) -> jnp.ndarray:
         w = jnp.asarray(freq.w)