Metadata-Version: 2.4
Name: batmods-lite
Version: 0.0.2rc0
Summary: Packaged battery models and material properties.
Author: Corey R. Randall
Author-email: corey.r.randall@gmail.com
Maintainer: Corey R. Randall
Maintainer-email: corey.r.randall@gmail.com
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/NatLabRockies/batmods-lite
Project-URL: Documentation, https://batmods-lite.readthedocs.io/
Project-URL: Repository, https://github.com/NatLabRockies/batmods-lite
Project-URL: Issues, https://github.com/NatLabRockies/batmods-lite/issues
Keywords: battery,models,lithium,NMC,LFP,SPM,P2D
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: <3.15,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tqdm
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: pandas
Requires-Dist: openpyxl
Requires-Dist: matplotlib
Requires-Dist: ruamel.yaml
Requires-Dist: scikit-sundae>=1.1.3
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: myst-nb; extra == "docs"
Requires-Dist: sphinx-design; extra == "docs"
Requires-Dist: sphinx-autoapi; extra == "docs"
Requires-Dist: sphinx-copybutton; extra == "docs"
Requires-Dist: pydata-sphinx-theme; extra == "docs"
Provides-Extra: tests
Requires-Dist: pytest; extra == "tests"
Requires-Dist: pytest-cov; extra == "tests"
Requires-Dist: pytest-html; extra == "tests"
Requires-Dist: pytest-xdist; extra == "tests"
Provides-Extra: dev
Requires-Dist: nox; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: codespell; extra == "dev"
Requires-Dist: batmods-lite[docs,tests]; extra == "dev"
Dynamic: license-file

<!-- <img alt='Logo' style='width: 75%; min-width: 250px; max-width: 500px;' 
 src='https://github.com/NatLabRockies/batmods-lite/blob/main/images/dark.png?raw=true#gh-dark-mode-only'/>
<img alt='Logo' style='width: 75%; min-width: 250px; max-width: 500px;' 
 src='https://github.com/NatLabRockies/batmods-lite/blob/main/images/light.png?raw=true#gh-light-mode-only'/> -->

# BATMODS-lite

[![ci](https://github.com/NatLabRockies/batmods-lite/actions/workflows/ci.yml/badge.svg)](https://github.com/NatLabRockies/batmods-lite/actions/workflows/ci.yml) &nbsp;
[![codecov](https://codecov.io/gh/NatLabRockies/batmods-lite/graph/badge.svg?token=MPuSOeIurf)](https://codecov.io/gh/NatLabRockies/batmods-lite) &nbsp;
[![license](https://img.shields.io/badge/license-BSD--3-blue.svg)](https://github.com/NatLabRockies/batmods-lite/blob/main/LICENSE) &nbsp;

## Summary
Battery Analysis and Training Models for Optimization and Design Studies (BATMODS) is a Python package with an API for pre-built battery models. The original purpose of the package was to quickly generate synthetic data for machine learning models to train with. However, the models are generally useful for any battery simulations or analysis. `BATMODS-lite` includes the following: 

1) A library and API for pre-built battery models
2) Kinetic/transport properties for common battery materials

Note that the package focuses on phsics-based models like the single-particle (SPM) and pseudo-2D (P2D) model. If you enjoy the interface but are looking to run equivalent circuit models (ECMs), you should check out [thevenin](https://github.com/NatLabRockies/thevenin), which is distributed separately, but is developed and maintained by the same team. Consequently, the interface to `thevenin` models is intentionally similar, allowing for a smooth transition between physics-based and ECM approaches.

## Installation
`BATMODS-lite` is only available via GitHub. Please clone the repo or download the files. Also, make sure you have a Python installation with a version >=3.10. If you are new to Python, we recommend using [Anaconda](https://anaconda.com/download) to set up your installation. 

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)
```

The editable installation is useful if you plan to make changes to your local package. It ensures that any changes are immediately available each time the package is imported, without needing to reinstall. The developer options will likely be helpful if you are modifying the package.

If you run into issues with installation due to the [scikit-sundae](https://github.com/NatLabRockies/scikit-sundae) dependency, please submit an issue [here](https://github.com/NatLabRockies/scikit-sundae/issues). We also manage this solver package, but distribute it separately since it is not developed in pure Python.

## Get Started
The API is organized around three main classes that allow you to construct simulations, define experiments, and interact with solutions. Two basic examples are given below. These demonstrate a 2C discharge for both the single particle model (SPM) and pseudo-2D (P2D) model. Note that the experiment class interfaces with all simulations. The simulations and their respective solutions, however, will depend on the model subpackage they are loaded from. For a more detailed tutorial, please check `docs/source/examples`. If you installed the editable version with developer options, you can also build the documentation locally using `nox -s docs`.

```python
# Single particle model example
import bmlite as bm

sim = bm.SPM.Simulation()

expr = bm.Experiment()
expr.add_step('current_C', 2., (1350., 10.))

soln = sim.run(expr)
soln.simple_plot('time_s', 'voltage_V')
```

```python
# Pseudo-2D model example
import bmlite as bm

sim = bm.P2D.Simulation()

expr = bm.Experiment()
expr.add_step('current_C', 2., (1350., 10.))

soln = sim.run(expr)
soln.simple_plot('time_s', 'voltage_V')
```

**Notes:**
* If you are new to Python, check out [Spyder IDE](https://www.spyder-ide.org/). Spyder is a powerful interactive development environment (IDE) that can make programming in Python more approachable to new users.
* Another friendly option for getting started in Python is to use [Jupyter Notebooks](https://jupyter.org/). We write our examples in Jupyter Notebooks since they support both markdown blocks for explanations and executable code blocks.
* Python, Spyder, and Jupyter Notebooks can be setup using [Anaconda](https://www.anaconda.com/download/success). Anaconda provides a convenient way for new users to get started with Python due to its friendly graphical installer and environment manager.

## Citing this Work
This work was authored by researchers at the National Laboratory of the Rockies (NLR). If you use this package in your work, please include the following citation:

> Randall, Corey R. "BATMODS-lite: Packaged battery models and material properties [SWR-25-108]." Computer software, Jun. 2025. url: [github.com/NatLabRockies/batmods-lite](https://github.com/NatLabRockies/batmods-lite). doi: [10.11578/dc.20260114.1](https://doi.org./10.11578/dc.20260114.1).

For convenience, we also provide the following for your BibTex:

```
@misc{randall2025bmlite,
  author = {Randall, Corey R.},
  title = {{BATMODS-lite: Packaged battery models and material properties [SWR-25-108]}},
  url = {github.com/NatLabRockies/batmods-lite},
  month = {Jun.},
  year = {2025},
  doi = {10.11578/dc.20260114.1},
}
```

## Contributing
If you'd like to contribute to this package, please look through the existing [issues](https://github.com/NatLabRockies/batmods-lite/issues). If the bug you've caught or the feature you'd like to add isn't already being worked on, please submit a new issue before getting started. 

<!-- You should also read through the [developer guidelines](https://batmods-lite.readthedocs.io/latest/development). Need to get on readthedocs first... -->

## Disclaimer
This work was authored by the National Laboratory of the Rockies (NLR), operated by Alliance for Energy Innovation, LLC, for the U.S. Department of Energy (DOE). The views expressed in the repository do not necessarily represent the views of the DOE or the U.S. Government.
