Datasetpublic

bsebench-org/severson-2019

severson-2019 Tier 2 BSEBench-canonical Parquet harmonization of the Severson et al. 2019 commercial LFP fastcharge cycling dataset, derived from the Tier 1 raw mirror of the three original .mat files. This is the version most users want : column names normalized to the BSEBench TimeSeriesSchema, current sign convention aligned to BPX-1.1, cycles 1-indexed, exclusion mask from the published cohort applied, partitioned by cell_id for parallel reading, and loadable in one line… See the full description on the dataset page: https://huggingface.co/datasets/bsebench-org/severson-2019.

sourceHugging Facecc-by-4.0updated 5mo agoView on Hugging Face

1likes737downloads

Dataset Card

severson-2019

Tier 2 BSEBench-canonical Parquet harmonization of the Severson et al. 2019 commercial LFP fastcharge cycling dataset, derived from the Tier 1 raw mirror of the three original .mat files.

This is the version most users want : column names normalized to the BSEBench TimeSeriesSchema, current sign convention aligned to BPX-1.1, cycles 1-indexed, exclusion mask from the published cohort applied, partitioned by cell_id for parallel reading, and loadable in one line through the bsebench-datasets Python package.

Status

This is a placeholder card. The harmonized Parquet files are not yet uploaded. Three preconditions must be satisfied before publication :

1.The Tier 1 raw mirror must be uploaded at `bsebench-org/severson-2019-raw` with SHA-256 digests committed to bsebench-datasets/manifests/severson_2019_lfp.yaml.
2.The bsebench-specs package must reach v0.2.0 and publish the canonical TimeSeriesSchema Pydantic v2 model (currently v0.1.0 only ships DatasetManifest).
3.The harmonization adapter at `bsebench-datasets/src/bsebench_datasets/adapters/severson_2019.py` must be implemented (currently a documented stub raising NotImplementedError) and tested against the Tier 1 mirror with a round-trip schema check.

Until step 3 is reached, this card describes the target schema that the upload will conform to, not a published artifact. Schema details should be considered authoritative ; SHA-256 digests, exact byte sizes, and Parquet partition counts will be filled in after upload.

What this will be

The Severson 2019 dataset converted to the BSEBench canonical TimeSeriesSchema, persisted as Parquet with Zstandard compression and partitioned by cell_id for parallel reads :

