mtnlion.models package

Available models for simulation with the mtnlion framework

class mtnlion.models.DoubleLayer(Ns)

Bases: mtnlion.models.isothermal.Isothermal

The double-layer model comes from surface science where a structure forms on the surface of a solid when exposed to a fluid. In this case, the structure that forms on the particles is an electrical charge which causes an opposing charge to build up in the electrolyte near the surface. The separation of electrical charge around the particle surface has the same behavior as a plate capacitor.

class DoubleLayer

Bases: mtnlion.formula.Formula

Double-layer flux.

form(arguments, domain)

This method must be overloaded to define the form of the Formula.

Parameters

• arguments – All arguments defined by overriding one or more of Formula.Variables, Formula.Formulas, Formula.Parameters, Formula.Lambdas, and Formula.TimeDiscretization

• domain – The current domain in which the function is being evaluated

Returns

FFL form

class TotalFlux

Bases: mtnlion.formula.Formula

Replaces the standard intercalation flux from the isothermal model.

form(arguments, domain)

This method must be overloaded to define the form of the Formula.

Parameters

• arguments – All arguments defined by overriding one or more of Formula.Variables, Formula.Formulas, Formula.Parameters, Formula.Lambdas, and Formula.TimeDiscretization

• domain – The current domain in which the function is being evaluated

Returns

FFL form

class mtnlion.models.Isothermal(num_functions)

Bases: mtnlion.model.Model

The basic DFN lithium-ion model with no thermal considerations and a 1D approximation of the solid concentration.

class ElectrolyteConcentration

Bases: mtnlion.formula.Formula

Concentration of lithium in the electrolyte.

form(arguments, domain)

This method must be overloaded to define the form of the Formula.

Parameters

• arguments – All arguments defined by overriding one or more of Formula.Variables, Formula.Formulas, Formula.Parameters, Formula.Lambdas, and Formula.TimeDiscretization

• domain – The current domain in which the function is being evaluated

Returns

FFL form

class ElectrolytePotential

Bases: mtnlion.formula.Formula

Charge conservation in the electrolyte.

form(arguments, domain)

This method must be overloaded to define the form of the Formula.

Parameters

• arguments – All arguments defined by overriding one or more of Formula.Variables, Formula.Formulas, Formula.Parameters, Formula.Lambdas, and Formula.TimeDiscretization

• domain – The current domain in which the function is being evaluated

Returns

FFL form

class ExchangeCurrentDensity

Bases: mtnlion.formula.Formula

The exchange current density is the current in the absence of net electrolysis and at zero overpotential.

form(arguments, domain)

This method must be overloaded to define the form of the Formula.

Parameters

• arguments – All arguments defined by overriding one or more of Formula.Variables, Formula.Formulas, Formula.Parameters, Formula.Lambdas, and Formula.TimeDiscretization

• domain – The current domain in which the function is being evaluated

Returns

FFL form

class IntercalationFlux

Bases: mtnlion.formula.Formula

Describes how the electrical current on an electrode depends on the electrode potential.

form(arguments, domain)

This method must be overloaded to define the form of the Formula.

Parameters

• arguments – All arguments defined by overriding one or more of Formula.Variables, Formula.Formulas, Formula.Parameters, Formula.Lambdas, and Formula.TimeDiscretization

• domain – The current domain in which the function is being evaluated

Returns

FFL form

class KappaDEff

Bases: mtnlion.formula.Formula

kappa_d effective

form(arguments, domain)

This method must be overloaded to define the form of the Formula.

Parameters

• arguments – All arguments defined by overriding one or more of Formula.Variables, Formula.Formulas, Formula.Parameters, Formula.Lambdas, and Formula.TimeDiscretization

• domain – The current domain in which the function is being evaluated

Returns

FFL form

class KappaEff

Bases: mtnlion.formula.Formula

Effective conductivity of the electrolyte.

form(arguments, domain)

This method must be overloaded to define the form of the Formula.

Parameters

• arguments – All arguments defined by overriding one or more of Formula.Variables, Formula.Formulas, Formula.Parameters, Formula.Lambdas, and Formula.TimeDiscretization

• domain – The current domain in which the function is being evaluated

Returns

FFL form

class KappaRef

Bases: mtnlion.formula.Formula

Bulk conductivity of the homogeneous materials.

form(arguments, domain)

This method must be overloaded to define the form of the Formula.

Parameters

• arguments – All arguments defined by overriding one or more of Formula.Variables, Formula.Formulas, Formula.Parameters, Formula.Lambdas, and Formula.TimeDiscretization

• domain – The current domain in which the function is being evaluated

Returns

FFL form

class OpenCircuitPotential

Bases: mtnlion.formula.Formula

