Reviewable MATLAB Models: Battery, Thermal, Converter and BESS Evidence

A practical reduced-order workflow for choosing a model by engineering question, exposing assumptions, running reproducible checks, and stating exactly what the evidence does—and does not—support.

From MATLAB Simulink Energy Lab, maintained by Mohammad Rezwan Khan.

Versioned evidence: The worked results below describe the repository snapshot bf36bfce071a8da2b49498d91518f766c00197c7, not a fresh benchmark of the latest release. They are synthetic or illustrative verification results, not measured-cell or hardware qualification evidence.

A precise number can answer the wrong question

A simulation can return six decimal places and still be unhelpful. The problem is usually not arithmetic. It is a mismatch between the engineering decision and the model boundary.

A useful model lets another person trace a result through five questions:

1. What decision is the model meant to support?
2. Which assumptions make that question tractable?
3. Which executable path produces the result?
4. Which complementary checks could expose a failure?
5. Which conclusions remain outside the evidence?

This trace is especially important for reduced-order models. A reduced-order model deliberately uses fewer states or less physical detail so that one bounded behavior is easier to inspect. That can make it an excellent teaching, method-development, or early sensitivity tool. It also means its omissions are part of the result, not an afterthought.

Synthetic data are generated by the model for repeatable testing. Illustrative values are teaching placeholders, not measured or site-specific inputs.

The workflow below applies that idea to battery equivalent circuits, state-of- charge estimation, pouch-cell thermal gradients, switched converters, and grid-following/grid-forming battery energy storage system control.

1. Start with the engineering decision

The question determines the model boundary; the block diagram comes second. Before choosing a script or Simulink diagram, write the decision in one sentence.

A battery equivalent-circuit model approximates open-circuit voltage, ohmic resistance, and polarization with electrical elements. It is not an electrochemical cell model. A two-RC version adds two polarization branches; their time constants, often written as tau = R*C, represent faster and slower voltage relaxation.

An extended Kalman filter, or EKF, combines a nonlinear state model with noisy observations. Here, SOC means state of charge and OCV means open-circuit voltage. A residual is the observed voltage minus the estimator's predicted voltage. None of those terms, by itself, says that the model is ready for a vehicle, inverter, or protection function.

2. Define the boundary before running the model

Every run should begin with a compact assumption record. At minimum, write down:

• units and sign conventions;
• solver or sample time;
• initial conditions;
• input profile and its provenance;
• parameter provenance;
• products required to execute the path;
• modeled states and algebraic relations;
• known omissions; and
• the interpretation boundary for every reported metric.

Sign conventions deserve special attention. In the battery examples, positive current represents discharge. In the unified BESS reference, positive active power represents injection at the point of common coupling, while charging is negative. A sign error can produce a smooth plot and a completely inverted engineering conclusion.

Separate source-backed concepts from project-derived values. A published equation, an illustrative parameter, and a site-specific acceptance limit are not interchangeable evidence. Label each one where it enters the model.

For a new dataset, add a provenance line: who produced it, which instrument or simulation created it, what processing was applied, and which record was reserved for evaluation. Without that separation, a low fitting error can be a description of the calibration record rather than evidence about a distinct case.

3. Build the smallest runnable path

A compact Base MATLAB script is often the clearest source of truth. It exposes the equations, update order, inputs, and assertions without requiring a reader to traverse a large diagram. A generated Simulink companion can then make signal flow, state boundaries, and interfaces inspectable.

That division matters: the generated .slx file is a disposable representation, while the MATLAB source and model builder remain reviewable and repeatable. Agreement between MATLAB and Simulink is a parity check under the same assumptions. It is not independent physical evidence.

To reproduce this article's historical results, use Git to create a new checkout of the exact snapshot below. MATLAB R2026a must be installed and available as matlab on your terminal path. Choose a new destination folder; do not replace an existing working checkout.

git clone https://github.com/mohammadrezwankhan/matlab-simulink-energy-lab.git energy-lab-article
cd energy-lab-article
git checkout --detach bf36bfce071a8da2b49498d91518f766c00197c7

From that repository root, the toolbox-free regression profile is:

matlab -batch "addpath('examples'); run_base_matlab_checks"

For the pinned source and documented MATLAB R2026a environment, the toolbox-free profile records all 20 checks passing. This is commit- and environment-specific; see the validation record for current provenance. It does not cover native block-diagram parity or the focused unified-BESS suite, and it does not establish physical validation.

For a single example, start even smaller. From examples/battery-2rc-model, run the check. In the same terminal, use:

cd examples/battery-2rc-model
matlab -batch "check_battery_2rc_fit"

A no-plot regression check is an automated repeatability and expected-behavior check. It is useful because it fails loudly when an implementation drifts. It is not a laboratory measurement.

4. Pair every metric with a countercheck

One attractive number is rarely enough. Pair each headline metric with a different failure mode.

RMSE means root-mean-square error. It summarizes a typical error magnitude over a record, but it does not identify every failure mode and it is not a physical uncertainty bound. Peak-to-peak ripple is the difference between the largest and smallest periodic value over the evaluated interval. Grid refinement compares solutions as the spatial discretization becomes finer; a small difference is numerical evidence about that discretization, not proof of temperature accuracy.

Worked example: calibration versus held-out synthetic evaluation

The two-RC identification path provides a useful pattern because it separates parameter fitting from evaluation.

First, the deterministic synthetic calibration record is generated from known starter parameters. The fit estimates bounded resistances and time constants. Then the fitted parameters are applied to a separate synthetic pulse profile that was not used for calibration.

