paramrf 0.36.4__tar.gz → 0.36.5__tar.gz

{paramrf-0.36.4 → paramrf-0.36.5}/CONTEXT.md

@@ -98,7 +98,9 @@ is derived, so it has no prior of its own.
 
 `prf.prior` attaches a prior to the parameters a selector picks (ADR-0005). A
 scalar distribution gives each of them its own prior. A distribution whose
-event size equals the number of parameters is a **joint prior** over them: a
+event size equals the parameters' total size (their number, when they are
+scalars; an array parameter counts each of its values) is a **joint prior** over
+them: a
 wrapper (`prf.modules.Probabilistic`) around the unchanged tree, so every
 parameter keeps its name. A joint prior replaces its parameters' own priors,
 and its `space` says which space its distribution is over. Raw space for its
@@ -170,6 +172,87 @@ Modifies conductor behaviour rather than line state — it scales a surface
 impedance — so it belongs to the material, not the geometry: it is a field of
 `RoughConductor` in `pmrf.materials.conductor`.
 
+## Discrepancy modelling
+
+A fit in Kennedy–O'Hagan form treats an observation as $\tilde h = h(\theta) +
+\delta + \varepsilon$: the model prediction, a **discrepancy** and measurement
+noise. `MarginalLogLikelihood` scores it; see `pmrf.discrepancy_models` and
+`pmrf.likelihoods`.
+
+### Event space and event block
+
+The space in which probability is defined: the prediction after the event
+transform, with frequency as the last (event) axis. Every other axis is a batch
+axis. One entry of that batch, for example the real part of S21, is an **event
+block**. Blocks are independent: a kernel chooses the covariance *within* each
+block (`AutoCrossKernel` routes by block, `SharedIndependentKernel` shares
+hyperparameters across blocks) and never couples two blocks.
+
+*Avoid:* "output" or "task" for a block; "cross-covariance" for the kernel an
+`AutoCrossKernel` gives a transmission block.
+
+### Discrepancy
+
+$\delta$, the systematic misfit between model and reality, as opposed to noise
+$\varepsilon$. Either deterministic or a `GaussianProcess` over each event block.
+It is on the observable unless it is a port discrepancy.
+
+### Residual
+
+The observation minus the model prediction, in event space: $r = \tilde h -
+h(\theta)$. It contains both discrepancy and noise.
+
+### Discrepancy prediction
+
+The distribution of $\delta$ at new frequencies $x_B$, conditioned on residuals
+at the fit frequencies $x_A$, per event block:
+$\mu = K_{BA}(K_{AA}+\Sigma_n)^{-1} r$ and
+$\Sigma = K_{BB} - K_{BA}(K_{AA}+\Sigma_n)^{-1}K_{AB}$. It excludes noise: it is
+the discrepancy, not a predicted observation.
+
+*Avoid:* "posterior predictive" (that includes noise); "discrepancy posterior"
+(ambiguous with a posterior over hyperparameters).
+
+### Linearisation
+
+A Gauss–Newton approximation of a fit at its MAP, with the discrepancy's
+hyperparameters held fixed: the Jacobian $J = -\partial r / \partial \theta$ of the
+residual with respect to the model's free parameters, and the Fisher matrix
+$F = J^\top \Sigma_D^{-1} J$ with $\Sigma_D = K + \Sigma_n$ per event block. With
+the prior precision $\Sigma_0^{-1}$ it gives the linearised posterior covariance
+$\Sigma_\text{post} = (F + \Sigma_0^{-1})^{-1}$, over parameter values in one space
+(declared by default). Fisher matrices of independent fits add.
+
+### Joint prediction
+
+The Gaussian over the free parameters and the discrepancy at new frequencies
+together, from a linearisation: unlike a discrepancy prediction, it carries the
+parameters' uncertainty into $\delta$ and the cross-covariance between them. It is
+the form in which one fit's posterior becomes the next fit's joint prior.
+
+### Port discrepancy
+
+A discrepancy embedded at a component's ports, on its S-parameters rather than on
+an observable: $\check S_{ii} = S_{ii} + \delta_{ii}$ for reflection and
+$\check S_{ij} = S_{ij} e^{\delta_{ij}}$ for transmission. A circuit containing
+the corrected component carries $\delta$ to any observable or quantity of
+interest, so it transfers between fits that observe the component differently.
+Transmission is split into a symmetric and an antisymmetric block,
+$\delta_{ij} = \delta^s_{ij} \pm \delta^a_{ij}$; a reciprocal component has no
+antisymmetric block. $\delta$ is defined at a reference impedance and is learnt
+at that impedance.
+
+When the component is observed directly, in an event space of the same form
+(additive for reflection, logarithmic for transmission), the port discrepancy *is*
+the event-space discrepancy, and is marginalised there: this is the **reference
+fit**. A later fit with the component inside a larger circuit holds $\delta$ as
+explicit parameters, under the reference fit's joint prediction as their prior:
+this is a **transfer fit**.
+
+*Avoid:* "embedded discrepancy" or "embedded model error" (in the literature
+these embed the error in the parameters); "stage 1" and "stage 2" (say reference
+fit and transfer fit).
+
 ## Records at the boundaries
 
 These frozen records are the seams that keep `Param`s and `Module`s out of the

