pybatteryse 1.0.0__tar.gz

pybatteryse-1.0.0/LICENSE.txt

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, A.M.A (Muiz) Sheikh
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pybatteryse-1.0.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: pybatteryse
+Version: 1.0.0
+Summary: Battery State Estimation in Python
+Home-page: https://github.com/muizabdul29/PyBatterySE
+Author: Muiz Sheikh
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: pybatteryid>=3.0.1
+Requires-Dist: numpy>=2.1.0
+Requires-Dist: tqdm>=4.67.3
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: summary
+
+# PyBatterySE
+
+<div>
+
+[![release](https://img.shields.io/github/v/release/muizabdul29/PyBatterySE)](https://github.com/muizabdul29/PyBatterySE/releases)
+[![Pylint](https://github.com/muizabdul29/PyBatterySE/actions/workflows/pylint.yml/badge.svg)](https://github.com/muizabdul29/PyBatterySE/actions/workflows/pylint.yml)
+
+</div>
+
+
+**PyBatterySE** — a shorthand for **Py**thon **Battery** **S**tate **E**stimation, is an open-source library for state estimation using Bayesian filters and linear parameter-varying (LPV) battery models.
+
+## Installation
+
+Use the package manager [pip](https://pip.pypa.io/en/stable/) to install PyBatterySE.
+
+```bash
+pip install pybatteryse
+```
+
+## Requirements
+
+PyBatterySE is a companion package to PyBatteryID, and utilises the models identified using PyBatteryID for state estimation. Whilst it is possible to use a custom model that follows the same format as PyBatteryID, it is recommended to use models identified using PyBatteryID for state estimation with PyBatterySE.
+
+## Basic usage
+
+In the following, an example usage of PyBatterySE has been demonstrated for performing state estimation of batteries, including SOC estimation, and ageing-aware parameter (and capacity) estimation.
+
+#### 1. SOC estimation
+
+For SOC estimation, we currently have two options, namely (i) extended Kalman filter (EKF), and (ii) particle filter (PF). In both cases, the state corresponding to overpotential model obtained using PyBatteryID is augmented with an extra SOC state, that is, $x = [s \ x_1 \ \cdots \ x_n]^\top$. Below, we give two basic example usages for SOC estimation using EKF and PF.
+
+**Example 1: SOC estimation using EKF**
+
+```python
+from pybatteryid.utilities import load_model_from_file
+from pybatteryse.filters.ekf import ExtendedKalmanFilter
+
+model = load_model_from_file('path/to/model.npy')
+dataset = helper.load_npy_datasets(f'path/to/dataset.npy')
+bad_current_measurements = [ ... ] # Bad current measurements
+
+# Initialize EKF
+ekf = ExtendedKalmanFilter(
+    model=model,
+    sigma_nu=1e-3,        # Input noise variance
+    sigma_ny_ne=1e-3      # Measurement noise variance
+)
+ 
+# Prepare initial conditions
+x0 = np.array([[0.5],    # Initial SOC
+               [0.0],    # state 1
+               [0.0],    # state 2
+               [0.0]])   # state 3
+ 
+P0 = np.diag([1, 0.1, 0.1, 0.1])  # Initial covariance
+ 
+# Run filter
+state_estimates = ekf.run(
+    temperature_values=dataset['temperature_values'],
+    current_values=bad_current_measurements,
+    voltage_values=dataset['voltage_values'],
+    initial_state=x0,
+    initial_covariance=P0
+)
+ 
+# Extract SOC estimates
+soc_estimates = state_estimates[:, 0]
+```
+
+**Example 2: SOC estimation using PF**
+
+```python
+from pybatteryid.utilities import load_model_from_file
+from pybatteryse.filters.ekf import ParticleFilter
+
+model = load_model_from_file('path/to/model.npy')
+dataset = helper.load_npy_datasets(f'path/to/dataset.npy')
+bad_current_measurements = [ ... ] # Bad current measurements
+
+# Initialize PF
+pf = ParticleFilter(
+    model,
+    num_particles=5,
+    eta_bounds=(-4, -1),
+    sigma_ny_ne=1e-3
+)
+ 
+initial_particles = np.hstack((
+    np.random.uniform(0.0001, 0.9999, size=(pf.num_particles, 1)),
+    np.zeros((pf.num_particles, model.model_order))
+))
+
+state_estimates = pf.run(initial_particles=initial_particles,
+                         temperature_values=temperature_values,
+                         current_values=bad_current_measurements,
+                         voltage_values=voltage_values)
+
+soc_estimates = state_estimates[:, 0]
+
+```
+
+#### 2. Ageing-aware model estimation
+
+We can perform ageing-aware model estimation using recursive state estimation. The detailed methodology is explained in [X], which proposes alternative approaches as well. An example has been provided in the examples folder, which can be consulted for more details.
+

pybatteryse-1.0.0/README.md

@@ -0,0 +1,106 @@
+# PyBatterySE
+
+<div>
+
+[![release](https://img.shields.io/github/v/release/muizabdul29/PyBatterySE)](https://github.com/muizabdul29/PyBatterySE/releases)
+[![Pylint](https://github.com/muizabdul29/PyBatterySE/actions/workflows/pylint.yml/badge.svg)](https://github.com/muizabdul29/PyBatterySE/actions/workflows/pylint.yml)
+
+</div>
+
+
+**PyBatterySE** — a shorthand for **Py**thon **Battery** **S**tate **E**stimation, is an open-source library for state estimation using Bayesian filters and linear parameter-varying (LPV) battery models.
+
+## Installation
+
+Use the package manager [pip](https://pip.pypa.io/en/stable/) to install PyBatterySE.
+
+```bash
+pip install pybatteryse
+```
+
+## Requirements
+
+PyBatterySE is a companion package to PyBatteryID, and utilises the models identified using PyBatteryID for state estimation. Whilst it is possible to use a custom model that follows the same format as PyBatteryID, it is recommended to use models identified using PyBatteryID for state estimation with PyBatterySE.
+
+## Basic usage
+
+In the following, an example usage of PyBatterySE has been demonstrated for performing state estimation of batteries, including SOC estimation, and ageing-aware parameter (and capacity) estimation.
+
+#### 1. SOC estimation
+
+For SOC estimation, we currently have two options, namely (i) extended Kalman filter (EKF), and (ii) particle filter (PF). In both cases, the state corresponding to overpotential model obtained using PyBatteryID is augmented with an extra SOC state, that is, $x = [s \ x_1 \ \cdots \ x_n]^\top$. Below, we give two basic example usages for SOC estimation using EKF and PF.
+
+**Example 1: SOC estimation using EKF**
+
+```python
+from pybatteryid.utilities import load_model_from_file
+from pybatteryse.filters.ekf import ExtendedKalmanFilter
+
+model = load_model_from_file('path/to/model.npy')
+dataset = helper.load_npy_datasets(f'path/to/dataset.npy')
+bad_current_measurements = [ ... ] # Bad current measurements
+
+# Initialize EKF
+ekf = ExtendedKalmanFilter(
+    model=model,
+    sigma_nu=1e-3,        # Input noise variance
+    sigma_ny_ne=1e-3      # Measurement noise variance
+)
+ 
+# Prepare initial conditions
+x0 = np.array([[0.5],    # Initial SOC
+               [0.0],    # state 1
+               [0.0],    # state 2
+               [0.0]])   # state 3
+ 
+P0 = np.diag([1, 0.1, 0.1, 0.1])  # Initial covariance
+ 
+# Run filter
+state_estimates = ekf.run(
+    temperature_values=dataset['temperature_values'],
+    current_values=bad_current_measurements,
+    voltage_values=dataset['voltage_values'],
+    initial_state=x0,
+    initial_covariance=P0
+)
+ 
+# Extract SOC estimates
+soc_estimates = state_estimates[:, 0]
+```
+
+**Example 2: SOC estimation using PF**
+
+```python
+from pybatteryid.utilities import load_model_from_file
+from pybatteryse.filters.ekf import ParticleFilter
+
+model = load_model_from_file('path/to/model.npy')
+dataset = helper.load_npy_datasets(f'path/to/dataset.npy')
+bad_current_measurements = [ ... ] # Bad current measurements
+
+# Initialize PF
+pf = ParticleFilter(
+    model,
+    num_particles=5,
+    eta_bounds=(-4, -1),
+    sigma_ny_ne=1e-3
+)
+ 
+initial_particles = np.hstack((
+    np.random.uniform(0.0001, 0.9999, size=(pf.num_particles, 1)),
+    np.zeros((pf.num_particles, model.model_order))
+))
+
+state_estimates = pf.run(initial_particles=initial_particles,
+                         temperature_values=temperature_values,
+                         current_values=bad_current_measurements,
+                         voltage_values=voltage_values)
+
+soc_estimates = state_estimates[:, 0]
+
+```
+
+#### 2. Ageing-aware model estimation
+
+We can perform ageing-aware model estimation using recursive state estimation. The detailed methodology is explained in [X], which proposes alternative approaches as well. An example has been provided in the examples folder, which can be consulted for more details.
+

pybatteryse-1.0.0/pybatteryse/__init__.py

@@ -0,0 +1 @@
+"""Load"""

pybatteryse-1.0.0/pybatteryse/coefficient.py

@@ -0,0 +1,97 @@
+"""Utilities concerning model state-space representation."""
+
+import re
+from dataclasses import dataclass
+
+import numpy as np
+
+
+@dataclass
+class CoefficientTerm:
+    """
+    Represents a term in the model coefficient. Note that the
+    coefficient is made up of several terms, e.g.,
+    b_0(k) = 2 * s(k) × log[s](k) + 4 * T(k) × 1/s(k) is made up
+    of two terms.
+    """
+    parameter: float
+    basis_function_strings: list[str]
+
+
+Coefficients = dict[str, list[CoefficientTerm]]
+
+
+def extract_model_coefficients(model_terms, model_estimate, output_symbol='v', input_symbol='i'):
+    """Extract p-dependent model coefficients."""
+
+    coefficients: dict[str, list[CoefficientTerm]] = {}
+
+    for term, parameter in zip(model_terms, model_estimate):
+        result = re.search(f'({output_symbol}|{input_symbol})\\(k(-(\\d+))?\\)', term)
+        if result is None:
+            raise ValueError('Invalid model terms.')
+
+        # Define coefficient
+        result_groups = result.groups()
+        coefficient_variable = 'a' if result_groups[0] == output_symbol else 'b'
+        coefficient_delay = result_groups[2] if result_groups[2] is not None else 0
+
+        # Remove input/output terms plus the time indices
+        coefficient_term = re.sub(f'({output_symbol}|{input_symbol})?\\(k(-(\\d+))?\\)', '', term)
+        # We split the term into a list of individual
+        # basis function strings
+        coefficient_term_bfs = coefficient_term.strip('×').split('×')
+
+        # Define coefficient key, e.g., b_0, b_1, ...
+        coefficient_key = f'{coefficient_variable}_{coefficient_delay}'
+        if coefficient_key not in coefficients:
+            coefficients[coefficient_key] = []
+        #
+        coefficient_parameter = -parameter if coefficient_variable == 'a' else parameter
+        coefficients[coefficient_key].append(CoefficientTerm(coefficient_parameter,
+                                                             coefficient_term_bfs))
+
+    return coefficients
+
+
+def evaluate_coefficient(coefficient_terms: list[CoefficientTerm],
+                         signal_trajectories: dict,
+                         time_instant: int):
+    """Evaluate a coefficient at a certain time instant."""
+
+    result = []
+    for coefficient_term in coefficient_terms:
+        #
+        term_value = coefficient_term.parameter
+        for bf_string in coefficient_term.basis_function_strings:
+            if bf_string == '':
+                continue
+            #
+            term_value *= signal_trajectories[f'{bf_string}(k)'][time_instant]
+        result.append(term_value)
+
+    return np.sum(result)
+
+
+def update_model_parameters(coefficients: Coefficients, model_estimate: list[float]) -> None:
+    """Update coefficient parameters in-place from a flat model_estimate vector.
+
+    Iterates coefficients.items() in insertion order (a_1, a_2, ..., b_0, b_1, ...)
+    which matches the canonical parameter order guaranteed by extract_model_coefficients.
+    a-term parameters are stored with negated sign (convention from extract_model_coefficients).
+
+    Raises:
+        ValueError: If len(model_estimate) does not match the total subterm count.
+    """
+    all_keyed_subterms = [
+        (subterm, coefficient_key.startswith('a'))
+        for coefficient_key, subterms in coefficients.items()
+        for subterm in subterms
+    ]
+    if len(model_estimate) != len(all_keyed_subterms):
+        raise ValueError(
+            f"Parameter count mismatch: expected {len(all_keyed_subterms)} parameters "
+            f"but got {len(model_estimate)}."
+        )
+    for (subterm, is_a_coefficient), new_parameter in zip(all_keyed_subterms, model_estimate):
+        subterm.parameter = -new_parameter if is_a_coefficient else new_parameter

pybatteryse-1.0.0/pybatteryse/filters/__init__.py

@@ -0,0 +1,3 @@
+"""Load"""
+from .ekf import ExtendedKalmanFilter
+from .pf import ParticleFilter