paramrf 0.36.6__tar.gz → 0.37.0__tar.gz

{paramrf-0.36.6 → paramrf-0.37.0}/CONTEXT.md

@@ -176,8 +176,8 @@ impedance — so it belongs to the material, not the geometry: it is a field of
 
 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`.
+noise. `pmrf.objectives.MarginalLogLikelihood` scores it; see
+`pmrf.stats.GaussianProcess` and `pmrf.stats.GaussianLikelihood`.
 
 ### Event space and event block
 

{paramrf-0.36.6 → paramrf-0.37.0}/CONTRIBUTING.md

@@ -32,13 +32,13 @@ For docs, we use sphinx. Simply run:
 In general, ParamRF follows a tiered API in order to isolate the JAX and solver logic. It is useful to understand the module split (and perhaps have a basic grasp on JAX PyTrees and perhaps the `Equinox` library) before continuing. A brief overview on the different modules and some JAX "gotchas" is given below.
 
 ### The Module Split
-Higher-level methods (fitting, optimization etc.) should be available to the user with minimal imports. However, these routines should build on top of "glue" helpers so that power users can pass additional arguments (such as custom evaluators in `pmrf.evaluators`) to customize the algorithm.
+Higher-level methods (fitting, optimization etc.) should be available to the user with minimal imports. However, these routines should build on top of "glue" helpers so that power users can pass additional arguments (such as custom evaluators in `pmrf.objectives`) to customize the algorithm.
 
 * **Core Primitives** (`pmrf.Model`, `pmrf.Frequency`, `pmrf.Param`). These are the library's core primitives. They represent the foundational classes and functions that both users and library routines will interact with.
 * **Lower-level Routines** (`pmrf.math`, `pmrf.rf`). These functions implement simple, standard formulae. They should operate directly on JAX arrays or very simple PyTree structures.
 * **RF Models** (`pmrf.models`). These are the main, built-in RF models in the library. They have been separated into an deep organizational structure (e.g. lumped components, surrogates etc.). If a model's forward pass has many different possible implementations (for example, different models for a coaxial line, or different circuit solver algorithms) then a separate strategy class should be created alongside the model which implements some abstract interface (referred to as the "strategy" pattern, described below). See `pmrf.models.CoaxialLine` and `pmrf.models.Circuit` for simple and complex examples, respectively.
 * **General Algorithms** (`pmrf.optimize` and `pmrf.infer`). These are a combination of functional entry points and wrappers around external libraries. They refer to parametric, model-agnostic algorithms. These modules should be structured in a tiered manner to decouple the Equinox/JAX logic from the RF/model logic. Refer to `pmrf.optimize.base` and `pmrf.optimize.minimize` for a good example.
-* **Toolkits** (`pmrf.evaluators`, `pmrf.losses`, `pmrf.likelihoods`, `pmrf.discrepancy_models`, `pmrf.noise_models`, `pmrf.covariance_models`). These are the concrete "glue" components that provide users with a toolkit to mix-and-match together, mostly for power users.
+* **Toolkits** (`pmrf.objectives`, `pmrf.stats`). These provide evaluators, losses, likelihoods, discrepancy models, noise models, and covariance kernels that users can mix and match.
 * **Routers** (`pmrf.fitting`) This is an example of a high-level convenience API specifically for fitting models to measured data. Functions here, like `fit`, `fit_minimize` or `fit_sample`, essentially act as "routers", converting different data formats (e.g. `skrf.Network`) and user specs into code that other modules in the library can understand.
 
 ### Abstract Classes and the Strategy Pattern

{paramrf-0.36.6/paramrf.egg-info → paramrf-0.37.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: paramrf
-Version: 0.36.6
+Version: 0.37.0
 Summary: Parametric radio frequency modeling
 Author-email: Gary Allen <gvcallen@gmail.com>
 Project-URL: homepage, https://github.com/gvcallen/paramrf
@@ -107,7 +107,7 @@ The code below demonstrate how to define and optimize an RLC model to satisfy a
   C = prf.Bounded(0.0, 100.0, scale=1e-12, name='C')
   
   model = Resistor(R) ** Inductor(L) ** Capacitor(C)
-  goal = prf.evaluators.Goal('s11_db', '<', -20)
+  goal = prf.objectives.Goal('s11_db', '<', -20)
   passband = prf.Frequency(2, 5, 101, 'GHz')
   
   result = prf.optimize.minimize(goal, model, passband, solver=prf.optimize.NelderMead())

{paramrf-0.36.6 → paramrf-0.37.0}/README.rst

@@ -60,7 +60,7 @@ The code below demonstrate how to define and optimize an RLC model to satisfy a
   C = prf.Bounded(0.0, 100.0, scale=1e-12, name='C')
   
   model = Resistor(R) ** Inductor(L) ** Capacitor(C)
-  goal = prf.evaluators.Goal('s11_db', '<', -20)
+  goal = prf.objectives.Goal('s11_db', '<', -20)
   passband = prf.Frequency(2, 5, 101, 'GHz')
   
   result = prf.optimize.minimize(goal, model, passband, solver=prf.optimize.NelderMead())
@@ -120,4 +120,4 @@ or using the BibTeX:
       eprint = {2510.15881},
       archivePrefix = {arXiv},
       primaryClass = {cs.OH},
-   }
+   }

{paramrf-0.36.6 → paramrf-0.37.0}/docs/api/index.rst

@@ -45,6 +45,9 @@ Main Modules
    pmrf.models
    pmrf.modules
    pmrf.materials
+   pmrf.parameters
+   pmrf.stats
+   pmrf.objectives
    pmrf.optimize
    pmrf.infer
    pmrf.fitting
@@ -56,18 +59,7 @@ Other Modules
    :toctree: generated/
    :recursive:
 
-   pmrf.constraints
-   pmrf.covariance_kernels
-   pmrf.discrepancy_models
-   pmrf.distributions
-   pmrf.evaluators
-   pmrf.problems
-   pmrf.terms
-   pmrf.likelihoods
-   pmrf.losses
    pmrf.math
-   pmrf.noise_models
-   pmrf.parameters
    pmrf.rf
    pmrf.serialization
    pmrf.viz

{paramrf-0.36.6 → paramrf-0.37.0}/docs/core_concepts/core_primitives.rst

@@ -1,7 +1,7 @@
 Core Primitives
 ===============
 
-The core primitives in ParamRF are the :class:`pmrf.Model`, :class:`pmrf.Frequency` and :class:`pmrf.Param` classes. Other classes, such as JAX arrays and :mod:`pmrf.evaluators`, help bring the rest of the library together.
+The core primitives in ParamRF are the :class:`pmrf.Model`, :class:`pmrf.Frequency` and :class:`pmrf.Param` classes. Other classes, such as JAX arrays and :mod:`pmrf.objectives`, help bring the rest of the library together.
 
 The Model
 ~~~~~~~~~
@@ -26,16 +26,16 @@ Power users may want to have a look at the `Parax <https://github.com/gvcallen/p
 The Evaluator and other classes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-:class:`~pmrf.evaluators.AbstractEvaluator` is an interface for a callable class that can be used to "evaluate" a model over frequency. Its output is a :class:`jnp.ndarray` (tensor or scalar). Evaluators can be used for extraction of model features, encapsulating loss/error/likelihood functions, and more. For example, to create a goal-oriented objective function for an optimization, the :class:`~pmrf.evaluators.Goal` evaluator can be used.
