matador.battery package

This module implements the Electrode class used for calculating relevant electrode properties from phase diagrams.

class matador.battery.Electrode[source]

Bases: object

The Electrode class wraps phase diagrams of battery electrode materials, and provides useful methods for electrochemical analysis.

Note

The units for relevant quantities are as follows:

  • gravimetric capacity –> mAh/g

  • volumetric capacity –> mAh/cm^3

  • gravimetric energy density –> Wh/kg

  • volumetric energy density –> Wh/l

kind

either ‘anode’ or ‘cathode’. Effects conventions used when computing capacities.

Type:

str

ion

species label for the active ion.

Type:

str

valence

number of electrons transferred per ion inserted/ removed. Currently assumes perfect Coulombic efficiency, and full oxidation at each stage (e.g. Li->Li+ and Mg->Mg2+).

Type:

int

valence_data = {'Ca': 2, 'K': 1, 'Li': 1, 'Mg': 2, 'Na': 1}

This comment contains some stubs for functionality that has not yet been implemented.

def __init__(self, active_ion, base_material, phases, kind=’anode’, valence=None):

“”” Initialise Electrode material for the given ion from a convex hull.

Parameters:

active_ion (str): label of species to use as active ion. base_formula (str): formula of the starting material (either

“empty” anode or “full” cathode).

phases (QueryConvexHull/list of dict):

either a QueryConvexHull object for the material system of interest, or a list of phases.

Keyword arguments:
kind (str): either ‘anode’ or ‘cathode’. This decides what

convention to use when computing capacities.

valence (int): the valence of the active ion, if not included

this will be looked up for common ions.

“””

if kind not in self._kinds:

raise TypeError(‘Electrode kind must be one of {}’.format(self._kinds))

self.kind = kind self.ion = active_ion

if valence is not None:

self.valence = valence

else:

self.valence = self._valence_data.get(‘active_ion’)

if self.valence is None:
raise RuntimeError(‘Unable to lookup valence of {}, please pass it manually’

.format(self.ion))

# TODO: detect different materials inside convex hull # or directly compute if just a list of phases

@property def gravimetric_capacities(self):

pass

@property def volumetric_capacities(self):

pass

@property def voltages(self):

pass

@property def average_voltage(self):

pass

@property def gravimetric_energy_density(self):

pass

@property def volumetric_energy_density(self):

pass

@property def max_gravimetric_capacity(self):

pass

@property def max_volumetric_capacity(self):

pass

@property def voltage_curve(self):

pass

@property def pdf_vs_voltage(self):

pass

@property def pdf_vs_capacity(self):

pass

@property def pxrd_vs_voltage(self):

pass

@property def pxrd_vs_capacity(self):

pass

classmethod calculate_average_voltage(capacities, voltages)[source]

For a given set of capacities and voltages, compute the average voltage during charge/discharge.

classmethod calculate_energy_density(capacities, voltages) → float[source]

Compute the energy density in Wh/kg from the maximum capacity and the average voltage.

class matador.battery.VoltageProfile(starting_stoichiometry: Tuple[Tuple[str, float], ...], capacities: List[float], voltages: List[float], average_voltage: float, active_ion: str, reactions: List[Tuple[Tuple[float, str], ...]])[source]

Bases: object

Container class for data associated with a voltage profile.

starting_stoichiometry

the initial stoichiometry of the electrode.

capacities

list of gravimetric capacities in mAh/g.

voltage

list of voltages at each capacity step.

average_voltage

the average voltage across the full cycle.

reactions

a list of (coefficient, formula) tuples showing the progression of the balanced reaction, e.g. [((1, "PSn")), ((1, "LiP"), (1, "LiSn"))]

active_ion

species label of the active ion.

Initialise the voltage profile with the given data.

voltage_summary(csv=False)[source]

Prints a voltage data summary.

Keyword Arguments:

csv (bool/str) – whether or not to write a CSV file containing the data. If this contains a string use this as the filename.

Submodules

