Microstructure Calculations¶

class ionworkspipeline.calculations.SurfaceAreaToVolumeRatio(electrode)¶

Calculate the surface area to volume ratio for the electrodes from the active material volume fraction and particle radius, assuming spherical particles.

Parameters¶

electrodestr: The electrode to calculate the surface area to volume ratio for, either “positive”, “negative” or “both”.

Examples¶

>>> import ionworkspipeline as iwp
>>> calc = iwp.calculations.SurfaceAreaToVolumeRatio("positive")
>>> params = iwp.ParameterValues({
...     "Positive electrode active material volume fraction": 0.65,
...     "Positive particle radius [m]": 5e-6,
... })
>>> result = calc.run(params)
>>> result["Positive electrode surface area to volume ratio [m-1]"]
390000.0

Extends: Calculation

See also: SurfaceAreaToVolumeRatio — field-level documentation.

run(parameter_values: ParameterValues) → ParameterValues¶

Execute the calculation to derive new parameters from inputs.

Parameters¶

parameter_valuesiwp.ParameterValues: Input parameters providing the values needed for this calculation.

Returns¶

iwp.ParameterValues: Newly calculated parameters to add to the pipeline.

supports_expression_output: bool = True¶: Set True only alongside a case in test_live_outputs.py: an allowlist, because a calculation that merely runs on placeholders can still differ.

class ionworkspipeline.calculations.ElectrodeVolumeFractionFromLoading(electrode, method)¶

Calculate active material volume fraction from loading or coating mass.

Two methods are available:

From loading (method="loading"): Calculate from capacity-based areal loading and maximum concentration:

\[\varepsilon_{AM} = \frac{Q_{load}}{L \cdot c_{max} \cdot F / 3600}\]

where \(\varepsilon_{AM}\) is the active material volume fraction [-], \(Q_{load}\) is the areal loading [A.h.m-2], \(L\) is electrode thickness [m], \(c_{max}\) is the maximum lithium concentration in the active material [mol.m-3], and \(F\) is Faraday’s constant [C.mol-1].

From coating mass (method="coating mass"): Calculate from mass-based loading and crystal density:

\[\varepsilon_{AM} = \frac{M}{L \cdot \rho}\]

where \(M\) is the coating mass per unit area [g.cm-2], \(L\) is the electrode thickness [cm], and \(\rho\) is the crystal density of the active material [g.cm-3].

Parameters¶

electrodestr: The electrode: “positive”, “negative”, or “both”.
methodstr: The calculation method: “loading” or “coating mass”.

Notes¶

The active material volume fraction directly affects capacity:

\[Q = c_{max} \cdot \varepsilon_{AM} \cdot L \cdot A \cdot \Delta\theta \cdot \frac{F}{3600}\]

Examples¶

>>> import ionworkspipeline as iwp
>>> calc = iwp.calculations.ElectrodeVolumeFractionFromLoading(
...     electrode="positive", method="loading"
... )
>>> params = iwp.ParameterValues({
...     "Positive electrode thickness [m]": 80e-6,
...     "Maximum concentration in positive electrode [mol.m-3]": 51385,
...     "Positive electrode loading [A.h.cm-2]": 2.5,
... })
>>> result = calc.run(params)
>>> "Positive electrode active material volume fraction" in result
True

Extends: Calculation

See also: ElectrodeVolumeFractionFromLoading — field-level documentation.

run(parameter_values: ParameterValues) → ParameterValues¶

Execute the calculation to derive new parameters from inputs.

Parameters¶

parameter_valuesiwp.ParameterValues: Input parameters providing the values needed for this calculation.

Returns¶

iwp.ParameterValues: Newly calculated parameters to add to the pipeline.

class ionworkspipeline.calculations.ElectrodeGeometryFromLoading(electrode)¶

Thickness, active material volume fraction and porosity from loading.

\[L = \frac{m}{\rho_{press}}, \quad \varepsilon_{AM} = \frac{w_{AM} \, \rho_{press}}{\rho_{AM}}, \quad \varepsilon_e = 1 - \frac{\varepsilon_{AM}}{f_{AM}}\]

