Data fit¶

DataFit / ArrayDataFit schemas for parameter estimation from data. Mirrors ionworkspipeline.data_fits.

Schemas for data_fit.

class ionworks_schema.data_fit.ArrayDataFit(objectives, source='', parameters=None, cost=None, initial_guesses=None, optimizer=None, cost_logger=None, multistarts=None, objective_parallelism='auto', initial_guess_sampler=None, priors=None, options=None)¶

Bases: DataFit

Fit the same model separately at each value of an independent variable.

Use this when you have one experiment repeated at different conditions — typically temperatures, C-rates, or pulse indices — and you want one fitted parameter set per condition rather than one global fit. objectives is keyed by the independent variable value ({298.15: ..., 313.15: ...}); each entry is fitted independently and the results can be post-processed to extract how parameters depend on the variable.

All other fields behave the same as DataFit.

Extends: ionworks_schema.data_fit.data_fit.DataFit

objectives: Annotated[dict[Any, Annotated[CalendarAgeing | CurrentDriven | CycleAgeing | EIS | ElectrodeBalancing | ElectrodeBalancingHalfCell | MSMRFullCell | MSMRHalfCell | OCPHalfCell | Objective | Pulse | Resistance, FieldInfo(annotation=NoneType, required=True, discriminator='type'), WrapValidator(func=_resolve_objective, json_schema_input_type=PydanticUndefined)]] | Annotated[CalendarAgeing | CurrentDriven | CycleAgeing | EIS | ElectrodeBalancing | ElectrodeBalancingHalfCell | MSMRFullCell | MSMRHalfCell | OCPHalfCell | Objective | Pulse | Resistance, FieldInfo(annotation=NoneType, required=True, discriminator='type'), WrapValidator(func=_resolve_objective, json_schema_input_type=PydanticUndefined)], FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(union_mode='left_to_right')])]¶

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

class ionworks_schema.data_fit.DataFit(objectives, source='', parameters=None, cost=None, initial_guesses=None, optimizer=None, cost_logger=None, multistarts=None, objective_parallelism='auto', initial_guess_sampler=None, priors=None, options=None)¶

Bases: BaseSchema

Fit a model’s parameters to measured experimental data.

A DataFit step says: “run these experiments through the model, compare the result to the measurements I supply, and adjust these parameters until the agreement is as good as possible”. One or more objectives describe what experiments to compare against and which measured curves to match. The parameters dict lists which parameters are free to move during the fit, and the optional priors express what you already believe about their plausible values.

The remaining fields (cost, optimizer, initial_guesses, multistarts, …) tune how the fit runs. The defaults are sensible — you only need to set them if you want finer control over the optimisation algorithm, parallelism, or runtime budget.

Parameters¶

objectivesobjective or dict, or a mapping of name to either

What to fit against. Either a single objective (a CurrentDriven, MSMRHalfCell, … from iws.objectives) or a dict of named objectives if the fit spans multiple experiments.

sourcestr, optional

Free-text label for the data source (paper, dataset name, instrument). Shown in reports and provenance records.

parametersdict[str, Parameter | pybamm.Symbol | callable] | None, optional

Which parameters are being fitted, and (optionally) how they relate to each other through pybamm expressions. At least one of parameters or priors must be set. Each value can be:

an iws.Parameter object, e.g. iws.Parameter("x")
a pybamm expression, in which case other referenced parameters must also be supplied as iws.Parameter objects via pybamm.Parameter wrapping. For example:
```
{
    "param": 2 * pybamm.Parameter("half-param"),
    "half-param": iws.Parameter("half-param"),
}
```
works, but {"param": 2 * iws.Parameter("half-param")} does not.

a function that constructs a pybamm expression referencing other parameters, which must again be explicitly supplied as iws.Parameter objects:

{
    "main parameter": lambda x: (
        pybamm.Parameter("other parameter") * x**2
    ),
    "other parameter": iws.Parameter("other parameter"),
}

