Experiments and studies

A Measurement holds observed values, an Experiment binds a model and its measurements, and a Study groups experiments with the parameters they share or vary. See fitting parameters.

diff_soup.inference.Measurement dataclass

One stream of observed values, compared with an observed quantity of the solution at the given times.

A measurement takes weight= or likelihood=, not both. Without a likelihood the fit is weighted least squares, and the statistics functions that need a noise model refuse it.

Parameters:

Name	Type	Description	Default
name	str	The label of the measurement in results and diagnostics, unique within an experiment.	required
times	Any	The observation times, a one-dimensional array.	required
values	Any	The observed values with one row per time, or a function of no arguments returning them, called once when first needed.	required
weight	Any	A positive weight on the squared residual, a scalar or an array that broadcasts against values.	None
likelihood	Likelihood | None	The noise model, such as Gaussian.	None
observe	Callable | str | None	The observed quantity: a function observe(state), optionally taking t= and theta=, the name of a spec.observe declaration, or None for the state.	None
mask	Any	One boolean per time, True where the time carries a measurement.	None
shape	tuple | None	The shape of values, checked against them.	None
dtype	Any	The dtype of values, checked against them.	None

diff_soup.inference.Experiment dataclass

One solve of a model, compared against its measurements.

Pass one or several experiments to an InferenceProblem or a Study. Every measurement time lies inside t_span.

Parameters:

Name	Type	Description	Default
model	Any	The built problem, or a Recipe template built with the template arguments in inputs.	required
solver	Any	The time-stepping solver used for every solve of the fit.	required
t_span	tuple[float, float]	The interval (t0, t1) of the solve, with t0 < t1.	required
initial_state	Any	The state the solve starts from at t0.	required
measurements	tuple[Measurement, ...]	A non-empty tuple of Measurement with distinct names.	required
inputs	Mapping[str, Any]	Template arguments and fixed parameter values for this experiment alone, by name.	dict()
id	Any	A hashable name for the experiment, or None to build one from inputs or, without inputs, to number the experiment.	None
trajectory	Trajectory | None	SingleShoot or Multishoot, or None for one solve over t_span.	None
schedule	Any	An operating protocol the solve follows, a ds.Schedule.	None
parameters	Any	A mapping from each level of the study's Hierarchy to this experiment's member of it.	None

diff_soup.inference.Study dataclass

A group of experiments with the parameters they share or vary, lowered with ds.lower for a joint fit.

With a Hierarchy, each experiment names its members in its own parameters=. With a ds.ParameterSet, clusters= gives the owner of each experiment for each cluster.

Parameters:

Name	Type	Description	Default
experiments	Experiment | Any	One Experiment or a non-empty iterable of them, with distinct ids.	required
parameters	ParameterSet | Hierarchy	A ds.ParameterSet or a Hierarchy.	required
clusters	Mapping[str, Any] | None	A mapping from cluster name to one owner label per experiment, for a ds.ParameterSet only.	None
independent	bool | None	Whether the experiments are independent, which must be True for several experiments under a ds.ParameterSet.	None

diff_soup.inference.Hierarchy dataclass

Declare which parameters of a study are shared and which take one value per member of a level.

Pass it as parameters= of a Study. Each handle appears once, in shared or under one level of per, and experiments that name the same member share its values.

Parameters:

Name	Type	Description	Default
levels	Any	The level names between the study and its experiments, outermost first, or None to take them from the keys of per.	None
shared	Any	The handles with one value for the whole study.	()
per	Any	A mapping from level name to the handles with one value per member of that level, where the key "experiment" means each experiment.	None

---

Lowered studies

ds.lower(study) returns a LoweredStudy for a hierarchical fit (hierarchical fits).

diff_soup.inference.LoweredStudy

A study prepared for fitting by ds.lower(study), with its experiments' solves compiled and batched.

ds.inference.optsolve and the statistics methods take it in place of an InferenceProblem, and ds.inference.TrustRegion fits only this form. A failed solve is retried from a smaller first step.

retry_kinds property

retry_kinds: tuple[str, ...]

The failure kinds that are solved again from a smaller first step.

retry_first_step_factors property

retry_first_step_factors: tuple[float, ...]

The factors of the first step a failed solve is retried with, in the order tried.

evaluation_noise property

evaluation_noise: float | None

The relative noise of the objective's evaluation, by default the largest rtol of the experiments' solvers, or None.

processes property

processes: int

The number of processes the study's experiments are split over.

prepare

prepare(*, modes: Any = None, **options: Any) -> PrepareReport

Compile the study's solves before the first evaluation.

Parameters:

Name	Type	Description	Default
modes	Any	The evaluation modes to compile, such as "value", "gradient" or "blocks", or None for the default set.	None
**options	Any	Not accepted.	{}

Returns:

Type	Description
PrepareReport	A report of what was compiled and how long each setup stage took.

Raises:

Type	Description
TypeError	If any keyword other than modes is passed.

evaluate

evaluate(request: Request) -> Results

Evaluate the experiments' solves for one request, retrying failed solves.

Parameters:

Name	Type	Description	Default
request	Request	The Request naming the evaluation mode and the parameter points.	required

Returns:

Type	Description
Results	The Results of every solve.

log_likelihood

log_likelihood(x: Any) -> Any

The log-likelihood of the measurements at x, differentiable with JAX.

Parameters:

Name	Type	Description	Default
x	Any	A point of the joint parameter vector.	required

Returns:

Type	Description
Any	A scalar JAX array.

value_and_gradient

value_and_gradient(points: Any, *, weights: Any = None) -> ValueAndGradient

Evaluate the objective and its gradient at many points in one batched request.

Parameters:

Name	Type	Description	Default
points	Any	One point (n,) or P points (P, n) of the joint vector, or (Q, P, n) with weights.	required
weights	Any	A (Q, m) array with one weight per member of the first level for each group of points.	None

Returns:

Type	Description
ValueAndGradient	A named tuple of values and gradients, NaN where a solve failed, with the failures and the raw results.

observed_information

observed_information(x: Any) -> Any

The observed information at x, the Hessian of the negative log-likelihood.

Parameters:

Name	Type	Description	Default
x	Any	A point of the joint parameter vector.	required

expected_information

expected_information(x: Any) -> Any

The expected information at x, the Gauss-Newton matrix, or None when the study does not provide it.

Parameters:

Name	Type	Description	Default
x	Any	A point of the joint parameter vector.	required

plan

plan() -> Plan

The plan that groups the experiments' solves into batches.

tables

tables(lane_ids: Any) -> TreeTables | LevelTables

The tables that map the given solves to their columns of the joint vector.

Parameters:

Name	Type	Description	Default
lane_ids	Any	The ids of the solves, as a request's results list them.	required

Returns:

Type	Description
TreeTables | LevelTables	LevelTables for a Hierarchy study, TreeTables otherwise.

for_population

for_population(members: int, *, chunk: Any = 'auto') -> LoweredStudy

A copy of the study re-planned to evaluate members parameter points per request.

Nothing is lowered again, and the copy reuses this study's compiled solves.

Parameters:

Name	Type	Description	Default
members	int	The number of points each request evaluates.	required
chunk	Any	The number of solves one compiled call evaluates, "auto" to choose it, or None to return this study.	'auto'

close

close() -> None

Stop the other processes of a run of several processes, or do nothing in a run of one.