Schemas (batdata.schemas)#

Schemas for battery data and metadata

pydantic model batdata.schemas.BatteryMetadata#

Bases: BaseModel

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.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Config:

  • extra: str = allow

Fields:
field associated_ids: List[Url] | None = None#

Any identifiers associated with this data file. Identifiers can be any URI, such as DOIs of associated paper or HTTP addresses of associated websites

field authors: List[Tuple[str, str]] | None = None#

Name and affiliation of each of the authors of the data. First and last names

field battery: BatteryDescription | None = None#

Description of the battery being tested

field comments: str | None = None#

Long form comments describing the test

field cycle_stats_columns: Dict[str, str] [Optional]#

Descriptions of non-standard columns in the cycle stats

field cycler: str | None = None#

Name of the cycling machine

field dataset_name: str | None = None#

Name of a larger dataset this data is associated with

field eis_data_columns: Dict[str, str] [Optional]#

Descriptions of non-standard columns in the EIS data

field is_measurement: bool = True#

Whether the data was created observationally as opposed to a computer simulation

field modeling: ModelMetadata | None = None#

Description of simulation approach

field name: str | None = None#

Name of the cell. Any format for the name is acceptable, as it is intended to be used by the battery data provider.

field raw_data_columns: Dict[str, str] [Optional]#

Descriptions of non-standard columns in the raw data

field schedule: str | None = None#

Schedule file used for the cycling machine

field set_temperature: float | None = None#

Set temperature for the battery testing equipment. Units: C

field source: str | None = None#

Organization who created this data

field start_date: date | None = None#

Date the initial test on the cell began

field version: str = '0.3.3'#

Version of this metadata. Set by the battery-data-toolkit

Battery Description (b.schemas.battery)#

Schemas associated with the components of a battery

pydantic model batdata.schemas.battery.BatteryDescription#

Bases: BaseModel

Description of the entire battery

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Config:

  • extra: str = allow

Fields:
field anode: ElectrodeDescription | None = None#

Name of the anode material

field cathode: ElectrodeDescription | None = None#

Name of the cathode material

field design: str | None = None#

Name of the battery type, such as the battery product ID

field dimensions: List[float] | None = None#

Dimensions of the battery in plain text.

field electrolyte: ElectrolyteDescription | None = None#

Name of the electrolyte material

field form_factor: str | None = None#

The general shape of the battery

field layer_count: int | None = None#

Number of layers within the battery

Constraints:

  • gt = 1

field manufacturer: str | None = None#

Manufacturer of the battery

field mass: float | None = None#

Mass of the entire battery. Units: kg

field nominal_capacity: float | None = None#

Rated capacity of the battery. Units: A-hr

pydantic model batdata.schemas.battery.ElectrodeDescription#

Bases: BaseModel

Description of an electrode

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Config:

  • extra: str = allow

Fields:
field area: float | None = None#

Total area of the electrode (units: cm2)

Constraints:

  • ge = 0

field loading: float | None = None#

Amount of active material per area (units: mg/cm^2)

Constraints:

  • ge = 0

field name: str [Required]#

Short description of the electrolyte type

field porosity: float | None = None#

Relative volume of the electrode occupied by gas (units: %)

Constraints:

  • ge = 0

  • le = 100

field product: str | None = None#

Name of the product. Unique to the supplier

field supplier: str | None = None#

Manufacturer of the material

field thickness: float | None = None#

Thickness of the material (units: μm)

Constraints:

  • ge = 0

pydantic model batdata.schemas.battery.ElectrolyteAdditive#

Bases: BaseModel

Additive to the electrolyte

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Config:

  • extra: str = allow

Fields:
field amount: float | None = None#

Amount added to the solution

field name: str [Required]#

Name of the additive

field units: float | None = None#

Units of the amount

pydantic model batdata.schemas.battery.ElectrolyteDescription#

Bases: BaseModel

Description of the electrolyte

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Config:

  • extra: str = allow

Fields:
field additives: List[ElectrolyteAdditive] [Optional]#

Any additives present in the electrolyte

field name: str [Required]#

Short description of the electrolyte types

Metadata: Computation (b.schemas.modeling)#

Metadata which describes how data produced by models were generated

pydantic model batdata.schemas.modeling.ModelMetadata#

Bases: BaseModel

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

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Config:

  • extra: str = allow

Fields:
field models: List[str] | None = None#

