⚡ MATLAB Simulink Energy Lab

See the equations become waveforms—and inspect every assumption in between.

MATLAB Simulink Energy Lab is a growing collection of small, runnable, and highly inspectable energy-system examples for students, researchers, and hobbyists. Start with a battery RC model or an averaged converter calculation, trace every parameter, run the checks, and extend the foundation for your own study.

Tip

If a model helps you learn or saves you setup time, star this repository. Your star helps more energy-engineering learners discover the lab and shows which open examples are worth expanding next.

What You Can Explore

• Simulate the terminal-voltage and state-of-charge response of a first-order battery RC model on uniform or native irregular time grids.
• Separate fast and slow battery polarization with an exact two-RC model.
• Identify positive two-RC parameters from voltage data and test them on an independent held-out pulse profile.
• Generate and validate a native Simulink two-RC battery block diagram.
• Estimate real-time battery SOC and RC polarization from noisy current and terminal-voltage measurements with a transparent extended Kalman filter.
• Preserve charge/discharge voltage history with a one-state OCV hysteresis model and validate a deterministic same-SOC reversal minor loop.
• Explore how irreversible electrical losses, reversible entropic heat, and cooling change a lumped cell temperature and temperature-dependent resistance.
• Quantify how lumped cooling conductance changes peak temperature, thermal-limit exposure, and net cooling energy under one shared duty cycle.
• Resolve six cell temperatures along a serial liquid-cooling channel, including coolant warming, cell-to-cell conduction, and module temperature spread.
• Resolve a pouch cell's through-thickness temperature profile with a conservative finite-volume model, asymmetric face cooling, and hot-spot tracking.
• Generate and validate a native Simulink electro-thermal feedback diagram.
• Generate and validate a native Simulink battery RC block diagram.
• Validate model behavior from the command line without opening plots.
• Estimate output voltage, load current, and ripple for an averaged converter.
• Inspect bounded closed-loop voltage tracking for an averaged buck converter.
• Compare open-loop, PI, and filtered-PID load-step regulation on the same averaged buck plant.
• Generate and validate a native Simulink averaged buck-converter diagram.
• Exercise one unified BESS controller through grid-following, grid-forming, islanding, load support, synchronization, saturation, fault, and recovery scenarios with requirement-level traceability.
• Trace every parameter, unit, sign convention, and limitation before extending a model.

Start in 60 Seconds

Seventeen established no-plot checks cover the battery and converter examples. The unified BESS entry point adds a focused 31-result MATLAB/Simulink suite, so run_all_checks now invokes eighteen check entry points. All are configured for MATLAB R2026a, and the validation workflow runs them whenever executable model code changes.

To try the lab in a browser, use the Open in MATLAB Online badge above. After the repository opens, run this from its root folder:

addpath('examples');
run_all_checks

For a local command-line run:

git clone https://github.com/mohammadrezwankhan/matlab-simulink-energy-lab.git
cd matlab-simulink-energy-lab
matlab -batch "addpath('examples'); run_all_checks"

Expected output:

Battery RC check passed. Final SOC: 0.767
Voltage range: 3.425 V to 3.877 V
Native Simulink battery RC check passed.
Final SOC: 0.767
Voltage range: 3.425 V to 3.877 V
Battery 2RC check passed. Final SOC: 0.767
Voltage range: 3.325 V to 3.925 V
Peak polarization: fast 0.075 V, slow 0.125 V
Battery 2RC identification check passed.
Calibration RMSE: 0.401 mV
Held-out RMSE: 0.440 mV
Estimated time constants: 2.01 s and 33.88 s
Native Simulink battery 2RC check passed.
Final SOC: 0.767
Voltage range: 3.325 V to 3.925 V
Battery SOC EKF check passed.
Initial prior SOC error: -0.200
First posterior SOC error: -0.142
Final SOC error: +0.0001
SOC RMSE: 0.0066
Two-percent settling time: 18 s
Posterior voltage RMSE: 1.581 mV
Battery OCV hysteresis check passed.
Final SOC: 0.600
Hysteresis state range: -0.777 to 0.676
Same-SOC minor-loop voltage gap: 8.13 mV
Battery thermal check passed.
Peak cell temperature: 36.92 degC
Final cell temperature: 28.96 degC
Peak irreversible heat: 33.31 W
Reversible heat range: -2.31 W to 1.12 W
Peak total heat: 34.29 W
Final SOC: 0.608
Battery cooling-sensitivity check passed.
hA (W/K)  Peak (degC)  Final (degC)  Time > 35.0 degC (s)  Degree-hours
     0.0        42.73         42.73                1399.6        2.5049
     0.6        38.89         33.25                1019.7        0.5032
     1.2        36.92         28.96                 305.6        0.0815
     2.4        34.05         26.02                   0.0        0.0000
     4.8        30.78         25.12                   0.0        0.0000
