Regularization

Regularization in iws.DataFit is expressed as priors on the fit parameters. Each prior pairs a parameter name with a distribution from iws.stats. For why regularization is needed and how to choose prior strengths, see the Regularization Guide.

Distributions

Schema	Use for
`iws.stats.Normal(mean=..., std=...)`	Gaussian prior, additive scale
`iws.stats.LogNormal(mean=..., std=...)`	Strictly-positive parameter spanning orders of magnitude (e.g. solid-phase diffusivities)
`iws.stats.Uniform(lb=..., ub=...)`	Hard support; equivalent to bounds with constant density
`iws.stats.MultivariateNormal(...)`	Correlated priors across multiple parameters

A regularized fit

import pybamm
import ionworks_schema as iws
from ionworks import Ionworks

parameters = {
    "Positive particle diffusivity [m2.s-1]": iws.Parameter(
        "Positive particle diffusivity [m2.s-1]",
        initial_value=1e-14,
        bounds=(1e-16, 1e-12),
    ),
    "Negative particle diffusivity [m2.s-1]": iws.Parameter(
        "Negative particle diffusivity [m2.s-1]",
        initial_value=3e-14,
        bounds=(1e-16, 1e-12),
    ),
}

priors = {
    "Positive particle diffusivity [m2.s-1]": iws.priors.Prior(
        "Positive particle diffusivity [m2.s-1]",
        iws.stats.LogNormal(mean=-32.2, std=1.0),  # log-mean, log-std
    ),
    "Negative particle diffusivity [m2.s-1]": iws.priors.Prior(
        "Negative particle diffusivity [m2.s-1]",
        iws.stats.LogNormal(mean=-31.1, std=1.0),
    ),
}

fit = iws.DataFit(
    objectives={
        "1C": iws.objectives.CurrentDriven(
            data_input="file:.../1C.csv",
            options={"model": pybamm.lithium_ion.SPMe()},
        ),
    },
    parameters=parameters,
    priors=priors,
    optimizer=iws.optimizers.ScipyLeastSquares(),
)

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

client = Ionworks()
submission = client.pipeline.create(pipeline)

The priors dict adds a regularization term to the cost function so deviations from the prior mean are penalised in proportion to the prior’s inverse variance.

Attaching priors via `Parameter`

Priors can also be attached directly to a Parameter rather than passed as a separate dict — useful when the prior is intrinsic to that parameter:

diffusivity = iws.Parameter(
    "Positive particle diffusivity [m2.s-1]",
    initial_value=1e-14,
    bounds=(1e-16, 1e-12),
    prior=iws.stats.LogNormal(mean=-32.2, std=1.0),
)

Dict-form priors

Schema configs can also be written as plain dicts — useful when a config is loaded from JSON or YAML. Two equivalent forms are accepted in the priors mapping:

# Flat form: distribution name as a string, params inline
priors = {
    "Positive particle diffusivity [m2.s-1]": {
        "distribution": "LogNormal",
        "mean": -32.2,
        "std": 1.0,
    },
}

# Nested form: distribution as its own dict
priors = {
    "Positive particle diffusivity [m2.s-1]": {
        "distribution": {"distribution": "LogNormal", "mean": -32.2, "std": 1.0},
        "regularizer_weight": 2.0,
    },
}

The mapping key is the authoritative parameter name. Any name embedded inside the prior dict is ignored — including when the parameter itself is literally named "distribution".

Strict validation

Priors, distributions, and samplers are validated against discriminated unions at submission time. This catches typos and stale configs before a run starts, rather than letting them surface as opaque runtime crashes. Mistakes that are now rejected with a ValidationError:

An unknown distribution name (e.g. {"distribution": "Guassian", ...}).
A stray or misspelled key in a distribution, prior, or sampler config.
A type discriminator that doesn’t match the field (e.g. {"type": "Penalty", ...} placed under priors).
A bare scalar or list passed where a prior, distribution, or sampler is expected.

The legacy type alias is still accepted in place of the distribution discriminator inside a distribution config — e.g. the nested form’s inner dict {"type": "Normal", "mean": 3.0, "std": 0.2} resolves to a Normal — so existing serialized configs round-trip unchanged. Note that type only aliases distribution at the distribution level: at the top level of a prior mapping, type is the prior discriminator (it must be "Prior"), so a flat-form prior must name its distribution with distribution, not type.

Why `LogNormal` for diffusivities

Solid-phase diffusivities span many orders of magnitude (often

10^{-16}

10^{-10}

m²/s). A Normal prior on the raw value is hard to specify — mean ± std doesn’t reflect order-of-magnitude uncertainty. A LogNormal prior treats the parameter on a log scale, so “mean ± 1 std” corresponds to a factor of

e

— much more natural. The mean=-32.2 in the example above is the natural log of

\sim 10^{-14}

, so the prior is centred on a typical particle diffusivity.

Regularization (theory)

Ridge regression, MAP estimation, bias–variance tradeoff.

Data Fitting overview

Putting priors together with objectives and optimisers.

Get Started

Core Concepts

Data

Build

Pipelines

Simulate

Optimize

Distributions

A regularized fit

Attaching priors via `Parameter`

Dict-form priors

Strict validation

Why `LogNormal` for diffusivities

Regularization (theory)

Data Fitting overview

​Distributions

​A regularized fit

​Attaching priors via Parameter

​Dict-form priors

​Strict validation

​Why LogNormal for diffusivities

Regularization (theory)

Data Fitting overview

Distributions

A regularized fit

Attaching priors via `Parameter`

Dict-form priors

Strict validation

Why `LogNormal` for diffusivities