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().
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file ionworks_schema-0.24.0.tar.gz.
File metadata
- Download URL: ionworks_schema-0.24.0.tar.gz
- Upload date:
- Size: 678.7 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
96b0ac3b5aee01daadc4d1114fc7c745161b2a946d862935b7a53926d0795e53
|
|
| MD5 |
708856d700682a23701c038bdc71b4ca
|
|
| BLAKE2b-256 |
eab7ddf9d9a17b662b37e253c1e09bfb871c78382748bd1892b987884c908e2a
|
File details
Details for the file ionworks_schema-0.24.0-py3-none-any.whl.
File metadata
- Download URL: ionworks_schema-0.24.0-py3-none-any.whl
- Upload date:
- Size: 122.4 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
08eff4578de11b26c35d231dd497379734defb505cdc6bc0ee7c474600debd92
|
|
| MD5 |
8f0f8d29e709b4f005055222760592a1
|
|
| BLAKE2b-256 |
da2cd4249810da8eef8dd95507f1a9694eb6b9ef23c88e4a2bbd86adc91e2536
|
