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.

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. BattX has its own parameter set for the same reason: BijuFang2022 is the grouped identification of a Samsung INR18650-25R cell from Biju and Fang's Tables 1-2, transcribed per table and equation number, including a table entry that is preserved despite looking internally inconsistent — see the parameter set's docstring.

Circuit entries may be functions of the state of charge and the cell temperature, or a LookupTable: a rectangular grid of measurements, interpolated bilinearly and held at its edges. A table is not compiled into the model; it is a nonnumeric parameter read by the pure function table_lookup, one per entry and shared by every cell of a pack, so a compiled problem swaps it for another with remake or setp. 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. Such tables for the Rint and the RCModel models can be identified from a recorded pulse test, as described in Identifying equivalent circuits from pulse tests.

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_degradation_default_params(; SEI_degradation = true, source = :PETLION)

[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>

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.

Plett E2 hysteresis model

PlettE2 provides the 25 °C E2 data for ESC, including the 201-point OCV curve, one RC pair, dynamic and instantaneous hysteresis amplitudes, hysteresis rate, capacity and charge efficiency. Its source and the negative efficiency in the archive's -25 °C row are documented in the API. The fit has no thermal parameters and carries no validation claim outside 25 °C.

Vandeputte Randles impedance

Vandeputte2023 provides the Randles impedance simulated in Section 6 of Vandeputte et al. (2023) for Randles(; diffusion = :cpe): series, charge-transfer and double-layer elements and a semi-infinite Warburg coefficient, realized as a CPE ladder over [5e-5, 1e4] Hz. The source gives no open-circuit voltage or capacity, so both are required keywords: Vandeputte2023(; open_circuit_voltage, nominal_capacity).

Nonlinear double-capacitor (NDC) model

NDC reuses RCModel's bulk/surface charge-transport network — the same "end resistance", "capacitor resistance", "bulk capacitance" and "surface capacitance" keys — and drives a nonlinear terminal voltage h(V_s) from it instead of the resistively-weighted OCV blend, in series with one polarization branch and the ohmic resistance. Tian2020NCR18650B transcribes the constant-current identification of Tian, Fang, Chen and Wang (2020) for a Panasonic NCR18650B cell, citing the paper's equation and section numbers for every entry, including the resistance the source sets to zero by assumption. It is checked against the paper's closed-form equations and the model's own conservation and limiting-case properties (see test/ndc.jl), not against the source's raw voltage traces, which are not published as data.