Battery module cooling-network check passed.
Peak cell temperature: 39.87 degC (cell 4 at 1320 s)
Peak cell-temperature spread: 5.10 degC
Peak coolant outlet temperature: 31.27 degC
Peak cell temperature at 3x flow: 38.01 degC
Pouch-cell thermal-gradient check passed.
Peak node temperature: 43.83 degC at 5.60 mm and 1800 s
Peak through-thickness node spread: 3.09 degC
Symmetric steady center error: 0.003 degC
Medium-to-fine grid center difference: 0.0024 degC
Native Simulink battery thermal check passed.
Peak cell temperature: 36.92 degC
Final cell temperature: 28.96 degC
Reversible heat range: -2.31 W to 1.12 W
Converter parameter check passed.
Output voltage: 360.0 V
Load current: 18.0 A
Closed-loop converter check passed.
Final average voltage: 399.49 V
Peak voltage after step: 421.90 V
Two-percent settling time: 38.6 ms
Controller comparison check passed.
Controller      Steady error (V)  Overshoot (%)  Settling (ms)  Duty range
Open loop                  1.984           3.84           20.6  0.502 to 0.502
PI                        -0.000           1.25           10.3  0.464 to 0.510
Filtered PID              -0.015           1.67           14.0  0.471 to 0.526
Switching buck converter check passed.
Average output voltage: 358.209 V
Average inductor current: 17.910 A
Current ripple: 9.901 A peak-to-peak
Voltage ripple: 0.124 V peak-to-peak
Measured duty cycle: 0.450
Native Simulink averaged buck check passed.
Final output voltage: 358.209 V
Final inductor current: 17.910 A
All 31 focused BESS controller tests passed.
All 18 MATLAB and Simulink checks passed.

To reproduce the plotted battery response above, run:

run('examples/battery-rc-model/run_battery_rc_model.m')

Models at a Glance

Example	Question It Explores	Validation	Requirements
Battery RC model	How do charge and discharge pulses affect SOC, terminal voltage, charge throughput, and delivered energy?	check_battery_rc_model.m	Base MATLAB
Native Simulink battery RC	Can a generated diagram reproduce the exact first-order battery pulse response and nonlinear OCV lookup?	check_battery_rc_simulink_model.m	MATLAB and Simulink
Battery 2RC model and identification	How do fast and slow polarization branches shape voltage recovery, and can their positive parameters generalize to a held-out pulse profile?	check_battery_2rc_model.m, check_battery_2rc_fit.m	Base MATLAB
Native Simulink battery 2RC	Can a generated diagram reproduce both exact battery polarization time scales?	check_battery_2rc_simulink_model.m	MATLAB and Simulink
Battery SOC EKF	Can noisy voltage measurements correct a biased real-time SOC and polarization estimate?	check_battery_soc_ekf.m	Base MATLAB
Battery OCV hysteresis	How does charge/discharge history create different equilibrium voltages at the same SOC after a current reversal?	check_battery_ocv_hysteresis.m	Base MATLAB
Temperature-aware battery model	How do loss, entropic heat, cooling, resistance feedback, limit exposure, and cooling-conductance sensitivity affect lumped cell temperature?	check_battery_thermal_model.m, check_battery_cooling_sensitivity.m	Base MATLAB
Battery module liquid-cooling network	How do nonuniform heat generation, serial coolant warming, and cell-to-cell conduction determine the hottest cell and module temperature spread?	check_battery_module_cooling_network.m	Base MATLAB
Pouch-cell thermal gradient	How do asymmetric face cooling and through-thickness conduction determine the internal hot spot and spatial temperature gradient?	check_pouch_cell_thermal_model.m	Base MATLAB
Native Simulink battery thermal	Can a generated discrete diagram reproduce coupled electrical, entropic, and thermal feedback sample by sample?	check_battery_thermal_simulink_model.m	MATLAB and Simulink
Converter average model	What do duty cycle and component values imply for average voltage, load current, and first-pass ripple?	check_converter_average_model.m	Base MATLAB
Switching buck converter	How do ideal PWM switching waveforms compare with averaged voltage, current, and ripple estimates?	check_switching_buck_converter.m	Base MATLAB
Closed-loop converter	How do bounded cascaded control and open-loop, PI, and filtered-PID strategies respond to voltage and load steps?	check_closed_loop_converter.m, check_converter_controller_comparison.m	Base MATLAB
Native Simulink averaged buck	Can a generated block diagram reproduce the exact transient and lossy steady state of the averaged equations?	check_average_buck_simulink_model.m	MATLAB and Simulink
Unified grid-tied and grid-forming BESS control	Can one controller transition among grid-following, grid-forming, islanded support, synchronization, recovery, and fault-safe behavior with reproducible numeric evidence?	check_bess_unified_control.m (31 focused results)	MATLAB and Simulink

