LIBquiv: Open-Source MATLAB Tool Brings Physics Into Battery Circuit Models

Lithium-ion batteries have quietly become the workhorses of the modern energy economy. Since their commercial debut in 1991, more than ten billion cells are now produced every year, powering everything from smartphones and electric vehicles to drones, home storage systems, and grid-scale battery farms. Yet behind every one of those cells sits a digital twin—a mathematical model that decides how safely it charges, how long it lasts, and when it is about to fail. Now, a team of researchers at Offenburg University of Applied Sciences has released LIBquiv, an open-source MATLAB class that promises to make those digital models dramatically more physical, more flexible, and easier to use than ever before.

The software, published in the journal SoftwareX and available under a BSD-3-Clause license on GitHub, tackles a long-standing tension in battery modelling. On one side are equivalent circuit models, or ECMs—the simple electrical representations that dominate both academic research and real-world battery management systems. They treat a battery as a network of voltage sources, resistors, and capacitors, which makes them computationally cheap enough to embed in the microcontrollers of a battery management system, or BMS, where they handle safety, charge control, and diagnosis of the state of charge and state of health. On the other side are detailed physicochemical models, such as the famous Newman-type models, which resolve the electrochemistry of both electrodes but at a computational cost that rules out long-term simulation and embedded use. LIBquiv, developed by Jonas A. Braun, David Schmider, Simon Schwab, Patricia O. Mmeka, and Wolfgang G. Bessler, is designed to bridge that gap.

The key innovation is what the developers call physics-informed equivalent circuit models. Instead of a generic resistor labelled R1, LIBquiv allows users to specify separate resistances for the positive and negative electrodes, each of which can be parameterized as a function of current, temperature, or lithium stoichiometry. This electrode-resolved structure means that a purely electrical model suddenly carries electrochemical knowledge: the model components are chosen and parameterized according to the underlying physicochemical processes, while the computational complexity remains low. The framework also supports a core-shell particle diffusion model, capturing the transport dynamics that occur inside battery particles, and a hysteresis model that reproduces the voltage memory effects typical of lithium iron phosphate chemistry.

Temperature, which has a strong impact on battery operation and aging, is handled through a zero-dimensional thermal equivalent circuit. The thermal submodel tracks cell temperature using a heat capacity and heat transfer resistance, and it computes both reversible heat generation—derived from the entropy of the electrode materials—and irreversible heat generation from ohmic losses in the resistive elements. This coupling of electrical and thermal behavior in a single lightweight model is what allows LIBquiv to reproduce the strongly nonlinear thermal signatures observed in real cells, such as the large-format 150 ampere-hour LFP prismatic cell from the manufacturer Eikto used as a first demonstration case.

From the user’s perspective, LIBquiv is deliberately simple. The object-oriented implementation lets researchers operate a virtual battery object much as they would operate a real cell on a test bench. One-line commands initiate constant-current, constant-voltage, or constant-power operation, complete with cut-off criteria expressed as logic strings such as a minimum voltage or a maximum temperature. The class tracks simulation time, so multiple operations can be chained sequentially—the final state of one simulation becomes the initial state of the next—allowing complex protocols, like the CCCV charge-rest-discharge-rest sequence demonstrated in the examples, to be assembled as easily as programming a battery cycler. The full thermo-electrical simulation of the 150 Ah Eikto cell runs in just 0.27 seconds on a laptop.

Mathematically, LIBquiv represents the battery as a modular system of coupled time-dependent nonlinear differential-algebraic equations, typically of low order, solved simultaneously by standard MATLAB solvers. Each submodel—electrical, diffusion, hysteresis, aging, thermal—can be individually activated through dedicated parameters, so the mathematical complexity of the model can be adapted to the simulation task at hand. The developers caution that this flexibility comes with a trade-off: activating additional submodels introduces additional state variables and parameters that must be determined experimentally, so model predictions ultimately depend on the quality of the underlying parameterization. Model complexity, they advise, should be selected according to the intended application and the available data.

