1.1.6. db

The db module implements an interface for retrieving cell specifications and model parameters. Data are read from a standardized cell database. The following sections explain how to access the information via the command-line tool and programmatically, and how to define the database format.

1.1.6.1. Usage

Important

The db module validates input data and exits with an error message if types or values are invalid, if linked sources are missing, or if duplicate cell identifiers are found.

The db module supports two main commands:

db list: Lists all available cells in the database.

Win32/PowerShellWin32/Git BashLinux

.\fox.ps1 db list \path\to\db-root

db show: Shows detailed information for a single cell by its identifier.

Win32/PowerShellWin32/Git BashLinux

.\fox.ps1 db show \path\to\db-root --cell-id "CELL-ID"

Note

The database root (db-root) can be:

• A directory containing subdirectories (one per cell), or

• A ZIP archive containing the same directory structure.

Note

The cell identifier is composed of <manufacturer>-<name>.

1.1.6.2. Download

To download the latest foxBMS 2 cell database and save it in your current working directory, use:

Win32/PowerShellWin32/Git BashLinux

curl "ftp://myftpsite/foxDB_latest.zip"

The naming pattern for the foxBMS 2 cell database is foxDB-<version>.zip, with <version> following Semantic Versioning (see versioning), or latest to indicate the most recent version of the cell database.

1.1.6.3. Database Format

The cell database is a (zipped) directory containing subdirectories for each cell. Each cell directory must contain the following structure:

cell-id

├── sources

│ ├── example_measurement_data.parquet

│ ├── …

│ └── example_source_parameter.npy

├── cell_spec.json

├── cell_datasheet.pdf

├── model_parameter.json

└── README.md

1.1.6.3.1. Sources

Place measurement data and complex model parameters in matrix form in the sources directory. These files are referenced from the corresponding sections in model_parameter.json. No mandatory file formats are specified for sources, but .parquet (for measurement data) and .npy (for matrices) are recommended.

Warning

The CLI exits with an error message if a linked source cannot be found.

1.1.6.3.2. Root

The root of the cell directory must contain at least the following four files:

• cell_spec.json: Specifications of the cell derived from cell_datasheet.pdf.

• cell_datasheet.pdf: Specifications provided by the manufacturer.

• model_parameter.json: Model parameters (e.g., current limits).

• README.md: Detailed information about all supported models, the parameters they use and model sources.

1.1.6.3.3. Cell Specification

Each cell must provide a cell_spec.json with the following fields:

Table 1.9 Mandatory Cell Specifications

Field	Type	Description	Constraints
name	str	Cell model/name	required
manufacturer	str	Cell manufacturer	required
shape	str	e.g., “cylindrical”, “prismatic”	required
chemistry	str	e.g., “NMC”, “LFP”	required
height	float	Physical height	required
length	float	Physical length	required
width	float	Physical width	required; if shape == "cylindrical", must equal length
weight	float	Mass of the cell	required
temperature_max	float	Maximum allowed temperature	must be >= temperature_min
temperature_min	float	Minimum allowed temperature	must be <= temperature_max
voltage_min	float	Minimum allowed voltage	must be <= voltage_max
voltage_max	float	Maximum allowed voltage	must be >= voltage_min
voltage_nom	float	Nominal cell voltage	must be >= voltage_min and <= voltage_max

Listing 1.11 Example cell_spec.json

{
  "name": "INR18650-MJ1",
  "manufacturer": "LG Chem",
  "shape": "cylindrical",
  "chemistry": "NMC",
  "height": 65.3,
  "length": 18.4,
  "width": 18.4,
  "weight": 48.5,
  "temperature_max": 60.0,
  "temperature_min": -20.0,
  "voltage_min": 2.5,
  "voltage_max": 4.2,
  "voltage_nom": 3.7
}

Important

All values in the cell specifications must be in SI base units.

1.1.6.3.4. Model Parameters

The model_parameter.json defines the parameters of each model attached to a cell. Parameters are provided as dictionaries containing the mandatory keys name and sources. Each dictionary is an element of a list of model parameters. Below is an example of parameters of a "current limits" model, which describes charge and discharge current limits as a function of temperature.

Listing 1.12 Example model_parameter.json

[
  {
    "name": "current limits",
    "sources": [
      "cell_datasheet.pdf"
    ],
    "charge": {
      "current": [
        1.0,
        2.0,
        3.0
      ],
      "temperatures": [
        0.0,
        25.0,
        40.0
      ]
    },
    "discharge": {
      "current": [
        2.0,
        3.0,
        4.0
      ],
      "temperatures": [
        0.0,
        25.0,
        40.0
      ]
    }
  }
]

1.1.6.4. API

The db module provides, for each cell, a Cell dataclass with two attributes:

• cell_spec: The specifications of the cell as a dataclass (CellSpec).

• model_parameters: A list of dataclasses (BaseModel) containing the parameters of each available model.

To obtain a Cell dataclass for a specific cell in the database and use it in another tool:

1. Import the cli.db.FoxDB class.

2. Create a FoxDB instance with a valid database root.

3. Access FoxDB.cells, which is a list of Cell instances.

Listing 1.13 Example Usage of the FoxDB API

"""Example API Usage"""

from pathlib import Path

from cli.db import FoxDB


def main() -> None:
    """Main of the example API usage"""
    root_db = Path("path/to/your/foxDB-latest.zip")
    db = FoxDB(root_db)
    # print all available cell in FoxDB
    print(db.cells)  # noqa: T201


if __name__ == "__main__":
    main()

1.1.6.5. Adding Cells and Models

New cells can be added by creating an additional cell directory in the database root directory with the required structure described above. To add new models (and their parameters), add a new Python file to cli/db/model_parameter. This Python file must define one or more dataclasses containing the model parameters, and the top-level dataclass must inherit from BaseModel in cli/db/model_parameter/__init__.py. It is recommended to use the __post_init__ method to validate each attribute of the dataclass. As last step, in the cli/db/setup.py the creates_models method must be modified to add the new model parameters to the Cell instances.

1.1.6.6. Validation

To validate a database directory or archive, run db list. It will parse all cells and report errors for invalid types/values, missing linked sources, or duplicate cell identifiers.

1.1.6.7. Architecture