Initial Concentration Calculations

class ionworkspipeline.calculations.InitialSOC(soc)

Calculate initial electrode concentrations from target SOC.

The most common approach to initialization: specify the desired state of charge, and the calculation determines the corresponding concentrations.

\[\theta_n = \theta_{n,0} + \text{SOC} \cdot (\theta_{n,100} - \theta_{n,0})\]
\[c = \theta \cdot c_{max}\]

Parameters

socfloat

Target state of charge (0.0 to 1.0).

Notes

This is the recommended approach when you have completed the ESOH calculation to determine stoichiometry windows.

Examples

>>> import ionworkspipeline as iwp
>>> calc = iwp.calculations.InitialSOC(soc=0.5)  # Start at 50% SOC
>>> params = iwp.ParameterValues({
...     "Negative electrode stoichiometry at 0% SOC": 0.0,
...     "Negative electrode stoichiometry at 100% SOC": 1.0,
...     "Positive electrode stoichiometry at 0% SOC": 1.0,
...     "Positive electrode stoichiometry at 100% SOC": 0.0,
...     "Maximum concentration in negative electrode [mol.m-3]": 28000,
...     "Maximum concentration in positive electrode [mol.m-3]": 50000,
... })
>>> result = calc.run(params)
>>> result["Initial stoichiometry in negative electrode"]
0.5

Extends: ionworkspipeline.calculations.calculation.Calculation

run(parameter_values: ParameterValues) → ParameterValues

Calculate initial concentrations from SOC.

Parameters

parameter_valuesiwp.ParameterValues

Input parameters with stoichiometry windows and max concentrations.

Returns

iwp.ParameterValues

Initial stoichiometry and concentration for both electrodes.

class ionworkspipeline.calculations.InitialSOCHalfCell(electrode, soc, options=None)

Calculate initial electrode concentration from target SOC for half-cell.

Converts SOC to stoichiometry and absolute concentration for the working electrode in half-cell models.

Parameters

electrodestr

Working electrode: “negative” or “positive”.

socfloat | int | str

Target SOC. Can be numeric (0.0-1.0) or string (“0%”, “100%”, “minimum”, “maximum”).

optionsdict, optional

Calculation options:

  • phasestr | None, default=None

    Phase for multi-phase materials: “primary” or “secondary”.

Examples

Numeric SOC (params must include stoichiometry at 0% and 100% SOC):

>>> import ionworkspipeline as iwp
>>> calc = iwp.calculations.InitialSOCHalfCell("positive", soc=0.5)
>>> params = iwp.ParameterValues({
...     "Positive electrode stoichiometry at 0% SOC": 0.0,
...     "Positive electrode stoichiometry at 100% SOC": 1.0,
...     "Maximum concentration in positive electrode [mol.m-3]": 50000,
... })
>>> result = calc.run(params)
>>> result["Initial stoichiometry in positive electrode"]
0.5

String SOC:

>>> calc = iwp.calculations.InitialSOCHalfCell("positive", soc="100%")
>>> params = iwp.ParameterValues({
...     "Positive electrode stoichiometry at 100% SOC": 0.3,
...     "Maximum concentration in positive electrode [mol.m-3]": 50000,
... })
>>> result = calc.run(params)
>>> result["Initial stoichiometry in positive electrode"]
0.3

Extends: ionworkspipeline.calculations.calculation.Calculation

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.InitialVoltageFromConcentration(electrode)

Calculate initial voltage from target concentration using OCP inversion.

Finds the voltage that produces a target electrode concentration by numerically inverting the lithiation function.

Parameters

electrodestr

Electrode: “negative” or “positive”.

Examples

Requires electrode lithiation function (from OCP/MSMR). Short example:

>>> import ionworkspipeline as iwp
>>> calc = iwp.calculations.InitialVoltageFromConcentration("positive")
>>> params = iwp.ParameterValues({
...     "Positive electrode lithiation": simple_lithiation,
...     "Maximum concentration in positive electrode [mol.m-3]": 50000,
...     "Initial concentration in positive electrode [mol.m-3]": 25000,
... })
>>> result = calc.run(params)
>>> "Initial voltage in positive electrode [V]" in result
True

Extends: ionworkspipeline.calculations.calculation.Calculation

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.InitialStoichiometryFromVoltageHalfCell(electrode, options=None)

