BaseRunner

class BaseRunner(model, *, frequency=None, features=None, **feature_kwargs)[source]

Bases: ABC

The unified base class for all ParamRF runners (fitters and samplers).

This class manages the core model, the frequency bands, and the specifications for feature extraction. It also handles the lazy compilation of JAX-traced functions for evaluating probabilities and model features.

Main methods

`cdf`	Evaluate the cumulative distribution function (CDF) for the model parameters.
`icdf`	Evaluate the inverse cumulative distribution function (ICDF), or quantile function.
`log_prior`	Evaluate the log-prior probability $log P(theta)$ of the model parameters.
`model_features`	Extract the RF features from the model for a given set of parameters.
`run`	Execute the primary algorithm for the runner.
`write_results`	Encode backend optimization or sampling results into a bytes stream.
`read_results`	Reconstruct backend optimization or sampling results from a bytes stream.

Parameters:

model (Model) – The base ParamRF model containing the free parameters to be evaluated.
frequency (Frequency, optional) – The frequency definitions over which the model should be evaluated.
features (FeatureSpecT, optional) – The target features to extract from the model’s simulated network.
**feature_kwargs – Additional keyword arguments passed directly to the underlying extract_features routine.

Raises:

ValueError – If the initialized model contains no free parameters.

cdf(theta)[source]

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

icdf(u)[source]

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)[source]

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)[source]

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.

abstractmethod run(*args, **kwargs)[source]

Execute the primary algorithm for the runner.

Must be implemented by subclasses.

static write_results(stream, results)[source]

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.

static read_results(stream)[source]

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