Ionworks Schema

This is a read-only mirror. The source of truth is a private repo.

Pydantic schemas for building Ionworks pipeline configurations.

Overview

Ionworks Schema (ionworks_schema) provides the schema for constructing Ionworks pipeline configurations. Use these classes to define pipelines (data fits, calculations, entries, validations) in Python with validation, then export JSON to submit via the Ionworks API. Pipeline concepts, objectives, and workflows are described in the Ionworks documentation.

Pipelines are executed by submitting configurations to the Ionworks API. Use the ionworks-api Python client to create and run jobs: pip install ionworks-api.

Installation

pip install ionworks-schema

Quick start

Build a pipeline configuration with schema classes, export to JSON, and submit with the Ionworks API client:

import ionworks_schema as iws
import json

# Define a parameter to fit (name, initial_value, bounds)
parameter = iws.Parameter(
    name="Positive electrode capacity [A.h]",
    initial_value=1.0,
    bounds=(0.5, 2.0),
)

# Objective: MSMR half-cell fit; data can be "db:<measurement_id>" for uploaded data (use objectives submodule)
objective = iws.objectives.MSMRHalfCell(
    data_input="db:your-measurement-id",
    options={"model": {"electrode": "positive"}},
)

data_fit = iws.DataFit(
    objectives={"ocp": objective},
    parameters={"Positive electrode capacity [A.h]": parameter},
)

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

# Export to JSON for API submission.
# `to_config()` is the only supported serializer — do NOT use Pydantic's
# `model_dump()`, which is not a wire format (it drops the `type` discriminator
# and emits Python attribute names, not the wire names the API expects).
config = pipeline.to_config()
with open("pipeline_config.json", "w") as f:
    json.dump(config, f, indent=2)

# Submit via ionworks-api (requires credentials and project ID — see ionworks-api README)
# from ionworks import Ionworks
# client = Ionworks()
# job = client.pipeline.create(config)
# client.pipeline.wait_for_completion(job.id, timeout=600)

Schema classes and pipeline elements

Schema classes mirror the pipeline configuration format consumed by the Ionworks pipeline and API. Runtime behavior and options are documented in the Ionworks documentation.

A pipeline is a top-level Pipeline with a dictionary of named elements. Each element has an element_type: entry, data_fit, calculation, or validation.

Role	Schema class	Description
Top-level	`Pipeline`	Pipeline configuration with named `elements`.
Entry	`DirectEntry`	Supply fixed parameter values (no fitting or calculation).
Data fit	`DataFit`, `ArrayDataFit`	Fit model parameters to data; contain `objectives` and `parameters`.
Calculation	`ionworks_schema.calculations`	Run calculations (e.g. OCP, diffusivity, geometry). See submodule for available classes.
Objectives	`MSMRHalfCell`, `MSMRFullCell`, `CurrentDriven`, `CycleAgeing`, `CalendarAgeing`, `EIS`, `Pulse`, `Resistance`, `ElectrodeBalancing`, `OCPHalfCell`, and others	Used inside `DataFit.objectives` to define what to fit. Import from `ionworks_schema.objectives` (e.g. `iws.objectives.MSMRHalfCell`).
Parameters	`Parameter`	`name`, `initial_value`, `bounds` (and optional prior, etc.). Used in `DataFit.parameters`; dict key is the parameter name.
Priors	`Prior`	Used in `DataFit.priors`. Import from `ionworks_schema.priors` (e.g. `iws.priors.Prior`).
Library	`Material`, `Library`	Built-in material library for initial parameter values.

Material library

Access built-in materials with validated parameter values for use as initial values or entries:

import ionworks_schema as iws

# List available materials
materials = iws.Library.list_materials()

# Get a specific material (e.g. NMC - Verbrugge 2017)
material = iws.Material.from_library("NMC - Verbrugge 2017")
print(material.parameter_values)

Parameter names and interpretation are described in the Ionworks documentation.

Resources

Ionworks documentation — workflows, objectives, data fits, and pipeline concepts.
ionworks-api — submit and manage pipelines (pip install ionworks-api).
Ionworks documentation — product and platform documentation.
Changelog — release notes for this package. See the full Ionworks changelog for the platform-wide view.

Note

This package provides configuration schemas only. To run pipelines, export JSON with pipeline.to_config() and submit it via the Ionworks API using the ionworks-api client.

to_config() is the only supported serializer. Pydantic's model_dump() is not a wire format: it omits the type discriminator and emits Python attribute names rather than the wire names the API expects (data_input rather than data), so it produces a different dict than to_config() — one the API may reject. Always build API payloads with to_config().

Metadata

Release files for ionworks-schema 0.31.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ionworks-schema 0.31.0
File	Size	Uploaded
ionworks_schema-0.31.0.tar.gz	874.0 kB	Oct 1, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for ionworks-schema 0.31.0
File	Interpreter	ABI	Platform	Reset
ionworks_schema-0.31.0-py3-none-any.whl 135.6 kB Oct 1, 2026	Python 3	none	any	Details

Total release size: 1.0 MB

Release files / ionworks_schema-0.31.0.tar.gz

Download URL	ionworks_schema-0.31.0.tar.gz
Size	874.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`8ca6a6b4c2723fbd623be9e115a61c323955250ee7b85d08867cd34a093485a4`
BLAKE2b-256 checksum How to use checksums	`27fe4bcf9a5d51aeca862cc93788621ab4ebadecbed3c4a082b5324bacb2e948`
Upload date	Oct 1, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Release files / ionworks_schema-0.31.0-py3-none-any.whl

Download URL	ionworks_schema-0.31.0-py3-none-any.whl
Size	135.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`afdd234db5348f31c60c2a2d28193db80615320dc69ced44dcbe0d42e709436d`
BLAKE2b-256 checksum How to use checksums	`a50070bbf6be27fa197665ab9d8d5967b126a0527f805ec3cfd04c6da326d41c`
Upload date	Oct 1, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`