Merge branch 'release/3.0.1'

Author: muizabdul29

README.md

@@ -1,5 +1,12 @@
 # PyBatteryID
 
+<div>
+
+[![release](https://img.shields.io/github/v/release/muizabdul29/PyBatteryID)](https://github.com/muizabdul29/PyBatteryID/releases)
+[![DOI](https://zenodo.org/badge/704093134.svg)](https://doi.org/10.5281/zenodo.15437221)
+
+</div>
+
 **PyBatteryID** — a shorthand for **Py**thon **Battery** Model **ID**entification, is an open-source library for data-driven battery model identification in the linear parameter-varying (LPV) framework. 
 
 > Briefly, the LPV framework can be considered as an upgrade to the linear time-invariant (LTI) framework for systems whose dynamics cannot be considered time-invariant — for instance, batteries exhibit varying dynamics as the battery state-of-charge (SOC), temperature, current magnitude, and current direction vary. Refer to the book [Modeling and Identification of Linear Parameter-Varying Systems](https://link.springer.com/book/10.1007/978-3-642-13812-6) for a formal introduction to the LPV systems.
@@ -12,10 +19,20 @@ Use the package manager [pip](https://pip.pypa.io/en/stable/) to install PyBatte
 pip install pybatteryid
 ```
 
+## Regarding the required experiments
+
+There are a few experiments that the user may need to perform before using PyBatteryID, namely,
+
+1. **Battery electromotive force (EMF) data**: Also referred to as the open-circuit voltage (OCV). The user needs to provide the (SOC, EMF) points that cover the SOC range expected in the test application. PyBatteryID performs interpolation using the given points to determine an EMF value for a certain SOC value. Note that by design, PyBatteryID DOES NOT perform extrapolation outside the given SOC range, because this can lead to poor modelling results.
+
+2. **Current-voltage data**: The user must provide a sufficiently informative identification dataset, comprising current-voltage data (and optionally, temperature data if temperature-dependent models are desired). Please DO NOT expect a low-quality dataset, such as an HPPC test or a random drive cycle, to give you good models. In our paper [1], we have emphasised as much as possible that an informative dataset is crucial for obtaining high-quality (accurate, sparse, etc.) models, while presenting a current profile design that can lead to suitable identification datasets (see [examples/4_input_design.ipynb](/examples/4_input_design.ipynb)). Also note that this requirement holds for *any* modelling activity, and not specific to PyBatteryID or batteries, namely, it is a general principle of the **[System Identification](https://en.wikipedia.org/wiki/System_identification)** to use informative identification datasets.
+
 ## Basic usage
 
 In the following, an example usage of PyBatteryID has been demonstrated for modelling the battery overpotential using the LPV framework while assuming the battery electromotive force (EMF) to be known *a priori* via appropriate experiments, such as GITT, or low-current cycling. In effect, the battery voltage output at a given time instant can then be calculated by using the EMF value at that instant and evaluating the overpotential using the identified LPV model.
 
+> It is recommended that the user follows the International System of Units (SI) while using PyBatteryID. For example, the battery capacity should be specified in Coulombs, time in seconds, current in amperes, and voltage in volts. For the temperature, both Celsius or Kelvin can be used as long as the user stays consistent and adjusts the temperature-related basis functions accordingly. Note that the temperature is in Celsius in the [example](/examples/3_1_nmc_with_temperature_identification.ipynb) provided with the package.
+
 #### 1. Initialize model structure
 
 The very first step is to create an instance of the `ModelStructure` class which requires the capacity of the studied battery and the model sampling time.
@@ -97,13 +114,16 @@ voltage_simulated = simulate_model(model, dataset)
 
 ## Relevant publications
 
-<a id="1">[1]</a> A.M.A. Sheikh, M.C.F. Donkers, and H.J. Bergveld, “A comprehensive approach to sparse identification of linear parameter-varying models for lithium-ion batteries using improved experimental design,” *Journal of Energy Storage, 2024*.
+<a id="1">[1]</a> A.M.A. Sheikh, M.C.F. Donkers, and H.J. Bergveld, “A comprehensive approach to sparse identification of linear parameter-varying models for lithium-ion batteries using improved experimental design,” *Journal of Energy Storage, 2024*. https://doi.org/10.1016/j.est.2024.112581
 
-<a id="2">[2]</a> A.M.A. Sheikh, M.C.F. Donkers, and H.J. Bergveld, “Investigating Identification Input Designs for Modelling Lithium-ion Batteries with Hysteresis using LPV Framework,” *2024 American Control Conference (ACC)*.
+<a id="2">[2]</a> A.M.A. Sheikh, M.C.F. Donkers, and H.J. Bergveld, “Investigating Identification Input Designs for Modelling Lithium-ion Batteries with Hysteresis using LPV Framework,” *2024 American Control Conference (ACC)*. https://doi.org/10.23919/ACC60939.2024.10644893
 
 <a id="3">[3]</a> A.M.A. Sheikh, M.C.F. Donkers, and H.J. Bergveld, “Towards temperature-dependent linear
-parameter-varying models for lithium-ion batteries
-using novel experimental design,” *Submitted to Journal*.
+parameter-varying models for lithium-ion batteries using novel experimental design,” *Journal of Energy Storage, 2025*. https://doi.org/10.1016/j.est.2025.116311
+
+## Get in touch
+
+For general inquiries about using the package, you can either [start a discussion](https://github.com/muizabdul29/PyBatteryID/discussions) or email at [a.m.a.sheikh@tue.nl](mailto:a.m.a.sheikh@tue.nl) (Muiz Sheikh).
 
 ## License
 PyBatteryID is an open-source library licensed under the BSD-3-Clause license. For more information, see [LICENSE](LICENSE.txt).

examples/1_1_nmc_identification.ipynb

@@ -2,7 +2,7 @@
  "cells": [
   {
    "cell_type": "code",
-   "execution_count": 1,
+   "execution_count": null,
    "metadata": {
     "jupyter": {
      "is_executing": true
@@ -12,7 +12,7 @@
    "source": [
     "from pybatteryid import ModelStructure\n",
     "from pybatteryid.identification import identify_model\n",
-    "from pybatteryid.utilities import print_model_details, save_model_to_file, invert_voltage_function, analyze_dataset\n",
+    "from pybatteryid.utilities import print_model_details, save_model_to_file, analyze_dataset\n",
     "from pybatteryid.plotter import plot_time_vs_current\n",
     "\n",
     "from data import helper"
@@ -7337,7 +7337,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.12.4"
+   "version": "3.13.5"
   },
   "orig_nbformat": 4
  },

examples/1_2_nmc_validation.ipynb

@@ -2,14 +2,14 @@
  "cells": [
   {
    "cell_type": "code",
-   "execution_count": 36,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
     "from sklearn.metrics import root_mean_squared_error, mean_absolute_error\n",
     "\n",
     "from pybatteryid.simulation import simulate_model\n",
-    "from pybatteryid.utilities import load_model_from_file, invert_voltage_function\n",
+    "from pybatteryid.utilities import load_model_from_file\n",
     "from pybatteryid.plotter import plot_time_vs_current, plot_time_vs_voltage\n",
     "\n",
     "from data import helper"

examples/3_1_nmc_with_temperature_identification.ipynb

@@ -2557,7 +2557,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.12.4"
+   "version": "3.13.5"
   },
   "orig_nbformat": 4
  },

examples/3_2_nmc_with_temperature_validation.ipynb

@@ -42,7 +42,7 @@ def extract_basis_functions(basis_function_strings: list[str]) -> list[BasisFunc
          r"(([0-9]*[.])?[0-9]+)\]$", [0, 1, 3], Operation.LOWPASS)
     ]
     #
-    for i, function_string in enumerate(basis_function_strings):
+    for function_string in basis_function_strings:
         for identifier, indices, operation in identifiers:
             #
             result = re.findall(identifier, function_string.strip())
@@ -52,7 +52,7 @@ def extract_basis_functions(basis_function_strings: list[str]) -> list[BasisFunc
                 basis_functions.append(BasisFunction(result[indices[0]], operation, args,
                                                      function_string))
                 break
-        if len(basis_functions) == i:
+        else:
             raise ValueError(f"Could not recognize expression: {function_string}")
     return basis_functions
 
@@ -222,9 +222,10 @@ def generate_signal_trajectories(signals: Tuple[list[Signal], ...], model_order:
     #
     io_signals, basis_function_signals, hysteresis_basis_function_signals = signals
     #
-    time_delays = [np.arange(1, model_order + 1, 1).tolist(), # voltage
-                    np.arange(0, model_order + 1, 1).tolist(), # current
-                    [0]] # hysteresis input
+    time_delays = [
+        [0] if signal.symbol == 'h'
+        else np.arange(signal.symbol == 'v', model_order + 1).tolist() for signal in io_signals
+    ]
     #
     io_trajectories_dict = generate_io_trajectories(io_signals,
                                                     time_delays, no_of_initial_values)

examples/4_input_design.ipynb

@@ -13,10 +13,11 @@
     generate_signal_trajectories
 
 
-# pylint: disable=R0914
+# pylint: disable=R0914,W0102
 def setup_regression_problems(datasets: list[CurrentVoltageData],
                               model_structure: ModelStructure,
-                              model_order: int, nonlinearity_order: int):
+                              model_order: int, nonlinearity_order: int,
+                              input_symbols: list[str] = ['i']):
     """Generate regression matrices for the given dataset(s)."""
     # Shorthand for convenience
     ms = model_structure
@@ -28,11 +29,10 @@ def setup_regression_problems(datasets: list[CurrentVoltageData],
         #
         bf_signal_vector = generate_basis_function_signals(ms.basis_functions, signals)
         hysteresis_bf_signal_vector = generate_basis_function_signals(ms.hysteresis_basis_functions,
-                                                              signals)
+                                                                      signals)
         #
-        io_signals = [ signals.find('v'), signals.find('i') ]
-        if ms.hysteresis_function is not None:
-            io_signals.append( signals.find('h') )
+        io_signals = [signals.find(s)
+                      for s in ['v'] + input_symbols + (['h'] if ms.hysteresis_function else [])]
         #
         signal_tuple = io_signals, bf_signal_vector.signals, hysteresis_bf_signal_vector.signals
         signal_trajectories = generate_signal_trajectories(signal_tuple,
@@ -66,8 +66,8 @@ def identify_model(datasets: list[CurrentVoltageData] | CurrentVoltageData,
     # Shorthand for convenience
     ms = model_structure
     #
-    if isinstance(datasets, dict):
-        datasets = [ datasets ]
+    if not isinstance(datasets, list):
+        datasets = [datasets]
     regression_problems, regressor_labels = setup_regression_problems(datasets,
                                                                       model_structure,
                                                                       model_order,

examples/results/nmc_with_temperature/model_n,l=3,3.npy

@@ -15,7 +15,7 @@
 
 from .typeddicts import CurrentVoltageData
 from .dataclasses import VoltageFunction, Model, BasisFunction
-from .basisfunctions import generate_signals
+from .basisfunctions import Operation, generate_signals
 from .plotter import plot_custom
 
 
@@ -110,7 +110,12 @@ def save_model_to_file(model: Model, path_to_directory: str, description: str):
     file_name = f'{description}_n,l={model.model_order},{model.nonlinearity_order}'
     file_path = f'{path_to_directory}/{file_name}'
 
-    np.save(file_path, asdict(model)) # type: ignore
+    model_as_dict = asdict(model)
+    # Change enum to its value
+    for bf in model_as_dict['basis_functions']:
+        bf['operation'] = bf['operation'].value
+    #
+    np.save(file_path, model_as_dict) # type: ignore
 
 
 def load_model_from_file(file_path: str):
@@ -120,9 +125,14 @@ def load_model_from_file(file_path: str):
     try:
         model = Model(**model_as_dict)
         # Load basis functions
-        model.basis_functions = [BasisFunction(**bf) for bf in model_as_dict['basis_functions']]
-        model.hysteresis_basis_functions = [BasisFunction(**hbf)
-                                            for hbf in model_as_dict['hysteresis_basis_functions']]
+        model.basis_functions = [
+            BasisFunction(**{**bf, 'operation': Operation(bf['operation'])})
+            for bf in model_as_dict['basis_functions']
+        ]
+        model.hysteresis_basis_functions = [
+            BasisFunction(**{**hbf, 'operation': Operation(hbf['operation'])})
+            for hbf in model_as_dict['hysteresis_basis_functions']
+        ]
         # Load voltage functions
         model.emf_function = VoltageFunction(**model_as_dict['emf_function'])
         if model_as_dict['hysteresis_function'] is not None: