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
Metadata
1 maintainer
Release files for ionworks-schema 0.32.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| ionworks_schema-0.32.1.tar.gz | 876.8 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| ionworks_schema-0.32.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.0 MB
Release files / ionworks_schema-0.32.1.tar.gz
| Download URL | ionworks_schema-0.32.1.tar.gz |
|---|---|
| Size | 876.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9dec8158a1c0931e490c1d1ff2a9765c7d926080d1785e78dcde787c358f2594
|
|
BLAKE2b-256 checksum How to use checksums |
88c9198312da66f692260f1787035b3356bd1f34d80505048344b63231b8e0a4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / ionworks_schema-0.32.1-py3-none-any.whl
| Download URL | ionworks_schema-0.32.1-py3-none-any.whl |
|---|---|
| Size | 137.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8d20efdcb3efbd88e7b763b9948fe33f13375724bf2e2404d433d7291fa3a093
|
|
BLAKE2b-256 checksum How to use checksums |
44c176a710d2fd4e9af1e9ddd740bdcfebffe5b47ae8f7cea568fb3b2dd22be9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Security for ionworks-schema 0.32.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
