Focused child case · MATLAB/Python · verified 28 July 2026
Battery thermal response from energy balance to tested code.
A transparent first-order model for early temperature-response sensitivity checks, with the equation, assumptions, source files, tests, research context, and limits available for inspection.
TL;DR
Model questions and limits.
- Problem: estimate first-order cell-temperature response before a higher-fidelity thermal model is justified.
- Method: solve a lumped energy balance with an analytical state update for piecewise-constant current.
- Inputs and output: current, resistance, thermal capacitance, ambient temperature, cooling conductance, and time step produce a temperature trace.
- Verification: open Python unit tests and a MATLAB equivalent make the implementation inspectable.
- Boundary: this is a sensitivity model, not a production-qualified battery, BMS, BESS, or safety model.
Method
Make heat generation and rejection explicit.
Joule heating raises the modeled cell temperature; effective cooling conductance rejects heat toward ambient. The reduced-order implementation is useful for sensitivity analysis and for challenging assumptions before CFD, FEA, electrochemical, or pack-level work begins.
Illustrative · retained generated output
Default resistance and thermal capacitance, 25 °C ambient, and an 80 A current show sensitivity to three effective cooling assumptions. Download the source CSV, retained SVG, or retained PNG.
Open full-size figure
Evidence chain
From research question to reproducible reference.
Research basis
Published multiphysics thermal modeling of a pouch lithium-ion cell for pack-level thermal-management development.
Verify the IEEE DOIExecutable source
Dependency-free Python and MATLAB implementations expose parameters, units, and the state update.
Open the pinned repository treeAutomated checks
Three thermal unit tests verify bounded monotonic heating, cooling-case ordering, and zero-current convergence. The repository has six tests across both model families.
Inspect the testsEngineering boundary
Thermal runaway, electrochemical aging, spatial gradients, tolerances, cooling geometry, and safety certification remain outside this model.
Review the wider research contextReproduction instructions
Distinct procedures for running the model and rebuilding the site figure.
1. Run the model (battery-power-models repository)
Clone the pinned model repository to execute the thermal simulation and unit tests (3 thermal tests):
git clone https://github.com/mohammadrezwankhan/battery-power-models.git
cd battery-power-models
git checkout 7d9f61f1ebdca73f9facce5129f79805b1747ed0
python src/battery_thermal.py --current 80 --duration 900 --output thermal_trace.csv
python -m unittest discover -s tests -vPrerequisites: Python 3.10+ (standard library only). MATLAB script matlab/battery_thermal_lumped.m is provided for MATLAB users.
2. Rebuilding the website figure is unavailable to public readers
The upstream battery model remains runnable from its separate public repository, and the retained SVG, PNG, and CSV are downloadable. Rebuilding this website figure depends on generate-open-engineering-figures.py in the private portfolio repository; that generator has no established public license and is unavailable anonymously.
The retained figure is an illustrative generated result, not a promise that the public reader can regenerate the website asset. This limitation does not prevent running the pinned upstream Python model.
3. Inspect retained results
Inspect or download the retained dataset directly: Download thermal-response.csv.
Direct questions
What an engineering reviewer should ask.
What problem does the battery thermal response model solve?
It estimates first-order cell-temperature response for a stated current profile, resistance, thermal capacitance, ambient temperature, and effective cooling conductance. It is intended for early sensitivity checks and assumption review.
How is the battery thermal model verified?
The public repository uses an analytical state update for piecewise-constant current, dependency-free Python unit tests, and a MATLAB equivalent. The page links directly to both source files and the test suite.
When should a higher-fidelity battery model be used?
Use CFD, FEA, electrochemical, or pack-level models when spatial gradients, cell geometry, cooling-channel design, material properties, aging, or safety qualification affect the decision.
Does this model qualify a battery or BESS design?
No. It is a transparent reference model, not a production-qualified battery, BMS, BESS, thermal-runaway, or safety-certification model. Project-specific inputs and test evidence remain necessary.
Related authority paths