Skip to content

Formulations

Electrode formulations blend active materials, binders, and conductive additives by weight percentage. The formulation computes a blended density, specific cost, and composite specific capacity curve from its constituents.

cathode_formulation = ocd.CathodeFormulation(
    active_materials={cathode_active: 95},       # weight %
    binders={binder: 2},
    conductive_additives={conductive_additive: 3},
)

Formulations

Electrode formulation definitions combining active materials, binders, and conductive additives.

Blending rule

A formulation is a list of (component, mass_fraction) pairs for three collections:

  • active_materials — store or source lithium and contribute to capacity.
  • binders — mechanical/chemical support, non-capacity contributors.
  • conductive_additives — improve electronic conductivity, non-capacity contributors.

All mass fractions are internally stored in the range [0, 1]. The public *_weight properties expose them as percentages ([0, 100]). The sum of all fractions across active materials, binders, and conductive additives must equal 1.0 within MASS_FRACTION_SUM_TOLERANCE (see Utils.Constants).

Blended properties are computed with the following rules:

  • Density: volume additivity, 1/rho = sum(w_i / rho_i).
  • Specific cost: mass-weighted sum, c = sum(c_i * w_i).
  • Colour: mass-weighted RGB.
  • Specific capacity curve: for a single active material, its curve scaled by the active material's mass fraction. For multiple active materials the common charge and discharge voltage windows are resampled on a grid of VOLTAGE_BLEND_GRID_POINTS points (see Utils.Constants); each material's weighted contribution is interpolated onto the grid and summed.

Indexed slot properties

Each formulation exposes a fixed number of indexed slot properties (active_material_1, active_material_2, active_material_3, binder_1, binder_2, conductive_additive_1, conductive_additive_2) that map to slots in the underlying dict. These names are required by PropagationMixin — child objects store the name of their slot in _parent_attr_name and setattr(parent, attr_name, self) is used to trigger recalculation up the tree.

Do not rename these indexed slot attributes without updating the corresponding _set_parent(..., "<name>") call sites and the _restore_child_parent_refs override.

Attributes

Classes

CathodeFormulation 

CathodeFormulation(active_materials: Dict[_ActiveMaterial, float], binders: Optional[Dict[Binder, float]] = {}, conductive_additives: Optional[Dict[ConductiveAdditive, float]] = {}, voltage_cutoff: Optional[float] = None, name: Optional[str] = 'Cathode Formulation')

Bases: _ElectrodeFormulation

Represents a cathode formulation in a battery. Inherits from _ElectrodeFormulation.

Initialize a cathode formulation with active materials, binders, and conductive additives.

Parameters

active_materials : Dict[_ActiveMaterial, float] Dictionary of active materials and their mass fractions in percent. binders : Optional[Dict[Binder, float]] Dictionary of binders and their mass fractions in percent. conductive_additives : Optional[Dict[ConductiveAdditive, float]] Dictionary of conductive additives and their mass fractions in percent. voltage_cutoff : Optional[float] The maximum voltage for the half-cell curves. If not provided, it will be set to the maximum voltage from the active materials' voltage cutoff range. name : Optional[str] Name of the cathode formulation. Defaults to 'Cathode Formulation'.

AnodeFormulation 

AnodeFormulation(active_materials: Dict[_ActiveMaterial, float], binders: Optional[Dict[Binder, float]] = {}, conductive_additives: Optional[Dict[ConductiveAdditive, float]] = {}, voltage_cutoff: Optional[float] = None, name: Optional[str] = 'Anode Formulation')

Bases: _ElectrodeFormulation

Represents an anode formulation in a battery. Inherits from _ElectrodeFormulation.

Initialize an anode formulation with active materials, binders, and conductive additives.

Parameters

active_materials : Dict[_ActiveMaterial, float] Dictionary of active materials and their mass fractions in percent. binders : Optional[Dict[Binder, float]] Dictionary of binders and their mass fractions in percent. conductive_additives : Optional[Dict[ConductiveAdditive, float]] Dictionary of conductive additives and their mass fractions in percent. voltage_cutoff : Optional[float] The voltage cutoff for the half-cell curves. If not provided, it will be set to the minimum voltage from the active materials' voltage cutoff range. name : Optional[str] Name of the anode formulation. Defaults to 'Anode Formulation'.