with \(m\) the coating mass per area, \(\rho_{press}\) the press density, \(w_{AM}\) the active material mass fraction, \(\rho_{AM}\) its crystal density and \(f_{AM}\) its active volume fraction of solid.

Parameters¶

electrodestr: The electrode: “positive” or “negative”.

Examples¶

>>> calc = iwp.calculations.ElectrodeGeometryFromLoading("positive")
>>> params = iwp.ParameterValues({
...     "Positive electrode coating mass per unit area [g.cm-2]": 0.026,
...     "Positive electrode press density [g.cm-3]": 3.5,
...     "Positive electrode active material mass fraction": 0.96,
...     "Positive electrode crystal density [g.cm-3]": 4.75,
...     "Positive electrode active volume fraction of solid": 0.9,
... })
>>> result = calc.run(params)
>>> round(float(result["Positive electrode thickness [m]"]) * 1e6, 1)
74.3

Extends: Calculation

See also: ElectrodeGeometryFromLoading — field-level documentation.

run(parameter_values: ParameterValues) → ParameterValues¶

Compute thickness, active material volume fraction and porosity.

Parameters¶

parameter_valuesiwp.ParameterValues: The inputs listed by inputs.

Returns¶

iwp.ParameterValues: The electrode thickness, active material volume fraction and porosity.

Raises¶

UserConfigurationError: If the coating mass is not positive, or the inputs give an active material volume fraction or porosity outside (0, 1).

class ionworkspipeline.calculations.ElectrodeVolumeFractionFromPorosity(electrode)¶

Calculate the volume fraction of active material in the electrodes from the porosity and the active volume fraction of solid.

Parameters¶

electrodestr: The electrode to calculate the volume fraction for. Must be either “negative” or “positive”.

Examples¶

>>> import ionworkspipeline as iwp
>>> calc = iwp.calculations.ElectrodeVolumeFractionFromPorosity("positive")
>>> params = iwp.ParameterValues({
...     "Positive electrode porosity": 0.3,
...     "Positive electrode active volume fraction of solid": 0.9,
... })
>>> result = calc.run(params)
>>> result["Positive electrode active material volume fraction"]
0.63

Extends: Calculation

See also: ElectrodeVolumeFractionFromPorosity — field-level documentation.

run(parameter_values: ParameterValues) → ParameterValues¶

Execute the calculation to derive new parameters from inputs.

Parameters¶

parameter_valuesiwp.ParameterValues: Input parameters providing the values needed for this calculation.

Returns¶

iwp.ParameterValues: Newly calculated parameters to add to the pipeline.

supports_expression_output: bool = True¶: Set True only alongside a case in test_live_outputs.py: an allowlist, because a calculation that merely runs on placeholders can still differ.

class ionworkspipeline.calculations.PorosityFromElectrodeVolumeFraction(electrode)¶

Calculate the porosity from the active material volume fraction.

Parameters¶

electrodestr: The electrode to calculate the porosity for. Must be either “negative” or “positive”.

Examples¶

>>> import ionworkspipeline as iwp
>>> calc = iwp.calculations.PorosityFromElectrodeVolumeFraction("positive")
>>> params = iwp.ParameterValues({
...     "Positive electrode active material volume fraction": 0.65,
...     "Positive electrode active volume fraction of solid": 0.9,
... })
>>> result = calc.run(params)
>>> result["Positive electrode porosity"]
0.277...

Extends: Calculation

See also: PorosityFromElectrodeVolumeFraction — field-level documentation.

run(parameter_values: ParameterValues) → ParameterValues¶

Execute the calculation to derive new parameters from inputs.

Parameters¶

parameter_valuesiwp.ParameterValues: Input parameters providing the values needed for this calculation.

Returns¶

iwp.ParameterValues: Newly calculated parameters to add to the pipeline.

supports_expression_output: bool = True¶: Set True only alongside a case in test_live_outputs.py: an allowlist, because a calculation that merely runs on placeholders can still differ.