Battery Data Schemas

The metadata schemas used by batdata standardize how we describe the source of battery datasets. Metadata are held as part of the BatteryDataset object and saved within the file formats produced by batdata to ensure that the provenance of a dataset is kept alongside the actual data.

Understanding the Metadata

The metadata we employ in batdata follows the style of the JSON or XML data structures which are ubiquitous in scientific computation and data infrastructure. Each record is composed of a single document that has a hierarchical set of fields which can correspond to single values or collections of values.

We recommend creating the metadata for a battery through the Python interface. Start by creating a BatteryMetadata object. There are no required fields, but you should always give your data a name.

from batdata.schemas import BatteryMetadata

metadata = BatteryMetadata(
    name='test-cell',
)

The metadata is a nested document where different types of information are grouped together into sub objects. For example, the details about the battery being tested are in BatteryDescription

from batdata.schemas.battery import BatteryDescription
from batdata.schemas import BatteryMetadata

metadata = BatteryMetadata(
    name='test-cell',
    battery=BatteryDescription(
        manufacturer='famous',
        nominal_capacity=1.,
    )
)

Components

We use a component-based approach for the metadata about a dataset.

See the schemas for a full accounting of the available fields in our schema.

BatteryMetadata

Source Object: batdata.schemas.BatteryMetadata

Representation for the metadata about a battery

The metadata captures the information about what experiment was run on what battery. A complete set of metadata should be sufficient to reproduce an experiment.

Column	Type	Description
name	str	Name of the cell. Any format for the name is acceptable, as it is intended to be used by the battery data provider.
comments	str	Long form comments describing the test
version	str	(Required) Version of this metadata. Set by the battery-data-toolkit
is_measurement	bool	(Required) Whether the data was created observationally as opposed to a computer simulation
cycler	str	Name of the cycling machine
start_date	date	Date the initial test on the cell began
set_temperature	float	Set temperature for the battery testing equipment. Units: C
schedule	str	Schedule file used for the cycling machine
battery	BatteryDescription	Description of the battery being tested
modeling	ModelMetadata	Description of simulation approach
source	str	Organization who created this data
dataset_name	str	Name of a larger dataset this data is associated with
authors	typing.List[typing.Tuple[str, str]]	Name and affiliation of each of the authors of the data. First and last names
associated_ids	typing.List[pydantic_core._pydantic_core.Url]	Any identifiers associated with this data file. Identifiers can be any URI, such as DOIs of associated paper or HTTP addresses of associated websites
raw_data_columns	str, str	Descriptions of non-standard columns in the raw data
cycle_stats_columns	str, str	Descriptions of non-standard columns in the cycle stats
eis_data_columns	str, str	Descriptions of non-standard columns in the EIS data

BatteryDescription

Source Object: batdata.schemas.battery.BatteryDescription

Description of the entire battery

Column	Type	Description
manufacturer	str	Manufacturer of the battery
design	str	Name of the battery type, such as the battery product ID
layer_count	int	Number of layers within the battery
form_factor	str	The general shape of the battery
mass	float	Mass of the entire battery. Units: kg
dimensions	typing.List[float]	Dimensions of the battery in plain text.
anode	ElectrodeDescription	Name of the anode material
cathode	ElectrodeDescription	Name of the cathode material
electrolyte	ElectrolyteDescription	Name of the electrolyte material
nominal_capacity	float	Rated capacity of the battery. Units: A-hr

ElectrodeDescription

Source Object: batdata.schemas.battery.ElectrodeDescription

Description of an electrode

Column	Type	Description
name	str	Short description of the electrolyte type
supplier	str	Manufacturer of the material
product	str	Name of the product. Unique to the supplier
thickness	float	Thickness of the material (units: μm)
area	float	Total area of the electrode (units: cm2)
loading	float	Amount of active material per area (units: mg/cm^2)
porosity	float	Relative volume of the electrode occupied by gas (units: %)

ElectrolyteDescription

Source Object: batdata.schemas.battery.ElectrolyteDescription

Description of the electrolyte

Column	Type	Description
name	str	Short description of the electrolyte types
additives	ElectrolyteAdditive	Any additives present in the electrolyte

ElectrolyteAdditive

Source Object: batdata.schemas.battery.ElectrolyteAdditive

Additive to the electrolyte

Column	Type	Description
name	str	Name of the additive
amount	float	Amount added to the solution
units	float	Units of the amount

ModelMetadata

Source Object: batdata.schemas.modeling.ModelMetadata

Describe the type and version of a computational tool used to generate battery data

