paramrf 0.36.2__tar.gz → 0.36.3__tar.gz

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

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

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

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

{paramrf-0.36.2 → paramrf-0.36.3}/pmrf/utils/transforms.py

@@ -1,6 +1,9 @@
+import dataclasses
+
 import jax
 import jax.numpy as jnp
 import equinox as eqx
+import parax as prx
 from typing import Callable, Any, Tuple, TypeVarTuple
 
 from pmrf.utils.tree import unwrap, batch_axes
@@ -35,6 +38,11 @@ def derivative(eval_fn: Callable[..., Any], *args: *Ts, space: str = 'declared')
     inside the differentiated function, so the source's derivative includes the
     path through the tie. Raw JAX arrays are differentiated as they are.
 
+    In declared and physical space a parameter on a closed bound, such as a
+    ``NonNegative`` loss at 0, has a finite derivative. In raw space it has none:
+    its raw value there is infinite, so a derivative with respect to it has no
+    finite meaning.
+
     Safely handles models as inputs by filtering out non-differentiable
     static fields (like strings, booleans, integers, AND NumPy arrays).
 
@@ -82,15 +90,15 @@ def derivative(eval_fn: Callable[..., Any], *args: *Ts, space: str = 'declared')
     -1.164e-01
     """
     # Imported here: pmrf.parameters imports pmrf.utils.
-    from pmrf.parameters import _check_space, _read, _set_paths, _with_fixed, _write, tree_param_paths
+    from pmrf.parameters import _check_space, _read, _set_paths, _with_fixed, _write, is_param, tree_param_paths
     from pmrf.utils.tree import Pathgetter
 
     _check_space(space)
 
     # Each parameter is replaced by its value in `space`, and rebuilt from it inside
     # the differentiated function, so the derivative is taken with respect to that
-    # value and the chain rule carries it through scale, constraint and ties. Fixed
-    # is an optimisation state, not a zero sensitivity, so parameters are rebuilt free.
+    # value and the chain rule carries it through scale and ties. Fixed is an
+    # optimisation state, not a zero sensitivity, so parameters are rebuilt free.
     rebuilds = []
     surrogates = []
     for arg in args:
@@ -103,12 +111,23 @@ def derivative(eval_fn: Callable[..., Any], *args: *Ts, space: str = 'declared')
         rebuilds.append((paths, nodes))
         surrogates.append(_set_paths(arg, paths, [_read(node, space) for node in nodes]))
 
+    def _rebuild_node(node, value):
+        # In declared and physical space a parameter holds its declared value directly,
+        # as in box space (#226), not through its raw value: on a closed bound that is
+        # infinite, the constraint's bijector gives 0 * inf = NaN, and forward mode
+        # spreads the NaN to every parameter. The value is the one the parameter was
+        # built with, so its bounds need no checking again. A `Real` is free.
+        if not is_param(node) or space == 'raw':
+            return _with_fixed(_write(node, value, space), False)
+        declared = value / node._scale if space == 'physical' and node._scale != 1.0 else value
+        return dataclasses.replace(node, variable=prx.Real(declared))
+
     def _rebuild(surrogate_args):
         rebuilt = []
         for surrogate, (paths, nodes) in zip(surrogate_args, rebuilds):
             values = [Pathgetter(path)(surrogate) for path in paths]
             rebuilt.append(_set_paths(
-                surrogate, paths, [_with_fixed(_write(node, value, space), False) for node, value in zip(nodes, values)]
+                surrogate, paths, [_rebuild_node(node, value) for node, value in zip(nodes, values)]
             ))
         return unwrap(tuple(rebuilt))
 

{paramrf-0.36.2 → paramrf-0.36.3}/pyproject.toml

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

{paramrf-0.36.2 → paramrf-0.36.3}/tests/test_models/test_edge_values.py

@@ -7,6 +7,12 @@ parameter in turn is set to zero, where its validity constraint allows it, and t
 finite closed bound of that constraint. S and its derivative with respect to that
 parameter must be finite, and the MNA and scattering solvers must agree on both.
 
+dS is taken with a `jax.jvp` through the component's constructor, which never goes
+through `prf.derivative`; that is how #238 shipped, NaN from `derivative` on closed
+bounds where every component passed. So each case also takes `prf.derivative` of S with
+respect to every parameter of the component, the swept one on its edge value, and checks
+it is finite and agrees with dS (#239).
+
 Infinite bounds are closed too (Parax ADR 0001: `Positive()` is (0, inf]), but a
 consumer that treats a closed bound as an evaluable point must skip non-finite ones, so
 the sweep does.
@@ -31,6 +37,7 @@ What the sweep found, and what was done (#224):
   negative winding inductance, so negative values never worked.
 - `Load.z0 = 0`, `Port.z0 = 0`: not evaluated; see `NOT_EVALUATED`.
 """