Perhaps the most striking demonstration is battery aging. Because of the low computational effort, LIBquiv can simulate months or years of battery performance, and because the models are physics-informed, degradation can be described using the concept of degradation modes—loss of lithium inventory and loss of active material. The team developed, parameterized, and validated an aging model for a cylindrical 3.35 Ah nickel cobalt oxide cell from Panasonic. A 650-hour aging simulation took only 139 seconds, and the results did more than reproduce the macroscopic capacity loss and resistance increase: they revealed the underlying degradation modes, showing that the notorious nonlinear aging knee in these cells arises from the interaction between internal resistance growth and lithium plating. That kind of interpretability—understanding not just that a battery degrades but why—is exactly what purely electrical models cannot deliver.

LIBquiv also opens the door to a novel diagnostic approach known as voltage-controlled modelling. Conventional simulations take current as input and predict voltage; LIBquiv can do the reverse, using measured cell voltage as the independent variable and simulating the current response along with the internal state of charge. The team demonstrated this on a 20 Ah lithium-ion pouch cell from Enertech, using measured voltage from a dynamic driving-cycle profile as model input. The simulated current agreed closely with the experimental data, allowing the state of charge to be inferred from internal model states without requiring measured current at all. The full diagnosis over 18,000 data points took just 7.92 seconds. Because modern vehicles and devices already log voltage continuously, this formulation could lead to innovative algorithms for diagnosing capacity, resistance, and even the open-circuit voltage curve of batteries in the field.

The software landscape for equivalent circuit simulation is crowded, spanning open-source projects in Python, C++, and MATLAB as well as commercial environments such as MathWorks Simscape Battery, Siemens Simcenter Amesim, and GT-SUITE. But according to the developers, no existing lightweight time-domain implementation combines electrode-resolved physics-informed models, hysteresis, degradation-mode-based aging, thermal behavior, and voltage-controlled simulation within a unified and intuitive framework. LIBquiv’s distinguishing feature is therefore not a single new circuit topology but the integration of multiple diagnostic and physicochemical extensions in one modular, computationally efficient package. The code has been tested with MATLAB R2019a, R2023b, and R2025b, and a reproducible capsule is archived on Zenodo.

The impact of the release extends across theory and practice. On the theoretical side, LIBquiv enables high-fidelity modelling and understanding-based interpretation of simulation results while remaining fast enough for long-term aging studies and parameter sweeps. On the practical side, the split architecture—model scripts separated from simulation scripts—mirrors the typical workflow of computational battery research and allows models to be exchanged easily between studies. Fully parameterized models of commercial cells ship with the code, and all three demonstration cases, from the thermo-electrical behavior of a large LFP cell to lifetime prediction and state-of-charge diagnosis, are provided in the GitHub repository and can be reproduced directly. For a field racing to electrify transport and stabilize grids with billions of cells, a free tool that makes battery models more physical, more transparent, and more accessible may prove to be one of the quiet catalysts of the energy transition.

Subject of Research: LIBquiv: An open-source MATLAB class for time-domain simulation of physics-informed equivalent circuit models of lithium-ion batteries

Article Title: LIBquiv: An open-source MATLAB class for time-domain simulation of physics-informed equivalent circuit models of lithium-ion batteries

Article References: Braun, J. A., Schmider, D., Schwab, S., Mmeka, P. O., & Bessler, W. G. (2026). LIBquiv: An open-source MATLAB class for time-domain simulation of physics-informed equivalent circuit models of lithium-ion batteries. SoftwareX, 36, Article 103088. https://doi.org/10.1016/j.softx.2026.103088

Image Credits: AI Generated

DOI: 10.1016/j.softx.2026.103088

Keywords: LIBquiv, open-source, MATLAB, class, time-domain, simulation, physics-informed, equivalent, circuit, models, lithium-ion, batteries