This article aims to enable users to get started with TWAICE Simulation Models and guide users through model download, license activation, how to run simulations and use case examples.
Model Download
Download the TWAICE battery simulation model trial package using the link provided in the e-mail. The download will start automatically by clicking the link.
License Activation
Open your file explorer and find the zipped folder called “TWAICE-demo-model-FMU.zip”.
Right-click the folder and select "Extract All" to unzip it, then choose a destination for the extracted files.
Select the respective version of the model depending on your operating system.
Open the file “RunMe_FMU_TWAICE_Cell_Model_Demo_Cell_v10_4_1_Python_xxx64.ipynb” in e.g. Jupyter Notebook, Visual Studio Code or a similar environment.
5. Navigate to the "Model Configuration" section, copy the License Key from your email, and paste it into line 11 of the “RunMe_FMU_TWAICE_Cell_Model_Demo_Cell_v10_4_1_Python_xxx64.ipynb” file, replacing “XXXXXX- XXXXXX- XXXXXX- XXXXXX- XXXXXX- XXXXXX”.
Congratulations - you are now ready to simulate!
Run Your First Simulation
To start a simulation, you must load all parameters and prepare the model by simply running the notebook “RunMe_FMU_TWAICE_Cell_Model_Python.ipynb”. Please find an example in Visual Studio Code below. The easiest way to simulate is by simply using the default parameters and just click “Run All” in Visual Studio Code.
After the simulation is completed, scroll to the bottom of the notebook to view the results in Plotly. The output for the predefined configuration will be displayed there.
Model Information
Model Specifications
Voltage Range: 2.5 – 4.2 V
State of Charge Range: 0 – 100 %
Nominal Capacity: 2.6 Ah
C-rates (dch / ch): -1.0 – 1.0
Ambient Temperature Range: 10 - 40°C
Model Inputs
# | Name | Unit | Description |
1 | FMU_Load_Input | A, W, or C-rate | Simulation input load profile |
2 | FMU_Tamb_Input | °C | Simulation input ambient temperature |
3 | FMU_Pcool_Input | W | Simulation input cooling power |
4 | FMU_SOC_Input | % | Simulation input state of charge |
5 | FMU_Tcell_Input | °C | Simulation input cell temperature |
6 | Prod_lic | - | License key |
Model Parameters
# | Name | Start Value | Unit | Description |
1 | FMU_cell_SOC_init | 50 | % | Initial state of charge |
2 | FMU_cell_T_init | 25 | °C | Initial cell temperature |
3 | FMU_cell_SOHc_init | 100 | % | Initial state of health (capacity) |
4 | FMU_cell_SOHr_init | 100 | % | Initial state of health (resistance) |
5 | FMU_cell_HTC | NaN | W/(m²K) | Heat transfer coefficient |
6 | FMU_cell_load_profile_unit | 1 | - | Unit of simulation input load profile |
7 | FMU_cell_use_Data_Tbat | 0 | - | Use cell temperature as input (off/on) |
8 | FMU_cell_use_Data_SOC | 0 | - | Use state of charge as input (off/on) |
9* | FMU_cell_m_cell_mask | NaN | kg | Cell mass |
10* | FMU_cell_Asurf_cell_mask | NaN | m² | Cell surface area |
11* | FMU_cell_C_nom_mask | NaN | Ah | Nominal cell capacity |
12** | FMU_cell_SOH_LI_init | 100 | % | Initial state of health (lithium inventory) |
13** | FMU_cell_SOH_PE_init | 100 | % | Initial state of health (positive electrode) |
14** | FMU_cell_SOH_NE_init | 100 | % | Initial state of health (negative electrode) |
15** | FMU_cell_SOH_Ne_Si_init | 100 | % | Initial state of health (silicon in NE) |
16*** | FMU_cell_SOH_swelling_init | 100 | % | Initial state of health (swelling force) |
17**** | FMU_cell_threshold_plating | 0 | V | Electrochemical Li-plating threshold |
*Requires TWAICE Model “Representative”
**Requires TWAICE Model “Pro” & Add-On “Degradation Modes”
***Requires TWAICE Model “Pro” & Add-On “Swelling Force”
****Requires TWAICE Model “Pro” & Add-On “Half Cell Potentials”
Model Outputs
| Name | Unit | Description |
1 | Current | A | Cell current |
2 | Voltage | V | Cell voltage |
3 | Temperature | °C | Cell temperature |
4 | SOC | % | State of charge |
5 | SOHc | % | State of health (capacity) |
6 | SOHr | % | State of health (resistance) |
7 | Power | W | Cell power |
8 | TotalAh | Ah | Charge throughput |
9 | PowerLoss | W | Cell losses |
10* | SOHc_UB | % | State of health (capacity) upper bound |
11* | SOHc_LB | % | State of health (capacity) lower bound |
12** | SOH_LI | % | State of health (lithium inventory) |
13** | SOH_PE | % | State of health (positive electrode) |
14** | SOH_NE | % | State of health (negative electrode) |
15*** | SOH_swelling | % | State of health (swelling force) |
16**** | AnodePotential | V | Anode potential |
17**** | CathodePotential | V | Cathode potential |
18**** | platingAh | Ah | Charge throughput while Li-plating |
*Requires TWAICE Model “Pro” & Add-On “Confidence Interval”
**Requires TWAICE Model “Pro” & Add-On “Degradation Modes”
***Requires TWAICE Model “Pro” & Add-On “Swelling Force”
****Requires TWAICE Model “Pro” & Add-On “Half Cell Potentials”
How to Use the Code
This notebook aims to offer a thorough collection of code samples for running Functional Mock-up Units (FMUs) in a Python environment. This section explains the key parts of the script, providing an overview of how the different components interact:
Model Configuration
The model configuration section defines the input for the simulation function call, specifying all configurable FMU model parameters. This includes the FMU path, licensing details, initial cell parameters, and other model inputs. Follow the inline comments carefully when entering values, as some inputs may require specific model types or add-ons.
Simulation Configuration
The simulation configuration section, similar to the model configuration section, defines all simulation parameters. This includes initial settings, stop conditions, and optional warning limits. Ensure you follow the inline comments closely when providing input.
Operational Scenario Configuration
The operational scenario configuration specifies the necessary simulation inputs for proper execution. You can define simulation inputs using either time series data or constant values, with examples of both included in the basic configuration. Additional inputs are optional and can be enabled or disabled as needed.
Input Interface
The primary purpose of the input interface is to standardize inputs for the simulation function call. It generates standardized input dictionaries that use the appropriate terminology for the FMU simulation model. Additionally, it verifies all model and simulation configuration parameters to ensure that the inputs fall within the specified ranges.
Simulation Function
The simulation function is the core of the script. In this section, standardized inputs are gathered, the FMU instance is created and initialized, the simulation is executed, and outputs are generated. A while loop iterates through the simulation steps to carry out the respective battery simulation.
Simulation Function Call
The simulation function call is a crucial component of the script that orchestrates the entire simulation process. This function collects all necessary input and ensures that the simulation function operates with the correct data.
Output Interface
The purpose of the output interface is similar to the input interface. It standardizes the results of the simulation and generates standardized output data frames.
Data Visualization
The data visualization section provides two sample plots of the simulation results. In the first example, model parameters are plotted over time. In the second example, SOHc and SOHr are plotted over throughput.
If you have any questions, please reach out to your TWAICE contact.