The dict key does not need to match the underlying pybamm parameter name — DataFit figures out which variable to fit from the iws.Parameter reference.

costCost or dict or None, optional

How disagreement between model and data is summed up into a single number (e.g. sum-of-squares, log-likelihood). Give a cost schema instance (e.g. iws.costs.SSE()) or a config dict ({"type": "SSE"}). Leave unset for a sensible default.

initial_guessesdict[str, float] or list[dict[str, float]] or None, optional

Starting point(s) for the optimiser. One dict applies to every restart; a list of dicts provides one starting point per restart.

optimizerOptimizer or dict or None, optional

Which optimisation algorithm to use (e.g. CMAES, PSO, ScipyMinimize). Leave unset for the default.

cost_loggerBaseSchema or dict or None, optional

Optional logger that records the cost trajectory and parameter values across the fit, for later inspection.

multistartsint | None, optional

Number of independent restarts from different initial guesses. More restarts is more robust but takes longer.

objective_parallelism{“auto”, “on”, “off”}, optional

Whether to evaluate objectives in parallel. "auto" (default) lets the engine decide; "on"/"off" force or disable it. A debugging escape hatch.

initial_guess_samplerDistributionSampler or dict or None, optional

How to spread the multistart guesses across the parameter space (LatinHypercube by default).

priorsPrior or list[Prior] or dict or None, optional

What you already believe about the parameter values. Acts as a regulariser on the fit. May be supplied alone (the prior names become the fit parameters) or alongside parameters (priors regularise the listed fit parameters).

optionsDataFitOptions or dict or None, optional

Runtime options for the fit — seed, low_memory, max_iterations, maxtime, validate, and skip_objective_callbacks. Pass a DataFitOptions or a plain dict; unknown keys are rejected. See DataFitOptions for each option’s meaning and default.

Examples¶

>>> # build the schema with the fields you care about
>>> obj = iws.objectives.OCPHalfCell(
...     electrode="positive",
...     data_input="path/to/ocp.csv",
... )
>>> fit = iws.DataFit(
...     objectives={"ocp": obj},
...     parameters={"Q_pe": iws.Parameter(
...         "Positive electrode capacity [A.h]", initial_value=3.0, bounds=(2.0, 4.0),
...     )},
...     priors={"Q_pe": iws.priors.Prior("Q_pe", iws.stats.Normal(3.0, 0.2))},
... )
>>> config = iws.Pipeline({"ocp fit": fit}).to_config()
>>> # then submit `config` via ionworks-api

Extends: ionworks_schema.base.BaseSchema

objectives: Annotated[dict[str, Annotated[CalendarAgeing | CurrentDriven | CycleAgeing | EIS | ElectrodeBalancing | ElectrodeBalancingHalfCell | MSMRFullCell | MSMRHalfCell | OCPHalfCell | Objective | Pulse | Resistance, FieldInfo(annotation=NoneType, required=True, discriminator='type'), WrapValidator(func=_resolve_objective, json_schema_input_type=PydanticUndefined)]] | Annotated[CalendarAgeing | CurrentDriven | CycleAgeing | EIS | ElectrodeBalancing | ElectrodeBalancingHalfCell | MSMRFullCell | MSMRHalfCell | OCPHalfCell | Objective | Pulse | Resistance, FieldInfo(annotation=NoneType, required=True, discriminator='type'), WrapValidator(func=_resolve_objective, json_schema_input_type=PydanticUndefined)], FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(union_mode='left_to_right')])]¶

source: str¶

parameters: dict[str, Any] | None¶

cost: Annotated[RMSE | MAE | MSE | Max | SSE | Wasserstein | ChiSquare | MultiCost | GaussianLogLikelihood | DesignFunction, FieldInfo(annotation=NoneType, required=True, discriminator='type')] | None¶

initial_guesses: dict[str, int | float] | list[dict[str, int | float]] | None¶