Calculate initial stoichiometry from target voltage for half-cell.

For matching experimental data: specify the initial open-circuit voltage observed in the data. The calculation numerically inverts the OCP function to find the corresponding stoichiometry:

\[U(\theta_{init}) = V_{init}\]

This is ideal when fitting to experimental data - initialize the model at the same voltage where the data begins.

Parameters

electrodestr

The electrode: “positive” or “negative”.

optionsdict, optional

Calculation options:

  • simulation_kwargs: dict, default={“solver”: pybamm.AlgebraicSolver()} Keyword arguments to pass to the simulation.

  • direction: str, default=None Direction for OCP: “lithiation” or “delithiation”.

  • phase: str, default=None Phase for multi-phase materials: “primary” or “secondary”.

Notes

This approach works best when the data starts after a long rest period, ensuring the cell is at equilibrium and the voltage represents the true OCV.

Examples

Requires OCP, voltage limits, initial temperature. Short example:

>>> import ionworkspipeline as iwp
>>> calc = iwp.calculations.InitialStoichiometryFromVoltageHalfCell("positive")
>>> # result = calc.run(params)  # params: OCP, V_init, V_min, V_max, T

Extends: ionworkspipeline.calculations.calculation.Calculation

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.InitialStoichiometryFromVoltageMSMRHalfCell(electrode)

Calculate the initial stoichiometry in the given electrode from the initial voltage (i.e. find the stoichiometry that gives the correct voltage) using the MSMR framework.

Parameters

electrodestr

The electrode to calculate the initial concentration for, either “positive” or “negative”.

Examples

>>> import ionworkspipeline as iwp
>>> calc = iwp.calculations.InitialStoichiometryFromVoltageMSMRHalfCell("positive")
>>> params = iwp.ParameterValues({
...     "Positive electrode lithiation": lambda U: 0.5,  # requires real MSMR fn
...     "Initial voltage in positive electrode [V]": 3.9,
... })
>>> result = calc.run(params)
>>> result["Initial stoichiometry in positive electrode"]
0.5

Extends: ionworkspipeline.calculations.calculation.Calculation

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.InitialSOCfromMaximumStoichiometry(options=None)

Calculate the initial concentration in the negative and positive electrodes from the initial SOC and stoichiometry windows in each electrode.

Parameters

optionsdict, optional

A dictionary of options to be passed to the calculation. The following options are available:

  • particle phases: tuple of str

    Specifies the number of phases for each electrode as a tuple (negative, positive). Each element can be “1” (single phase) or “2” (composite with Primary and Secondary phases). Default is (“1”, “1”).

Examples

>>> import ionworkspipeline as iwp
>>> calc = iwp.calculations.InitialSOCfromMaximumStoichiometry()
>>> params = iwp.ParameterValues({
...     "Negative electrode stoichiometry at maximum SOC": 0.95,
...     "Positive electrode stoichiometry at maximum SOC": 0.3,
...     "Maximum concentration in negative electrode [mol.m-3]": 28000,
...     "Maximum concentration in positive electrode [mol.m-3]": 50000,
... })
>>> result = calc.run(params)
>>> result["Initial stoichiometry in negative electrode"]
0.95
>>> result["Initial stoichiometry in positive electrode"]
0.3

Extends: ionworkspipeline.calculations.calculation.Calculation

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.InitialConcentrationFromInitialStoichiometryHalfCell(electrode, options=None)

Calculate the initial concentration in the given electrode from the initial stoichiometry and maximum concentration.

Parameters

electrodestr

The electrode to calculate the initial concentration for, either “positive” or “negative”.

optionsdict, optional

A dictionary of options to be passed to the calculation. The following options are available:

  • phase: str

    The phase to solve for the initial concentration. Can be “primary” or “secondary”. Default is None.

Examples

>>> import ionworkspipeline as iwp
>>> calc = iwp.calculations.InitialConcentrationFromInitialStoichiometryHalfCell(
...     "positive"
... )
>>> params = iwp.ParameterValues({
...     "Initial stoichiometry in positive electrode": 0.5,
...     "Maximum concentration in positive electrode [mol.m-3]": 50000,
... })
>>> result = calc.run(params)
>>> result["Initial concentration in positive electrode [mol.m-3]"]
25000.0

Extends: ionworkspipeline.calculations.calculation.Calculation

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.