+:class:`~pmrf.objectives.AbstractEvaluator` is an interface for a callable class that can be used to "evaluate" a model over frequency. Its output is a :class:`jnp.ndarray` (tensor or scalar). Evaluators can be used for extraction of model features, encapsulating loss/error/likelihood functions, and more. For example, to create a goal-oriented objective function for an optimization, the :class:`~pmrf.objectives.Goal` evaluator can be used.
 
-Evaluators are created automatically when fitting routines are called, such as :func:`~pmrf.optimize.minimize` or :func:`~pmrf.infer.sample`. For example, specifying ``'s21_db'`` as a fitting feature for :func:`~pmrf.fitting.fit` creates a :class:`~pmrf.evaluators.Feature` evaluator, whilst specifying a loss or likelihood function creates a :class:`~pmrf.evaluators.TargetLoss` or :class:`~pmrf.evaluators.MarginalLogLikelihood` evaluator respectively.
+Evaluators are created automatically when fitting routines are called, such as :func:`~pmrf.optimize.minimize` or :func:`~pmrf.infer.sample`. For example, specifying ``'s21_db'`` as a fitting feature for :func:`~pmrf.fitting.fit` creates a :class:`~pmrf.objectives.Feature` evaluator, whilst specifying a loss or likelihood function creates a :class:`~pmrf.objectives.TargetLoss` or :class:`~pmrf.objectives.MarginalLogLikelihood` evaluator respectively.
 
 Since an evaluator takes frequency *as input*, the same evaluator can be re-used over different sweeps. For example, an evaluator can be fitted over a coarse sweep of measured data, and then plotted over a much finer one.
 
