Get Started#

BattINFO is the semantic data layer for battery technology. It gives you:

  • A Python library and CLI for authoring, validating, and publishing canonical battery metadata

  • JSON Schema validation for cell specs, cells, test specs, tests, and datasets

  • Automatic JSON → JSON-LD conversion aligned with the EMMO Battery Domain Ontology

  • A reusable cell-spec library backed by canonical records in battinfo-records

Working at the bench? The how-to guides map twelve lab tasks — register materials, build a cell from components, label cells, publish — to short runnable recipes, and the glossary decodes the vocabulary in plain language.

Installation#

BattINFO requires Python 3.11 or later.

Note

The package is not on PyPI yet — it publishes with the 0.8 release. Until then, install from source.

git clone https://github.com/BIG-MAP/BattINFO.git
cd BattINFO
pip install -e ".[dev]"

Once 0.8 is released, pip install battinfo will work, with optional extras that add features as you need them (each missing dependency raises an error naming the extra to install):

pip install battinfo                  # core
pip install "battinfo[processing]"    # cycler-file conversion (ws.convert) + plotting
pip install "battinfo[tabular]"       # CSV/Parquet/XLSX readers
pip install "battinfo[publish]"       # RO-Crate validation for publishing

If you have data: the workspace#

The workspace is the one object for the whole journey — convert raw cycler files, register the cells you tested, link tests and data, save validated records, publish. ws.quickstart() prints the full recipe in your terminal; the offline-safe core is:

import battinfo

ws = battinfo.workspace(".")

ws.convert()                                  # raw cycler files → tidy BDF tables

spec = battinfo.CellSpec(                     # or reuse the registry's identity:
    manufacturer="Molicel",                   #   spec = ws.search("molicel p45b")[0]
    model="INR21700-P45B",
    format="cylindrical",
    chemistry="Li-ion",
)
ws.add("cell", spec=spec, serial_numbers=["S1"])
ws.add("test", type="cycling", cell="S1", data="bdf/S1.bdf.csv")

ws.save()                                     # validated records, stable IRIs
# ws.login(api_key="...")                     # then: ws.publish() for the registry
#                                             # (zenodo=True mints a citable DOI)

Tutorial 6 — Publish your first dataset walks this exact flow against a sample Neware CSV.

If you are describing a product: record classes#

For a standalone cell-spec record — a datasheet as data — use the CellSpec record class and the publish shortcut:

from battinfo import CellSpec, publish

spec = CellSpec(
    manufacturer="Energizer",
    model="CR2032",
    format="coin",
    chemistry="Li-primary",
    properties={"nominal_capacity": {"value": 0.235, "unit": "Ah"}},
)

result = publish(spec, destination="local")
print(result.canonical_iri)

This validates the record, assigns it a stable BattINFO IRI, and writes the canonical JSON to a local .battinfo/ tree.

Note

The printed IRI is permanent, but not yet resolvable on the web — opening https://w3id.org/battinfo/spec/... in a browser returns 404 for a record published locally. It becomes resolvable once you publish the record to the registry (see Tutorial 6 — Publish your first dataset). A local publish mints the identity; the registry makes it dereferenceable.

What you just created. destination="local" writes to a .battinfo/ directory. It is a dot-directory, so a plain ls hides it — use ls -a:

.battinfo/publish/energizer-cr2032/          # one folder per record, named from the spec
├── index.json
└── examples/cell-spec/cell-spec-<id>.json   # the canonical record JSON

CLI quick reference#

BattINFO ships a command-line interface for validation and querying:

# Validate a cell-spec record
battinfo validate examples/cell-spec/A123__ANR26650M1-B.json --profile cell-spec

# Query the example cell specs packaged with BattINFO (for your own
# library, use the Python query_* functions with an explicit directory)
battinfo query cell-spec

# Save a cell record from a draft file
battinfo save cell-instance --input draft.json --source-root examples

See the CLI reference for every command.