Open-circuit potential formula.

form(arguments, domain)

Evaluate the open-circuit potential equation.

class Overpotential

Bases: mtnlion.formula.Formula

Voltage difference between a reduction potential and the potential of the redox event.

form(arguments, domain)

This method must be overloaded to define the form of the Formula.

Parameters

• arguments – All arguments defined by overriding one or more of Formula.Variables, Formula.Formulas, Formula.Parameters, Formula.Lambdas, and Formula.TimeDiscretization

• domain – The current domain in which the function is being evaluated

Returns

FFL form

class SolidConcentration(legendre)

Bases: mtnlion.formula.Formula

Concentration of lithium in the solid, 1D approximation using Legendre polynomials.

form(arguments, domain)

This method must be overloaded to define the form of the Formula.

Parameters

• arguments – All arguments defined by overriding one or more of Formula.Variables, Formula.Formulas, Formula.Parameters, Formula.Lambdas, and Formula.TimeDiscretization

• domain – The current domain in which the function is being evaluated

Returns

FFL form

class SolidConcentrationBoundary

Bases: mtnlion.formula.Formula

This Formula defines the value of the lithium concentration at the surface of the solid particle.

form(arguments, domain)

This method must be overloaded to define the form of the Formula.

Parameters

• arguments – All arguments defined by overriding one or more of Formula.Variables, Formula.Formulas, Formula.Parameters, Formula.Lambdas, and Formula.TimeDiscretization

• domain – The current domain in which the function is being evaluated

Returns

FFL form

class SolidConcentrationNeumann

Bases: mtnlion.formula.Formula

Nuemann boundary for the solid concentration. This Formula doesn’t use a boundary domain due to the 1D 1D approximation.

form(arguments, domain)

This method must be overloaded to define the form of the Formula.

Parameters

• arguments – All arguments defined by overriding one or more of Formula.Variables, Formula.Formulas, Formula.Parameters, Formula.Lambdas, and Formula.TimeDiscretization

• domain – The current domain in which the function is being evaluated

Returns

FFL form

class SolidPotential

Bases: mtnlion.formula.Formula

Charge conservation in the solid.

form(arguments, domain)

This method must be overloaded to define the form of the Formula.

Parameters

• arguments – All arguments defined by overriding one or more of Formula.Variables, Formula.Formulas, Formula.Parameters, Formula.Lambdas, and Formula.TimeDiscretization

• domain – The current domain in which the function is being evaluated

Returns

FFL form

class SolidPotentialNeumann

Bases: mtnlion.formula.Formula

Neumann boundary for the solid potential at the anode/cathode current collector boundaries.

form(arguments, domain)

This method must be overloaded to define the form of the Formula.

Parameters

• arguments – All arguments defined by overriding one or more of Formula.Variables, Formula.Formulas, Formula.Parameters, Formula.Lambdas, and Formula.TimeDiscretization

• domain – The current domain in which the function is being evaluated

Returns

FFL form

class StateOfCharge

Bases: mtnlion.formula.Formula

State of Charge (SOC) formula.

form(arguments, domain)

This method must be overloaded to define the form of the Formula.

Parameters

• arguments – All arguments defined by overriding one or more of Formula.Variables, Formula.Formulas, Formula.Parameters, Formula.Lambdas, and Formula.TimeDiscretization

• domain – The current domain in which the function is being evaluated

Returns

FFL form

class mtnlion.models.LithiumPlating(Ns)

Bases: mtnlion.models.isothermal.Isothermal

Lithium plating often occurs when the manufacturer-specified upper voltage on the cell is not observed, which can cause a cell to become inoperable within a few overcharge events.

class Overpotential

Bases: mtnlion.formula.Formula

Voltage difference between a reduction potential and the potential of the redox event.

form(arguments, domain)

This method must be overloaded to define the form of the Formula.

Parameters

• arguments – All arguments defined by overriding one or more of Formula.Variables, Formula.Formulas, Formula.Parameters, Formula.Lambdas, and Formula.TimeDiscretization

• domain – The current domain in which the function is being evaluated

Returns

FFL form

class SideReactionExchangeCurrentDensity

Bases: mtnlion.formula.Formula

The current in the absence of net electrolysis and at zero overpotential in the side reaction.

form(arguments, domain)

This method must be overloaded to define the form of the Formula.

Parameters

• arguments – All arguments defined by overriding one or more of Formula.Variables, Formula.Formulas, Formula.Parameters, Formula.Lambdas, and Formula.TimeDiscretization

• domain – The current domain in which the function is being evaluated

Returns

FFL form

class SideReactionFlux

Bases: mtnlion.formula.Formula

