See the equations become waveforms—and inspect every assumption in between.
MATLAB Simulink Energy Lab is an open collection of runnable, reduced-order reference models for lithium-ion battery equivalent circuits, state-of-charge (SOC) estimation with extended Kalman filters (EKF), battery thermal management, buck converters, and grid-forming/grid-following battery energy storage system (BESS) control. It includes toolbox-free Base MATLAB examples and generated Simulink block diagrams with deterministic no-plot checks. Start with the model-selection guide, trace every parameter and limitation, and reproduce the exact validation evidence before adapting a model. Bundled benchmarks and parameters are synthetic or illustrative unless an example explicitly identifies another source; the checks are not physical-cell, hardware, certification, or grid-code validation.
Source of record: this GitHub repository is authoritative for code, releases, citation metadata, and validation evidence. The public project overview is the search landing page and concise cross-model introduction.
- Start in 60 Seconds for the fastest runnable path.
- Model selection guide to choose the smallest battery, converter, thermal, SOC-estimation, or BESS model for your question.
- Model selection by engineering decision for thesis, classroom, first-simulation, and engineering-study routes.
- Reduced-order versus higher-fidelity workflows for the boundary between this lab and Simscape, CFD, pack, HIL, or measured validation work.
- Technical FAQ for direct answers about models, requirements, validation boundaries, reproduction, citation, and licensing.
- Models at a Glance for the model-to-question map.
- Requirements for MATLAB and toolbox expectations.
- Scope and Limitations before reusing outputs.
- Validation results for the complete expected output.
- Machine-readable validation manifest for per-commit CI provenance and check status.
- Two-RC battery parameter-identification tutorial for a reproducible fit-versus-held-out-validation workflow.
- Grid-forming BESS control tutorial for an executable grid-following-to-islanding-to-reconnection walkthrough.
- Contribute a Scoped Improvement for focused changes.
- Citation metadata and release notes for published or shared work.
- CodeMeta and AI navigation index for machine-readable software metadata and source routing.
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.
- 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.
- Quantify how a prescribed constant current-sensor bias changes SOC error, voltage residuals, and filter-consistency diagnostics on the same benchmark.
- 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.
- Generate and validate a fixed-step native Simulink switching closed-loop buck diagram against the Base MATLAB reference.
- Compare fixed-junction-temperature switch loss across published 25-to-175 degC SiC MOSFET anchors without inventing a thermal state.
- Exercise one unified BESS controller through grid-following, grid-forming, islanding, load support, synchronization, saturation, fault, and recovery scenarios with requirement-level traceability.
- Trace how battery SOC reserve, current capability, and DC-link energy turn a requested BESS converter power profile into deliverable power and curtailment.
- Map how illustrative reserve floors change average deliverable power and actual curtailment time under constant DC-side requests.
- Trace every parameter, unit, sign convention, and limitation before extending a model.
Twenty-five established no-plot checks cover the battery, converter, and DC-side
BESS examples. The unified BESS entry point adds a focused 31-result
MATLAB/Simulink suite, so run_all_checks invokes 26 check entry points. CI
also verifies the machine-readable manifest contract. All are configured
for MATLAB R2026a, and the validation workflow runs them whenever executable
model code changes.
If you have MATLAB without Simulink, run the deterministic 20-check subset:
addpath('examples');
run_base_matlab_checksThat subset validates every toolbox-free script example. It does not include native block-diagram parity or the focused unified-BESS controller suite.
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_checksOr open one focused Base MATLAB example directly:
- Hysteresis-aware battery SOC EKF
- SOC EKF current-bias sensitivity
- Switching closed-loop buck converter
- Switch fixed-junction-temperature sensitivity
- BESS DC-link and SOC reserve
- BESS prescribed dynamic-profile sensitivity
Prefer an inspectable block diagram? Use one of the two focused Simulink first runs.
If you are unsure which example fits, use the battery, converter, and BESS model selection guide.
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"The latest tagged release is v0.10.0.
The latest hosted MATLAB R2026a executable-code evidence is
run 32667995625
at exact source commit
ab42bc8.
Current main contains only documentation changes after that source commit. The
two CI jobs report:
| Evidence | Result |
|---|---|
| Repository regression | All 25 general check entry points pass; the separate unified-BESS entry point yields 31 focused results. Together, the two CI jobs cover 26 entry points. |
| Base MATLAB profile | The dedicated run_base_matlab_checks profile contains 20 toolbox-free script checks. It was not invoked as a separate no-Simulink job in this hosted run. |
| BESS DC reserve | 10.225 kWh delivered and 8.109 kWh curtailed discharge; SOC remains above the 0.20 reserve. |
| BESS reserve sensitivity | Across 18 fixed-profile cases, average delivered power saturates at 176.277 kW and maximum curtailed energy is 30.924 kWh; this is illustrative DC-side sensitivity, not pack capability. |
| BESS dynamic-profile sensitivity | Across nine prescribed profile/reserve cases, delivered discharge energy spans 6.806 to 20.364 kWh and curtailment time spans 0.0 to 303.4 s; profiles are not energy-normalized or compared as a general law. |
| Switched closed-loop buck | 399.62 V final average for a 400 V target; 5.91% reference-step overshoot; 2.08% load-step undershoot; 3.354 J nominal switch-conduction and 0.405 J transition loss. |
| Switch temperature sensitivity | Fixed-junction-temperature sweep from 25 to 175 degC increases total switch loss from 3.759 J to 8.594 J under published datasheet-anchor interpolation. |
| Native switched-buck parity | Exact agreement across 180,000 PWM intervals, 1,800 controller periods, and both electrical states. |
| Two-RC identification (synthetic) | 0.440 mV held-out voltage RMSE; 0.401 mV calibration RMSE. |
| SOC EKF (synthetic) | 0.0066 SOC RMSE; 1.581 mV posterior voltage RMSE. |
| SOC EKF prescribed current bias | Across -0.50 to +0.50 A, final signed SOC error spans -0.0218 to +0.0217; this is synthetic sensitivity, not bias rejection. |
| Unified BESS focused suite | 31 focused MATLAB/Simulink results pass across eight mandatory scenarios. |
| Environment | MATLAB R2026a; Simulink is required for generated diagrams. |
These are deterministic regression checks for reduced-order educational models, not physical-cell, hardware, or grid-code validation. In particular, the two-RC identification benchmark uses transparent synthetic voltage records with deterministic sensor-like perturbations, not measured cell data. See the full expected output and provenance and per-commit machine-readable manifest, plus the Scope and Limitations before reusing results.
To reproduce the plotted battery response above, run:
run('examples/battery-rc-model/run_battery_rc_model.m')
| 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 initial SOC estimate, and how does prescribed current-sensor bias change the result? | check_battery_soc_ekf.m, check_battery_soc_ekf_current_bias.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 |
| Battery SOC hysteresis EKF | How much SOC error appears when an estimator omits known OCV hysteresis under current reversals? | check_battery_soc_hysteresis_ekf.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 |
| Switching closed-loop buck | Can a period-sampled controller regulate an explicitly switched buck while separating source-backed nominal and fixed-junction-temperature switch losses? | check_switching_closed_loop_buck.m, check_switching_closed_loop_buck_temperature_sensitivity.m |
Base MATLAB |
| Native Simulink switching closed-loop buck | Can an inspectable fixed-step diagram reproduce the sampled controller, integer PWM, and exact switched-plant states? | check_switching_closed_loop_buck_simulink_model.m |
MATLAB and Simulink |
| 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 |
| BESS DC-link and SOC reserve | How do SOC reserve, battery-current capability, and finite DC-link energy constrain constant and prescribed dynamic requests? | check_bess_dc_reserve.m, check_bess_dc_reserve_envelope.m, check_bess_dc_reserve_profile_sensitivity.m |
Base MATLAB |
| 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 converter references run as MATLAB scripts. Native battery RC, battery 2RC, battery thermal, averaged buck, and switching closed-loop 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.
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.
- 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.
matlab-simulink-energy-lab/
|-- assets/ # Result images used in the documentation
|-- docs/ # Full expected validation output
|-- 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-soc-hysteresis-ekf/ # Hysteresis-aware SOC estimation comparison
| |-- 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-switching-closed-loop-model/ # Controlled PWM plant and check
| |-- converter-switching-closed-loop-simulink-model/ # Native switched parity
| |-- converter-closed-loop-model/ # Dynamic plant, controller, and check
| |-- converter-simulink-model/ # Generated native Simulink model and check
| |-- bess-dc-reserve-model/ # SOC reserve and DC-link availability
| |-- bess-unified-control/ # Unified BESS modes, builder, tests, evidence
| `-- guides/ # Reproducibility and review notes
|-- notes/ # Repository-wide modeling standards
|-- CONTRIBUTING.md
`-- LICENSE
- MATLAB R2026a is the verified release.
- The script-based examples and their validation checks use base MATLAB only.
run_base_matlab_checksexecutes all 20 of those checks with one command.- Simulink is required for the six generated block-diagram examples, including unified BESS control.
- No power-electronics, control, or testing toolbox is required.
Compatibility evidence is release-, environment-, and commit-specific:
| Release | Evidence status | Environment | Exact evidence |
|---|---|---|---|
| R2026a | Maintained primary CI baseline | Ubuntu, MATLAB and Simulink | Latest executable-code run: 25 general checks and 31 focused unified-BESS results passed. |
| R2025b Update 6 | One-time maintainer-automated proof; not community-tested | Ubuntu 24, GLNXA64, MATLAB 25.2.0.3312555, Simulink 25.2 |
Exact commit c0a5a2c and hosted run: 25 general checks and 31 focused unified-BESS results passed. |
The R2025b row is a bounded compatibility record for that exact environment and commit, not a general support promise for other operating systems or releases.
If you run the examples on another MATLAB release, please share the result in an issue so the compatibility record can grow.
- 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 and assumes exact electrical parameters. Its current-bias study prescribes a constant unmodeled estimator-input offset; it does not estimate or reject that bias. Temperature, hysteresis, ageing, and constrained-filter theory remain omitted.
- The open-loop switching converter uses ideal complementary switches. The switched closed-loop converter adds a constant-drop freewheel diode, period-sampled control, nominal switch loss, and a fixed-junction-temperature sensitivity limited to published 25-to-175 degC anchors. It still omits a solved thermal state, multidimensional nonlinear device behavior, dead time, capacitance, reverse recovery, parasitics, EMI, protection, sensor dynamics, and hardware validation.
- The native averaged Simulink converter omits PWM ripple and switching events. The native switching companion reproduces the Base MATLAB sampled controller and exact affine plant maps; its parity is not independent physical evidence.
- The DC-side BESS reserve model uses affine OCV, constant resistance, exact initial SOC, and an energy-state DC link. It omits battery polarization, estimation error, temperature, ageing, switching conversion, protection, and closed-loop integration with the unified AC-side controller.
- Parameters and expected outputs must be revalidated before use with real cells, converters, or control designs.
The most useful next additions are likely to be:
- a traceable physical-cell dataset for the two-RC identification workflow;
- dynamic semiconductor electrothermal feedback from a sourced transient thermal network;
- held-out measured reversal data for the hysteresis-aware SOC estimator; 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.
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.
Versioned snapshots and engineering highlights are available on the releases page. For a checksum-verifiable snapshot, download the tracked v0.10.0 source package and its published SHA-256 checksum. 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.
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.
Released under the MIT License.