-When a model is solved, an evaluator is paired with the sweep it should be evaluated over using :class:`pmrf.terms.BoundEvaluator`, which optionally also accepts a relative weight. The result is a *term*, which is any callable that takes a model and returns a result. A :class:`pmrf.problems.SummedTerms` problem is then simply a model together with the terms to be summed over it. Where an evaluator takes a model and a frequency, and a term takes a model, a :class:`pmrf.problems.AbstractProblem` takes nothing further and returns the result directly.
+When a model is solved, an evaluator is paired with the sweep it should be evaluated over using :class:`pmrf.objectives.BoundEvaluator`, which optionally also accepts a relative weight. The result is a *term*, which is any callable that takes a model and returns a result. A :class:`pmrf.objectives.SummedTerms` problem is then simply a model together with the terms to be summed over it. Where an evaluator takes a model and a frequency, and a term takes a model, a :class:`pmrf.objectives.AbstractProblem` takes nothing further and returns the result directly.
 
-Terms that do not require a frequency, such as a penalty on the model's parameters, can be written as a plain function of the model. The built-in terms inherit from :class:`pmrf.terms.AbstractTerm`, but this is a convenience and not a requirement. In most cases these classes do not need to be created manually, as :func:`~pmrf.optimize.minimize` and :func:`~pmrf.infer.sample` create them automatically.
+Terms that do not require a frequency, such as a penalty on the model's parameters, can be written as a plain function of the model. The built-in terms inherit from :class:`pmrf.objectives.AbstractTerm`, but this is a convenience and not a requirement. In most cases these classes do not need to be created manually, as :func:`~pmrf.optimize.minimize` and :func:`~pmrf.infer.sample` create them automatically.
 
-Priors are parameter metadata, and are stripped when a tree is unwrapped for a solver, so they cannot be read from inside an evaluator or a term. Instead, :class:`pmrf.problems.PriorPenalized` extracts them once when it is constructed and evaluates them against the parameter values on each call. This is what separates a maximum a posteriori estimate from a maximum likelihood one, and it is selected automatically when `inference` is 'bayesian' in :func:`~pmrf.fitting.fit`.
+Priors are parameter metadata, and are stripped when a tree is unwrapped for a solver, so they cannot be read from inside an evaluator or a term. Instead, :class:`pmrf.objectives.PriorPenalized` extracts them once when it is constructed and evaluates them against the parameter values on each call. This is what separates a maximum a posteriori estimate from a maximum likelihood one, and it is selected automatically when `inference` is 'bayesian' in :func:`~pmrf.fitting.fit`.
 
-Other core class interfaces include those in :class:`~pmrf.losses`, :class:`~pmrf.likelihoods`, :class:`~pmrf.discrepancy_models` and :class:`~pmrf.noise_models`. These help glue the rest of the library together, as well as enable more advanced features such as hyperparameter-based optimization and Gaussian process discrepancy modeling. See the :doc:`../tutorials/index` section for more information.
+Other interfaces include :class:`~pmrf.objectives.AbstractLoss`, :class:`~pmrf.stats.AbstractLikelihood`, :class:`~pmrf.stats.AbstractDiscrepancyModel` and :class:`~pmrf.stats.AbstractNoiseModel`. See the :doc:`../tutorials/index` section for more examples.

{paramrf-0.36.6 → paramrf-0.37.0}/docs/core_concepts/optimization_and_inference.rst

@@ -17,11 +17,11 @@ An objective can also be paired with its own frequency sweep. This allows a sing
 .. code-block:: python
 
    result = minimize([
-       (prf.evaluators.Goal('s11_db', '<', -20), prf.Frequency(50, 130, 101, 'MHz')),
-       (prf.evaluators.Goal('s21_db', '>', -1), prf.Frequency(10, 500, 401, 'MHz')),
+       (prf.objectives.Goal('s11_db', '<', -20), prf.Frequency(50, 130, 101, 'MHz')),
+       (prf.objectives.Goal('s21_db', '>', -1), prf.Frequency(10, 500, 401, 'MHz')),
    ], model)
 
