Small, inspectable reference models for early battery-thermal and DC-link design checks. The repository favors explicit equations, stated assumptions, and tests over opaque tooling.
- Models explains the equations and engineering questions.
- Quick start runs the Python and test paths from a clean clone.
- Engineering boundary defines what the references do not certify.
- Repository layout points to the Python, MATLAB, and test implementations.
- Contributing and citation metadata support shared work.
src/battery_thermal.py solves a first-order cell thermal balance for a piecewise-constant current profile:
C_th dT/dt = I^2 R - hA(T - T_ambient)
The implementation uses the analytical state update over each time step. It is useful for sensitivity checks involving current, internal resistance, thermal capacitance, ambient temperature, and effective cooling conductance.
src/dc_link.py contains two transparent sizing relationships:
- Voltage ripple from an assumed triangular capacitor-current waveform.
- Minimum capacitance for an energy pulse at a specified bus voltage and allowed voltage drop.
MATLAB equivalents are provided in matlab/ for model-based engineering workflows.
Python 3.10 or later is sufficient; there are no third-party runtime dependencies.
python src/battery_thermal.py --current 80 --duration 900 --output thermal_trace.csv
python src/dc_link.py
python -m unittest discover -s tests -vsrc/ # dependency-free Python reference implementations
matlab/ # MATLAB equivalents for model-based workflows
tests/ # regression tests for the Python references
These are reference models, not production-qualified battery, BMS, inverter, or safety models. They do not replace electrochemical characterization, CFD/FEA, component tolerances, control-loop analysis, standards compliance, or test evidence. Inputs and assumptions must be replaced with project-specific data before an engineering decision is made.
See CONTRIBUTING.md for focused documentation, model, and validation changes. Please keep units, assumptions, and project-specific data visible in any example you add.
For research, teaching, or technical reports, use the machine-readable CITATION.cff metadata and identify the model inputs and assumptions used in the result.
Mohammad Rezwan Khan - Electrical R&D Engineer and PhD in Energy Technology.