Battery State of Charge (SoC) Estimator Model

This repository contains a Python implementation of a battery State of Charge (SoC) estimator model. The model estimates the SoC of a battery cell based on input sensor data (voltage, current, temperature) and battery specifications defined in a cell model. It is designed to integrate with the Altergo platform for data retrieval and storage.

Battery State of Charge (SoC) Estimator Model

Features

SoC Estimation: Calculates the State of Charge of a battery cell using voltage, current, and temperature data.
Altergo Integration: Seamless integration with the Altergo platform for data retrieval and data submission.
Configurable Parameters: Easy customization of sensor names, model parameters, and configuration settings.
Incremental Computation: Supports incremental computation over specified time periods.
Detailed Cell Model: Utilizes a comprehensive cell model for accurate estimation.

Prerequisites

Python: Version 3.7 or higher.
Altergo Account: Access to the Altergo platform with valid API keys.
Python Packages: All required packages are listed in requirements.txt.

Installation

Clone the Repository

git clone https://github.com/yourusername/soc-estimator.git
cd soc-estimator

Install Dependencies
```
pip install -r requirements.txt
```

Configuration

Model Settings

The model settings are defined in altergo-settings.json. This file contains configurations for sensor names, blueprint parameters, and other configurations.

Example altergo-settings.json:

{
    "name": "Battery SoC Estimator",
    "version": "1.0.0",
    "main": "entrypoint.py",
    "type": "model",
    "category": "custom",
    "parameters": {
        "bp_sensors": {
            "SENSOR_CURRENT": {
                "description": "Input: Current sensor name from your blueprint",
                "default": "Current",
                "valueDev": "Current"
            },
            "SENSOR_VOLTAGE": {
                "description": "Input: Voltage sensor name from your blueprint",
                "default": "Voltage",
                "valueDev": "Voltage"
            },
            "SENSOR_TEMPERATURE": {
                "description": "Input: Temperature sensor name from your blueprint",
                "default": "Temperature",
                "valueDev": "Temperature"
            }
        },
        "bp_parameters": {
            "PARAMETER_CAPACITY": {
                "description": "Input: Capacity parameter name from your blueprint",
                "default": "Capacity",
                "valueDev": "Capacity"
            }
        },
        "configuration": {
            "DECIMATION_THRESHOLD": {
                "description": "Conf: Decimation threshold for your model",
                "default": 0.01,
                "valueDev": 0.01
            },
            "MAX_DAYS_PERIOD_COMPUTE": {
                "description": "The number of days that the model will compute in one execution",
                "default": 7,
                "valueDev": -1
            },
            "COMPUTE_TYPE": {
                "description": "Compute type for the model execution",
                "default": "incremental",
                "valueDev": "incremental"
            },
            "CELL_MODEL_PATH": {
                "description": "The path to the cell model",
                "default": "cell/cell_model.json",
                "valueDev": "cell/cell_model.json"
            }
        }
    }
}

Parameter Descriptions:

bp_sensors: Sensor names from your data source.
- SENSOR_CURRENT: Name of the current sensor.
- SENSOR_VOLTAGE: Name of the voltage sensor.
- SENSOR_TEMPERATURE: Name of the temperature sensor.
bp_parameters: Blueprint parameters.
- PARAMETER_CAPACITY: Name of the capacity parameter.
configuration: Model configuration settings.
- DECIMATION_THRESHOLD: Threshold for data decimation.
- MAX_DAYS_PERIOD_COMPUTE: Maximum number of days to compute in one execution.
- COMPUTE_TYPE: Type of computation (e.g., "incremental").
- CELL_MODEL_PATH: Path to the cell model JSON file.

Development Parameters

Development parameters are specified in dev-parameters.json. These include API keys and asset IDs for interacting with the Altergo platform.

Example dev-parameters.json:

