Battery Feature Inference Toolbox (BatFIT)

Summary

This package implements several data-based techniques for parameter fitting in Li-ion battery models. It uses BATMODS-lite to generate the data.

Installation

We recommend using a conda environment

conda create -n batfit python=3.14
conda activate batfit

Once the files are available on your machine, use your terminal to navigate into the folder and execute one of the following depending on your installation preference.

pip install .             (basic installation)
pip install -e .[dev]     (editable installation with developer options)

Tutorial

The regression tests (run as part of the CI) show how to use the basic capabilities of the code.

1. Data generation with BATMODS-lite (scripts/reg_tests/1.gen_data). This demonstrates how to generate data from a single particle model in parallel. This has been tested with up to 3328 workers but uses 4 workers here. A single run_spm.sh also assembles the data and writes the train/test/validation split reused by every later step. Once BatFIT is installed

bash run_spm.sh

2. Train a surrogate of the physics-based model (scripts/reg_tests/2.surrogate). This demonstrates how to preprocess the data and train a surrogate model of the single particle model that can be used for simulation-based inference.

bash run_spm.sh

3. Run MCMC to identify parameters with the trained surrogate (scripts/reg_tests/3.surrogate_mcmc). This demonstrates how to run MCMC with a data-based surrogate instead of a physics-based model.

bash run_spm.sh

4. Use Gaussian Neural Posterior Estimation to approximate the parameter posterior PDF (scripts/reg_tests/4.npe_gaussian).

bash run_spm.sh

5. Use flow-matching Neural Posterior Estimation to approximate the parameter posterior PDF (scripts/reg_tests/5.npe_fm).

bash run_spm.sh

Citing this Work

This software is registered as SWR-26-034 (doi:10.11578/dc.20260401.2).

If you use BatFIT, please cite the accompanying paper, "Neural posterior estimation for scalable and accurate inverse parameter inference in Li-ion batteries" (journal | arXiv):

@article{hassanaly2026npe,
  title   = {Neural posterior estimation for scalable and accurate inverse parameter inference in Li-ion batteries},
  author  = {Hassanaly, Malik and Randall, Corey R. and Weddle, Peter J. and Gasper, Paul J. and Kelly, Conlain and Tanim, Tanvir R. and Smith, Kandler},
  journal = {Journal of Energy Storage},
  year    = {2026},
  pages   = {123823},
  doi     = {10.1016/j.est.2026.123823},
}

Acknowledgements

This work was authored by the National Laboratory of the Rockies (NLR) for the U.S. Department of Energy (DOE) under Contract No. DE-AC36-08GO28308. This work was supported by funding from DOE's Transportation Technologies Office (TTO). The research was performed using computational resources sponsored by the Department of Energy's Office of Critical Minerals and Energy Innovation (CMEI) and located at the National Laboratory of the Rockies. The views expressed in the repository do not necessarily represent the views of the DOE or the U.S. Government.