Active Materials¶
Active materials define the electrochemistry of a cell. Each material wraps one or more half-cell voltage–capacity curves and exposes properties like reversible specific capacity, density, and cost.
Most active materials can be loaded from the database:
cathode = ocd.CathodeMaterial.from_database("NMC811")
anode = ocd.AnodeMaterial.from_database("Synthetic Graphite")
Active material definitions with half-cell voltage-capacity curves.
Classes¶
CathodeMaterial(name: str, reference: str, specific_cost: float, density: float, specific_capacity_curves: Union[List[DataFrame], DataFrame], color: str = '#2c2c2c', voltage_cutoff: Optional[float] = None, extrapolation_window: float = 0.4, reversible_specific_capacity_scaling_percentage: float = 0.0, irreversible_specific_capacity_scaling_percentage: float = 0.0, *, volume=None, mass=None, **kwargs)
Bases: _ActiveMaterial
Cathode active material with half-cell voltage-capacity curve data.
Inherits capacity curve processing from _ActiveMaterial and adds
cathode-specific voltage cutoff handling.
Initialize an object that represents a cathode material.
Parameters¶
name : str Name of the material. reference : str Reference electrode for the material, e.g., 'Li/Li+'. specific_cost : float Specific cost of the material in $/kg. density : float Density of the material in g/cm^3. specific_capacity_curves : Union[List[pd.DataFrame], pd.DataFrame] Half cell curves for the material, either as a list of pandas DataFrames or a single DataFrame. voltage_cutoff : float The voltage cutoff for the half cell curves in V. This is the maximum voltage at which the half cell curve will be calculated. extrapolation_window : float The negative voltage extrapolation window in V. This is the amount of voltage below the minimum voltage of the half cell curves that will be used for extrapolation. This is useful for cathode materials where the voltage can go below 0V, e.g., for Li-ion batteries. color : str Color of the material, used for plotting. reversible_specific_capacity_scaling_percentage : float Percentage adjustment for the reversible capacity of the material. Default is 0.0 (no change). Positive values increase capacity (e.g., 10 = 10% increase), negative values decrease it (e.g., -10 = 10% decrease). irreversible_specific_capacity_scaling_percentage : float Percentage adjustment for the irreversible capacity of the material. Default is 0.0 (no change). Positive values increase capacity (e.g., 10 = 10% increase), negative values decrease it (e.g., -10 = 10% decrease).
AnodeMaterial(name: str, reference: str, specific_cost: float, density: float, specific_capacity_curves: Union[List[DataFrame], DataFrame], color: str = '#2c2c2c', extrapolation_window: float = 0.05, reversible_specific_capacity_scaling_percentage: float = 0.0, irreversible_specific_capacity_scaling_percentage: float = 0.0, *, volume=None, mass=None, **kwargs)
Bases: _ActiveMaterial
Anode active material with half-cell voltage-capacity curve data.
Inherits capacity curve processing from _ActiveMaterial and adds
anode-specific voltage cutoff handling.
Initialize an object that represents an anode material.
Parameters¶
name : str Name of the material. reference : str Reference electrode for the material, e.g., 'Li/Li+'. specific_cost : float Specific cost of the material in $/kg. density : float Density of the material in g/cm^3. specific_capacity_curves : Union[List[pd.DataFrame], pd.DataFrame] Half cell curves for the material, either as a list of pandas DataFrames or a single DataFrame. color : str Color of the material, used for plotting. extrapolation_window : float The positive voltage extrapolation window in V. This is the amount of voltage above the maximum voltage of the half cell curves that will be used for extrapolation. This is useful for anode materials where the voltage can go above 0V, e.g., for Li-ion batteries. reversible_specific_capacity_scaling_percentage : float Percentage adjustment for the reversible capacity of the material. Default is 0.0 (no change). Positive values increase capacity (e.g., 10 = 10% increase), negative values decrease it (e.g., -10 = 10% decrease). irreversible_specific_capacity_scaling_percentage : float Percentage adjustment for the irreversible capacity of the material. Default is 0.0 (no change). Positive values increase capacity (e.g., 10 = 10% increase), negative values decrease it (e.g., -10 = 10% decrease).
Capacity Curve Utilities¶
Helper functions for manipulating and combining voltage–capacity curves.
Utilities for processing, interpolating, and scaling half-cell voltage-capacity curves.
Classes¶
Mixin providing static methods for processing half-cell voltage-capacity curves.
Handles curve direction correction, monotonicity enforcement, interpolation, truncation, and reversible/irreversible capacity scaling.
Methods:¶
staticmethod
¶
Normalize and prepare raw half-cell curves for downstream use.
Steps include unit conversion, direction validation, monotonic cleanup, reversing the discharge curve, and ensuring both segments share a common point.
Parameters¶
curve : np.ndarray Experimental curve data ordered as [specific_capacity, voltage, direction]. Capacity must be in mAh/g before conversion.
Returns¶
np.ndarray Processed curve ready for property calculations.