FrequentistFitter

class FrequentistFitter(model, *, cost_kind=None, error_kind=None, error_fn=None, tikhonov_lambda=0.0, **kwargs)[source]

Bases: BaseFitter, ABC

A base class for frequentist (classical) optimization methods.

This class sets up the objective function (or cost function) needed by standard numerical optimizers (like those in SciPy). It automatically configures the target features and error metrics based on the type of fit you want to perform.

Methods

run

Run the fitting process against the provided measurement data.

execute

Implemented by subclasses to run the specific optimization algorithm.

cost

Calculate the scalar error (cost) for a given set of parameters.
Parameters:

  • model (Model) – The ParamRF model containing the parameters to optimize.

  • cost_kind (str, optional) – A preset string to automatically configure both the features and error function into a combined cost function. Options are ‘complex’, ‘magnitude’, ‘geometric’, or ‘convolutional’. ‘convolutional’ and ‘geometric’ use custom error functions with the same names, whereas ‘complex’ and ‘magnitude’ use the ‘independent’ error function. If left None, and no features or error function is provided, then ‘complex’ is assumed.

  • error_kind (str, optional:) – A preset string to automatically configure an error function. Options are ‘independent’, ‘geometric’ or ‘convolutional’. Note that all of these currently use the L2 norm (RMS).

  • error_fn (callable, optional) – The specific function used to calculate the error. Passed the difference between the model and measured features. If not provided, is configured based on cost_kind and error_kind.

  • tikhonov_lambda (float, default=0.0) – The weight to use for Tikhonov regularization. The weight is multiplied to a regularization term which depends on the squared difference between the new model parameters and the initial model parameters in normalized space.

  • **kwargs – Additional arguments passed up to BaseFitter (such as frequency).

cdf(theta)

Evaluate the cumulative distribution function (CDF) for the model parameters.

This computes the probability \(P(X \leq \theta)\) and lazily compiles the evaluation graph using jax.jit on the first call.

Parameters:

theta (jax.numpy.ndarray) – The parameter values to evaluate.

Returns:

The evaluated CDF probabilities, bounded between \(0\) and \(1\).

Return type:

jax.numpy.ndarray

abstractmethod execute(target, **kwargs)

Implemented by subclasses to run the specific optimization algorithm.

Parameters:

  • target (jax.numpy.ndarray) – The extracted target features to fit against.

  • **kwargs – Backend-specific algorithm parameters passed down from run().

Returns:

The fitted model and the raw results from the solver.

Return type:

tuple[Model, Any]

icdf(u)

Evaluate the inverse cumulative distribution function (ICDF), or quantile function.

This computes \(\theta = F^{-1}(u)\) and lazily compiles the evaluation graph using jax.jit on the first call.

Parameters:

u (jax.numpy.ndarray) – The probability values to evaluate, typically uniformly distributed between \(0\) and \(1\).

Returns:

The corresponding parameter values \(\theta\).

Return type:

jax.numpy.ndarray

log_prior(theta)

Evaluate the log-prior probability \(\log P(\theta)\) of the model parameters.

The prior is calculated by summing the log-probabilities of the flat parameter vector. The JAX graph is lazily compiled on the first call.

Parameters:

theta (jax.numpy.ndarray) – The parameter values to evaluate.

Returns:

The scalar log-prior probability.

Return type:

float or jax.numpy.ndarray

model_features(theta)

Extract the RF features from the model for a given set of parameters.

This function maps the parameters into the model, simulates it over the defined frequency band, and extracts the target specifications. The entire extraction pipeline is vectorized over the batch dimension and lazily compiled via jax.jit(jax.vmap(...)).

Parameters:

theta (jax.numpy.ndarray) – A 1D array of a single parameter set, or a 2D array representing a batch of parameters.

Returns:

The extracted model features. Matches the batch dimension of theta.

Return type:

jax.numpy.ndarray

Raises:

RuntimeError – If frequency or features were not provided during initialization.

static read_results(stream)

Reconstruct backend optimization or sampling results from a bytes stream.

Parameters:

stream (BytesIO) – The open byte stream to read from.

Returns:

The deserialized Python objects.

Return type:

Any

run(measured, *, output_path=None, output_root=None, plot=None, save_model=True, save_results=True, figure_dir=None, fitted_uniform_frac=None, **kwargs)

Run the fitting process against the provided measurement data.

This method automatically sets up the frequency, extracts the target features, and calls the subclass’s execute method. It also handles saving the results and generating plots if requested.

Note: Any extra keyword arguments (**kwargs) are passed directly to the underlying execute method.

Parameters:

  • measured (str or skrf.Network or NetworkCollection) – The ground-truth measurement data to fit the model against. Can be a path to a Touchstone file, a scikit-rf Network, or a collection.

  • output_path (str, optional) – The directory where results, models, and figures should be saved.

  • output_root (str, optional) – A prefix string appended to all saved filenames.

  • plot (FeatureSpecT, optional) – Specific features to plot and save as PNG images after fitting.

  • save_model (bool, default=True) – Whether to save the fitted model to disk.

  • save_results (bool, default=True) – Whether to save the full FitResults object to an HDF5 file.

  • figure_dir (str, optional) – A sub-directory within output_path specifically for saved figures.

  • fitted_uniform_frac (float, optional, default=0.1) – If provided, the final fitted model’s parameters will be assigned uniform distributions spanning \(\pm\) this fraction around the optimal values (e.g., \(0.1\) implies \(\pm 10\%\)). Set to None to skip.

  • **kwargs – Additional arguments passed directly to the subclass’s execute method.

Returns:

A tuple containing the fitted ParamRF model and the results object.

Return type:

tuple[Model, FitResults]

static write_results(stream, results)

Encode backend optimization or sampling results into a bytes stream.

Parameters:

  • stream (BytesIO) – The open byte stream to write to.

  • results (Any) – The data structure containing the backend results.

Notes

The default implementation uses jsonpickle for robust, research-grade serialization of complex Python objects.

cost(theta, target_features)[source]

Calculate the scalar error (cost) for a given set of parameters.

This function computes the model features, calculates the residual against the target data, and passes it through the defined error function. The entire calculation is lazily compiled using jax.jit on the first call to ensure the optimization loop runs as fast as possible.

Parameters:

  • theta (jax.numpy.ndarray) – A 1D array containing the current parameter values being tested by the optimizer.

  • target_features (jax.numpy.ndarray) – The extracted measurement data that the optimizer is trying to match.

Returns:

The scalar cost value representing the total error.

Return type:

jax.numpy.ndarray