Column	Pandas / Arrow type	Description
`cell_id`	`string`	Stable cell identifier within the dataset (e.g., `b1c0`, `b1c1`, ..., `b3c45`). The Severson cohort uses `b<batch>c<channel>` IDs, where `<batch>` is `1`/`2`/`3` and `<channel>` is the within-batch zero-indexed channel number from the original `.mat` `channel_id` field.
`time_s`	`float64`	Seconds elapsed since the first sample of the cycling experiment for that cell (`t = 0` at the first sample).
`voltage_V`	`float64`	Terminal voltage, always positive. Range typically 2.0–3.6 V (the cycling cutoffs).
`current_A`	`float64`	Cell current under the BPX-1.1 sign convention : positive on charge, negative on discharge.
`temperature_C`	`float64`	Cell-can surface temperature, in degrees Celsius.
`cycle_number`	`int32`	1-indexed cycle counter. The original Severson `summary.cycle` field is 0-indexed ; the adapter applies a `+1` offset to align with the BSEBench convention used across all benchmark datasets.
`step_id`	`string`	Within-cycle step identifier. For Severson 2019, derived from the protocol metadata as `charge`, `rest_after_charge`, `discharge`, or `rest_after_discharge`.
`capacity_Ah`	`float64`	Running cumulative capacity (Coulomb counting from Severson's per-cycle `Qc` and `Qd` fields). Optional in the BSEBench schema but populated for this dataset since it is directly derivable.

Two further BSEBench schema columns (soc_truth, soh_truth) are not provided for this dataset because Severson 2019 does not publish a reference SOC trajectory and supplies only per-cycle discharge-capacity summaries (summary.QDischarge, summary.QCharge) rather than a continuous SOH ground truth. Filter benchmarks that require ground-truth SOC must compute it from capacity_Ah themselves or treat Severson 2019 as an SOC-blind benchmark.

Estimated total size : ~50 GB uncompressed, ~8 GB after Zstandard compression — comparable to the ~7.6 GB total of the three raw .mat files. Final sizes will be locked at upload.

Mapping from original

The Severson .mat v7.3 files store data as a single top-level batch struct with one entry per cell. The BSEBench harmonization performs the following mapping :

BSEBench column	Severson source field	Conversion
`cell_id`	(synthesized)	`f"b{batch_idx}c{channel_idx}"` where `batch_idx ∈ {1,2,3}` matches the file date and `channel_idx` is the zero-indexed position in `batch.channel_id`.
`time_s`	`batch.cycles[i].t`	Per-cycle local time arrays are concatenated end-to-end with cumulative offset to produce a monotonically increasing global time axis. Severson stores `t` in seconds.
`voltage_V`	`batch.cycles[i].V`	Direct copy.
`current_A`	`batch.cycles[i].I`	Sign convention preserved as published (charge-positive). The Severson convention is consistent with BPX-1.1, so no sign flip is applied. See Sign convention notes below.
`temperature_C`	`batch.cycles[i].T`	Direct copy. Severson logs cell-can surface temperature in °C.
`cycle_number`	`batch.summary.cycle` (per cycle)	`+1` offset applied (Severson is 0-indexed, BSEBench is 1-indexed).
`step_id`	`batch.policy_readable` + step heuristics	Within a cycle, the policy plus current-sign transitions identify charge / rest / discharge / rest segments.
`capacity_Ah`	`batch.cycles[i].Qc`, `batch.cycles[i].Qd`	Cumulative capacity reconstructed from per-cycle charge / discharge throughput.

Cells excluded from the published 124-cell cohort by Severson and collaborators are also excluded by this Tier 2 harmonization, matching the upstream Braatz Group Load Data.ipynb exclusion mask :

—Batch 1 : b1c8, b1c10, b1c12, b1c13, b1c22 (did not reach 80 % capacity threshold).
—Batch 2 : b2c7, b2c8, b2c9, b2c15, b2c16 (re-assigned to batch 1, continued from earlier run ; remapped to their batch-1 IDs).
—Batch 3 : b3c2, b3c23, b3c32, b3c37, b3c42, b3c43 (noisy channels excluded by Severson).

Total : 140 raw channels across 3 files → 124 published cells, exactly matching the cohort cited in the Severson 2019 paper.

Sign convention notes

The BSEBench canonical sign convention follows BPX 1.1 : charge = positive current, discharge = negative current. Severson's published .mat files appear to use the same convention based on the pattern seen in the upstream Braatz Group BuildPkl notebooks, where charge capacity (Qc) and discharge capacity (Qd) are plotted as separate strictly-positive quantities aggregated from I. The harmonization adapter therefore applies no sign flip to current_A.

The exact sign of the 'I' field in the raw .mat data has not been confirmed by direct inspection of the binary at the time this card was drafted. The adapter implementation (see severson_2019.py docstring) includes a runtime sanity check that verifies, on the first cycle of the first cell loaded, that the integral of I·dt over the charge phase produces a positive cumulative capacity_Ah matching Qc. If this check fails, the upload is aborted and the convention is re-evaluated.

Why "canonical" tier

Tier 2 is the version users should consume for filter benchmarking. It :

—Maps Severson's idiosyncratic struct schema to the standardized BSEBench TimeSeriesSchema shared with all other BSEBench datasets (NASA Randomized Walk 2014, Sandia 2020, Oxford 2017, Empa Aurora 2025, ...) so that filter pipelines work cross-dataset without per-dataset glue code.
—Harmonizes the sign convention to BPX 1.1 (no-op for Severson since it already matches).
—Applies the published exclusion mask, so users do not have to re-implement the cell-quality filters from the upstream notebooks.
—Strips analysis-only metadata (Qdlin, Tdlin, discharge_dQdV, Vdlin interpolation grids) that are not needed for state estimation.
—Ships as Parquet with column-statistics indexing, partitioned by cell_id so that filter benchmarks can read individual cells in ~milliseconds instead of loading the full 8 GB.
—Loads in one line via the bsebench-datasets Python package's load_bsebench() helper.

For provenance, audits, or independent harmonizations, see the Tier 1 raw mirror.

Anchor standards

—Sign convention : BPX 1.1 (charge = positive, discharge = negative).
—Time-series schema : aligned with the LF Energy Battery Data Format (BDF), released December 2025, where applicable.
—Manifest schema : bsebench-dataset-manifest/v1 (Pydantic v2, defined in bsebench-specs).

License

Creative Commons Attribution 4.0 International (CC-BY-4.0) — inherited from the original Severson 2019 dataset on the TRI Energy & Materials Datasets platform (whose earlier (pre-2025) datasets are distributed under CC-BY-4.0). The BSEBench-canonical Parquet harmonization is a derivative work of the original .mat files and is offered under the same CC-BY-4.0 license, with BSEBench attribution added on top of the Severson 2019 attribution.

Verbatim core grant of the underlying license, from the CC-BY-4.0 legal code :

"Subject to the terms and conditions of this Public License, the Licensor hereby grants You a worldwide, royalty-free, non-sublicensable, non-exclusive, irrevocable license to exercise the Licensed Rights in the Licensed Material to: (1) reproduce and Share the Licensed Material, in whole or in part; and (2) produce, reproduce, and Share Adapted Material."

How to use (target API)

python

# Once shipped (M2.1 milestone)
from bsebench_datasets import load_bsebench

ds = load_bsebench("severson-2019", revision="v1.0")
print(ds.chemistry)                # "LFP"
print(ds.n_cells)                  # 124
print(ds.first_cell_data().head()) # canonical Parquet columns

Equivalent pure-pandas / Arrow access for users who do not want the bsebench-datasets package :

python

import pandas as pd
from huggingface_hub import snapshot_download

local_dir = snapshot_download(
    "bsebench-org/severson-2019",
    repo_type="dataset",
)

# Load one cell's full timeseries
df = pd.read_parquet(f"{local_dir}/cell_id=b1c0")
print(df.dtypes)
# cell_id           string[python]
# time_s                    float64
# voltage_V                 float64
# current_A                 float64    (BPX-1.1 sign)
# temperature_C             float64
# cycle_number                int32
# step_id           string[python]
# capacity_Ah               float64

Citation

bibtex

@article{severson2019datadriven,
  author  = {Severson, Kristen A. and Attia, Peter M. and Jin, Norman
             and Perkins, Nicholas and Jiang, Benben and Yang, Zi
             and Chen, Michael H. and Aykol, Muratahan
             and Herring, Patrick K. and Fraggedakis, Dimitrios
             and Bazant, Martin Z. and Harris, Stephen J.
             and Chueh, William C. and Braatz, Richard D.},
  title   = {Data-driven prediction of battery cycle life before
             capacity degradation},
  journal = {Nature Energy},
  volume  = {4},
  number  = {5},
  pages   = {383--391},
  year    = {2019},
  doi     = {10.1038/s41560-019-0356-8},
  url     = {https://www.nature.com/articles/s41560-019-0356-8},
}

@misc{bsebench2026,
  author = {Akir, Oussama and {BSEBench Contributors}},
  title  = {{BSEBench}: an open-source benchmark for battery
            state-estimation filters},
  year   = {2026},
  url    = {https://bsebench.org},
}

Provenance

This Tier 2 harmonization is derived from `bsebench-org/severson-2019-raw` via `bsebench-datasets/src/bsebench_datasets/adapters/severson_2019.py`.

Once published, the manifest YAML `bsebench-datasets/manifests/severson_2019_lfp.yaml` will record :

—the Tier 1 commit SHA whose .mat files were the input to harmonization
—the adapter file commit SHA at the time of the Parquet build
—the per-Parquet-partition sha256 and size_bytes
—the Pydantic-validated bsebench-dataset-manifest/v1 block

These provenance pointers are not yet populated because the upload has not yet occurred. The card will be updated with concrete SHAs at publication time.