-To weight the objectives against one another, the pairing can be created explicitly using :class:`pmrf.terms.BoundEvaluator`. Any callable that accepts only a model, such as a penalty on the parameters that requires no frequency, can also be summed in directly:
+To weight the objectives against one another, the pairing can be created explicitly using :class:`pmrf.objectives.BoundEvaluator`. Any callable that accepts only a model, such as a penalty on the parameters that requires no frequency, can also be summed in directly:
 
 .. code-block:: python
 

{paramrf-0.36.6 → paramrf-0.37.0}/docs/examples/custom_models.rst

@@ -54,7 +54,7 @@ The code below demonstrates this by extending the previous class, while constrai
    :include-source:
 
    # <previous imports>
-   from pmrf.constraints import Positive
+   from pmrf.parameters.constraints import Positive
    
    class Capacitor(Capacitor):
        C: prf.Param = prf.param(constraint=Positive(), as_free=True, scale=1e-12)

{paramrf-0.36.6 → paramrf-0.37.0}/docs/examples/discrepancy_prediction.rst

@@ -1,12 +1,12 @@
 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.
+A fitted Gaussian-process discrepancy can be predicted at new frequencies, with its uncertainty. Here we fit the S11 of a coaxial line and predict its discrepancy beyond the fit band.
 
 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:
+We add a slow ripple and measurement noise to the line's S11, then fit the dielectric constant with a :class:`~pmrf.stats.GaussianProcess` for the discrepancy. The kernel length scale uses the fit frequency's unit, MHz:
 
 .. plot::
    :context: reset
@@ -18,9 +18,7 @@ The measured S11 is a coaxial line plus a slow ripple that the model cannot prod
    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
+   from pmrf.stats import GaussianLikelihood, GaussianProcess, Matern52Kernel
 
    def coax(ep_r):
        return CoaxialLine(
@@ -48,7 +46,7 @@ The measured S11 is a coaxial line plus a slow ripple that the model cannot prod
 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.
+:meth:`~pmrf.objectives.MarginalLogLikelihood.predict_discrepancy` uses the fitted model and residuals to predict the discrepancy. The new frequency grid extends beyond the fit band and uses GHz; the method handles the unit conversion.
 
 .. plot::
    :context:
@@ -74,4 +72,4 @@ The fitted :class:`~pmrf.evaluators.MarginalLogLikelihood`, with its optimized G
    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.
+The prediction has separate real and imaginary S11 blocks, with frequency last. It excludes measurement noise. Beyond the fit band, the mean approaches zero and uncertainty grows.

{paramrf-0.36.6 → paramrf-0.37.0}/docs/examples/index.rst

@@ -9,10 +9,9 @@ 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
    multiple_models_one_parameter_set
-   shared_substrates
+   shared_modules
+   discrepancy_prediction

{paramrf-0.36.6 → paramrf-0.37.0}/docs/examples/model_optimization.rst

@@ -26,13 +26,13 @@ It is best practice to apply a scaling factor to our values in order to keep the
 Running the Optimizer
 ~~~~~~~~~~~~~~~~~~~~~
 
-Next, we define our design goals. In this case, we want to ensure good matching (low reflection) across our passband. We can use the :class:`~pmrf.evaluators.Goal` evaluator and pass it to the :func:`~pmrf.optimize.minimize` function alongside our frequency range:
+Next, we define our design goals. In this case, we want to ensure good matching (low reflection) across our passband. We can use the :class:`~pmrf.objectives.Goal` evaluator and pass it to the :func:`~pmrf.optimize.minimize` function alongside our frequency range:
 
 .. plot::
    :context:
    :include-source:
 
-   from pmrf.evaluators import Goal
+   from pmrf.objectives import Goal
    from pmrf.optimize import minimize, ScipyMinimize
 
    match_goal = Goal('s11_db', '<', -20)
@@ -71,6 +71,6 @@ For more complex designs, the :func:`~pmrf.optimize.minimize` function can accep
        (Goal('s21_db', '<', -40), stopband),
    ], lpf, solver=ScipyMinimize(method='L-BFGS-B'))
 
