Model Builders

Manage model builders: recipes that turn a cell specification into a model’s parameters.

For usage examples and guides, see Model builders on docs.ionworks.com.

Model builders: recipes that turn a cell specification into a model’s parameters.

A recipe reads the cell spec the way a DirectEntry cell spec entry does: a mapping of parameter names to dotted paths, such as cathode.properties.thickness. It leaves out cell_spec_id, since a builder reads whichever cell spec it builds from. Each value is converted to the unit in its parameter’s name, so 75 um becomes 7.5e-05 for "Positive electrode thickness [m]".

class ionworks.api.model_builder.ModelBuilder(*, id: str, organization_id: str, project_id: str, model_id: str, name: str, description: str | None = None, config: dict[str, Any], **extra_data: Any)

Bases: BaseModel

A model builder.

model_config = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

id: str

organization_id: str

project_id: str

model_id: str

name: str

description: str | None

config: dict[str, Any]

class ionworks.api.model_builder.ReadinessIssue(*, severity: Literal['error', 'warning'], code: str, message: str, parameter: str | None = None, path: str | None = None, element: str | None = None, **extra_data: Any)

Bases: BaseModel

One reason a cell specification cannot (or only with assumptions) be built.

model_config = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

severity: Literal['error', 'warning']

code: str

message: str

parameter: str | None

path: str | None

element: str | None

class ionworks.api.model_builder.ReadinessReport(*, ready: bool, issues: list[ReadinessIssue], resolved: int, total: int, **extra_data: Any)

Bases: BaseModel

Result of ModelBuilderClient.check().

model_config = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

ready: bool

issues: list[ReadinessIssue]

resolved: int

total: int

class ionworks.api.model_builder.BuilderReadiness(*, model_builder_id: str, model_id: str, name: str, ready: bool, error_count: int, warning_count: int, **extra_data: Any)

Bases: BaseModel

One builder’s readiness for a cell specification.

model_config = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_builder_id: str

model_id: str

name: str

ready: bool

error_count: int

warning_count: int

class ionworks.api.model_builder.BuildResult(*, parameters: dict[str, Any], missing: list[str] = [], issues: list[ReadinessIssue] = [], parameterized_model_id: str | None = None, **extra_data: Any)

Bases: BaseModel

Result of ModelBuilderClient.build().

model_config = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

parameters: dict[str, Any]

missing: list[str]

issues: list[ReadinessIssue]

parameterized_model_id: str | None

class ionworks.api.model_builder.ModelBuilderClient(client: Any)

Bases: object

Client for model builders.

__init__(client: Any) → None

Initialize the ModelBuilderClient.

Parameters:

client (Any) – The HTTP client instance used for API calls.

list(model_id: str | None = None, project_id: str | None = None, limit: int | None = None, offset: int | None = None) → PaginatedList[ModelBuilder]

List a project’s model builders.

Parameters:

• model_id (str | None, optional) – Only builders for this model.

• project_id (str | None, optional) – Project to list; defaults to the client’s project. Without either, every builder readable in the organization is listed.

• limit (int | None, optional) – Page size (at most 100).

• offset (int | None, optional) – Number of builders to skip.

Returns:

The page of builders, newest first.

Return type:

PaginatedList[ModelBuilder]

get(model_builder_id: str) → ModelBuilder

Get a model builder by ID.

create(model_id: str, name: str, config: TypeAliasForwardRef('ionworks.pipeline.Pipeline') | dict[str, Any], description: str | None = None, project_id: str | None = None) → ModelBuilder

Create a model builder in a project.

Parameters:

• model_id (str) – Model the builder produces parameters for.

• name (str) – Name, unique per model within the project.

• config (iw.pipeline.Pipeline | dict) – The recipe: a pipeline of entry and calculation elements, as a schema object or its to_config() dict. An entry that reads the cell spec is {"element_type": "entry", "mapping": {...}}, without a cell_spec_id. Fits and validations are rejected.

• description (str | None, optional) – Free-text description.

• project_id (str | None, optional) – Project the builder belongs to; defaults to the client’s project.

Returns:

The created builder.

Return type:

ModelBuilder

Raises:

ValueError – If no project_id is given and the client has no default.

Examples