matador.battery.electrode module

This module implements the Electrode class, which contains methods used for calculating electrode properties from phase diagrams.

class matador.battery.electrode.Electrode[source]

Bases: object

The Electrode class wraps phase diagrams of battery electrode materials, and provides useful methods for electrochemical analysis.

Note

The units for relevant quantities are as follows:

  • gravimetric capacity –> mAh/g

  • volumetric capacity –> mAh/cm^3

  • gravimetric energy density –> Wh/kg

  • volumetric energy density –> Wh/l

kind

either ‘anode’ or ‘cathode’. Effects conventions used when computing capacities.

Type:

str

ion

species label for the active ion.

Type:

str

valence

number of electrons transferred per ion inserted/ removed. Currently assumes perfect Coulombic efficiency, and full oxidation at each stage (e.g. Li->Li+ and Mg->Mg2+).

Type:

int

valence_data = {'Ca': 2, 'K': 1, 'Li': 1, 'Mg': 2, 'Na': 1}

This comment contains some stubs for functionality that has not yet been implemented.

def __init__(self, active_ion, base_material, phases, kind=’anode’, valence=None):

“”” Initialise Electrode material for the given ion from a convex hull.

Parameters:

active_ion (str): label of species to use as active ion. base_formula (str): formula of the starting material (either

“empty” anode or “full” cathode).

phases (QueryConvexHull/list of dict):

either a QueryConvexHull object for the material system of interest, or a list of phases.

Keyword arguments:
kind (str): either ‘anode’ or ‘cathode’. This decides what

convention to use when computing capacities.

valence (int): the valence of the active ion, if not included

this will be looked up for common ions.

“””

if kind not in self._kinds:

raise TypeError(‘Electrode kind must be one of {}’.format(self._kinds))

self.kind = kind self.ion = active_ion

if valence is not None:

self.valence = valence

else:

self.valence = self._valence_data.get(‘active_ion’)

if self.valence is None:
raise RuntimeError(‘Unable to lookup valence of {}, please pass it manually’

.format(self.ion))

# TODO: detect different materials inside convex hull # or directly compute if just a list of phases

@property def gravimetric_capacities(self):

pass

@property def volumetric_capacities(self):

pass

@property def voltages(self):

pass

@property def average_voltage(self):

pass

@property def gravimetric_energy_density(self):

pass

@property def volumetric_energy_density(self):

pass

@property def max_gravimetric_capacity(self):

pass

@property def max_volumetric_capacity(self):

pass

@property def voltage_curve(self):

pass

@property def pdf_vs_voltage(self):

pass

@property def pdf_vs_capacity(self):

pass

@property def pxrd_vs_voltage(self):

pass

@property def pxrd_vs_capacity(self):

pass

classmethod calculate_average_voltage(capacities, voltages)[source]

For a given set of capacities and voltages, compute the average voltage during charge/discharge.

classmethod calculate_energy_density(capacities, voltages) → float[source]

Compute the energy density in Wh/kg from the maximum capacity and the average voltage.

class matador.battery.electrode.VoltageProfile(starting_stoichiometry: Tuple[Tuple[str, float], ...], capacities: List[float], voltages: List[float], average_voltage: float, active_ion: str, reactions: List[Tuple[Tuple[float, str], ...]])[source]

Bases: object

Container class for data associated with a voltage profile.

starting_stoichiometry

the initial stoichiometry of the electrode.

capacities

list of gravimetric capacities in mAh/g.

voltage

list of voltages at each capacity step.

average_voltage

the average voltage across the full cycle.

reactions

a list of (coefficient, formula) tuples showing the progression of the balanced reaction, e.g. [((1, "PSn")), ((1, "LiP"), (1, "LiSn"))]

active_ion

species label of the active ion.

Initialise the voltage profile with the given data.

voltage_summary(csv=False)[source]

Prints a voltage data summary.

Keyword Arguments:

csv (bool/str) – whether or not to write a CSV file containing the data. If this contains a string use this as the filename.