Summary

This package is a wrapper for the well-known Thevenin equivalent circuit model. The model is comprised of a single series reistor followed by any number of parallel RC pairs. Figure 1 below illustrates a circuit with 2 RC paris; however, the model can be run with as few as zero, and as many as $N$.

Figure 1: 2RC Thevenin circuit.

This system is governed by the evolution of the state of charge (soc, -), RC overpotentials ($V_j$, V), cell voltage ($V_{\rm cell}$, V), and temperature ($T_{\rm cell}$, K). soc and $V_j$ evolve in time as

$$\begin{align} &\frac{d\rm soc}{dt} = \frac{-I}{3600 Q_{\rm max}}, \\\ &\frac{dV_j}{dt} = -\frac{V_j}{R_jC_j} + \frac{I}{C_j}, \end{align}$$

where $I$ is the load current (A), $Q_{\rm max}$ is the maximum nominal cell capacity (Ah), and $R_j$ and $C_j$ are the resistance (Ohm) and capacitance (F) of each RC pair $j$. Note that the sign convention for $I$ is chosen such that positive $I$ discharges the battery (reduces soc) and negative $I$ charges the battery (increases soc). This convention is consistent with common physics-based models, e.g., the single particle model or pseudo-2D model. While not explicitly included in the equations above, $R_j$ and $C_j$ are functions of soc and $T_{\rm cell}$. The temperature increases while the cell is active according to

$$\begin{equation} mC_p\frac{dT_{\rm cell}}{dt} = \dot{Q}_{\rm gen} + \dot{Q}_{\rm conv}, \end{equation}$$

where $m$ is mass (kg), $C_p$ is specific heat capacity (J/kg/K), $Q_{\rm gen}$ is the heat generation (W), and $Q_{\rm conv}$ is the convective heat loss (W). Heat generation and convection are defined by

$$\begin{align} &\dot{Q}_{\rm gen} = I \times (V_{\rm ocv}({\rm soc}) - V_{\rm cell}), \\\ &\dot{Q}_{\rm conv} = hA(T_{\infty} - T_{\rm cell}), \end{align}$$

where $h$ is the convecitive heat transfer coefficient (W/m²/K), $A$ is heat loss area (m²), and $T_{\infty}$ is the air/room temperature (K). $V_{\rm ocv}$ is the open circuit voltage (V) and is a function of soc.

The overall cell voltage is

$$\begin{equation} V_{\rm cell} = V_{\rm ocv}({\rm soc}) - \sum_j V_j - IR_0, \end{equation}$$

where $R_0$ the lone series resistance (Ohm), as shown in Figure 1. Just like the other resistive elements, $R_0$ is a function of soc and $T_{\rm cell}$.

Installation

We recommend using Anaconda to install this package due to the scikits.odes dependency, which is installed separately using conda install to avoid having to download and install C++ and Fortran compilers. Please refer to the linked scikits.odes documentation if you'd prefer to install their software without using conda.

After cloning the repository, or downloading the files, use your terminal (MacOS/Linux) or Anaconda Prompt (Windows) to navigate into the folder with the pyproject.toml file. Once in the correct folder, execute the following commands:

conda create -n rovi python=3.10 scikits.odes -c conda-forge
conda activate rovi
pip install .

Note that if you are using a Mac with arm-64 for conda, you will have to force your new environment to use packages built on osx-64 because scikits.odes does not currently have any builds for arm-64. You can check if this is the case by running conda info and checking the platform value. To set up and force your new environment to osx-64, run the following:

conda create -n rovi
conda activate rovi
conda config --env --set subdir osx-64
conda install python=3.10 scikits.odes -c conda-forge
pip install .

The first command will create a new Python environment named rovi. The environment will be set up using Python 3.10 and will install the scikits.odes dependency from the conda-forge channel. You can change the environment name as desired and specify any Python version >= 3.8 and < 3.12. Although the package supports multiple Python versions, development and testing is primarily done using 3.10. Therefore, if you have issues with another version, you should revert to using 3.10.

Before running the pip install command, which installs thevenin, you should activate your new rovi environment using the second command. If you plan to make changes to your local package, use the -e flag and add the optional developer dependencies during the pip install step, as shown below.

pip install -e .[dev]

Getting Started

The API is organized around three main classes that allow you to construct the model, define an experiment, and interact with the solution. A basic example for a constant-current discharge is given below. To see the documentation for any of the classes or their methods, use Python's built in help() function. You can also access the documentation by visiting the website hosted through GitHub pages. The website includes search functionality and more detailed examples compared to those included in the docstrings.

import thevenin

model = thevenin.Model()

exp = thevenin.Experiment()
exp.add_step('current_A', 15., (3600., 1.), limit=('voltage_V', 3.))

sol = model.run(experiment)
sol.plot('capacity_Ah', 'voltage_V')

Contributions

Contributions are welcomed and encouraged. If you choose to contribute, please note that this package mostly follows the PEP8 style guide style guide. However, we allow adding extra spaces around parentheses and brackets, and under- or over-indenting multi-line expressions when it improves readability or avoids the 80-character line limit.

Be aware that it is the authors' preference to not adopt the more opinionated black formatting style. Please avoid autoformatting any files in this style if you plan to contribute.

Acknowledgements

This work was authored by the National Renewable Energy Laboratory (NREL), operated by Alliance for Sustainable Energy, LLC, for the U.S. Department of Energy (DOE). The views expressed in the repository do not necessarily represent the views of the DOE or the U.S. Government.