Built with Vicena
Vicena is an integrated cloud lab for end-to-end R&D: search papers and patents, develop ideas, build computational models, design experiments, analyze results, and use scientific software and service providers through one workspace with pay-for-what-you-use access.

---

Battery Research Twin

An open-source lithium-ion battery digital twin and battery simulation framework built with PyBaMM and Vicena. It provides reproducible SPM, SPMe and DFN electrochemical models, thermal simulation, validation, parameter provenance, degradation and pack-extension interfaces, and a baseline for battery-management-system (BMS) research. Researchers can replace cells, parameters, experiments, estimators and physical submodels without rebuilding the entire workflow.

Download the one-page overview

What release 0.2 provides

• SPM, SPMe and DFN model hierarchy through a stable configuration interface.
• Isothermal, lumped and through-cell thermal model selection.
• Machine-readable experiment and validation configuration.
• A pinned Chen2020 NMC/graphite-SiOx reference configuration.
• Provenance and applicability metadata.
• IDAKLU integration with explicit solver tolerances.
• Standard CSV/JSON outputs with SHA-256 manifests.
• Scientific sanity checks and executable regression tests.
• A research notebook comparing model hierarchy, voltage, temperature, capacity and runtime.

Scientific status

This is a research framework, not a universally validated commercial cell model. The bundled reference configuration demonstrates reproducible execution and model-internal verification. Experimental validation for a specific manufactured cell requires independent measured data and an explicit train/validation split.

Quick start

python -m pip install -e .
battery-twin configs/experiments/chen2020_1C_discharge.yaml --output outputs/reference
pytest

Expected artifacts:

• timeseries.csv
• metadata.json
• validation.json
• manifest.json

Extension contract

1. Put cell identity and parameter provenance in cells/<cell-id>/.
2. Prefer BPX for portable physics-based parameter files.
3. Put protocols in configs/experiments/, not inside notebooks.
4. Add new physics behind the package API.
5. Add unit, conservation, regression and validation tests.
6. State the applicability envelope and unsupported regimes.
7. Never use fit data as the only validation evidence.

See docs/ARCHITECTURE.md, docs/VALIDATION.md and CONTRIBUTING.md.

Remote compute

Remote CFD or other managed workflows are optional extensions. They are appropriate for detailed pack cooling or other expensive validated workflows, not for replacing reproducible local cell-model tests. Rowan molecular workflows are not scientifically relevant to the continuum battery cell twin in this release and are therefore not invoked.

Frequently asked questions

What is a lithium-ion battery digital twin?

A lithium-ion battery digital twin is a computational representation of a battery cell or pack that connects operating conditions and physical parameters to predicted voltage, temperature, internal electrochemical states, degradation indicators, and system behavior. This repository provides a reproducible research baseline rather than claiming universal validity for every manufactured cell.

How is this different from using PyBaMM directly?

PyBaMM supplies the core battery-model equations and solvers. Battery Research Twin adds a reusable project structure around them: machine-readable experiments, provenance records, validation limits, standardized artifacts, regression tests, agent instructions, presentation material, and routing for optional Vicena Compute or Rowan workflows.

Which battery models are included?

The baseline exposes the Single Particle Model (SPM), Single Particle Model with electrolyte dynamics (SPMe), and Doyle–Fuller–Newman (DFN) model through one configuration interface, with isothermal, lumped, and through-cell thermal options.

Can it be used for battery degradation, packs, and BMS research?

Yes, as an extensible starting point. Researchers can add PyBaMM degradation submodels, parameter-estimation workflows, uncertainty analysis, multi-cell electrical and thermal coupling, state estimation, charging control, and BMS algorithms. Each extension should include provenance, tests, an applicability envelope, and held-out validation evidence.

What is Vicena's role?

Vicena is the scientific research workspace used to build and operate this baseline. A researcher can give Vicena the repository URL, ask it to verify the project, upload experimental data, and extend the twin. Vicena works locally for normal cell simulations and routes to protected remote scientific compute only when an appropriate workflow and budget are established.

License

The repository-owned code and documentation use the 0BSD license, permitting use, copying, modification, distribution and commercial use with no attribution condition. Dependencies, parameter sets and external datasets retain their own licenses; the repository does not relicense third-party material.

Using this repository with Vicena

Give Vicena the public GitHub repository URL and ask it to use the Battery Research Twin. The root AGENTS.md routes Vicena to .agents/skills/battery-research-twin/SKILL.md, which provides the setup, validation and local/remote execution contract.

Vicena should first verify the baseline locally. It invokes Vicena Compute only after the relevant CFD, circuit or optics skill selects an appropriate workflow, and Rowan only for a scientifically suitable molecular/material workflow after checking availability and budget.