Type of mathematical model(s) being used in physics simulation.Use terms defined in BattINFO, such as “BatteryEquivalentCircuitModel”.

field name: str [Required]#

Name of the software

field references: List[Url] | None = None#

List of references associated with the software

field simulation_type: str | None = None#

Type of simulation being performed. Use terms defined in BattINFO, such as “TightlyCoupledModelsSimulation”

field type: ModelTypes | None = None#

Type of the computational method it implements.

field version: str | None [Required]#

Version of the software if known

class batdata.schemas.modeling.ModelTypes(value)#

Bases: str, Enum

Type of computational method

data = 'data'#

A computational application that uses existing data to predict the behaviour of a system without providing a identifiable analogy with the original object.

IRI: https://w3id.org/emmo#EMMO_a4b14b83_9392_4a5f_a2e8_b2b58793f59b

empirical = 'empirical'#

A computational application that uses an empiric equation to predict the behaviour of a system without relying on the knowledge of the actual physical phenomena occurring in the object.

IRI: https://w3id.org/emmo#EMMO_67c70dcd_2adf_4e6c_b3f8_f33dd1512487

physics = 'physics'#

A computational application that uses a physical model to predict the behaviour of a system, providing a identifiable analogy with the original object.

IRI: https://w3id.org/emmo#EMMO_8d4962d7_9608_44f7_a2f1_82a4bb173f4a

Data: Time Series (b.schemas.cycling)#

Schemas related to describing cycling data

class batdata.schemas.cycling.ChargingState(value)#

Bases: str, Enum

Potential charging states of the battery:

  • charging: Battery is being charged

  • hold: Battery is neither charging nor discharging

  • discharging: Battery is being discharged

  • unknown: State was unable to be determined

charging = 'charging'#
discharging = 'discharging'#
hold = 'hold'#
unknown = 'unknown'#
pydantic model batdata.schemas.cycling.ColumnSchema#

Bases: BaseModel

Base class for schemas that describe the columns of a tabular dataset

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

classmethod validate_dataframe(data: DataFrame, allow_extra_columns: bool = True)#
class batdata.schemas.cycling.ControlMethod(value)#

Bases: str, Enum

Method used to control battery during a certain step

  • short_rest: A very short rest period. Defined as a step with 4 or fewer measurements with near-zero current

  • rest: An extended period of neither charging nor discharging

  • short_nonrest: A very short period of charging or discharging. Defined as a step with 4 or fewer measurements

    with at least one non-zero current.

  • constant_current: A step where the current is held constant

  • constant_voltage: A step where the voltage is held constant

  • other: A step that does not fit into any of the predefined categories

constant_current = 'constant_current'#
constant_power = 'constant_power'#
constant_voltage = 'constant_voltage'#
other = 'other'#
pulse = 'pulse'#
rest = 'rest'#
short_nonrest = 'short_nonrest'#
short_rest = 'short_rest'#
pydantic model batdata.schemas.cycling.CycleLevelData#

Bases: ColumnSchema

Statistics about the performance of a cell over a certain cycle

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Fields:
field V_maximum: List[float] = None#

Maximum voltage during cycle. Units: V

field V_minimum: List[float] = None#

Minimum voltage during cycle. Units: V

field capacity_charge: List[float] = None#

Total amount of electrons stored during charge. Units: A-hr

field capacity_discharge: List[float] = None#

Total amount of electrons released during discharge. Units: A-hr

field charge_I_average: List[float] = None#

Average current during charge. Units: A

field charge_V_average: List[float] = None#

Average voltage during charge. Units: V

field coulomb_efficiency: List[float] = None#

Fraction of electric charge that is lost during charge and recharge. Units: %

field cycle_duration: List[float] = None#

Duration of this cycle. Units: s

field cycle_number: List[int] [Required]#

Index of the cycle

field cycle_start: List[float] = None#

Time since the first data point recorded for this battery for the start of this cycle. Units: s

field discharge_I_average: List[float] = None#

Average current during discharge. Units: A

field discharge_V_average: List[float] = None#

Average voltage during discharging. Units: V

field energy_charge: List[float] = None#

Total amount of energy stored during charge. Units: W-hr

field energy_discharge: List[float] = None#

Total amount of energy released during discharge. Units: W-hr

field energy_efficiency: List[float] = None#

Amount of energy lost during charge and discharge

field temperature_average: List[float] = None#

Average observed battery temperature during cycle. Units: C