>>> recipe = {"elements": {
...     "from cell spec": {
...         "element_type": "entry",
...         "mapping": {
...             "Positive electrode thickness [m]": "cathode.properties.thickness",
...         },
...     },
... }}
>>> builder = client.model_builder.create(model_id, "Default", recipe)

update(model_builder_id: str, *, name: str | None = None, description: str | None = None, config: TypeAliasForwardRef('ionworks.pipeline.Pipeline') | dict[str, Any] | None = None) → ModelBuilder

Update one of the organization’s own builders; unset fields are kept.

delete(model_builder_id: str) → None

Delete a builder. Parameterized models it produced are kept.

check(model_builder_id: str, cell_spec_id: str) → ReadinessReport

Report everything a cell specification lacks for this builder.

Parameters:

• model_builder_id (str) – The builder.

• cell_spec_id (str) – The cell specification to check.

Returns:

ready plus every issue, each naming the path in the cell specification and the model parameter it feeds.

Return type:

ReadinessReport

build(model_builder_id: str, cell_spec_id: str, *, save: bool = False, name: str | None = None, description: str | None = None, set_as_default: bool = False) → BuildResult

Build the model’s parameters for a cell specification.

Parameters:

• model_builder_id (str) – The builder.

• cell_spec_id (str) – The cell specification to build from.

• save (bool, optional) – Save the result as a parameterized model on the cell specification. Refused when any parameter is still missing. Defaults to False.

• name (str | None, optional) – Name for the saved parameterized model; required with save.

• description (str | None, optional) – Description for the saved parameterized model.

• set_as_default (bool, optional) – Make the saved model the cell specification’s default.

Returns:

The parameters, any the model still needs (missing), the readiness warnings, and the saved model’s ID when save is set.

Return type:

BuildResult

dry_run(model_id: str, config: TypeAliasForwardRef('ionworks.pipeline.Pipeline') | dict[str, Any], cell_spec_id: str) → dict[str, Any]

Run a builder config against a cell spec without saving anything.

Try a recipe before creating the builder. A spec that is not ready, or a calculation that fails, comes back in the result instead of raising.

Parameters:

• model_id (str) – The model the config produces parameters for.

• config (ionworks.pipeline.Pipeline or dict) – The builder config, as it would be passed to create().

• cell_spec_id (str) – The cell specification to run it on.

Returns:

{"report", "parameters", "missing", "error"}: the readiness report, the parameters produced (empty when not ready), the parameters the model still lacks, and why the calculations failed when they did.

Return type:

dict

Examples

>>> result = client.model_builder.dry_run(
...     model_id, pipeline, spec_id
... )
>>> result["report"]["ready"], result["missing"]
(True, [])

preview_mapping(cell_spec_id: str, mapping: dict[str, str]) → dict[str, dict[str, Any]]

Show what a mapping reads from a cell spec, before and after unit conversion.

Parameters:

• cell_spec_id (str) – The cell specification to read from.

• mapping (dict) – Parameter name -> dotted path in the cell spec, as in a recipe entry, e.g. {"Positive electrode thickness [m]": "cathode.properties.thickness"}.

Returns:

Parameter name -> {"found", "converted", "curve", "issue"}: the spec’s value with its own unit ("75.6 um"), the value in the parameter’s unit ("7.56e-05 m"), a sketch of a table, and why it failed when it did.

Return type:

dict

Examples

>>> client.model_builder.preview_mapping(spec_id, {
...     "Positive electrode thickness [m]": "cathode.properties.thickness",
... })
{'Positive electrode thickness [m]': {'found': '75.6 um', 'converted': '7.56e-05 m', 'curve': None, 'issue': None}}

calculations_producing(parameter: str) → list[dict[str, Any]]

Calculations, with options filled in, that produce parameter.

resolved_cell_spec(cell_spec_id: str) → dict[str, Any]

The cell spec as a recipe’s mapping paths read it.

Useful for writing a builder: every leaf here is addressable by its dotted path, e.g. cathode.properties.thickness or, for a material property dataset, cathode.material.datasets.scalar_parameters.maximum_concentration.

readiness(cell_spec_id: str, model_id: str | None = None) → list[BuilderReadiness]

Which builders (optionally for one model) a cell specification is ready for.