In this deterministic synthetic benchmark, calibration RMSE is 0.401 mV and held-out RMSE is 0.440 mV. The two values show that the fitted parameters were evaluated on a separate synthetic pulse. Their closeness is a property of this benchmark, not proof of generalization or physical identifiability. It remains a held-out synthetic evaluation. It is not measured-cell accuracy or evidence across chemistry, temperature, ageing, or sensor conditions.

The important habit is the separation:

1. fit on one transparent record;
2. evaluate on a distinct record;
3. report both errors with the same units and precision;
4. inspect residuals rather than only a scalar score; and
5. state which real-world variation is still missing.

The same structure transfers to measured work. Calibration data should remain separate from evaluation data, and both should carry traceable conditions and instrument provenance.

Additional evidence cards

SOC estimation with an EKF

In the deterministic synthetic SOC-EKF benchmark, SOC RMSE is 0.0066 and posterior-voltage RMSE is 1.581 mV. SOC is normalized, while the voltage residual uses millivolts. The pairing matters: a state estimate that looks smooth can still be inconsistent with the observed voltage.

The benchmark uses illustrative OCV, covariance, noise, and sensor assumptions. The prescribed current-bias sensitivity case does not detect, estimate, or reject a real sensor bias. The result is not production-BMS performance or a safety-function claim.

Pouch-cell thermal gradients

The illustrative finite-volume thermal check reports a 0.0024 °C medium-to-fine grid-center difference and checks energy balance and symmetry. A finite-volume model divides the one-dimensional thickness into control volumes and balances stored energy, conduction, prescribed heat, and boundary heat transfer.

The properties and heat input are illustrative, and the heat source is uniform and prescribed. The model omits electrochemical heat generation, in-plane gradients, tabs, edge cooling, current-collector and layer-by-layer detail, and it does not separately resolve contact resistance from convection; phase change, gas generation, thermal runaway, and safety controls are outside scope. The grid result therefore describes numerical refinement, not cell-temperature accuracy.

Buck-converter switching and ripple

The prescribed ideal-switching regression reports 358.209 V average output and 9.901 A peak-to-peak current ripple. PWM means pulse-width modulation: the switch duty controls the fraction of each period connected to the source, and the switching sequence produces periodic voltage and current variation.

The path uses ideal complementary switches and prescribed parameters. It omits dead time, diode drops, reverse recovery, parasitics, electromagnetic interference, protection, sensor dynamics, and hardware measurement. The numbers are regression evidence for the stated model, not device qualification or hardware-efficiency evidence.

Grid-following and grid-forming BESS transitions

A BESS is a battery energy storage system. Grid-following control uses an existing grid reference; grid-forming control establishes voltage and frequency behavior within its stated model. P/Q denotes active and reactive power, and per-unit quantities are normalized to a selected electrical base.

The unified BESS example is a transparent reduced-order research translation and educational starter. Its supervisor organizes eight mandatory scenarios covering normal operation, grid loss, synchronization, recovery, limit events, and fault-safe behavior. These are educational transition and limit-gate regressions, not eight qualified operating environments.

The cited framework leaves material equations, gains, plant data, transition rules, synchronization windows, and acceptance limits unspecified. The project adds explicit assumptions so the workflow can be executed and inspected. It is not an exact paper reproduction, qualified controller, protection relay, safety case, hardware model, or grid-code compliance result.

5. Interpret evidence at the right level

The next section moves from what the model computes to what the result can legitimately support.

An evidence ladder helps prevent category errors:

1. Numerical regression: the same source and inputs retain documented behavior.
2. Analytical or conservation check: a result agrees with a derived relation under the same assumptions.
3. MATLAB/Simulink parity: two representations agree under a shared model.
4. Held-out synthetic evaluation: a fitted method is evaluated on a distinct simulated record.
5. Grid refinement: a finer spatial discretization changes a selected result only slightly.
6. Measured-component evidence: traceable laboratory data cover stated conditions and uncertainty.
7. System and qualification evidence: hardware, protection, environmental, safety, interconnection, and compliance work cover the intended operating envelope.

Each rung answers a different question. Lower rungs can be valuable and rigorous without being relabeled as higher ones. This checks implementation consistency under stated assumptions, not physical accuracy.

6. Turn each limitation into the next experiment

A limitation becomes useful when it selects the next test.

HIL means hardware-in-the-loop: real control hardware interacts with a real-time simulated plant. It can reveal timing, I/O, and implementation effects that an offline reduced-order script cannot cover. It still does not replace every commissioning or safety activity.

7. Make reproduction part of the result

A reviewable result should travel with five items:

• the exact command;
• expected output and assertion behavior;
• environment and required products;
• source version or commit; and
• an interpretation boundary.

For this article, the source of record is the full commit shown in the evidence note. The pinned model-selection guide maps questions to examples and non-goals. The pinned validation record records commands, environment, expected output, and limitations. Each example README explains its assumptions and next steps beside the executable path.

Before reusing a result, ask:

• Can I trace every parameter, unit, sign, and initial condition?
• Does the check exercise a failure mode different from the headline metric?
• Is evaluation data separate from calibration data?
• Does a parity result share assumptions with the reference?
• Which physical effects and operating conditions remain absent?
• What evidence would cause me to reject the model for this decision?

Closing: make the claim as inspectable as the model

The goal is not to make every model more complicated. It is to make every claim traceable, testable, and honestly bounded.

Choose the example that matches your engineering question, run its no-plot check, and write down one assumption you would replace or test next with measured data. If a boundary is unclear, send a documented critique or correction naming the example and the evidence.

Repository and reproducible examples: https://github.com/mohammadrezwankhan/matlab-simulink-energy-lab

Prepared with AI assistance. See the authorship and accountability policy. Questions and corrections are welcome through the repository.