Parameter sets

Pre-defined parameter sets

BatteryComponents offers pre-defined parameter sets for several widely used lithium-ion battery chemistries, which can be conveniently employed in your simulations. The available chemistries are:

Lithium Cobalt Oxide (LCO):
- A popular choice for portable electronic devices
- Known for its high energy density and good cycling performance
Lithium Nickel Manganese Cobalt Oxide (NMC):
- Widely used in electric vehicles and energy storage systems
- Balances energy density, power density, and safety
Lithium Nickel Cobalt Aluminum Oxide (NCA):
- Commonly found in electric vehicles and portable electronics
- Offers high energy density and power density
Lithium Iron Phosphate (LFP and LFP2):
- Favored for its excellent safety and long cycle life
- Commonly found in electric vehicles, stationary storage, and other high-power applications
NMC against a lithium metal negative electrode (NMC_LiMetal)

Where the parameters come from

A parameter set of this kind is rarely the work of a single paper: the open-circuit potentials, the electrolyte transport correlations, the electrode geometry and the thermal properties are typically each taken from a different source. The table below gives the source per chemistry; the docstring of each constructor breaks it down per physical quantity, which is the granularity you need if you are swapping one correlation out.

Set	Cell	Sources
`LCO`	The LIONSIMBA reference ("Northrop") LiCoO₂/graphite cell	Torchio et al. 2016 (doi); chemistry parameters from Northrop et al. 2011 (doi); open-circuit potentials from Ramadass et al. 2004 (doi); entropic coefficients from Guo et al. 2011 (doi), as attributed by Northrop et al.; electrolyte transport from Valøen & Reimers 2005 (doi)
`BatteryComponents.LCO2`	Kokam SLPB78205130H pouch cell	Marquis et al. 2019 (doi), Table 1, via S. Moura's fastDFN and J. Newman's Dualfoil; open-circuit potentials from Dualfoil; electrolyte diffusivity fit by Dualfoil to Capiglia et al. 1999 (doi); electrolyte conductivity from Bellcore measurements reported by Doyle 1995 (OSTI)
`LFP`	A123 LFP/graphite cylindrical cell	Lain et al. 2019 (doi); graphite and separator from Chen et al. 2020 (doi); LFP electrode from Prada et al. 2013 (doi); LFP open-circuit potential from Afshar et al. 2017 (arXiv); electrolyte transport from Nyman et al. 2008 (doi)
`LFP2`	LFP/graphite 2 Ah 18650, parameterised by About:Energy Limited	The BPX example file `lfp_18650_cell_BPX.json`; electrolyte transport from Nyman et al. 2008 (doi); electrode thermal properties as in `LFP`. The reaction rate constants are the file's normalised values, unconverted.
`NCA`	NCA/graphite cell	Kim et al. 2011 (doi)
`NMC`	NMC111/graphite 12.5 Ah pouch cell, parameterised by About:Energy Limited	The BPX example file `nmc_pouch_cell_BPX.json`; electrolyte transport from Nyman et al. 2008 (doi); positive electrode entropic coefficient from Viswanathan et al. 2010 (doi); electrode thermal properties as in Marquis et al. 2019 (doi)
`NMC_LiMetal`	—	Electrolyte transport from Valøen & Reimers 2005 (doi). The remaining values have no recorded source.

The equivalent circuits have their own parameter sets, since a circuit element is a property of one measured cell rather than of a chemistry: see ChenRinconMora2006 and He2011LiMn2O4, selected with BatteryParameterSet. SaftHighPower12Ah is the bulk/surface circuit of one 12 A⋅h cell whose published pulse response the test suite replays, and SaftLiIon6Ah is a Julia-side set whose every entry is a measured grid.

Circuit entries may be functions of the state of charge and the cell temperature, and a LookupTable is such a function built from a rectangular grid of measurements, interpolated bilinearly and held at its edges. It is the format the Rint-model battery data files of the ADVISOR vehicle simulator use — open-circuit voltage and a separate discharge and charge resistance over (SOC, T), capacity and coulombic efficiency over T — and SaftLiIon6Ah is one of those files carried over: the 6 A⋅h Saft lithium-ion cell NREL tested in 1999. The "discharge resistance" / "charge resistance" pair, a temperature-dependent "nominal capacity" and a temperature-dependent "coulombic efficiency" are described with the rest of the set contract in EquivalentCircuitParameters; with a constant capacity, or in an isothermal cell, nothing about the existing sets changes.

A double-layer capacitor is specified by a capacitance, an equivalent series resistance and a voltage rating rather than by an ampere-hour capacity and an open-circuit-voltage curve, so EDLC takes its parameters from EDLCParameters, which builds a set from exactly those numbers. MaxwellPC2500 is one measured device written that way. Neither is reachable from BatteryParameterSet or ECMTopology: the double-layer capacitor is a Julia-side model for now.

Degradation parameter sets

The SEI capacity-fade submodel has its own parameters, independent of the chemistry. Three parameterisations of the Ramadass et al. 2004 solvent-reduction side reaction are available through the SEI_parameters keyword of BatteryCell and CyclingCircuit, or the SEIParameterSet enum of ArrayBatteryPack in Dyad:

