battinfo 0.8.0rc2

The semantic data layer for battery technology

Create, validate, and publish battery metadata as machine-readable Linked Data — typed against EMMO domain-battery and resolvable through persistent https://w3id.org/battinfo/ identifiers.

Quickstart · Documentation · How-to guides · Tutorials · Contributing · Cite

New words? The plain-language glossary decodes Linked Data, EMMO, IRI, and friends in two sentences each.

BattINFO provides a Python library, a CLI, and a canonical asset suite — JSON Schemas, ontology mappings, profiles, and examples — that make it straightforward to describe batteries as valid, machine-readable Linked Data.

Every record gets a persistent https://w3id.org/battinfo/ IRI. The JSON-LD that BattINFO writes for a record (battinfo.record_to_jsonld), for a workspace's saved cell specs, cells, test specs, tests and datasets (ws.export) and for a Zenodo deposit is valid RDF, typed against EMMO domain-battery and ready to query with SPARQL. What a record's IRI serves from the registry is not yet that model; the known limitations say what it serves instead.

Table of contents

• Why BattINFO
• Installation
• Quickstart
• Tutorials
• What BattINFO does
• Semantic foundation
• Project status
• Repository layout
• Core principles
• Contributing
• Citation
• License

Why BattINFO

Battery data is fragmented across spreadsheets, vendor datasheets, and ad-hoc JSON. BattINFO turns that into a single, semantically-grounded record model:

• Write plain JSON or Python — get validated, EMMO-aligned JSON-LD.
• Interoperable by construction — records share one ontology (EMMO) and one identifier scheme.
• Provenance built in — a CellSpec → Cell → Test → Dataset chain links every measurement back to the cell that produced it.

Installation

Supports Python 3.11–3.14. 0.8.0 will be the first working release of battinfo on PyPI. Until then, install it from GitHub into a virtual environment:

python -m venv .venv
source .venv/bin/activate            # Windows: .venv\Scripts\activate
pip install "battinfo @ git+https://github.com/BIG-MAP/BattINFO.git"

Optional extras: battinfo[processing] (cycler-file conversion via ws.convert() + plotting), battinfo[tabular] (CSV/Parquet/XLSX readers), battinfo[publish] (RO-Crate validation), battinfo[storage] (S3), battinfo[docs] (Sphinx), and battinfo[dev] (full test/lint/build toolchain). To convert raw cycler files, install the converter and the plotting libraries with:

pip install "battinfo[processing] @ git+https://github.com/BIG-MAP/BattINFO.git"

The processing extra requires batterydf[nda,excel,mat]>=0.2.0rc2,<0.3, so pip installs the batterydf 0.2.0 release candidate until 0.2.0 itself is published.

Working on BattINFO itself? See Contributing.

Quickstart

from battinfo import CellSpec, publish

result = publish(
    CellSpec(
        manufacturer="Panasonic",
        model="NCR18650B",
        format="cylindrical",
        chemistry="Li-ion",
        nominal_capacity={"value": 3.2, "unit": "Ah"},
    ),
    destination="local",
    root=".battinfo/my-library",
)
print(result.canonical_iri)
# https://w3id.org/battinfo/spec/xxxx-xxxx-xxxx-xxxx

That IRI is permanent, but not yet resolvable on the web — opening it in a browser returns 404 for a record published locally. A local publish mints the identity; it becomes dereferenceable once you publish the record to the registry (ws.publish(), see Tutorial 6).

destination="local" writes to a .battinfo/ directory (a dot-directory — ls -a to see it):

.battinfo/my-library/
├── index.json
└── examples/cell-spec/cell-spec-<id>.json   # the canonical record JSON

Or from the command line:

battinfo --help

For interactive, multi-record work — cells, tests, datasets, equipment — the authoring workspace is the blessed surface:

import battinfo
ws = battinfo.workspace(".")
ws.quickstart()   # prints a copy-pasteable end-to-end example

Lab work? Start at the how-to guides, where bench tasks such as registering materials, building a cell from components, labelling cells, converting cycler exports and publishing each map to a runnable recipe. The capability table shows which surface (workspace, battinfo.api, CLI) authors which record types today.

→ Read the full quickstart and the documentation index.

Tutorials

Six tutorial notebooks in docs/guides/ — one story, from the record model to a published dataset. Each runs from its own folder and writes only to a throwaway _scratch/ directory next to it. The example files they read ship inside the package, so a pip install is enough to run them (tutorial 6 also needs the processing extra).

What BattINFO does