field temperature_maximum: List[float] = None#

Maximum observed battery temperature during cycle. Units: C

field temperature_minimum: List[float] = None#

Minimum observed battery temperature during cycle. Units: C

pydantic model batdata.schemas.cycling.RawData#

Bases: ColumnSchema

Schema for the time series data.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Fields:
field current: List[float] [Required]#

Measured current of the system. Positive current represents the battery discharging and negative represents the batterycharging. Units: A

field cycle_capacity: List[float] = None#

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.

field cycle_capacity_charge: List[float] = None#

Cycle capacity computed only during the ‘charging’ phase of a cycle

field cycle_capacity_discharge: List[float] = None#

Cycle capacity computed only during the ‘discharging’ phase of a cycle

field cycle_energy: List[float] = None#

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.

field cycle_number: List[int] = None#

Index of the testing cycle, starting at 0. All indices should be nonnegative and be monotonically increasing

field cycle_time: List[float] = None#

Time from the beginning of a cycle. Units: s

field file_number: List[int] = None#

Used if test data is stored in multiple files. Number represents the index of the file. All indices should be nonnegative and monotonically increasing

field internal_resistance: List[float] = None#

Internal resistance of the battery. Units: ohm

field method: List[ControlMethod] = None#

List of the method used to control the battery system

field state: List[ChargingState] = None#

Determination of whether the battery is being charged, discharged or held at a constant charge

field step_index: List[int] = None#

Index of the step number within a testing cycle. A step change is defined by a change states between charging, discharging, or resting.

field substep_index: List[int] = None#

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

field temperature: List[float] = None#

Temperature of the battery. Units: C

field test_time: List[float] [Required]#

Time from the beginning of the cycling test. Times must be nonnegative and monotonically increasing. Units: s

field time: List[float] = None#

Time as a UNIX timestamp. Assumed to be in UTC

field voltage: List[float] [Required]#

Measured voltage of the system. Units: V

Data: EIS (b.schemas.eis)#

Schemas associated with Electrochemical Impedance Spectroscopy

pydantic model batdata.schemas.eis.EISData#

Bases: ColumnSchema

Measurements for a specific EIS test

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Fields:
field frequency: List[float] [Required]#

Applied frequency. Units: Hz

field test_id: List[int] [Required]#

Integer used to identify rows belonging to the same experiment.

field test_time: List[float] = None#

Time from the beginning of the cycling test. Times must be nonnegative and monotonically increasing. Units: s

field time: List[float] = None#

Time as a UNIX timestamp. Assumed to be in UTC

field z_imag: List[float] [Required]#

Imaginary component of impedance. Units: Ohm

field z_mag: List[float] [Required]#

Magnitude of impedance. Units: Ohm

field z_phase: List[float] [Required]#

Phase angle of the impedance. Units: Degree

field z_real: List[float] [Required]#

Real component of impedance. Units: Ohm

classmethod validate_dataframe(data: DataFrame, allow_extra_columns: bool = True)#

Utility: Ontologies (b.schemas.ontology)#

Tools used for linking terms in our data format to the BattINFO ontology

class batdata.schemas.ontology.TermInfo(name: str, iri: str, elucidation: str | None)#

Bases: object

Information about a term as referenced from the BattINFO ontology

elucidation: str | None#

Explanation of the term

classmethod from_thing(thing: Thing)#
iri: str#

IRI of the term

name: str#

Name of the matching term

batdata.schemas.ontology.cross_reference_terms(model: Type[BaseModel]) → dict[str, TermInfo]#

Gather the descriptions of fields from our schema which are cross-referenced to a term within the BattINFO/EMMO ontologies

Parameters:

model – Schema object to be cross-referenced

Returns:

Mapping between metadata fields in elucidation field from the ontology

batdata.schemas.ontology.gather_descendants(term: Type[Thing] | str) → List[TermInfo]#

Get descriptions of the descendants of a certain base type

Parameters:

term – Term for which to gather all descendants. Either the class object itself or its preferred label or IRI

Returns:

List of descriptions of the descendants

batdata.schemas.ontology.load_battinfo()#

Download and store the latest ontology into an in-memory

batdata.schemas.ontology.resolve_term(name_or_iri: str) → Thing#

Resolve the Term object associated with a string

Parameters:

name_or_iri – The preferred label or the IRI of a term in the ontology

Returns:

Thing matching the term

On this page
Show Source