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

Note

The processing extra depends on the BDF converter (batterydf), which is not yet published to PyPI, so the extra cannot resolve there today. Until it lands, install the converter from source instead:

pip install "batterydf[nda,excel,mat] @ git+https://github.com/battery-data-alliance/battery-data-format.git@07dd7a6923ae12fba0ea1079c5034883c14ebbf5" matplotlib plotly

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 (here one of the repository examples;
# point it at any record you created or downloaded)
battinfo validate examples/cell-spec/A123__ANR26650M1-B.json --profile cell-spec

# Query the example cell specs packaged with BattINFO — the flag searches
# the bundled corpus, so this works outside a repository checkout (for
# your own library, use the Python query_* functions with an explicit
# directory)
battinfo query cell-spec --include-packaged-examples

# Save a cell record from a draft file (--source-root is where your
# linked records live)
battinfo save cell-instance --input draft.json --source-root records

See the CLI reference for every command.