Skip to main content
iws.DataFit describes a parameter fit: which experiments to compare against, which parameters are free, and how to search. The schema is submitted as one element of a pipeline. For the theory (cost functions, identifiability, multi-start), see the Data Fitting Guide.

​
A minimal fit

import ionworks_schema as iws
from ionworks import Ionworks

# Known parameters (everything not fit)
known = iws.direct_entries.DirectEntry(
    parameters={"Ambient temperature [K]": 298.15},
)

# Objective: compare a current-driven SPMe simulation against measured voltage
obj_1C = iws.objectives.CurrentDriven(
    data_input="file:examples/data/chen_synthetic_1C/time_series.csv",
    options={"model": {"type": "SPMe"}},
)

# Free parameters
parameters = {
    "Negative particle diffusivity [m2.s-1]": iws.Parameter(
        "Negative particle diffusivity [m2.s-1]",
        initial_value=2e-14,
        bounds=(1e-14, 1e-13),
    ),
    "Positive particle diffusivity [m2.s-1]": iws.Parameter(
        "Positive particle diffusivity [m2.s-1]",
        initial_value=2e-15,
        bounds=(1e-15, 1e-14),
    ),
}

fit = iws.DataFit(
    objectives={"test_1C": obj_1C},
    parameters=parameters,
    cost=iws.costs.SSE(),
    optimizer=iws.optimizers.DifferentialEvolution(),
)

pipeline = iws.Pipeline({"known": known, "fit": fit})

client = Ionworks()
submission = client.pipeline.create(pipeline)
client.pipeline.wait_for_completion(submission.id)
result = client.pipeline.result(submission.id)
print(result.element_results["fit"])

​
Multiple objectives

Pass multiple objectives to fit against several experiments simultaneously (e.g. discharge at different C-rates or temperatures): 
fit = iws.DataFit(
    objectives={
        "1C": iws.objectives.CurrentDriven(
            data_input="file:.../1C.csv",
            options={"model": {"type": "SPMe"}},
        ),
        "0.5C": iws.objectives.CurrentDriven(
            data_input="file:.../0.5C.csv",
            options={"model": {"type": "SPMe"}},
        ),
    },
    parameters=parameters,
)
Each objective contributes to a single combined cost.

​
Optimizers

iws.optimizers exposes the optimisers available to DataFit. Pick the one that fits your problem:
SchemaBest for
iws.optimizers.ScipyMinimize(method="L-BFGS-B")Smooth problems, fast local optimisation
iws.optimizers.ScipyLeastSquares()Residual-based least-squares; good with priors
iws.optimizers.DifferentialEvolution()Global, no gradients required
iws.optimizers.CMAES()Global, many local minima, well-tested defaults
iws.optimizers.PSO()Global, parallelisable population search
See Objective Functions for the cost-function options.

​
Multi-start

For problems with multiple local minima, run several optimisations from different starting points: 
fit = iws.DataFit(
    objectives=objectives,
    parameters=parameters,
    multistarts=20,
)
The pipeline generates initial guesses (Latin Hypercube by default), runs them in parallel, and returns every result sorted by cost.

​
Retrieving results

client.pipeline.wait_for_completion(submission.id)
result = client.pipeline.result(submission.id)
print(result.element_results["fit"])
result.element_results["fit"] is a dict keyed by the data-fit’s outputs (best parameter values, final cost, and any logged trajectories). See packages/ionworks-api/examples/pipeline/datafit.py for an end-to-end example.

Data Fitting (theory)

Cost-function math, identifiability, multi-start strategy.

Objective Functions

Pick the right cost for your data shape.

Regularization

Stabilise fits with Gaussian priors.

Sensitivity Analysis

Quantify which parameters the fit actually constrains.