+import dataclasses
 import inspect
 
 import equinox as eqx
@@ -40,8 +47,10 @@ import numpy as np
 import parax as prx
 import pytest
 
+import pmrf as prf
 import pmrf.models
 from pmrf.frequency import Frequency
+from pmrf.materials import ColeColeDielectric, MultipoleDebyeDielectric, RoughConductor
 from pmrf.parameters import Param
 from pmrf.models import (
     Model, Circuit, Port,
@@ -88,9 +97,17 @@ EXAMPLES = {
     RLGCLine: lambda: RLGCLine(R=0.1, L=250e-9, G=1e-6, C=100e-12, length=0.07),
     PhysicalLine: lambda: PhysicalLine(zn=50.0, ep_r=2.2, A=0.01, f_A=1e9, tand=0.001, length=1.0),
     DatasheetLine: lambda: DatasheetLine(zn=50.0, vf=0.69, k1=0.2, k2=0.01, length=1.0),
-    CoaxialLine: lambda: CoaxialLine(length=0.5),
+    # Dispersive and rough materials, so their loss parameters (dep_r, alpha, rms) are
+    # swept too; MicrostripLine keeps the default ConstantDielectric and BulkConductor.
+    CoaxialLine: lambda: CoaxialLine(
+        length=0.5,
+        dielectric=ColeColeDielectric(ep_inf=2.0, dep_r=0.3, f_relax=1e9, alpha=0.2, sigma=1e-4),
+        conductor=RoughConductor(sigma=5.8e7, roughness=1e-6),
+    ),
     MicrostripLine: lambda: MicrostripLine(length=0.1),
-    StriplineLine: lambda: StriplineLine(length=0.1),
+    StriplineLine: lambda: StriplineLine(
+        length=0.1, dielectric=MultipoleDebyeDielectric(ep_inf=2.0, poles=[(0.3, 1e9)]),
+    ),
     FloatingLine: lambda: FloatingLine(floating=PhaseLine(z0=50.0, theta=90.0, f0=0.5e9)),
     Resistor: lambda: Resistor(R=10.0),
     Capacitor: lambda: Capacitor(C=1e-12),
@@ -226,12 +243,46 @@ def _s_and_ds(cls, path, value, solver):
     return jax.jvp(s_of, (jnp.asarray(value),), (jnp.asarray(1.0),))
 
 
+def _with_param(model, path, x):
+    """`model` with the parameter at `path` kept a parameter, holding the declared value `x`.
+
+    Unlike `_at`, which puts a plain array there, so `prf.derivative` meets the parameter
+    on its bound, constraint and all.
+    """
+    get = _getter(path)
+    param = get(model)
+    declared = jnp.broadcast_to(jnp.asarray(x), jnp.shape(param.value))
+    return eqx.tree_at(get, model, dataclasses.replace(param, value=declared))
+
+
+def _derivative(cls, path, value, solver):
+    """dS with respect to every parameter of the component, by `prf.derivative`.
+
+    Returns the swept parameter's derivative, and every parameter's derivative.
+    """
+    model = _with_param(EXAMPLES[cls](), path, value)
+    s_of = lambda m: _in_circuit(m, solver).s(FREQ)
+    # Forward mode is where a NaN from one parameter reaches every other (#238), so the
+    # derivative must be taken in forward mode. S is complex, which `derivative` always
+    # takes forward, and it has more entries than the component has parameters, so it
+    # would be wide, and taken forward, if it were real.
+    n_params = sum(jnp.size(param.value) for _, param in _params(model))
+    assert jax.eval_shape(s_of, model).size > n_params, "the derivative is not wide"
+    (d_model,) = prf.derivative(s_of, model)
+    param_derivatives = [_getter(p)(d_model) for p, _ in _params(model)]
+    return _getter(path)(d_model), param_derivatives
+
+
 # The scattering solver regularises its own system with eps = 1e-12, which moves S, and
 # dS relative to its size, by about 2e-12 (see test_lumped.py). dS is compared relative
 # to its largest entry, which reaches 6e6 for an inductor at zero.
 SCATTERING_TOL = 1e-11
 
 
+def _ds_atol(ref_ds):
+    return SCATTERING_TOL * max(1.0, np.max(np.abs(ref_ds)))
+
+
 @pytest.mark.parametrize("cls, path, value", _cases())
 def test_component_at_edge_value(cls, path, value):
     s, ds = _s_and_ds(cls, path, value, GlobalMNACircuitSolver())
@@ -242,7 +293,18 @@ def test_component_at_edge_value(cls, path, value):
     assert np.all(np.isfinite(ref_s)), "non-finite S under scattering"
     assert np.all(np.isfinite(ref_ds)), "non-finite dS under scattering"
     np.testing.assert_allclose(s, ref_s, rtol=0, atol=SCATTERING_TOL)
-    np.testing.assert_allclose(ds, ref_ds, rtol=0, atol=SCATTERING_TOL * max(1.0, np.max(np.abs(ref_ds))))
+    np.testing.assert_allclose(ds, ref_ds, rtol=0, atol=_ds_atol(ref_ds))
+
+    # `prf.derivative` against the jvp under the same solver: both differentiate the same
+    # computation, so they differ only by rounding, well inside the sweep's dS tolerance.
+    for solver, sweep_ds in [(GlobalMNACircuitSolver(), ds), (GlobalScatteringCircuitSolver(), ref_ds)]:
+        name = type(solver).__name__
+        swept, param_derivatives = _derivative(cls, path, value, solver)
+        assert all(np.all(np.isfinite(d)) for d in param_derivatives), f"non-finite prf.derivative under {name}"
+        np.testing.assert_allclose(
+            np.reshape(swept, np.shape(sweep_ds)), sweep_ds, rtol=0, atol=_ds_atol(sweep_ds),
+            err_msg=f"prf.derivative disagrees with dS under {name}",
+        )
 
 
 @pytest.mark.parametrize("cls, field", [

{paramrf-0.36.2 → paramrf-0.36.3}/tests/test_transforms.py

@@ -245,6 +245,104 @@ def test_derivative_rejects_an_unknown_space():
         prf.derivative(lambda x: x ** 2, jnp.array(1.0), space='unscaled')
 
 
+@pytest.mark.parametrize("space", ["declared", "physical"])
+@pytest.mark.parametrize("k2", [0.0, 1e-6])
+def test_derivative_on_and_near_a_closed_bound(space, k2):
+    """`k2` is NonNegative: at 0 its raw value is -inf, which must not reach the derivative."""
+    from pmrf.models import DatasheetLine
+
+    line = DatasheetLine(length=1.0, zn=50.0, vf=0.8, k1=0.1, k2=k2)
+
+    (d_line,) = prf.derivative(lambda m: 2.0 * m.k2, line, space=space)
+
+    assert prf.values(d_line)['k2'] == 2.0
+
+
+def test_a_closed_bound_is_still_a_valid_value():
+    from pmrf.models import DatasheetLine
+
+    line = DatasheetLine(length=1.0, zn=50.0, vf=0.8, k1=0.1, k2=0.5)
+
+    assert prf.values(prf.update(line, {'k2': 0.0}))['k2'] == 0.0
+    with pytest.raises(Exception, match="outside the constraint"):
+        prf.update(line, {'k2': -1.0})
+
+
+_CLOSED_BOUNDS = {
+    'non_negative': (0.0, prf.constraints.NonNegative()),
+    'greater_than': (2.0, prf.constraints.GreaterThan(2.0)),
+    'interval_upper': (3.0, prf.constraints.Interval(1.0, 3.0)),
+    'less_than': (3.0, prf.constraints.LessThan(3.0)),
+}
+
+
+@pytest.mark.parametrize("n", [1, 50], ids=['tall', 'wide'])
+@pytest.mark.parametrize("space", ["declared", "physical"])
+@pytest.mark.parametrize("bound", list(_CLOSED_BOUNDS))
+def test_derivative_on_a_closed_bound_is_exact_and_confined(bound, space, n):
+    """On a closed bound the derivative is finite and exact, and does not reach the
+    other parameters, whether taken by reverse mode (tall) or forward mode (wide)."""
+    value, constraint = _CLOSED_BOUNDS[bound]
+    scale = 1e-3
+    tree = {
+        'a': prf.Param(value=value, constraint=constraint, scale=scale),
+        'b': prf.Unconstrained(1.5),
+    }
+    x = jnp.linspace(0.0, 1.0, n)
+
+    (d_tree,) = prf.derivative(lambda t: 2.0 * t['a'] + t['b'] * x, tree, space=space)
+
+    per_unit = 1.0 if space == 'physical' else scale
+    assert jnp.array_equal(d_tree['a'], jnp.full(n, 2.0 * per_unit))
+    assert jnp.array_equal(d_tree['b'], x)
+
+
+def test_derivative_in_physical_space_on_a_closed_bound_is_declared_over_scale():
+    tree = {'a': prf.Param(value=0.0, constraint=prf.constraints.NonNegative(), scale=1e-3)}
+    fn = lambda t: jnp.sin(t['a'] + 0.3)
+
+    (declared,) = prf.derivative(fn, tree)
+    (physical,) = prf.derivative(fn, tree, space='physical')
+
+    assert jnp.isfinite(declared['a'])
+    assert jnp.allclose(physical['a'], declared['a'] / 1e-3, rtol=1e-12, atol=0)
+
+
+def _coax_on_a_closed_bound():
+    from pmrf.models import CoaxialLine, SchelkunoffCoaxialFormulation
+    from pmrf.materials import DjordjevicSarkarDielectric, BulkConductor
+
+    # The dielectric's conductivity defaults to 0, the closed bound of NonNegative.
+    return CoaxialLine(
+        length=1.0, d_in=3.124e-3, d_out=8.328e-3,
+        dielectric=DjordjevicSarkarDielectric(ep_r=1.33, tand=1e-4, f_low=1.5e4, f_high=1e11, f_ref=1e8),
+        conductor=BulkConductor(sigma=5.8e7), formulation=SchelkunoffCoaxialFormulation(),
+    )
+
+
+@pytest.mark.parametrize("n", [5, 50], ids=['tall', 'wide'])
+def test_derivative_of_a_line_with_a_parameter_on_a_closed_bound(n):
+    """A parameter on a closed bound gives every parameter a finite derivative, and the
+    others match a reference taken through free parameters inside their bounds."""
+    line = _coax_on_a_closed_bound()
+    freq = prf.Frequency(50, 130, n, 'MHz')
+    fn = lambda m: jnp.abs(m.s(freq)[:, 1, 1])
+
+    (d_line,) = prf.derivative(fn, line)
+    actual = prf.values(d_line)
+
+    assert prf.values(line)['dielectric.sigma'] == 0.0
+    assert all(jnp.isfinite(v).all() for v in actual.values()), actual
+
+    # Fixed parameters stop the gradient through `prf.update`, so the reference frees them.
+    names = ['length', 'd_in', 'd_out', 'dielectric.ep_r', 'dielectric.tand']
+    free = prf.update(line, names, fixed=False)
+    values = prf.values(free, names)
+    expected = jax.jacfwd(lambda v: fn(prf.unwrap(prf.update(free, v))))(values)
+    for name in names:
+        assert jnp.allclose(actual[name], expected[name], rtol=1e-12, atol=0), name
+
+
 def test_sweep_parallel():
     """
     Verifies that a standard sweep correctly vectorizes across the leading