-See the :doc:`/core_concepts/optimization_and_inference` page for how to weight such goals against one another. For even more advanced optimization, custom losses can be specified, either using the built-in losses in :mod:`~pmrf.losses`; using a custom callable; or by creating a custom :class:`~pmrf.evaluators.AbstractEvaluator`. The last example is the most powerful, allowing the specification of arbitrary, tunable hyper-parameters.
+See the :doc:`/core_concepts/optimization_and_inference` page for how to weight such goals against one another. For even more advanced optimization, custom losses can be specified, either using the built-in losses in :mod:`~pmrf.objectives`; using a custom callable; or by creating a custom :class:`~pmrf.objectives.AbstractEvaluator`. The last example is the most powerful, allowing the specification of arbitrary, tunable hyper-parameters.
 
 Note that ParamRF also provides convenience functions for fitting models directly to data in :func:`~pmrf.fitting`. See the tutorial for a detailed guide.

paramrf-0.37.0/docs/examples/shared_modules.rst

@@ -0,0 +1,30 @@
+Sharing a Module Across Models
+==============================
+
+A model normally owns its modules and their parameters. To share one module across
+several models, store it on an :class:`pmrf.models.AbstractBuilder` and pass it to
+each model in ``build``. This board shares one substrate between two traces.
+
+.. jupyter-execute::
+
+   import pmrf as prf
+   from pmrf.materials import ConstantDielectric, Substrate
+   from pmrf.models import AbstractBuilder, MicrostripLine
+
+   class Board(AbstractBuilder):
+       substrate: Substrate
+       w1: prf.Param
+       w2: prf.Param
+
+       def build(self):
+           return (
+               MicrostripLine(w=self.w1, substrate=self.substrate, length=0.1)
+               ** MicrostripLine(w=self.w2, substrate=self.substrate, length=0.2)
+           )
+
+   board = Board(
+       substrate=Substrate(h=1.6e-3, dielectric=ConstantDielectric(ep_r=4.3, tand=0.02)),
+       w1=1.0e-3,
+       w2=2.0e-3,
+   )
+   list(prf.params(board))

{paramrf-0.36.6 → paramrf-0.37.0}/docs/skrf_comparison/performance.rst

@@ -28,7 +28,7 @@ The script below builds the same circuit in ``scikit-rf`` and ParamRF once, then
         GlobalMNACircuitSolver,
     )
     from pmrf.parameters import Bounded
-    from pmrf.evaluators import Goal
+    from pmrf.objectives import Goal
     from pmrf.optimize import minimize as pmrf_minimize, ScipyMinimize
 
     c = scipy.constants.c

paramrf-0.37.0/docs/tutorials/3_discrepancy_transfer.ipynb

