Source Metadata#
‘’Source Metadata’’ captures high-level information about a battery dataset
in the BatteryMetadata object.
Information included in BatteryMetadata, in contrast to Column Schemas, are relevant to
all measurements performed on a battery, such as:
The type of battery (e.g., NMC Li-ion, Pb acid)
The simulation code used, if the data is from a model
How the battery was cycled
The authors of the data and any related publications
Metadata Structure#
BatteryMetadata objects have a hierarchical structure where
each record is composed of a single document that has fields which can correspond
to single values, collections of values, or entire sub-documents.
Create new metadata through the Python interface by first creating a BatteryMetadata object.
from battdat.schemas import BatteryMetadata
metadata = BatteryMetadata(
name='test-cell',
)
Different types of information are grouped together into subdocuments,
such as details about the battery in BatteryDescription
from battdat.schemas.battery import BatteryDescription
from battdat.schemas import BatteryMetadata
metadata = BatteryMetadata(
name='test-cell',
battery=BatteryDescription(
manufacturer='famous',
nominal_capacity=1.,
)
)
BatteryMetadata automatically validate inputs,
and can convert to and JSON formats. (Pydantic!)
See the battdat.schemas for a full accounting of the available fields in our schema.
Note
Validation only checks that already-defined fields are specified properly. Add metadata beyond what is described in battery-data-toolkit as desired.
Source of Terminology#
The BattINFO ontology is the core source of terms.
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 battdat.
from battdat.schemas.ontology import gather_descendants
print(gather_descendants('MathematicalModel'))
Note
The schema will be a continual work in progress. Consider adding an Issue to the GitHub if you find you use a term enough it should be part of the schema.
Metadata Objects#
The battery-data-toolkit expresses the metadata schema using Pydantic BaseModel objects.
High-level Data#
All metadata starts with the BatteryMetadata object.
BatteryMetadata#
Source Object: battdat.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 |
test_protocol |
CyclingProtocol |
Method used to |
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.networks.AnyUrl] |
Any identifiers associated with this data file. Identifiers can be any URI, such as DOIs of associated paper or HTTP addresses of associated websites |
Describing Batteries#
BatteryDescription and its related class capture details about the structure of a battery.
BatteryDescription#
Source Object: battdat.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 |
ElectrolyteDescription#
Source Object: battdat.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: battdat.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 |
ElectrodeDescription#
Source Object: battdat.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: um) |
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: %) |
Simulation Data#
ModelMetadata and its related class capture details about data produces using computational methods.
ModelMetadata#
Source Object: battdat.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.networks.AnyUrl] |
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” |
Cycling Data#
Annotate how batteries were cycled following protocol description objects.
CyclingProtocol#
Source Object: battdat.schemas.cycling.CyclingProtocol
Test protocol for cell cycling
Column |
Type |
Description |
|---|---|---|
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 |