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 Pipeline documentation and 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 Pipeline user guide and in the ionworkspipeline package (e.g. parsers, data_fits, objectives).

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 Pipeline documentation.

Resources

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().

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.24.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for ionworks from gravatar.com ionworks

Credits

Author: Ionworks

Requires

Python >=3.11

Provides Extra

all dev docs

Tags

battery ionworks pipeline pydantic schema

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ionworks_schema-0.18.0.tar.gz (644.4 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

ionworks_schema-0.18.0-py3-none-any.whl (103.8 kB view details)

Uploaded Python 3

File details

Details for the file ionworks_schema-0.18.0.tar.gz.

File metadata

  • Download URL: ionworks_schema-0.18.0.tar.gz
  • Upload date:
  • Size: 644.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for ionworks_schema-0.18.0.tar.gz
Algorithm Hash digest
SHA256 2d42f6f40f6602d0d075ac5f7ee933616e6b33c6eb9379ca8f02fcfca4515c0f
MD5 f8c64ab95ba1371b9cbd01f5832b0175
BLAKE2b-256 c97c69ad6bf266076e194b9618a35cf77736d640787b1b390cb44a23dd0b05c3

See more details on using hashes here.

File details

Details for the file ionworks_schema-0.18.0-py3-none-any.whl.

File metadata

File hashes

Hashes for ionworks_schema-0.18.0-py3-none-any.whl
Algorithm Hash digest
SHA256 f89d78bd368bca533b94ec6e19556c927f43633be6eeb7bb1e86c1311f7d69cc
MD5 0d21a1b49f8dcf5c179e215321cb47cb
BLAKE2b-256 bb3d2a5f7c9254a8e6cd532773ec7ec925c63ada235375a3738ed1de2f961f84

See more details on using hashes here.

Release history Release notifications | RSS feed

0.24.0

2 files

0.23.0

2 files

0.22.0

2 files

0.21.0

2 files

0.20.0

2 files

0.19.0

2 files

0.18.1

2 files

This release

0.18.0 This release

2 files

0.17.2

2 files

0.17.1

2 files

0.17.0

2 files

0.16.0

2 files

0.15.5

2 files

0.15.4

2 files

0.15.3

2 files

0.15.2

2 files

0.15.1

2 files

0.15.0

2 files

0.14.0

2 files

0.13.1

2 files

0.13.0

2 files

0.12.0

2 files

0.11.0

2 files

0.10.0

2 files

0.9.0

2 files

0.8.2

2 files

0.8.1

2 files

0.8.0

2 files

0.7.0

2 files

0.6.0

2 files

0.5.0

2 files

0.4.0

2 files

0.3.3

2 files

0.3.2

2 files

0.3.1

2 files

0.2.1

2 files

0.2.0

2 files

0.1.6

2 files

0.1.4

2 files

0.1.3

2 files

0.1.2

2 files

0.1.1

2 files

0.1.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page