paramrf 0.36.4__tar.gz → 0.36.6__tar.gz

{paramrf-0.36.4 → paramrf-0.36.6}/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,108 @@ 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 or internal 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).
+
+### Internal discrepancy
+
+A discrepancy on a quantity inside a model rather than on its ports: for a
+uniform line, its characteristic impedance, attenuation and phase constant,
+$\check Z_c = Z_c e^{z}$, $\check\alpha = \alpha e^{a}$, $\check\beta = \beta e^{b}$.
+The correction is log-relative and per unit length, so it is independent of the
+line's length. A port discrepancy carries the whole instance's error and does
+not transfer to another length; an internal discrepancy does, provided the
+line's $\gamma L$ scales with its length. Choose the internal quantity by what
+stays the same between the instances it must transfer across.
+
+$\alpha$ and $\beta$ are corrected separately rather than by one complex factor
+on $\gamma$, which would mix phase into loss because $\beta \gg \alpha$.
+
+It is learnt in a reference fit either from reference internal quantities, in
+an event space of the same log form, or from port observables alone, and is
+carried into transfer fits as a port discrepancy is.
+
+*Avoid:* "internal hook" (no general method interception exists; each
+internal discrepancy corrects one typed quantity).
+
 ## 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.6}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: paramrf
-Version: 0.36.4
+Version: 0.36.6
 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.6}/docs/adr/0002-parameter-api.md

@@ -124,6 +124,19 @@ It replaces `with_values`, `with_free`, `with_fixed`, `Module.map`,
 - **Not an optimiser step.** In fitting, "updates" also means Optax gradient
   steps; the docstring says `update` is neither.
 
+- **Numerical trials can opt out of raising on invalid parameter values.**
+  `update(..., on_invalid='raise')` remains strict by default. Numerical value
+  updates may opt into `on_invalid='nan'`, which marks the entire updated
+  parameter leaf NaN when its candidate is outside the effective constraint,
+  lies on an excluded open edge, or contains a nonfinite value. This gives
+  line searches and other numerical objectives a non-raising way to reject a
+  trial while keeping the parameter pytree structure and the other requested
+  values intact. The policy applies only to numerical value updates; structural
+  replacements and fixed-state changes remain outside it. Only parameter
+  validity failures become NaN: independent model errors keep their existing
+  behavior. NaN trials require a floating or complex leaf and do not promote
+  integer leaves.
+
 `prf.replace` stays as the plain `dataclasses.replace`: fields of one object,
 unvalidated, able to break a type. Its docstring points to `update` for
 anything name-based.

{paramrf-0.36.4 → paramrf-0.36.6}/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
@@ -109,6 +126,28 @@ whether a bound is the model's (validity, such as a positive width) or the
 user's (a range, such as `prf.Bounded`), so the check treats every bound as
 validity.
 
+### Explicit unnormalised truncation for inference
+
+Declared- and physical-space joint priors may opt into `prior(...,
+truncate='unnormalised')` when their support leaves a selected parameter's
+validity. The distribution keeps its supplied density at every interior
+validity point, and the attached prior contributes `-inf` outside validity;
+ParamRF does not estimate or apply a truncation normaliser. The wrapper stores
+this choice as static `normalised=False` metadata, which survives resolution,
+updates, enclosing trees and supported serialization. The default remains
+`truncate='normalised'` and retains the support-inside-validity check. Scalar
+events and raw-space joint priors do not support unnormalised truncation.
+
+This opt-in is for MAP, scoring, differentiation and posterior covariance.
+Keeping the declared Gaussian density unchanged in the interior preserves its
+gradient and precision, which are needed when transferring a local Gaussian
+fit into a later linearised inference problem. It is not a probability
+normalised over the valid region and cannot be used for sampling or evidence:
+every public sampling path rejects an active unnormalised joint prior before
+calling the sampler, with the affected parameter names in the error. This
+includes direct sampling, `fit_sample`, joint samplers, split samplers and
+hypercube samplers.
+
 ### Hypercube samplers
 
 A hypercube sampler maps the unit cube through a joint prior's block as