{paramrf-0.36.4/paramrf.egg-info → paramrf-0.36.5}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: paramrf
-Version: 0.36.4
+Version: 0.36.5
 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.5
+Requires-Dist: parax>=0.11.6
 Requires-Dist: threadpoolctl
 Requires-Dist: eqxpress
 Requires-Dist: jax

{paramrf-0.36.4 → paramrf-0.36.5}/docs/adr/0005-priors-by-name.md

@@ -1,6 +1,7 @@
 # ADR-0005: Priors are attached by name, and a joint prior keeps its parameters
 
-Status: accepted (2026-09)
+Status: accepted (2026-09); amended (2026-10) to allow array-valued parameters
+under a joint prior, and to compute a constant whitening log-determinant once.
 
 ## Context
 
@@ -43,8 +44,8 @@ The distribution's event size decides which:
   `prf.Random`. Its raw space becomes the new prior's whitening, as for
   `prf.Random`, and the prior is truncated to the parameter's existing bounds so
   the bounds still hold.
-- **Event size equal to the number of selected parameters**: a **joint prior**
-  over them.
+- **Event size equal to the total size of the selected parameters**: a **joint
+  prior** over them. For scalar parameters the total size is their number.
 - Anything else raises.
 
 ### A joint prior keeps its parameters
@@ -63,6 +64,22 @@ transparent to the name resolver, as `Tied` is. So:
   would count the earlier fit's priors twice, since its posterior already
   includes them.
 
+### Array-valued parameters
+
+A parameter under a joint prior may be an array, such as a port discrepancy's
+values on a frequency grid. The distribution's vector is the selected parameters'
+values, each flattened in C order, concatenated in name order. A parameter's own
+shape is its declared shape: leading batch axes of a batched model stay batch
+axes. Its raw value under the joint prior is its slice of the whitened vector,
+reshaped to its shape, so it keeps one name however many values it holds.
+Bounds are checked element by element, and fixing or tying the parameter raises,
+as for a scalar.
+
+The driving case is a port discrepancy (`CONTEXT.md`), whose values number
+about $6 N_f$ for a reciprocal two-port, a few thousand. One parameter per value
+would give it thousands of names and makes attaching and compiling the prior
+slow (7 s and 52 s at 6000 scalars).
+
 ### Space
 
 `space` states the space the distribution is over: `'raw'`, `'declared'` or
@@ -130,6 +147,14 @@ CDF.
 - `prf.resolve` keeps a joint prior, since it is not a tie and does not change
   what the parameters are. `prf.unwrap` drops it, as it drops every prior.
 