`SEI_parameters`	Source	Notes
`:PETLION` (default)	The `LiC6` set of PETLION, Berliner et al. 2021 (doi): the Table II values of Ramadass et al. 2004 (doi) in LIONSIMBA's rate expression	The per-chemistry exchange current densities of `LCO`, `LFP`, `NCA` and `NMC` belong to this set. Film admittance 1 S/m, so the film resistance is negligible.
`:Ramadass2004`	Exchange current density and reference potential from Ramadass et al. 2004 (doi) Table II; film admittance from LIONSIMBA's `Parameters_init.m`	Film admittance 3.79e-7 S/m, where Ramadass et al. give 1 S/m; fades much faster than the default and is not fitted to any cell here.
`:PyBaMM`	The `Ramadass2004` set of PyBaMM, with the corrections of Safari et al. 2009 (doi)	Reference potential 0 V and Li₂EDC partial molar volume; fades much slower than the default and is not fitted to any cell here.

BatteryComponents.SEI_degradation_default_params — Function

SEI_degradation_default_params(; SEI_degradation = true, source = :PETLION)

Parameters of the SEI capacity-fade submodel, or a set that disables it.

source selects one of three parameterisations of the same Ramadass et al. [1] solvent-reduction side reaction, each kept as a fixed tuple: exchange current density i0, film admittance k, reference potential U_ref and partial molar volume V̂ (the charge transfer coefficient is 0.5 in all of them). For reference, Table II of [1] gives U_ref = 0.4 V, i0 = 1.5e-6 A/m², a film conductivity of 1 S/m, a product density of 2.1e3 kg/m³ and a product molar mass printed as "7.3 × 10⁴ mol/kg"; its Table I gives an initial SEI resistance of 0.01 Ω⋅m².

:PETLION (default): the LiC6 set of PETLION [3]: i0 = 1.5e-6 A/m² (divided by 5 in this package), k = 1 S/m, U_ref = 0.4 V, which are the Table II values of [1], in the rate expression of LIONSIMBA [2]. The per-chemistry "SEI exchange current density" values of LCO, LFP, NCA and NMC are this package's own, were set under this source and apply to it only. V̂ is the molar mass of Li₂CO₃, 73.89e-3 kg/mol, over the 2100 kg/m³ product density of [1]. [1] itself takes the product to be a mixture of lithium compounds rather than Li₂CO₃ alone (its assumption 3), so the molar mass is this package's choice. PETLION grows the film with a molar mass of 7.3e-4 kg/mol over its electrode density of 2500 kg/m³, 100× less.
:Ramadass2004: i0 = 1.5e-6 A/m² and U_ref = 0.4 V from Table II of [1], V̂ as above, and the film admittance k = 3.79e-7 S/m of LIONSIMBA's Parameters_init.m [2] in place of the 1 S/m of [1]. The tuple is neither [1]'s nor LIONSIMBA's, whose exchange current density is 0.80e-10 A/m². LIONSIMBA notes that the molar mass printed in [1] is wrong in unit and number and refers to [4] for the correction.
:PyBaMM: the SEI values of PyBaMM's Ramadass2004 parameter set, which PyBaMM describes as [1] with the corrections of Safari et al. [5]: i0 = 1.5e-6 A/m², a resistivity of 2e5 Ω·m (k = 5e-6 S/m), U_ref = 0 V, V̂ = 9.585e-5 m³/mol (Li₂EDC).

What the choice changes in a simulation: SOH integrates the side-reaction current, which depends on i0 and U_ref only, so the fade rates of the three sets differ by orders of magnitude, and only :PETLION with the per-chemistry i0 has been tuned against anything. V̂ and k enter only the film thickness and its resistance R_film = film / k. In the SPM and SPMe models that resistance is not part of the terminal voltage; in the DFN it is, and there the two non-default sets add tens to hundreds of millivolts at 3C near end of life where the default adds microvolts.

The rate expression in eqs_SEIdegradation! multiplies the Tafel term by abs(C_rate)^2 for every source. That factor is not in [1]; it is the (I/I1C)^w weighting with w = 2 of LIONSIMBA's ionicFlux.m, kept by PETLION and absent from PyBaMM.

[1] Ramadass, P., Haran, B., Gomadam, P. M., White, R., & Popov, B. N. (2004).
Development of first principles capacity fade model for Li-ion cells. Journal of
The Electrochemical Society, 151(2), A196. <https://doi.org/10.1149/1.1634273>

[2] LIONSIMBA, the ageing parameters of `Parameters_init.m` and the side reaction of
`battery_model_files/P2D_equations/ionicFlux.m`,
<https://github.com/lionsimbatoolbox/LIONSIMBA>. The toolbox paper, Torchio et al.
(2016), <https://doi.org/10.1149/2.0291607jes>, does not describe the ageing model.

[3] Berliner, M. D., Cogswell, D. A., Bazant, M. Z., & Braatz, R. D. (2021).
Methods — PETLION: Open-source software for millisecond-scale porous electrode
theory-based lithium-ion battery simulations. Journal of The Electrochemical
Society, 168(9), 090504. <https://doi.org/10.1149/1945-7111/ac201c>

[4] Santhanagopalan, S., Guo, Q., Ramadass, P., & White, R. E. (2006). Review of
models for predicting the cycling performance of lithium ion batteries. Journal of
Power Sources, 156(2), 620–628. <https://doi.org/10.1016/j.jpowsour.2005.05.070>

[5] Safari, M., Morcrette, M., Teyssot, A., & Delacourt, C. (2009). Multimodal
physics-based aging model for life prediction of Li-ion batteries. Journal of The
Electrochemical Society, 156(3), A145. <https://doi.org/10.1149/1.3043429>

source

Custom parameter sets

For users with their own battery model parameters, the toolbox offers the flexibility to create custom parameter sets. This feature allows you to tailor your simulations to your specific battery chemistry and operating conditions, ensuring accurate and relevant results.