pymatgen.apps.battery.battery_abc module

class AbstractElectrode[source]

Bases: collections.abc.Sequence, monty.json.MSONable

An Abstract Base Class representing an Electrode. It is essentially a sequence of VoltagePairs. Generally, subclasses only need to implement three abstract properties: voltage_pairs, working_ion and working_ion_entry.

The general concept is that all other battery properties such as capacity, etc. are derived from voltage pairs.

One of the major challenges with representing battery materials is keeping track of the normalization between different entries. For example, one entry might be TiO2 with one unit cell whereas another is LiTi2O4 with two unit cells. When computing battery properties, it is needed to always use a universal reference state otherwise you have normalization errors (e.g., the energy of LiTi2O4 must be divided by two to be compared with TiO2).

For properties such as volume, mass, or mAh transferred within the voltage pair, a universal convention is necessary. AbstractElectrode can query for extrinsic properties of several different AbstractVoltagePairs belonging to a single charge/discharge path and be confident that the normalization is being carried out properly throughout, even if more AbstractVoltagePairs are added later.

The universal normalization is defined by the reduced structural framework of the entries, which is common along the entire charge/discharge path. For example, LiTi2O4 has a reduced structural framework of TiO2. Another example is Li9V6P16O58 which would have a reduced structural framework of V3P8O29. Note that reduced structural frameworks need not be charge-balanced or physical, e.g. V3P8O29 is not charge-balanced, they are just a tool for normalization.

Example: for a LiTi2O4 -> TiO2 AbstractVoltagePair, extrinsic quantities like mAh or cell volumes are given per TiO2 formula unit.

Developers implementing a new battery (other than the two general ones already implemented) need to implement a VoltagePair and an Electrode.

get_average_voltage(min_voltage=None, max_voltage=None)[source]

Average voltage for path satisfying between a min and max voltage.

Parameters:
  • min_voltage (float) – The minimum allowable voltage for a given step.
  • max_voltage (float) – The maximum allowable voltage allowable for a given step.
Returns:

Average voltage in V across the insertion path (a subset of the path can be chosen by the optional arguments)

get_capacity_grav(min_voltage=None, max_voltage=None, use_overall_normalization=True)[source]

Get the gravimetric capacity of the electrode.

Parameters:
  • min_voltage (float) – The minimum allowable voltage for a given step.
  • max_voltage (float) – The maximum allowable voltage allowable for a given step.
  • use_overall_normalization (booL) – If False, normalize by the discharged state of only the voltage pairs matching the voltage criteria. if True, use default normalization of the full electrode path.
Returns:

Gravimetric capacity in mAh/g across the insertion path (a subset of the path can be chosen by the optional arguments).

get_capacity_vol(min_voltage=None, max_voltage=None, use_overall_normalization=True)[source]

Get the volumetric capacity of the electrode.

Parameters:
  • min_voltage (float) – The minimum allowable voltage for a given step.
  • max_voltage (float) – The maximum allowable voltage allowable for a given step.
  • use_overall_normalization (booL) – If False, normalize by the discharged state of only the voltage pairs matching the voltage criteria. if True, use default normalization of the full electrode path.
Returns:

Volumetric capacity in mAh/cc across the insertion path (a subset of the path can be chosen by the optional arguments)

get_energy_density(min_voltage=None, max_voltage=None, use_overall_normalization=True)[source]
Parameters:
  • min_voltage (float) – The minimum allowable voltage for a given step.
  • max_voltage (float) – The maximum allowable voltage allowable for a given step.
  • use_overall_normalization (booL) – If False, normalize by the discharged state of only the voltage pairs matching the voltage criteria. if True, use default normalization of the full electrode path.
Returns:

Energy density in Wh/L across the insertion path (a subset of the path can be chosen by the optional arguments).

get_specific_energy(min_voltage=None, max_voltage=None, use_overall_normalization=True)[source]

Returns the specific energy of the battery in mAh/g.

Parameters:
  • min_voltage (float) – The minimum allowable voltage for a given step.
  • max_voltage (float) – The maximum allowable voltage allowable for a given step.
  • use_overall_normalization (booL) – If False, normalize by the discharged state of only the voltage pairs matching the voltage criteria. if True, use default normalization of the full electrode path.
Returns:

Specific energy in Wh/kg across the insertion path (a subset of the path can be chosen by the optional arguments)

max_delta_volume

Maximum volume change along insertion

max_voltage

Highest voltage along insertion

max_voltage_step

Maximum absolute difference in adjacent voltage steps

min_voltage

Lowest voltage along insertion

normalization_mass
normalization_volume
num_steps

The number of distinct voltage steps in from fully charge to discharge based on the stable intermediate states

voltage_pairs

Returns all the VoltagePairs

working_ion

The working ion as an Element object

working_ion_entry

The working ion as an Entry object

class AbstractVoltagePair[source]

Bases: object

An Abstract Base Class for a Voltage Pair.

frac_charge
frac_discharge
mAh
mass_charge
mass_discharge
vol_charge
vol_discharge
voltage
working_ion_entry