optimizer: Annotated[DifferentialEvolution | CMAES | PSO | XNES | BayesianOptimization | SOBER | TuRBO | AskTellOptimizer | Nested | ScipyDifferentialEvolution | ScipyMinimize | ScipyLeastSquares | ScipyLsqLinear | ScipyBasinhopping | ScipyDualAnnealing | ScipyShgo | GridSearch | PointEstimateOptimizer | PointEstimateSampler | DummyOptimizer | DummySampler | PintsSampler, FieldInfo(annotation=NoneType, required=True, discriminator='type')] | None¶

cost_logger: Annotated[dict[str, Any] | BaseSchema | Any, FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(union_mode='left_to_right')])] | None¶

multistarts: int | None¶

objective_parallelism: Literal['auto', 'on', 'off']¶

initial_guess_sampler: Annotated[LatinHypercube | Uniform, FieldInfo(annotation=NoneType, required=True, discriminator='type'), WrapValidator(func=_resolve_sampler, json_schema_input_type=PydanticUndefined)] | None¶

priors: Annotated[dict[str, Any] | Prior | Any, FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(union_mode='left_to_right')])] | list[Annotated[dict[str, Any] | Prior | Any, FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(union_mode='left_to_right')])]] | None¶

options: DataFitOptions | None¶

wrap_bare_objective()¶

Wrap a bare objective in a dict for a consistent internal shape.

Only applies to DataFit, not ArrayDataFit (which requires a dict keyed by independent variable values).

validate_parameters_or_priors()¶

At least one of parameters or priors must be supplied.

The runtime accepts both together — priors then act as regularizers on the listed fit parameters — so we mirror the runtime here rather than enforce a stricter mutual exclusion at the schema boundary.

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

class ionworks_schema.data_fit.DataFitOptions(*, seed: Annotated[int | None, Ge(ge=0), Le(le=4294967295)] = None, low_memory: bool | None = None, max_iterations: Annotated[int | None, Gt(gt=0)] = None, maxtime: Annotated[float | None, Gt(gt=0), _PydanticGeneralMetadata(allow_inf_nan=False)] = None, validate: bool = True, skip_objective_callbacks: bool = False)¶

Bases: BaseSchema

Runtime options for a DataFit.

Tunes how a fit executes rather than what it fits. Every field is optional; unknown keys are rejected so a misplaced option (for example multistarts, which is a DataFit field rather than an option) fails when you build the config instead of part-way through the job.

Parameters¶

seedint, optional: Random seed, for reproducibility. Must be in [0, 2**32 - 1], the range numpy accepts. When unset the engine generates one from the current time.
low_memorybool, optional: Reduce log size by appending an entry only when the cost improves the best-so-far by at least 0.1%. When unset the engine enables it for deterministic optimizers and disables it for probabilistic ones.
max_iterationsint, optional: Maximum iterations per optimization job. Must be positive. Only takes effect when the model’s convert_to_format is "casadi".
maxtimefloat, optional: Maximum wall time in seconds per optimization job. Must be positive and finite. With multistarts the total may exceed this, since many jobs run. Only takes effect when the model’s convert_to_format is "casadi".
validatebool, optional: Check, before the fit starts, that every fit parameter is actually used by at least one objective’s model. Catches a misspelt or orphaned parameter name up front rather than after a fit that could never move it. Defaults to True.
skip_objective_callbacksbool, optional: Skip the per-objective callbacks that capture the initial and final fit results. Improves performance when those results are not needed. Defaults to False.

Examples¶

>>> options = iws.DataFitOptions(seed=42, max_iterations=500)
>>> options.to_config()
{'seed': 42, 'max_iterations': 500}

Extends: ionworks_schema.base.BaseSchema

seed: int | None¶

low_memory: bool | None¶

max_iterations: int | None¶

maxtime: float | None¶

validate_: bool¶

skip_objective_callbacks: bool¶

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.