@@ -130,6 +169,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 +195,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.4 → paramrf-0.36.6}/docs/adr/0007-edge-values.md

@@ -85,7 +85,9 @@ wrong for complex $Z_r$.
 - **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.
+  itself. A finite open edge is inset by a dtype-aware relative distance based
+  on machine epsilon, the bound and the original start; infinite edges stay
+  infinite. The exact algorithm is recorded below.
 - **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.
@@ -95,6 +97,64 @@ wrong for complex $Z_r$.
   is silent: it is the kind of difference engineers expect between optimisers.
 - **Raw space is unchanged.** It stays whitened by the prior (ADR-0005).
 
+### Open box edges preserve valid starts
+
+For each finite open edge `b`, let `x0` be the original box-space start, `eps`
+the dtype's machine epsilon and `tiny` its smallest positive normal value. The
+inward distance is
+
+`max(tiny, eps * max(abs(b), abs(x0 - b), tiny))`.
+
+Add this distance at a lower edge and subtract it at an upper edge. If rounding
+leaves the result on the excluded edge, move one representable value inward.
+If the proposed inset would exclude an already valid interior start, use that
+start as the search edge. A start exactly on an open edge is moved to the
+resulting interior edge; construction still rejects a deliberately declared
+invalid start. Keep infinite edges infinite. This preserves tiny positive
+starts, avoids a fixed absolute inset and ensures `Positive` has a positive
+normal-number search edge. Closed edges and raw-space closed-start nudging keep
+their existing behavior.
+
+### Trust-constr uses fixed affine search coordinates
+
+When bounds are supplied to SciPy `trust-constr` (case-insensitively), pass
+feasible `Bounds` and use fixed affine coordinates. For flattened original box
+start `x0`, choose each scale `s` as `upper - lower` for two finite bounds,
+`abs(x0 - lower)` for lower-only, `abs(upper - x0)` for upper-only, and
+`abs(x0)` for unbounded coordinates. Replace a zero or nonfinite scale by 1.
+SciPy starts at `z0 = 0`, sees bounds `(lower - x0) / s` and
+`(upper - x0) / s`, and evaluates the original objective at `x = x0 + s * z`.
+Apply the affine chain rule to supplied gradients and convert the returned
+coordinates to box space before rebuilding parameters. Scales stay fixed for
+the solve.
+
+Metrics retain SciPy's actual internal coordinates. Add `box_origin=x0` and
+`box_scale=s` so callers can recover box coordinates from `metrics.x`; do not
+partially rewrite derivative or multiplier fields. Other methods and calls
+without supplied bounds keep their existing representations and coordinates.
+This is private solver scaling, not a new public value space, and `SolverView`
+continues to expose box space.
+
+### Nonfinite SciPy evaluations fail immediately
+
+Before returning an objective value to SciPy, check the loss and each requested
+gradient entry for finiteness; check a Hessian only when a callback is actually
+passed. A nonfinite value raises `FloatingPointError` on that evaluation.
+Include the method, one-based evaluation number, failing quantity and affected
+free parameter names for a nonfinite gradient. A nonfinite loss may list the
+available free names as context without attributing cause. Identify a
+nonfinite attempted parameter vector separately. Diagnostics use the original
+box or raw coordinates before private affine scaling, never the internal vector
+as if it were box space. Direct low-level calls may identify positional
+coordinates when names are unavailable.
+
+Do not include parameter values, full model representations or distributions
+in errors or logs. Synchronize deferred JAX results before checking. Public
+minimize and Bayesian fit APIs propagate the exception rather than returning a
+failed start point; close any progress bar on failure. Finite nonconvergence
+still returns `success=False` with its existing warning, and unrelated user
+exceptions retain their type and message.
+
 ## Rejected options
 
 - **Keep Y from the MNA solver and detect ill-conditioning.** Wrong answers get

paramrf-0.36.6/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.6}/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