Current release status: the battery examples, module liquid-cooling network, and three converter references run as MATLAB scripts. Native battery RC, battery 2RC, battery thermal, and averaged buck references additionally generate, compile, and simulate Simulink diagrams. The unified BESS reference generates its model, runs eight mandatory scenarios through MATLAB and Simulink, and publishes requirements, source/assumption boundaries, and validation artifacts.

Why This Lab Is Inspectable

Foundational engineering models are often either too abbreviated to trust or too elaborate to learn from. This repository takes a middle path:

• Small models: the governing logic fits in a short script.
• Visible assumptions: parameters, units, and sign conventions live beside the equations.
• Repeatable checks: no-plot scripts assert basic physical and numerical behavior.
• Engineering context: every example begins with a question and ends with limitations and next steps.
• Extension-friendly: simple baselines make it easier to add controls, higher-order dynamics, measured data, or Simulink implementations.

The examples index connects each model to reproducibility, unit consistency, validation, and review guidance. Shared conventions live in the modeling standards.

Who It Is For

• Students learning how electrical assumptions become executable models.
• Instructors looking for compact examples that can be discussed and modified in class.
• Researchers who need a transparent baseline before introducing higher-fidelity behavior.
• Hobbyists and engineers exploring battery and converter fundamentals without a large framework.

Project Structure

matlab-simulink-energy-lab/
|-- assets/                         # Result images used in the documentation
|-- examples/
|   |-- battery-rc-model/           # RC simulation, pulse data, and check
|   |-- battery-simulink-model/     # Generated native battery RC diagram
|   |-- battery-2rc-model/          # Fast/slow polarization model and check
|   |-- battery-2rc-simulink-model/ # Generated native two-RC diagram
|   |-- battery-soc-ekf/            # Real-time SOC and polarization estimator
|   |-- battery-ocv-hysteresis/     # Dynamic OCV history and minor loops
|   |-- battery-thermal-model/      # Coupled electrical-thermal cell model
|   |-- battery-module-cooling-network/ # Six-cell liquid-cooling network
|   |-- pouch-cell-thermal-gradient/ # Through-thickness finite-volume model
|   |-- battery-thermal-simulink-model/ # Generated thermal feedback diagram
|   |-- converter-average-model/    # Average-model scaffold and check
|   |-- converter-switching-model/  # Ideal PWM switching model and check
|   |-- converter-closed-loop-model/ # Dynamic plant, controller, and check
|   |-- converter-simulink-model/   # Generated native Simulink model and check
|   |-- bess-unified-control/        # Unified BESS modes, builder, tests, evidence
|   `-- guides/                     # Reproducibility and review notes
|-- notes/                          # Repository-wide modeling standards
|-- CONTRIBUTING.md
`-- LICENSE