Describes how the electrical current on an electrode depends on the electrode potential due to the side reaction.

form(arguments, domain)

Flux through the boundary of the solid.

class SideReactionOverpotential

Bases: mtnlion.formula.Formula

Voltage difference between a reduction potential and the potential of the redox event in the side reaction.

form(arguments, domain)

This method must be overloaded to define the form of the Formula.

Parameters

• arguments – All arguments defined by overriding one or more of Formula.Variables, Formula.Formulas, Formula.Parameters, Formula.Lambdas, and Formula.TimeDiscretization

• domain – The current domain in which the function is being evaluated

Returns

FFL form

class mtnlion.models.SEI(Ns)

Bases: mtnlion.models.isothermal.Isothermal

The SEI model is an extension to the isothermal model that attempts to quantify solid-electrolyte interphase formation and growth on the negative-electrode solid particles during chargning.

class LocalMolecularFlux

Bases: mtnlion.formula.Formula

The total flux of the system including intercalation flux and side reaction flux.

form(arguments, domain)

This method must be overloaded to define the form of the Formula.

Parameters

• arguments – All arguments defined by overriding one or more of Formula.Variables, Formula.Formulas, Formula.Parameters, Formula.Lambdas, and Formula.TimeDiscretization

• domain – The current domain in which the function is being evaluated

Returns

FFL form

class Overpotential

Bases: mtnlion.formula.Formula

Voltage difference between a reduction potential and the potential of the redox event.

form(arguments, domain)

This method must be overloaded to define the form of the Formula.

Parameters

• arguments – All arguments defined by overriding one or more of Formula.Variables, Formula.Formulas, Formula.Parameters, Formula.Lambdas, and Formula.TimeDiscretization

• domain – The current domain in which the function is being evaluated

Returns

FFL form

class SideReactionFlux

Bases: mtnlion.formula.Formula

Describes how the electrical current on an electrode depends on the electrode potential due to the side reaction.

form(arguments, domain)

Flux through the boundary of the solid.

class SideReactionOverpotential

Bases: mtnlion.formula.Formula

Voltage difference between a reduction potential and the potential of the redox event in the side reaction.

form(arguments, domain)

This method must be overloaded to define the form of the Formula.

Parameters

• arguments – All arguments defined by overriding one or more of Formula.Variables, Formula.Formulas, Formula.Parameters, Formula.Lambdas, and Formula.TimeDiscretization

• domain – The current domain in which the function is being evaluated

Returns

FFL form

class mtnlion.models.Thermal(Ns)

Bases: mtnlion.models.isothermal.Isothermal

The thermal model extends the isothermal model to allow the modeling of internal heat generation which is used to determine the temperature of the cell at any location.

class AdaptT

Bases: mtnlion.formula.Formula

An adapter formula to allow existing formulas to use the temperature variable T as if it were still a parameter.

form(arguments: mtnlion.formula.Arguments, domain: str) → ufl.core.expr.Expr

This method must be overloaded to define the form of the Formula.

Parameters

• arguments – All arguments defined by overriding one or more of Formula.Variables, Formula.Formulas, Formula.Parameters, Formula.Lambdas, and Formula.TimeDiscretization

• domain – The current domain in which the function is being evaluated

Returns

FFL form

class DeEff

Bases: mtnlion.formula.Formula

Effective diffusivity of the electrolyte.

form(arguments, domain)

This method must be overloaded to define the form of the Formula.

Parameters

• arguments – All arguments defined by overriding one or more of Formula.Variables, Formula.Formulas, Formula.Parameters, Formula.Lambdas, and Formula.TimeDiscretization

• domain – The current domain in which the function is being evaluated

Returns

FFL form

class Ds

Bases: mtnlion.formula.Formula

Solid diffusivity.

form(arguments, domain)

This method must be overloaded to define the form of the Formula.

Parameters

• arguments – All arguments defined by overriding one or more of Formula.Variables, Formula.Formulas, Formula.Parameters, Formula.Lambdas, and Formula.TimeDiscretization

• domain – The current domain in which the function is being evaluated

Returns

FFL form

class ExchangeCurrentDensity

Bases: mtnlion.models.isothermal.ExchangeCurrentDensity

The exchange current density is the current in the absence of net electrolysis and at zero overpotential.

form(arguments, domain)

This method must be overloaded to define the form of the Formula.

Parameters

• arguments – All arguments defined by overriding one or more of Formula.Variables, Formula.Formulas, Formula.Parameters, Formula.Lambdas, and Formula.TimeDiscretization

• domain – The current domain in which the function is being evaluated

Returns

FFL form

class HeatGeneration

Bases: mtnlion.formula.Formula

Total heat generated in the cell.

