Skip to main content

Battery Lifecycle Simulation

This repository contains a Python script designed to simulate the lifecycle of a battery using a digital twin approach. The simulation takes into account various battery parameters, power profiles, ambient conditions, and safety cutoffs to compute the battery’s behavior over time. The primary function, simulate_lifecycle, manages the simulation loop, sensor updates, and state transitions.

Overview​

The simulation script integrates several components to create a comprehensive battery simulation:

  • Digital Twin Sensors: Tracks parameters such as power demand, voltage, current, state-of-charge (SoC), temperature, and state-of-health (SoH).
  • Battery Dynamics: Uses a battery object that encapsulates electrochemical properties and simulation behaviors.
  • Power Profile Interpolation: Processes power and ambient temperature profiles to interpolate values at each simulation timestep.
  • Time Step Management: Dynamically adjusts the simulation time step based on battery conditions and profile inputs.
  • State Machine: Implements a battery state machine (batteryStateMachine) to handle safety checks, charge tapering, and other operational states.

Features​

  • Lifecycle Simulation: Computes battery performance over time based on varying load profiles.
  • Dynamic Sensor Logging: Records key metrics (SoC, voltage, current, temperature, etc.) at configurable intervals.
  • Safety Mechanisms: Integrates safety cutoffs for temperature, voltage, and current to prevent unrealistic battery behavior.
  • Configurable Parameters: Supports configuration of initial conditions, maximum continuous charge/discharge rates, and simulation cutoff thresholds.
  • Visualization Ready: Uses Plotly for data visualization (plotting capabilities are available for further extension).

Installation​

Ensure you have Python 3.7 or higher installed. Then, install the required packages. You may use a requirements.txt file similar to the following:

pip install numpy pandas plotly

Additionally, ensure that the following custom modules are available in your Python environment:

  • altergo_sdk
  • lair.components.battery_iq
  • lair.tools.simulation

These modules are part of the project’s internal library or should be obtained from the relevant repository.

Usage​

The main function in the script is simulate_lifecycle, which can be imported and used as follows:

from your_module_name import simulate_lifecycle
from lair.components.battery_iq.battery import Battery, SimulationLevel
import pandas as pd

# Example configuration dictionary
configuration = {
    "initial_soc": {"value": 0.8},
    "Maximum Continuous Charge C-rate": {"value": 0.5},
    # ... add other configuration parameters as needed
}

# Example simulation cutoffs
simulation_cutoffs = {
    "lowVoltageSafetyCutoff": 3.0,
    "highVoltageSafetyCutoff": 4.2,
    "maxSoC": 1.0,
    "minSoC": 0.0,
    "maxCurrent": 100,
}

# Simulation time step settings
simulation_time_step_settings = {
    "maximum_dt_s": 60,  # Maximum time step in seconds
    "minimum_dt_s": 1,   # Minimum time step in seconds
}

# Instantiate a Battery object (custom implementation)
battery = Battery(...)
simulation_depth = SimulationLevel.FULL  # Or another appropriate level

# Create a power profile DataFrame with a datetime index and required columns
power_profile = pd.DataFrame({
    "normalized_charge_power": [...],
    "normalized_discharge_power": [...],
    "temperature": [...],
}, index=pd.date_range("2025-01-01", periods=100, freq="T"))

# Run simulation
results = simulate_lifecycle(
    configuration,
    battery,
    power_profile,
    simulation_cutoffs,
    simulation_time_step_settings,
    simulation_depth,
    is_prod_run=False
)

# The results are stored in a dictionary of sensor objects with logged simulation data.

Configuration Details​

  • Initial Conditions:
    Set the initial state-of-charge (initial_soc) and initial ambient temperature from the provided power profile.

  • Power Profile:
    The input DataFrame should contain columns for normalized charge/discharge power and temperature. These are used to compute:

    • charge_current
    • discharge_current
    • totalCurrent
    • power_demand

  • Safety Cutoffs:
    Parameters such as lowVoltageSafetyCutoff, highVoltageSafetyCutoff, and temperature thresholds (e.g., temperatureSafety) are used to trigger state transitions within the battery state machine.

  • Time Step Management:
    The simulation dynamically adjusts the timestep (dt_s) using factors like the minimum and maximum allowable step sizes and the interval until the next profile input.

Simulation Workflow​

  1. Data Preparation:

    • Interpolates power and ambient temperature profiles.
    • Initializes sensors for various battery parameters.

  2. Simulation Loop:

    • Iterates over the simulation time, adjusting dt_s as needed.
    • Updates battery conditions using the calculateNextStep method on each battery element.
    • Logs sensor data at each timestep.
    • Uses a state machine to adjust current based on safety and operational constraints.

  3. Results:
    The simulation concludes when the battery’s state-of-health drops below a threshold or when the simulation time elapses. Sensor data is returned in a dictionary for further analysis and visualization.

Extending and Visualizing Results​

The script is designed to be modular. You can extend the simulation by:

  • Adding new sensor metrics.
  • Modifying the battery state machine for advanced control logic.
  • Using Plotly to create detailed visualizations of sensor data over time.

Example of plotting a sensor’s data:

import plotly.express as px

# Assuming results["SoH"] is a sensor with a 'data' list and 'time' list
fig = px.line(x=results["SoH"].time, y=results["SoH"].data, labels={'x': 'Time (s)', 'y': 'State of Health (%)'})
fig.show()

Contributing​

Contributions to improve the simulation model, extend features, or add visualization examples are welcome. Please fork the repository and submit a pull request with your improvements.

License​

This project is licensed under the MIT License. See the LICENSE file for details.

Acknowledgements​

Special thanks to the developers of the lair battery simulation modules and the altergo_sdk for their foundational work in digital twin battery simulation.

Happy simulating!

Version​

0.1.0