Stats

Probability distribution schemas used as priors, samplers, and for uncertainty propagation.

Schemas for stats.

class ionworks.pipeline.stats.Dirichlet(alpha=None, *, distribution: Literal['Dirichlet'] = 'Dirichlet')

Bases: Distribution

Dirichlet distribution over the unit simplex.

Concentration parameters must be > 1 so the distribution’s mode (argmin of the negative logpdf) is well-defined.

Examples

>>> dist = iw.pipeline.stats.Dirichlet(alpha=[2.0, 2.0, 2.0])
>>> param = iw.pipeline.Parameter("Xj", initial_value=0.33, bounds=(0.0, 1.0), prior=dist)

distribution: Literal['Dirichlet']

alpha: list | tuple

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': 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.pipeline.stats.Distribution

Bases: BaseSchema

A probability distribution you can sample from.

This is the shared parent of every named distribution (Normal, LogNormal, Uniform, PointMass, Dirichlet, MultivariateNormal, MultivariateLogNormal). Anywhere a schema field is typed as Distribution (e.g. Prior.distribution or Parameter.initial_guess_distribution), you can pass any of those named subclasses.

to_config() → dict

Build the dict you submit through ionworks.api.

The output carries a "distribution" key set to the name of this distribution ("Normal", "Uniform", …), plus one entry per parameter you supplied (mean, std, lb, ub, alpha, …). Pass this dict wherever the Ionworks API expects a distribution payload.

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': 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.pipeline.stats.LogNormal(mean=None, std=None, *, distribution: Literal['LogNormal'] = 'LogNormal')

Bases: Distribution

Univariate lognormal distribution.

Parameterised by the mean and std of the underlying normal (i.e. values of \(\log X\)).

Examples

>>> prior = iw.pipeline.stats.LogNormal(mean=-32.2, std=2.0)
>>> param = iw.pipeline.Parameter(
...     "Negative particle diffusivity [m2.s-1]",
...     initial_value=1e-14, bounds=(1e-16, 1e-12), prior=prior,
... )

distribution: Literal['LogNormal']

mean: float | int

std: float | int

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': 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.pipeline.stats.MultivariateLogNormal(mean=None, cov=None, *, distribution: Literal['MultivariateLogNormal'] = 'MultivariateLogNormal')

Bases: Distribution

Multivariate lognormal distribution.

Parameterised by the mean vector and covariance matrix of the underlying multivariate normal.

Examples

>>> prior = iw.pipeline.stats.MultivariateLogNormal(
...     mean=[-32.0, -33.0],
...     cov=[[1.0, 0.0], [0.0, 1.0]],
... )
>>> param = iw.pipeline.Parameter("D", initial_value=1.0, bounds=(0.1, 10.0), prior=prior)

distribution: Literal['MultivariateLogNormal']

mean: list | tuple

cov: list | tuple

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': 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.pipeline.stats.MultivariateNormal(mean=None, cov=None, *, distribution: Literal['MultivariateNormal'] = 'MultivariateNormal')

Bases: Distribution

Multivariate normal distribution.

Requires a positive semi-definite covariance matrix of shape matching len(mean).

Examples

>>> prior = iw.pipeline.stats.MultivariateNormal(
...     mean=[1.0, 2.0],
...     cov=[[0.04, 0.0], [0.0, 0.09]],
... )
>>> param = iw.pipeline.Parameter("x", initial_value=1.0, bounds=(0.0, 5.0), prior=prior)

distribution: Literal['MultivariateNormal']

mean: list | tuple

cov: list | tuple

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': 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.pipeline.stats.Normal(mean=None, std=None, *, distribution: Literal['Normal'] = 'Normal')

Bases: Distribution

Univariate normal distribution.

Parameterised by scalar mean and standard deviation.

Examples

>>> prior = iw.pipeline.stats.Normal(mean=3.0, std=0.2)
>>> param = iw.pipeline.Parameter(
...     "Positive electrode capacity [A.h]",
...     initial_value=3.0, bounds=(2.0, 4.0), prior=prior,
... )

distribution: Literal['Normal']

mean: float | int

std: float | int

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': 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.pipeline.stats.PointMass(value=None, *, distribution: Literal['PointMass'] = 'PointMass')

Bases: Distribution

Point mass distribution — a constant value with zero variance.

Useful for pinning a parameter to a fixed value while still flowing through a distribution-aware pipeline step.

Examples

>>> guess = iw.pipeline.stats.PointMass(value=1.0)
>>> param = iw.pipeline.Parameter(
...     "x", initial_value=1.0, bounds=(0.0, 2.0),
...     initial_guess_distribution=guess,
... )

distribution: Literal['PointMass']

value: float | int

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': 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.pipeline.stats.Uniform(lb=None, ub=None, *, distribution: Literal['Uniform'] = 'Uniform')

Bases: Distribution

Uniform distribution on [lb, ub].

Lower bound must be strictly less than upper bound.

Examples

>>> guess = iw.pipeline.stats.Uniform(lb=0.0, ub=2.0)
>>> param = iw.pipeline.Parameter(
...     "x", initial_value=1.0, bounds=(0.0, 2.0),
...     initial_guess_distribution=guess,
... )

distribution: Literal['Uniform']

lb: float | int

ub: float | int

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': 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.