{
    "altergoUserApiKey": "your_user_api_key",
    "altergoFactoryApi": "https://your-altergo-instance.com",
    "altergoIotApi": "https://your-altergo-instance.com",
    "assetId": "your_asset_id"
}

Parameter Descriptions:

altergoUserApiKey: Your Altergo user API key.
altergoFactoryApi: URL of the Altergo Factory API.
altergoIotApi: URL of the Altergo IoT API.
assetId: The ID of the asset for which the SoC estimation is performed.

Cell Model

The cell model defines the characteristics of the battery cell and is located at cell/cell_model.json. It includes parameters such as:

Cell capacity
Open Circuit Voltage (OCV) curves
Resistance and capacitance values
Temperature and SoC ranges

Ensure that the CELL_MODEL_PATH in your settings matches the actual location of the cell_model.json file.

Usage

Run the SoC estimation model using the entrypoint.py script:

python entrypoint.py --altergoUserApiKey your_user_api_key --altergoFactoryApi https://your-altergo-instance.com --altergoIotApi https://your-altergo-instance.com --assetId your_asset_id --activityId your_activity_id

Alternatively, if you have configured dev-parameters.json, you can run:

python entrypoint.py

How It Works

Data Flow

Initialization: entrypoint.py initializes by extracting parameters from the command-line arguments or dev-parameters.json.
Altergo Client Setup: Initializes the Altergo API client using the provided API keys and URLs.
Asset and Activity Retrieval:
- Retrieves the asset using assetId.
- Retrieves the activity (time period) using activityId.
Sensor Data Retrieval:
- Sensor names are obtained from the configuration.
- Sensor data (voltage, current, temperature) is fetched for the specified time range.
Data Preprocessing:
- Resamples data to a 1-second frequency to ensure consistent time intervals.
- Forward-fills missing data to handle any gaps.
Estimation:
- Loads the cell model from CELL_MODEL_PATH.
- Creates an instance of the Estimator class with the cell model parameters.
- Applies the estimation function to each row of the resampled data to compute SoC.
Result Handling:
- Extracts estimated SoC values.
- Renames columns for clarity.
- Sends the estimated data back to the Altergo platform.

Estimator Logic

The Estimator class in estimator/soc_estimator.py models the battery behavior by:

Coulomb Counting: Tracking charge/discharge based on current flow over time.
OCV Hysteresis: Accounting for the difference in OCV during charge and discharge cycles.
Dynamic Voltage Response: Modeling the voltage response to current changes using resistance and capacitance.
Temperature Effects: Adjusting calculations based on the battery temperature.

Key Methods:

initOCV(initVolt): Initializes OCV values based on the initial voltage.
countCoulomb(current, deltaT): Updates Coulomb count.
updateSOCI(): Updates internal SOC bounds and hysteresis coefficient.
calculateNextVdyns(current): Calculates dynamic voltage response.
calculateNextOcvs(vTerm, current, temperature): Updates OCV estimates.
getOcvSocArray(temperature, ocVoltage): Interpolates OCV to find corresponding SOC.

Directory Structure

soc-estimator/
├── .gitignore
├── .vscode/
│   └── launch.json
├── README.md
├── altergo-settings.json
├── cell/
│   └── cell_model.json
├── dev-parameters.json
├── entrypoint.py
├── estimator/
│   └── soc_estimator.py
├── requirements.txt
└── tree.py

Descriptions:

entrypoint.py: Main script orchestrating the estimation process.
estimator/soc_estimator.py: Contains the Estimator class.
cell/cell_model.json: JSON file with cell model parameters.
altergo-settings.json: Model configuration settings.
dev-parameters.json: Development parameters with API keys and asset IDs.
requirements.txt: Lists required Python packages.

Table of Contents​

Features​

Prerequisites​

Installation​

Configuration​

Model Settings​

Development Parameters​

Cell Model​

Usage​

How It Works​

Data Flow​

Estimator Logic​

Directory Structure​

Table of Contents