Column	Type	Description
name	str	Name of the software
version	str	Version of the software if known
type	ModelTypes	Type of the computational method it implements.
references	typing.List[pydantic_core._pydantic_core.Url]	List of references associated with the software
models	typing.List[str]	Type of mathematical model(s) being used in physics simulation.Use terms defined in BattINFO, such as “BatteryEquivalentCircuitModel”.
simulation_type	str	Type of simulation being performed. Use terms defined in BattINFO, such as “TightlyCoupledModelsSimulation”

Source of Terminology

We use terms from BattINFO ontology wherever possible.

Fields in the schema whose names correspond to a BattINFO term are marked with the “IRI” of the field, which points to a website containing the description.

Fields whose values should be terms from the BattINFO ontology are marked with the root of the terms. For example, the model_type field of ModelMetadata can be any type of MathematicalModel. Look them up using some utilities in batdata.

from batdata.schemas.ontology import gather_descendants

print(gather_descendants('MathematicalModel'))

Feel free to add fields to any part of the schema. The schema is a continual work in progress and the battery-data-toolkit will store your new fields. Consider adding an Issue to our GitHub if you find you use a term enough that we should add it to the schema.

Column Datasets

The columns of datasets are described in the cycling module.

Use the descriptions here when formatting your dataset, playing attention to the sign conventions and units for each column.

Record columns that are not defined in our schema in the *_columns fields of the BatteryMetadata.

from batdata.schemas import BatteryMetadata

metadata = BatteryMetadata(
    name='test_cell',
    raw_data_columns={'new_signal': 'A column not yet defined in our schemas.'}
)

RawData

Source Object: batdata.schemas.cycling.RawData

Schema for the time series data.

Column	Description
cycle_number	Index of the testing cycle, starting at 0. All indices should be nonnegative and be monotonically increasing
step_index	Index of the step number within a testing cycle. A step change is defined by a change states between charging, discharging, or resting.
file_number	Used if test data is stored in multiple files. Number represents the index of the file. All indices should be nonnegative and monotonically increasing
test_time	Time from the beginning of the cycling test. Times must be nonnegative and monotonically increasing. Units: s
cycle_time	Time from the beginning of a cycle. Units: s
time	Time as a UNIX timestamp. Assumed to be in UTC
voltage	Measured voltage of the system. Units: V
current	Measured current of the system. Positive current represents the battery discharging and negative represents the batterycharging. Units: A
state	Determination of whether the battery is being charged, discharged or held at a constant charge
method	List of the method used to control the battery system
temperature	Temperature of the battery. Units: C
internal_resistance	Internal resistance of the battery. Units: ohm
substep_index	Index of the substep within a testing cycle. A substep change is defined by a change of the charging or discharging method, such as change from constant voltage to constant current
cycle_capacity	Cumulative change in amount of charge transferred from a battery since the start of a cycle. Positive values indicate the battery has discharged since the start of the cycle.
cycle_energy	Cumulative change in amount of energy transferred from a battery the start of a cycle. Positive values indicate the battery has discharged more than since the start of the cycle.
cycle_capacity_charge	Cycle capacity computed only during the ‘charging’ phase of a cycle
cycle_capacity_discharge	Cycle capacity computed only during the ‘discharging’ phase of a cycle

CycleLevelData

Source Object: batdata.schemas.cycling.CycleLevelData

Statistics about the performance of a cell over a certain cycle

Column	Description
cycle_number	Index of the cycle
cycle_start	Time since the first data point recorded for this battery for the start of this cycle. Units: s
cycle_duration	Duration of this cycle. Units: s
capacity_discharge	Total amount of electrons released during discharge. Units: A-hr
energy_discharge	Total amount of energy released during discharge. Units: W-hr
capacity_charge	Total amount of electrons stored during charge. Units: A-hr
energy_charge	Total amount of energy stored during charge. Units: W-hr
coulomb_efficiency	Fraction of electric charge that is lost during charge and recharge. Units: %
energy_efficiency	Amount of energy lost during charge and discharge
discharge_V_average	Average voltage during discharging. Units: V
charge_V_average	Average voltage during charge. Units: V
V_maximum	Maximum voltage during cycle. Units: V
V_minimum	Minimum voltage during cycle. Units: V
discharge_I_average	Average current during discharge. Units: A
charge_I_average	Average current during charge. Units: A
temperature_minimum	Minimum observed battery temperature during cycle. Units: C
temperature_maximum	Maximum observed battery temperature during cycle. Units: C
temperature_average	Average observed battery temperature during cycle. Units: C