Stats

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

Schemas for stats.

class ionworks_schema.stats.Dirichlet(alpha)

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 = iws.stats.Dirichlet(alpha=[2.0, 2.0, 2.0])
>>> param = iws.Parameter("Xj", initial_value=0.33, bounds=(0.0, 1.0), prior=dist)

Extends: ionworks_schema.stats.stats.Distribution

alpha: list | tuple

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 initialise 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.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.

Extends: ionworks_schema.base.BaseSchema

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, '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 initialise 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.stats.LogNormal(mean, std)

Bases: Distribution

Univariate lognormal distribution.

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

Examples

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

Extends: ionworks_schema.stats.stats.Distribution

mean: float | int

std: float | int

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 initialise 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.stats.MultivariateLogNormal(mean, cov)

Bases: Distribution

Multivariate lognormal distribution.

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

Examples

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

Extends: ionworks_schema.stats.stats.Distribution

mean: list | tuple

cov: list | tuple

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 initialise 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.stats.MultivariateNormal(mean, cov)

Bases: Distribution

Multivariate normal distribution.

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

Examples

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

Extends: ionworks_schema.stats.stats.Distribution

mean: list | tuple

cov: list | tuple

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 initialise 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.stats.Normal(mean, std)

Bases: Distribution

Univariate normal distribution.

Parameterised by scalar mean and standard deviation.

Examples

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

Extends: ionworks_schema.stats.stats.Distribution

mean: float | int

std: float | int

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 initialise 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.stats.PointMass(value)

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 = iws.stats.PointMass(value=1.0)
>>> param = iws.Parameter(
...     "x", initial_value=1.0, bounds=(0.0, 2.0),
...     initial_guess_distribution=guess,
... )

Extends: ionworks_schema.stats.stats.Distribution

value: float | int

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 initialise 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.stats.Uniform(lb, ub)

Bases: Distribution

Uniform distribution on [lb, ub].

Lower bound must be strictly less than upper bound.

Examples

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

Extends: ionworks_schema.stats.stats.Distribution

lb: float | int

ub: float | int

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 initialise 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.