+### A constant whitening log-determinant
+
+Scoring in raw space adds the log-determinant of the whitening. When the
+whitening's Jacobian is constant, as for a multivariate normal, that term is a
+constant: it is computed once, when the prior is attached, and held by the joint
+prior. Recomputing it as a dense Jacobian and its determinant on every call cost
+15.7 s per evaluation at 6000 values.
+
 ## Rejected options
 
 - **Polishing the collapsing `Probabilistic`** (keeping the names of the
@@ -148,6 +173,10 @@ CDF.
 - **`Transformed.icdf` in distreqx.** It would not be an inverse CDF, and it would
   put ParamRF's sampler logic in another repository.
 
+- **A separate Gaussian-prior node for large arrays** (for a port discrepancy).
+  It would be a second way to attach a joint prior, which this ADR removed, and a
+  flow or Gaussian posterior over any array parameter needs the same thing.
+
 ## Consequences
 
 - The old `Probabilistic` constructor (`target=`, `static=`, tuple targets) and

paramrf-0.36.5/docs/examples/discrepancy_prediction.rst

@@ -0,0 +1,77 @@
+Discrepancy Prediction
+======================
+
+A fit with a Gaussian-process discrepancy learns how the model differs from the data, not just the model parameters. That discrepancy can be predicted at frequencies the fit never saw, with its uncertainty. In this example we fit the S11 of a 10 m coaxial line with a GP discrepancy, then predict the discrepancy off the fit grid.
+
+Fitting with a Discrepancy
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The measured S11 is a coaxial line plus a slow ripple that the model cannot produce, and a little measurement noise. We fit the dielectric constant, with a :class:`~pmrf.discrepancy_models.GaussianProcess` to absorb the ripple. Its kernel's length scale is in the fit frequency's unit, here MHz:
+
+.. plot::
+   :context: reset
+   :include-source:
+   :nofigs:
+
+   import numpy as np
+   import pmrf as prf
+   from pmrf.models import CoaxialLine
+   from pmrf.materials import BulkConductor, ConstantDielectric
+   from pmrf.fitting import fit
+   from pmrf.likelihoods import GaussianLikelihood
+   from pmrf.discrepancy_models import GaussianProcess
+   from pmrf.covariance_kernels import Matern52Kernel
+
+   def coax(ep_r):
+       return CoaxialLine(
+           d_in=1.05e-3, d_out=3.2e-3,
+           dielectric=ConstantDielectric(ep_r=ep_r, tand=1e-3),
+           conductor=BulkConductor(sigma=1 / 1.7e-8),
+           length=10.0,
+       )
+
+   freq = prf.Frequency(10, 500, 100, 'MHz')
+   ripple = 0.01 * np.exp(2j * np.pi * freq.f_scaled / 150.0)
+   rng = np.random.default_rng(0)
+   noise = 1e-3 * (rng.normal(size=freq.npoints) + 1j * rng.normal(size=freq.npoints))
+   s11 = np.asarray(coax(1.40).s(freq)[:, 0, 0]) + ripple + noise
+
+   gp = GaussianProcess(
+       Matern52Kernel(prf.Bounded(10.0, 200.0, value=50.0)) * prf.Bounded(1e-5, 1e-3, value=1e-4)
+   )
+   result = fit(
+       coax(prf.Bounded(1.38, 1.42, value=1.39)), s11, frequency=freq, features='s11',
+       likelihood=GaussianLikelihood(prf.Bounded(1e-7, 1e-4, value=1e-6)),
+       discrepancy=gp,
+   )
+
+Predicting the Discrepancy
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The fitted :class:`~pmrf.evaluators.MarginalLogLikelihood`, with its optimized GP hyperparameters and noise, is the one term of the fit's objective. :meth:`~pmrf.evaluators.MarginalLogLikelihood.predict_discrepancy` conditions the GP on the fit's residuals and returns the distribution of the discrepancy at new frequencies. Here they extend past the fit band and are given in GHz; they are converted to the fit's unit first.
+
+.. plot::
+   :context:
+   :include-source:
+
+   import matplotlib.pyplot as plt
+
+   (term,) = result.solution.objective
+   mll = term.evaluator.evaluator
+
+   new_freq = prf.Frequency(0.005, 0.6, 300, 'GHz')
+   delta = mll.predict_discrepancy(result.model, freq, new_freq)
+
+   mean = delta.mean()
+   std = np.sqrt(np.diagonal(delta.covariance(), axis1=-2, axis2=-1))
+
+   fig, axes = plt.subplots(2, 1, sharex=True)
+   for ax, m, s, r, part in zip(axes, mean, std, (ripple.real, ripple.imag), ('Re', 'Im')):
+       ax.fill_between(new_freq.f_scaled * 1e3, m - s, m + s, alpha=0.3, label=r'$\pm 1\sigma$')
+       ax.plot(new_freq.f_scaled * 1e3, m, label='predicted mean')
+       ax.plot(freq.f_scaled, r, 'k.', markersize=3, label='true ripple')
+       ax.set_ylabel(rf'{part} $\delta$')
+   axes[0].legend()
+   axes[1].set_xlabel('Frequency (MHz)')
+
+The prediction is in event space: one block for the real part of S11 and one for the imaginary part, with frequency last. It is of the discrepancy alone, and excludes measurement noise. Inside the fit band it follows the ripple closely; beyond it, the mean relaxes towards zero and the uncertainty grows back to the GP's prior.

{paramrf-0.36.4 → paramrf-0.36.5}/docs/examples/index.rst

@@ -9,6 +9,8 @@ This chapter includes some basic examples to demonstrate ParamRF's core features
    cascading_and_terminating
    circuit_models
    model_optimization
+   discrepancy_prediction
+   port_discrepancy
    derivatives_and_sweeps
    parameter_naming_and_model_manipulation
    custom_models

paramrf-0.36.5/docs/examples/port_discrepancy.py

@@ -0,0 +1,273 @@
+"""Port discrepancy from a reference two-port to a reflection-only transfer fit.
+
+Run with ``python docs/examples/port_discrepancy.py --n-frequency 1000``.
+"""
+import argparse
+from time import perf_counter
+
+import equinox as eqx
+import jax
+import jax.numpy as jnp
+import numpy as np
+from distreqx.bijectors import AbstractBijector
+from distreqx.distributions import Normal
+from scipy.optimize import minimize
+
+import pmrf as prf
+from pmrf.covariance_kernels import Matern52Kernel
+from pmrf.discrepancy_models import GaussianProcess
+from pmrf.evaluators import MarginalLogLikelihood
+from pmrf.likelihoods import GaussianLikelihood
+from pmrf.linearization import posterior_covariance
+from pmrf.models import GridPortDiscrepancy, Load, PortCorrected, RLGCLine, SModel
+
+jax.config.update('jax_enable_x64', True)
+
+
+def line(resistance):
+    return RLGCLine(length=10.0, R=resistance, L=250e-9, C=100e-12, G=1e-6)
+
+
+@prf.derived
+def fitted_line(base, *, log_R):
+    return prf.replace(base, R=jnp.exp(log_R))
+
+
+def truth(frequency):
+    f = frequency.f_scaled
+    # Skin-effect R and a small inductive dispersion absent from the fit model.
+    dispersive = RLGCLine(length=10.0, R=0.5 * jnp.sqrt(f / 250),
+                          L=250e-9 * (1 + 0.0005 * jnp.log(f / 250)), C=100e-12, G=1e-6)
+    return SModel(dispersive.s(frequency), frequency, 50.0)
+
+
+class AbstractPortEventTransform(AbstractBijector, strict=True):
+    """Example-local event transform conditioned on a predicted response."""
+
+    #: Prediction selecting the local unwrapped logarithm branch.
+    predicted: jax.Array
+    #: Log-transmission derivatives depend on the response.
+    _is_constant_jacobian: bool = eqx.field(static=True, init=False, default=False)
+    #: The log determinant depends on transmission magnitude.
+    _is_constant_log_det: bool = eqx.field(static=True, init=False, default=False)
+
+    def inverse_log_det_jacobian(self, event):
+        return -self.forward_log_det_jacobian(self.inverse(event))
+
+    def forward_and_log_det(self, s):
+        return self.forward(s), self.forward_log_det_jacobian(s)
+
+    def inverse_and_log_det(self, event):
+        return self.inverse(event), self.inverse_log_det_jacobian(event)
+
+    def same_as(self, other):
+        return self is other
+
+
+class PortEventTransform(AbstractPortEventTransform, strict=True):
+    r"""Invertible full two-port transform, with frequency last in event space.
+
+    **Mathematical Formulation**
+
+    $$h(\widetilde S; S)=\ln|\widetilde S| + i[\operatorname{unwrap}(\arg S)
+    + \operatorname{unwrap}(\arg(\widetilde S/S))].$$
+
+    Reflections remain additive. Directional transmission logs become their
+    mean and half-difference. Each complex log contributes
+    $$-2\ln|\widetilde S|$$ to the forward log determinant, and the rotation
+    contributes $$-2\ln 2$$ per frequency.
+    """
+
+    def forward(self, s):
+        anchor = jnp.unwrap(jnp.angle(self.predicted), axis=0)
+        phase = anchor + jnp.unwrap(jnp.angle(s / self.predicted), axis=0)
+        logs = jnp.log(jnp.abs(s)) + 1j * phase
+        blocks = jnp.stack((s[:, 0, 0], s[:, 1, 1],
+                            (logs[:, 1, 0] + logs[:, 0, 1]) / 2,
+                            (logs[:, 1, 0] - logs[:, 0, 1]) / 2))
+        return jnp.stack((blocks.real, blocks.imag), axis=1)
+
+    def inverse(self, event):
+        blocks = event[:, 0] + 1j * event[:, 1]
+        return jnp.stack((jnp.stack((blocks[0], jnp.exp(blocks[2] - blocks[3])), axis=-1),
+                          jnp.stack((jnp.exp(blocks[2] + blocks[3]), blocks[1]), axis=-1)), axis=-2)
+
+    def forward_log_det_jacobian(self, s):
+        # The mean/half-difference rotation has determinant 1/2 for each Re/Im pair.
+        return -2 * jnp.log(jnp.abs(s[:, 0, 1])) - 2 * jnp.log(jnp.abs(s[:, 1, 0])) - 2 * jnp.log(2.0)
+
+
+class ReciprocalEventTransform(AbstractPortEventTransform, strict=True):
+    r"""Transform the retained reflections and symmetric transmission only.
+
+    **Mathematical Formulation**
+
+    The symmetric transmission uses the anchored logarithm of
+    :class:`PortEventTransform`, with forward log determinant
+    $$-2\ln|\widetilde S^s|.$$ Reflections remain additive.
+    """
+
+    def forward(self, s):
+        anchor = jnp.unwrap(jnp.angle(self.predicted[:, 2]))
+        log_t = jnp.log(jnp.abs(s[:, 2])) + 1j * (
+            anchor + jnp.unwrap(jnp.angle(s[:, 2] / self.predicted[:, 2])))
+        blocks = jnp.stack((s[:, 0], s[:, 1], log_t))
+        return jnp.stack((blocks.real, blocks.imag), axis=1)
+
+    def inverse(self, event):
+        blocks = event[:, 0] + 1j * event[:, 1]
+        return jnp.stack((blocks[0], blocks[1], jnp.exp(blocks[2])), axis=-1)
+
+    def forward_log_det_jacobian(self, s):
+        return -2 * jnp.log(jnp.abs(s[:, 2]))
+
+
+def reciprocal_predictor(model, frequency):
+    s = model.s(frequency)
+    return jnp.stack((s[:, 0, 0], s[:, 1, 1], s[:, 1, 0]), axis=-1)
+
+
+def reference_fit(mll, model, frequency):
+    """Fit the reference line's one log-resistance coordinate."""
+    def loss(vector):
+        candidate = prf.update(model, {'log_R': vector[0]})
+        return -mll(candidate, frequency) - prf.log_prior(candidate)
+
+    value_gradient = jax.jit(jax.value_and_grad(loss))
+    result = minimize(lambda x: tuple(np.asarray(v) for v in value_gradient(jnp.asarray(x))),
+                      np.array([prf.values(model)['log_R']]), jac=True, method='L-BFGS-B',
+                      bounds=[(np.log(0.05), np.log(2.0))],
+                      options={'gtol': 1e-6, 'ftol': 1e-14, 'maxiter': 200})
+    if not np.isfinite(result.fun) or np.linalg.norm(result.jac, ord=np.inf) > 1e-3:
+        raise RuntimeError(f'MAP fit failed: {result.message}; gradient {result.jac}')
+    return prf.update(model, {'log_R': jnp.asarray(result.x[0])})
+
+
+def run(n_frequency=1000, n_transfer=None, mc_samples=10000):
+    """Run the complete recipe, returning diagnostics and synchronized timings."""
+    n_transfer = n_frequency if n_transfer is None else n_transfer
+    timings = {}
+    before = perf_counter()
+
+    def finish(name, value):
+        nonlocal before
+        jax.block_until_ready(value)
+        now = perf_counter()
+        timings[name] = now - before
+        before = now
+        print(f'{name}: {timings[name]:.3f} s', flush=True)
+
+    frequency = prf.Frequency(10, 500, n_frequency, 'MHz')
+    transfer_frequency = prf.Frequency(10.1, 499.9, n_transfer, 'MHz')
+    true_s = truth(frequency).s(frequency)
+    rng = np.random.default_rng(265)
+    sigma = 0.002
+    observed = true_s + sigma * (rng.normal(size=true_s.shape) + 1j * rng.normal(size=true_s.shape))
+    initial = fitted_line(line(0.5), log_R=prf.Unconstrained(jnp.log(0.5)))
+    initial = prf.prior(initial, 'log_R', Normal(jnp.log(0.5), 0.02))
+    full_event = PortEventTransform(initial.s(frequency)).forward(observed)
+    # Discard only the antisymmetric block, then encode the symmetric log in S space.
+    retained = full_event[:3, 0] + 1j * full_event[:3, 1]
+    reciprocal_observed = jnp.stack((retained[0], retained[1], jnp.exp(retained[2])), axis=-1)
+    variance = jnp.ones((3, 2, n_frequency)) * sigma**2
+    variance = variance.at[2].set(sigma**2 / (2 * jnp.abs(reciprocal_observed[:, 2])**2))
+    reference = MarginalLogLikelihood(
+        predictor=reciprocal_predictor, observed=reciprocal_observed,
+        likelihood=GaussianLikelihood(variance),
+        discrepancy=GaussianProcess(Matern52Kernel(100.0) * 0.05**2, jitter=1e-8),
+        event_transform=ReciprocalEventTransform,
+    )
+    finish('synthetic data and event transform', reciprocal_observed)
+    fitted = reference_fit(reference, initial, frequency)
+    finish('reference MAP', fitted.s(frequency))
+    event = ReciprocalEventTransform(reciprocal_predictor(fitted, frequency))
+    log_residual = event.forward(reciprocal_observed)[2] - event.forward(reciprocal_predictor(fitted, frequency))[2]
+    additive_residual = true_s[:, 1, 0] - fitted.s(frequency)[:, 1, 0]
+    names, joint = reference.predict_joint(fitted, frequency, transfer_frequency)
+    finish('joint prediction', joint.covariance())
+    corrected = PortCorrected(fitted, GridPortDiscrepancy(
+        prf.Unconstrained(joint.mean()[1:].reshape(3, 2, n_transfer)),
+        transfer_frequency, ('11', '22', 's21')))
+    corrected = prf.prior(corrected, [*names, 'discrepancy.values'], joint)
+    finish('joint prior attachment', prf.log_prior(corrected))
+    # Keep the cable as the base: its parameter names and joint prior survive.
+    @prf.derived
+    def terminated(cable, *, load):
+        return cable.terminated(Load(gamma=(load - 50) / (load + 50)))
+
+    transfer = terminated(corrected, load=prf.Unconstrained(75.0))
+    true_reflection = truth(transfer_frequency).terminated(Load(gamma=(76.0 - 50) / (76.0 + 50))).s(transfer_frequency)[:, 0, 0]
+    transfer_observed = true_reflection + sigma * (
+        rng.normal(size=n_transfer) + 1j * rng.normal(size=n_transfer))
+    transfer_mll = MarginalLogLikelihood(
+        predictor=lambda m, f: m.s(f)[:, 0, 0], observed=transfer_observed,
+        likelihood=GaussianLikelihood(sigma**2),
+    )
+    # Whiten the cable's joint prior, leaving the new load in ohms.
+    mean = joint.mean()
+    factor = jnp.linalg.cholesky(joint.covariance())
+
+    def from_white(x):
+        cable_vector = mean + factor @ x[:-1]
+        return prf.update(transfer, {'log_R': cable_vector[0],
+                                    'discrepancy.values': cable_vector[1:].reshape(3, 2, n_transfer),
+                                    'load': x[-1]})
+
+    def loss_white(x):
+        return -transfer_mll(from_white(x), transfer_frequency) + jnp.sum(x[:-1]**2) / 2
+
+    value_gradient = jax.jit(jax.value_and_grad(loss_white))
+    solution = minimize(lambda x: tuple(np.asarray(v) for v in value_gradient(jnp.asarray(x))),
+                        np.r_[np.zeros(len(mean)), 75.0], jac=True, method='L-BFGS-B',
+                        options={'maxiter': 300, 'gtol': 1e-5, 'ftol': 1e-12})
+    if not solution.success:
+        raise RuntimeError(f'Transfer fit failed: {solution.message}')
+    transfer_map = from_white(jnp.asarray(solution.x))
+    finish('transfer MAP', transfer_map.s(transfer_frequency))
+    linearization = transfer_mll.linearize(transfer_map, transfer_frequency)
+    covariance = posterior_covariance([linearization], transfer_map)
+    finish('transfer linearisation and posterior', covariance)
+
+    # QoI belongs to the unterminated corrected cable; the fitted load does not enter it.
+    def qoi(model):
+        cable = model.operands[0]
+        return jnp.mean(jnp.abs(cable.s(transfer_frequency)[:, 1, 0])**2)
+
+    (gradient,) = prf.derivative(qoi, transfer_map)
+    gradient_values = prf.values(gradient)
+    J_q = jnp.concatenate([jnp.ravel(gradient_values[name]) for name in linearization.names])
+    q_variance = J_q @ covariance @ J_q
+    J = linearization.J.reshape(-1, covariance.shape[0])
+    # Independent real/imaginary reflection noise makes Sigma_D diagonal here.
+    G = covariance @ J.T / sigma**2
+    R = G @ J
+    P_q = J_q @ (jnp.eye(len(J_q)) - R)
+    G_q = J_q @ G
+    finish('QoI and gain diagnostics', (q_variance, P_q, G_q))
+    parameter_mean = jnp.concatenate([jnp.ravel(prf.values(transfer_map)[name]) for name in linearization.names])
+    posterior_factor = jnp.linalg.cholesky(covariance)
+    evaluate = jax.jit(jax.vmap(lambda x: qoi(prf.update(transfer_map, linearization.unflatten(x)))))
+    # Batch both sampling and evaluation: 10^4 by 6002 need not stay resident.
+    q_samples = []
+    for start in range(0, mc_samples, 100):
+        count = min(100, mc_samples - start)
+        draws = parameter_mean + jnp.asarray(rng.normal(size=(count, len(parameter_mean)))) @ posterior_factor.T
+        q_samples.append(np.asarray(evaluate(draws)))
+    mc_std = np.std(np.concatenate(q_samples), ddof=1)
+    delta_std = float(jnp.sqrt(q_variance))
+    finish('Monte Carlo push-forward', q_variance)
+    relative_std_error = abs(mc_std / delta_std - 1)
+    print(f'QoI {float(qoi(transfer_map)):.6f}; linear std {delta_std:.6g}; '
+          f'MC std {mc_std:.6g}; relative std error {relative_std_error:.2%}', flush=True)
+    return dict(timings=timings, relative_std_error=relative_std_error,
+                frequency=frequency, additive_residual=additive_residual,
+                log_residual=log_residual, P_q=P_q, G_q=G_q,
+                fitted_load=float(prf.values(transfer_map)['load']),
+                delta_std=delta_std, mc_std=mc_std)
+
+
+if __name__ == '__main__':
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--n-frequency', type=int, default=1000)
+    args = parser.parse_args()
+    run(args.n_frequency)

paramrf-0.36.5/docs/examples/port_discrepancy.rst

@@ -0,0 +1,81 @@
+Port Discrepancy Transfer
+===========================
+
+A port discrepancy learned from a two-port reference fit can inform a reflection-only transfer fit. The joint prediction retains the correlation between the cable parameters and its discrepancy. Attach that prediction to :class:`~pmrf.models.PortCorrected` before terminating the cable; the correction then changes the reflection seen through the load as well as the cable's transmission.
+
+The runnable :download:`example <port_discrepancy.py>` uses a synthetic 10 m line over 10–500 MHz. The truth has skin-effect resistance and a weak frequency dependence in its inductance. The fit uses constant RLGC, with resistance parameterised by an unconstrained ``log_R`` and a docs-local :func:`~pmrf.derived` constructor. This coordinate admits a Gaussian joint prior while keeping physical resistance positive. The reference fit has a 2% prior standard deviation on log-resistance, representing a separate resistance calibration. This limits the resistance–discrepancy confounding and keeps the subsequent local Gaussian approximation useful.
+
+Log Transmission Event Space
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Reflection errors are additive. A cable's transmission phase winds many times over the band, so an additive transmission residual oscillates on the inverse-delay scale. A log-ratio residual removes that winding. The example defines its own bijectors, using the ``AbstractBijector`` interface available in released distreqx. For predicted transmission $S$ and observed transmission $\widetilde S$, the transform uses
+
+$$h(\widetilde S;S)=\ln|\widetilde S| + i\left[\operatorname{unwrap}(\arg S)+\operatorname{unwrap}\left(\arg\frac{\widetilde S}{S}\right)\right].$$
+
+Subtracting $h(S;S)$ gives the unwrapped complex log ratio. Unwrap the ratio along frequency, rather than independently unwrapping the two transmissions. Their initial ratio phase selects the local branch; transmissions must be nonzero and the frequency spacing must resolve their phase. The forward log determinant is $-2\ln|\widetilde S|$ per complex transmission entry.
+
+.. literalinclude:: port_discrepancy.py
+   :pyobject: PortEventTransform
+
+The symmetric transmission block is the mean of the two directional logs; the antisymmetric block is their half-difference. This rotation adds the constant $-2\ln2$ to the log determinant per frequency. The full ``PortEventTransform`` is an invertible, example-local subclass of distreqx's ``AbstractBijector``. For this reciprocal model, the antisymmetric residual has no parameter sensitivity and is independent of the retained blocks in the first-order, equal-directional-noise approximation, so the fit discards it before constructing a reduced, invertible three-block transform. The discarded likelihood and rotation determinant are constants for the reference parameters.
+
+.. literalinclude:: port_discrepancy.py
+   :pyobject: ReciprocalEventTransform
+
+Each directional transmission has noise variance $\sigma^2/\lvert S\rvert^2$ in log space to first order. Averaging independent directional measurements halves that variance. The example fixes this approximation at the observed symmetric transmission, while each additive reflection retains variance $\sigma^2$. This is a small-noise approximation, with GP hyperparameters held fixed.
+
+Reference Fit and Joint Handoff
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The reference likelihood uses a block-independent Matérn 5/2 GP with discrepancy amplitude 0.05 and length scale 100 MHz. Its event layout is ``(block, real_or_imaginary, frequency)``, with blocks ``('11', '22', 's21')``. The fitted additive S21 residual oscillates while the log residual changes slowly:
+
+.. plot::
+   :include-source:
+
+   import importlib.util
+   from pathlib import Path
+   import matplotlib.pyplot as plt
+
+   path = Path('port_discrepancy.py')
+   spec = importlib.util.spec_from_file_location('port_discrepancy_example', path)
+   example = importlib.util.module_from_spec(spec)
+   spec.loader.exec_module(example)
+   result = example.run(n_frequency=150, n_transfer=30)
+   frequency = result['frequency'].f_scaled
+   fig, axes = plt.subplots(2, 1, sharex=True)
+   axes[0].plot(frequency, result['additive_residual'].real)
+   axes[0].set_ylabel('Re additive S21 residual')
+   axes[1].plot(frequency, result['log_residual'][0])
+   axes[1].set_ylabel('Re log-ratio residual')
+   axes[1].set_xlabel('Frequency (MHz)')
+
+:meth:`~pmrf.evaluators.MarginalLogLikelihood.predict_joint` returns a Gaussian over ``[log_R; discrepancy]``, with discrepancy flattened in that event order on the transfer grid. Its cross-covariance must survive the handoff:
+
+.. code-block:: python
+
+   names, joint = reference.predict_joint(fitted, frequency, transfer_frequency)
+   corrected = PortCorrected(fitted, GridPortDiscrepancy(
+       prf.Unconstrained(joint.mean()[1:].reshape(3, 2, n_transfer)),
+       transfer_frequency, ('11', '22', 's21')))
+   corrected = prf.prior(corrected, [*names, 'discrepancy.values'], joint)
+
+The transfer fit terminates this corrected cable in a load whose resistance is a new parameter. It observes S11 only. The example optimises the cable parameters in whitened joint-prior coordinates, then linearises the transfer likelihood in declared coordinates. The dense prior costs memory quadratically and dense posterior operations cost time cubically in the number of transfer points. The plot uses a smaller transfer grid; the standalone command exercises 1000 points in both grids and reports synchronized timings:
+
+.. code-block:: bash
+
+   python docs/examples/port_discrepancy.py --n-frequency 1000
+
+Quantity of Interest and Diagnostics
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The quantity of interest $q$ is band-mean $|S_{21}|^2$ of the corrected, unterminated cable on the transfer grid. The fitted load informs the cable through the posterior, though $q$ has no direct load dependence. With transfer parameters $\vartheta$, :func:`~pmrf.derivative` supplies $J_q$, and :func:`~pmrf.linearization.posterior_covariance` supplies $\Sigma_\vartheta$:
+
+$$\Sigma_q=J_q\Sigma_\vartheta J_q^\top.$$
+
+The diagnostic recipe uses the transfer linearisation's event Jacobian $J$ and data covariance $\Sigma_D$:
+
+$$G=\Sigma_\vartheta J^\top\Sigma_D^{-1},\qquad R=GJ,\qquad P_q=J_q(I-R),\qquad G_q=J_qG.$$
+
+Here $\Sigma_D=\sigma^2 I$: the discrepancy is an explicit parameter with a joint prior, rather than another marginal GP in the transfer likelihood. ``P_q`` measures the QoI sensitivity left to the prior; ``G_q`` maps small reflection-data changes to QoI changes. Both are local diagnostics at the transfer MAP.
+
+The script compares the propagated standard deviation with a nonlinear push-forward of 10,000 draws from $N(\hat\vartheta,\Sigma_\vartheta)$, evaluated in batches. The 5% standard-deviation criterion applies at amplitude 0.05; stronger log corrections can make the exponential nonlinearity too large for this linear approximation.

{paramrf-0.36.4 → paramrf-0.36.5/paramrf.egg-info}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: paramrf
-Version: 0.36.4
+Version: 0.36.5
 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.5
+Requires-Dist: parax>=0.11.6
 Requires-Dist: threadpoolctl
 Requires-Dist: eqxpress
 Requires-Dist: jax