form(arguments, domain)

This method must be overloaded to define the form of the Formula.

Parameters

• arguments – All arguments defined by overriding one or more of Formula.Variables, Formula.Formulas, Formula.Parameters, Formula.Lambdas, and Formula.TimeDiscretization

• domain – The current domain in which the function is being evaluated

Returns

FFL form

class HeatGenerationChemical

Bases: mtnlion.formula.Formula

Irreversible heat generation due to chemical reactions for each chemical reaction at the interface.

form(arguments, domain)

This method must be overloaded to define the form of the Formula.

Parameters

• arguments – All arguments defined by overriding one or more of Formula.Variables, Formula.Formulas, Formula.Parameters, Formula.Lambdas, and Formula.TimeDiscretization

• domain – The current domain in which the function is being evaluated

Returns

FFL form

class HeatGenerationEntropy

Bases: mtnlion.formula.Formula

Reversible heat generation due to a change in entropy for each chemical reaction at the interface

form(arguments, domain)

This method must be overloaded to define the form of the Formula.

Parameters

• arguments – All arguments defined by overriding one or more of Formula.Variables, Formula.Formulas, Formula.Parameters, Formula.Lambdas, and Formula.TimeDiscretization

• domain – The current domain in which the function is being evaluated

Returns

FFL form

class JouleHeatingElectrolyte1

Bases: mtnlion.formula.Formula

Joule heating due to electrical potential gradient in the electrolyte

form(arguments, domain)

This method must be overloaded to define the form of the Formula.

Parameters

• arguments – All arguments defined by overriding one or more of Formula.Variables, Formula.Formulas, Formula.Parameters, Formula.Lambdas, and Formula.TimeDiscretization

• domain – The current domain in which the function is being evaluated

Returns

FFL form

class JouleHeatingElectrolyte2

Bases: mtnlion.formula.Formula

Joule heating due to electrical potential gradient in the electrolyte

form(arguments, domain)

This method must be overloaded to define the form of the Formula.

Parameters

• arguments – All arguments defined by overriding one or more of Formula.Variables, Formula.Formulas, Formula.Parameters, Formula.Lambdas, and Formula.TimeDiscretization

• domain – The current domain in which the function is being evaluated

Returns

FFL form

class JouleHeatingSolid

Bases: mtnlion.formula.Formula

Joule heating due to electrical potential gradient in the solid.

form(arguments, domain)

This method must be overloaded to define the form of the Formula.

Parameters

• arguments – All arguments defined by overriding one or more of Formula.Variables, Formula.Formulas, Formula.Parameters, Formula.Lambdas, and Formula.TimeDiscretization

• domain – The current domain in which the function is being evaluated

Returns

FFL form

class KappaDEff

Bases: mtnlion.formula.Formula

kappa_d effective.

form(arguments, domain)

This method must be overloaded to define the form of the Formula.

Parameters

• arguments – All arguments defined by overriding one or more of Formula.Variables, Formula.Formulas, Formula.Parameters, Formula.Lambdas, and Formula.TimeDiscretization

• domain – The current domain in which the function is being evaluated

Returns

FFL form

class KappaEff

Bases: mtnlion.models.isothermal.KappaEff

Effective conductivity of the electrolyte.

form(arguments, domain)

This method must be overloaded to define the form of the Formula.

Parameters

• arguments – All arguments defined by overriding one or more of Formula.Variables, Formula.Formulas, Formula.Parameters, Formula.Lambdas, and Formula.TimeDiscretization

• domain – The current domain in which the function is being evaluated

Returns

FFL form

class SigmaEff

Bases: mtnlion.formula.Formula

Effective conductivity (electrode-dependent parameter), represents a volume averaged conductivity of the solid matrix in a porous media in the vicinity of a given point.

form(arguments, domain)

This method must be overloaded to define the form of the Formula.

Parameters

• arguments – All arguments defined by overriding one or more of Formula.Variables, Formula.Formulas, Formula.Parameters, Formula.Lambdas, and Formula.TimeDiscretization

• domain – The current domain in which the function is being evaluated

Returns

FFL form

class Temperature

Bases: mtnlion.formula.Formula

Temperature of the cell.

form(arguments, domain)

This method must be overloaded to define the form of the Formula.

Parameters

• arguments – All arguments defined by overriding one or more of Formula.Variables, Formula.Formulas, Formula.Parameters, Formula.Lambdas, and Formula.TimeDiscretization

• domain – The current domain in which the function is being evaluated

Returns

FFL form

Submodules

• mtnlion.models.double_layer module
• mtnlion.models.isothermal module
• mtnlion.models.lithium_plating module
• mtnlion.models.sei module
• mtnlion.models.thermal module