• Validates battery metadata as plain JSON (JSON Schema / Pydantic) and as semantic RDF (JSON-LD + URDNA2015 normalisation).
• Maps JSON inputs into domain-battery-aligned JSON-LD using authoritative curated property and unit mappings.
• Provides profiles, examples, and mapping rules for all common battery record types.
• Supports a reusable cell-spec library, curated once as BattINFO descriptors and published as generated RDF/JSON-LD.
• Publishes dataset metadata with a core CellSpec → Cell → Test → Dataset provenance chain.

Semantic foundation

The JSON-LD that record_to_jsonld, ws.export and the Zenodo deposit graph write uses:

• hasProperty → [ClassName, ConventionalProperty] → hasNumericalPart → hasNumberValue (canonical EMMO quantity pattern) for cell specs, cells, tests, datasets, materials and components; some test-protocol and parameter-set values do not follow it yet (see the known limitations)
• hasMeasurementUnit → full EMMO or QUDT IRI (never a bare string)
• @type stacking: the cell that a cylindrical LFP cell spec describes is a BatteryCell, a CylindricalBattery, a LithiumIonBattery and a LithiumIonIronPhosphateBattery, taken from its format, chemistry and positive_electrode_basis. LithiumIonGraphiteBattery is added only when negative_electrode_basis is graphite.

Project status

Beta. The test suite (more than 5,000 tests at the 0.8.0 release) runs in CI on Python 3.11–3.14, on Linux and Windows. Ontology dependency versions are pinned and verified. See docs/scope.md for the full capability map and the known limitations of this release.

Supported

• Cell-descriptor validation and mapping, canonical record query/save/publish/index flows, JSON-LD-first publication, and validation policies.
• CLI and Python API covering cell-spec, cell-instance, test, dataset, and test-protocol records.

Preview (may still change)

• Reusable cell-spec library flows beyond the walkthrough fixtures.

In development (no stability promise)

• The folder-based batch path: battinfo push processes a folder of raw cycler files, packages it and uploads it to the Zenodo sandbox, and battinfo batch runs the same steps one at a time. To publish on zenodo.org, use ws.zenodo().
• battinfo dataset is experimental: its init, process and publish flow cannot complete in 0.8.0, so publish a dataset with ws.zenodo() instead.
• Registry administration (battinfo registry bootstrap).
• Large-scale reference validation.

Repository layout

Core principles

• Domain-battery is the normative ontology (semantics and terms). BattINFO is non-normative and operational (schemas, mappings, tooling).
• The JSON Schema is the save-time contract, and the pydantic models in bundle.py are the hand-written authoring surface. tests/test_schema_model_parity.py checks that every schema property can be reached from the models, apart from a listed set of known gaps, and AGENTS.md lists which files are generated and how.
• JSON-LD-first publication: record_to_jsonld, ws.export and the Zenodo deposit graph write valid RDF aligned to domain-battery.
• Stable, opaque identifiers: all published entities carry a https://w3id.org/battinfo/{type}/{uid} IRI, governed by IDENTIFIER_POLICY.md.
• BattINFO does not host or modify the domain-battery ontology.

Contributing

Contributions are welcome. Please open an issue to discuss substantial changes before submitting a pull request, and make sure the full quality gate passes:

uv sync --all-extras
uv run ruff check src tests
uv run mypy
uv run pytest -q tests

A shorter acceptance gate runs the acceptance tests, a smoke test of the installed package and a wheel build. It is part of the repository, not of the installed package, so run it from a checkout:

uv run python .tools/quality/run_verification.py

CI runs the same checks across Python 3.11–3.14 on Linux and Windows via the CI workflow, alongside Security (pip-audit + CodeQL) and Docs builds.

Citation

If you use BattINFO in your research, please cite it. The concept DOI 10.5281/zenodo.6304782 always resolves to the latest archived release; each release also gets its own version DOI on Zenodo.

@software{battinfo,
  title        = {BattINFO: The semantic data layer for battery technology},
  author       = {Clark, Simon and Friis, Jesper and L{\o}nstad Bleken, Francesca and Andersen, Casper Welzel and Flores, Eibar and Snijder, Hendrik and Stier, Simon and Battaglia, Corsin},
  year         = {2026},
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.6304782},
  url          = {https://github.com/BIG-MAP/BattINFO}
}

Maintainers: publishing a GitHub Release archives it on Zenodo as a new version under this concept DOI. Zenodo takes the metadata, including the author list, from CITATION.cff.

License

Distributed under the Apache License 2.0. See LICENSE. The package also includes EMMO-derived context files and labels under CC BY 4.0 and five BPX example parameter sets under MIT; NOTICE says which files they are.

Acknowledgements

Built on the EMMO ontology suite — in particular domain-battery and domain-electrochemistry — and informed by the Battery Pass data content guidance.