Requirements

• MATLAB R2026a is the verified release.
• The script-based examples and their validation checks use base MATLAB only.
• Simulink is required for the five generated block-diagram examples, including unified BESS control.
• No power-electronics, control, or testing toolbox is required.

If you run the examples on another MATLAB release, please share the result in an issue so the compatibility record can grow.

Scope and Limitations

• These examples are educational engineering references, not calibrated design models.
• The unified BESS controller is a transparent research translation rather than an exact paper reproduction. Its reduced-order averaged plant, transition/fault supervisor, synchronization thresholds, limits, and tuning include explicit project assumptions. It is not a qualified controller, protection system, or grid-code certification model.
• The battery models use a deliberately simple, replaceable OCV-SOC lookup table that must be calibrated before cell-specific use. The two-RC fitter requires OCV values estimated independently from the terminal-voltage fit.
• The native battery RC diagram receives the reference model's prevalidated, SOC-feasible current trace rather than duplicating its boundary limiter.
• The native battery 2RC diagram uses that same prevalidated current policy and independently integrates both polarization branches.
• The native thermal diagram reproduces a checked discrete educational model; it is not a spatial, safety, or thermal-runaway simulation.
• Its SOC-indexed entropic-coefficient table is illustrative, varies neither with temperature nor ageing, and must be replaced with measured cell data.
• The module cooling network uses lumped cell temperatures and a quasi-steady one-dimensional coolant path; it omits spatial gradients, pressure drop, manifolds, coolant transport delay, pump power, and runaway propagation.
• The pouch-cell thermal model resolves only the through-thickness direction with effective homogeneous properties; it omits tabs, in-plane gradients, layer detail, and electrochemical heat-generation nonuniformity.
• Battery current is zero-order held between supplied timestamps; RC polarization states are propagated exactly over each interval, and applied current is limited to the interval charge available before SOC reaches zero or one.
• The parameter-identification benchmark uses transparent synthetic voltage records with deterministic sensor-like perturbations; it does not claim validation against a physical cell.
• Ageing and cell-to-cell variation are not yet modeled. The OCV hysteresis example is a single-state educational reference with illustrative parameters, not a calibrated chemistry-specific model.
• The SOC EKF uses illustrative OCV and covariance data, assumes exact electrical parameters, and omits current bias, temperature, hysteresis, ageing, and constrained-filter theory.
• The switching converter resolves ideal PWM and inductor copper loss but omits semiconductor loss, dead time, parasitics, EMI, protection, and switched closed-loop control.
• The native Simulink converter is an averaged open-loop model and therefore omits PWM ripple and switching events.
• Parameters and expected outputs must be revalidated before use with real cells, converters, or control designs.

What Should Come Next?

The most useful next additions are likely to be:

• a traceable physical-cell dataset for the two-RC identification workflow;
• switched closed-loop control or a source-backed semiconductor loss model;
• hysteresis-aware SOC estimation with held-out measured reversals; or
• measured thermal-parameter identification and held-out drive-cycle validation.

Request an example, open a focused issue, or propose an implementation through a pull request.

Contribute a Scoped Improvement

Choose an item from the roadmap above or browse the open issues. Before starting substantial work, open or comment on a focused issue so the assumptions, acceptance checks, and ownership are visible. The contribution guide explains the local checks, modeling standard, pull request workflow, and attribution policy.

Releases and Citation

Versioned snapshots and engineering highlights are available on the releases page. See the changelog for the model and validation history.

If you use the lab in research, coursework, or teaching material, use GitHub's Cite this repository control to export APA or BibTeX metadata. The source metadata, including the author's ORCID, is available in CITATION.cff.

Contributing

Contributions are welcome—especially measured-data validation, sourced parameter sets, equivalent-circuit variants, converter topologies, automated checks, and clearer teaching notes. Read CONTRIBUTING.md before opening a pull request.

If the lab saves you time or helps you understand a model, please leave a ⭐. It is the simplest way to support continued open engineering work.

License

Released under the MIT License.