@@ -0,0 +1,317 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Fitting and transferring discrepancy\n",
+    "\n",
+    "A discrepancy describes the part of a measured response that a physical model misses. This tutorial fits a lossy coax with a small conductor error, predicts the correction with its uncertainty, and carries it to a new line length. It then shows how a port discrepancy can carry a joint parameter and correction prediction into a terminated circuit.\n",
+    "\n",
+    "The [discrepancy prediction example](../examples/discrepancy_prediction.rst) is the short introduction. The code here uses small synthetic data sets so every result can be checked against a known line."
+   ],
+   "id": "discrepancy-01"
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## A reference line and a shorter target\n",
+    "\n",
+    "The reference line is 30 cm long; the target is 15 cm. The nominal line has 10% excess conductor loss. A port correction belongs to the reference response, while an internal correction changes characteristic impedance, attenuation, and phase per unit length. That distinction matters when the line length changes."
+   ],
+   "id": "discrepancy-02"
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pathlib import Path\n",
+    "import sys\n",
+    "import jax\n",
+    "import jax.numpy as jnp\n",
+    "import matplotlib.pyplot as plt\n",
+    "import numpy as np\n",
+    "from scipy.optimize import minimize as scipy_minimize\n",
+    "import pmrf as prf\n",
+    "from pmrf.materials import BulkConductor, ConstantDielectric\n",
+    "from pmrf.models import (\n",
+    "    CoaxialLine, GridLineDiscrepancy, GridPortDiscrepancy, LineCorrected,\n",
+    "    Load, PortCorrected, line_internal_features, project_line_basis_joint,\n",
+    "    reference_line_features,\n",
+    ")\n",
+    "from pmrf.objectives import MarginalLogLikelihood\n",
+    "from pmrf.optimize import ScipyMinimize, minimize\n",
+    "from pmrf.stats import (\n",
+    "    GaussianLikelihood, GaussianProcess, Matern52Kernel, RBFKernel, posterior_covariance,\n",
+    ")\n",
+    "\n",
+    "tutorial_dir = Path.cwd()\n",
+    "if not (tutorial_dir / \"line_internal_discrepancy.py\").exists():\n",
+    "    tutorial_dir = Path(\"docs/tutorials\")\n",
+    "sys.path.insert(0, str(tutorial_dir.resolve()))\n",
+    "from line_internal_discrepancy import (\n",
+    "    MODEL_SIGMA, TRUTH_SIGMA, _basis, compare_transfer,\n",
+    "    exact_values, frequency, line,\n",
+    ")\n",
+    "from port_discrepancy import ReciprocalEventTransform, reciprocal_predictor\n",
+    "\n",
+    "f = frequency()\n",
+    "comparison = compare_transfer()\n",
+    "for name, errors in comparison.items():\n",
+    "    print(f\"{name}: RMS S21 error = {errors['rms_s21']:.4g}, eta bias = {errors['eta_bias']:.4g}\")"
+   ],
+   "id": "discrepancy-03"
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The internal correction follows the shorter line's electrical length. The port correction uses the reference line's S-parameter error as if it belonged to the shorter line."
+   ],
+   "id": "discrepancy-04"
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Learn an internal correction\n",
+    "\n",
+    "Here the reference measurement supplies characteristic impedance $Z_c$ and propagation constant $\\gamma$. `reference_line_features` converts them to the four log-ratio channels used by `GridLineDiscrepancy`: real and imaginary $\\log Z_c$, log attenuation, and log phase constant. The likelihood variance is specified in this transformed event space.\n",
+    "\n",
+    "The nominal model has a free conductor parameter. `predict_joint` returns one Gaussian over that parameter and the correction grid, preserving their covariance."
+   ],
+   "id": "discrepancy-05"
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "reference = line(0.30, TRUTH_SIGMA)\n",
+    "zc, gamma_length = reference.zc_and_gammaL(f)\n",
+    "observed = reference_line_features(zc, gamma_length / 0.30)\n",
+    "nominal = line(0.30, MODEL_SIGMA, free_sigma=True)\n",
+    "reference_likelihood = MarginalLogLikelihood(\n",
+    "    predictor=line_internal_features,\n",
+    "    observed=observed,\n",
+    "    likelihood=GaussianLikelihood(1e-10),\n",
+    "    discrepancy=GaussianProcess(RBFKernel(0.5) * 0.1**2, jitter=1e-12),\n",
+    ")\n",
+    "names, joint = reference_likelihood.predict_joint(nominal, f, f)\n",
+    "print(\"Joint dimensions:\", joint.mean().shape[0], \"parameter names:\", names)"
+   ],
+   "id": "discrepancy-06"
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The same prediction can be attached to a shorter line. The joint prior keeps the conductor parameter correlated with the discrepancy values. `truncate='unnormalised'` respects the conductor's validity range for MAP work; it is unsuitable for sampling or evidence calculations."
+   ],
+   "id": "discrepancy-07"
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "carrier = GridLineDiscrepancy.from_prediction(f, joint, joint=True)\n",
+    "short_line = LineCorrected(line(0.15, MODEL_SIGMA, free_sigma=True), carrier)\n",
+    "short_line = prf.prior(\n",
+    "    short_line, [*names, \"discrepancy.values\"], joint,\n",
+    "    truncate=\"unnormalised\",\n",
+    ")\n",
+    "truth_short = line(0.15, TRUTH_SIGMA)\n",
+    "rms_s21 = np.sqrt(np.mean(np.abs(np.asarray(short_line.s(f) - truth_short.s(f))[:, 1, 0])**2))\n",
+    "print(\"Transferred RMS S21 error:\", float(rms_s21))"
+   ],
+   "id": "discrepancy-08"
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The joint mean contains the conductor parameter first, then four correction channels. Its diagonal gives marginal uncertainty in each channel; the off-diagonal entries still matter when the correction is used with the conductor parameter."
+   ],
+   "id": "discrepancy-09"
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "mean = np.asarray(joint.mean())[1:].reshape(2, 2, f.npoints)\n",
+    "std = np.sqrt(np.diag(np.asarray(joint.covariance()))[1:]).reshape(2, 2, f.npoints)\n",
+    "truth = np.asarray(exact_values(f))\n",
+    "labels = (\"log Zc real\", \"log Zc imaginary\", \"log attenuation\", \"log phase\")\n",
+    "fig, axes = plt.subplots(2, 2, figsize=(10, 6), sharex=True)\n",
+    "for axis, label, predicted, sigma, actual in zip(axes.flat, labels, mean.reshape(4, -1), std.reshape(4, -1), truth.reshape(4, -1)):\n",
+    "    axis.plot(f.f_scaled, actual, label=\"injected\")\n",
+    "    axis.plot(f.f_scaled, predicted, label=\"predicted\")\n",
+    "    axis.fill_between(f.f_scaled, predicted - 2*sigma, predicted + 2*sigma, alpha=0.2)\n",
+    "    axis.set_title(label)\n",
+    "axes[0, 0].legend()\n",
+    "fig.tight_layout()"
+   ],
+   "id": "discrepancy-10"
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## When only S-parameters are measured\n",
+    "\n",
+    "The preceding route uses $Z_c$ and $\\gamma$. If the reference only provides complex S-parameters, represent the internal correction with basis coefficients and fit them through the line response. The [supporting script](line_internal_discrepancy.py) defines the basis from an RBF spectral density; the fit and projection are shown below."
+   ],
+   "id": "discrepancy-11"
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "basis = _basis(f)\n",
+    "nominal_s = LineCorrected(line(0.30, MODEL_SIGMA), basis)\n",
+    "observed_s = line(0.30, TRUTH_SIGMA).s(f)\n",
+    "s_likelihood = MarginalLogLikelihood(\n",
+    "    predictor=lambda model, grid: model.s(grid),\n",
+    "    observed=observed_s,\n",
+    "    likelihood=GaussianLikelihood(1e-8),\n",
+    ")\n",
+    "objective = lambda model: -s_likelihood(model, f) - prf.log_prior(model)\n",
+    "fitted_s = minimize(objective, nominal_s, solver=ScipyMinimize(method=\"BFGS\"), max_iter=400).model\n",
+    "fitted_basis = prf.update(\n",
+    "    basis, \"coefficients\", value=prf.values(fitted_s)[\"discrepancy.coefficients\"]\n",
+    ")\n",
+    "linearization = s_likelihood.linearize(fitted_s, f)\n",
+    "covariance = posterior_covariance([linearization], fitted_s)\n",
+    "names_s, joint_s = project_line_basis_joint(\n",
+    "    fitted_s, fitted_basis, linearization, covariance, f\n",
+    ")\n",
+    "carrier_s = GridLineDiscrepancy.from_prediction(f, joint_s, joint=True)\n",
+    "short_s = LineCorrected(line(0.15, MODEL_SIGMA), carrier_s)\n",
+    "rms_s = np.sqrt(np.mean(np.abs(np.asarray(short_s.s(f) - truth_short.s(f))[:, 1, 0])**2))\n",
+    "mean_s = np.asarray(joint_s.mean()).reshape(2, 2, f.npoints)\n",
+    "std_s = np.sqrt(np.diag(np.asarray(joint_s.covariance()))).reshape(2, 2, f.npoints)\n",
+    "coverage = np.mean(np.abs(np.asarray(exact_values(f)) - mean_s) <= 2 * std_s)\n",
+    "print(\"Transferred RMS S21 error:\", float(rms_s))\n",
+    "print(\"Injected values within mean ± 2σ:\", float(coverage))"
+   ],
+   "id": "discrepancy-12"
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Port discrepancy in a later circuit\n",
+    "\n",
+    "A port correction applies when the fitted component stays the same and its surrounding circuit changes. Here the reference fit estimates a bounded coax length and a reciprocal port discrepancy. The [supporting script](port_discrepancy.py) defines the event transform used for symmetric transmission and contains independent covariance checks. We use that transform below, then carry the joint prediction into a terminated circuit."
+   ],
+   "id": "discrepancy-13"
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def cable(length):\n",
+    "    return CoaxialLine(\n",
+    "        length=length,\n",
+    "        d_in=prf.Fixed(1.12e-3), d_out=prf.Fixed(3.2e-3),\n",
+    "        dielectric=ConstantDielectric(ep_r=prf.Fixed(1.384), tand=prf.Fixed(0.001)),\n",
+    "        conductor=BulkConductor(sigma=prf.Fixed(1 / 1.6e-8)),\n",
+    "    )\n",
+    "\n",
+    "reference_f = prf.Frequency(100, 500, 12, \"MHz\")\n",
+    "transfer_f = prf.Frequency(120, 480, 6, \"MHz\")\n",
+    "true_cable = cable(prf.Fixed(0.1))\n",
+    "initial_cable = cable(prf.Bounded(0.05, 0.15, value=0.095))\n",
+    "reference_port = MarginalLogLikelihood(\n",
+    "    predictor=reciprocal_predictor,\n",
+    "    observed=reciprocal_predictor(true_cable, reference_f),\n",
+    "    likelihood=GaussianLikelihood(jnp.full((3, 2, reference_f.npoints), 1e-8)),\n",
+    "    discrepancy=GaussianProcess(Matern52Kernel(80.0) * 1e-6, jitter=1e-12),\n",
+    "    event_transform=ReciprocalEventTransform,\n",
+    ")\n",
+    "\n",
+    "def port_loss(length):\n",
+    "    return -reference_port(prf.update(initial_cable, {\"length\": length}), reference_f)\n",
+    "\n",
+    "value_gradient = jax.jit(jax.value_and_grad(port_loss))\n",
+    "fit_result = scipy_minimize(\n",
+    "    lambda x: tuple(np.asarray(v) for v in value_gradient(jnp.asarray(x))),\n",
+    "    np.array([0.095]), jac=True, method=\"L-BFGS-B\", bounds=[(0.05, 0.15)],\n",
+    "    options={\"maxiter\": 1000, \"gtol\": 1e-10, \"ftol\": 1e-14},\n",
+    ")\n",
+    "assert fit_result.success\n",
+    "fitted_cable = prf.update(initial_cable, {\"length\": jnp.asarray(fit_result.x[0])})\n",
+    "port_names, port_joint = reference_port.predict_joint(fitted_cable, reference_f, transfer_f)\n",
+    "print(\"Fitted length:\", float(prf.values(fitted_cable)[\"length\"]))"
+   ],
+   "id": "discrepancy-14"
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "port_mean = port_joint.mean()[1:].reshape(3, 2, transfer_f.npoints)\n",
+    "corrected_cable = PortCorrected(\n",
+    "    fitted_cable,\n",
+    "    GridPortDiscrepancy(prf.Unconstrained(port_mean), transfer_f, (\"11\", \"22\", \"s21\")),\n",
+    ")\n",
+    "corrected_cable = prf.prior(\n",
+    "    corrected_cable, [*port_names, \"discrepancy.values\"], port_joint,\n",
+    "    truncate=\"unnormalised\",\n",
+    ")\n",
+    "load = Load(gamma=(75.0 - 50.0) / (75.0 + 50.0), z0=50.0)\n",
+    "transfer_circuit = corrected_cable.terminated(load)\n",
+    "observed_reflection = true_cable.terminated(load).s(transfer_f, z0=50.0)[:, 0, 0]\n",
+    "transfer_likelihood = MarginalLogLikelihood(\n",
+    "    predictor=lambda model, grid: model.s(grid, z0=50.0)[:, 0, 0],\n",
+    "    observed=observed_reflection,\n",
+    "    likelihood=GaussianLikelihood(1e-6),\n",
+    ")\n",
+    "transfer_linearization = transfer_likelihood.linearize(\n",
+    "    transfer_circuit, transfer_f, space=\"declared\"\n",
+    ")\n",
+    "transfer_covariance = posterior_covariance(\n",
+    "    [transfer_linearization], transfer_circuit, space=\"declared\"\n",
+    ")\n",
+    "print(\"Joint dimension:\", port_joint.mean().shape[0])\n",
+    "print(\"Transferred log prior:\", float(prf.log_prior(transfer_circuit, space=\"declared\")))\n",
+    "print(\"Posterior variance, first coordinate:\", float(transfer_covariance[0, 0]))"
+   ],
+   "id": "discrepancy-15"
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The carrier follows what stays physically common between fits: use an internal line correction across lengths, or a port correction when moving the same component into another circuit. The joint distribution retains parameter–discrepancy covariance in each later calculation. The [port script](port_discrepancy.py) compares the final covariance with a NumPy Kalman update and checks the transferred prior's precision."
+   ],
+   "id": "discrepancy-16"
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

{paramrf-0.36.6 → paramrf-0.37.0}/docs/tutorials/index.rst

@@ -7,4 +7,5 @@ This section includes more detailed tutorials that can be followed step-by-step
    :maxdepth: 2
 
    1_cable_fitting.ipynb
-   2_chip_inductor_fitting.ipynb
+   2_chip_inductor_fitting.ipynb
+   3_discrepancy_transfer.ipynb