Docstrings

CellView

A view of one cell's symbolic states and parameters in a shared array pack. Use cell_views to obtain views. Property access returns the (series, parallel) element of the pack array that holds the quantity, at the quantity's grid index where the array has grid axes, for use in parameter updates and solution indexing; it creates no subsystem.

CycleLife(variable, results)

Marker for plot(sol, CycleLife(circuit.SOH, results)): the value of variable (usually the state of health) at the end of every cycle against the cycle number. results are the ExperimentResults of the solution, from experiment_results.

The mutable state of a Cycler that is shared with its event affects: the protocol (steps) and a log of the steps that ended (log: time, step index, exit reason), which experiment_results turns into results. The cycler appends to the log, so empty!(state.log) before solving the same problem a second time.

DFN(chemistry; options...)
DFN()

The Doyle-Fuller-Newman (`DFN`) model is an advanced pseudo-2D battery model. It accurately represents electrochemical processes within a lithium-ion battery, including diffusion, reactions, and concentration gradients in both electrodes. This model offers high-fidelity simulations, enabling analysis and optimization of battery performance under various operating conditions.

DP()

The dual-polarization (DP) model of [1]: Thevenin with two RC pairs, the first standing for electrochemical polarization (R_1, C_1, the fast pair Rpa/Cpa of [1]) and the second for concentration polarization (R_2, C_2, the slow Rpc/Cpc). Splitting the two is what [1] adds to the first-order model, and it is the most accurate of the five models compared there.

It is the same topology as Thevenin(2) and has the same variables; the separate type exists because the literature names it separately and because a parameter set identified per model (He2011LiMn2O4) has its own entry for it.

Parameter set keys: those of Thevenin, with two entries per RC vector.

[1] Hongwen He, Rui Xiong and Jinxin Fan. "Evaluation of Lithium-Ion Battery Equivalent Circuit Models for State of Charge Estimation by an Experimental Approach." Energies 4, no. 4 (2011): 582-598. https://doi.org/10.3390/en4040582

EDLC()

The electric double-layer capacitor (supercapacitor) cell: an ideal capacitance C in series with an equivalent series resistance R_0, which is Rint with the open-circuit voltage of a capacitor rather than of a faradaic cell,

V = q / C - I * R_0,    dq/dt = -I

Its state of charge is the stored charge against the charge at the rated voltage, SOC = q / (C * V_rated), which makes the open-circuit voltage the straight line OCV = SOC * V_rated and the usable energy C (V₁² - V₂²) / 2 rather than a plateau. That is the whole physical difference from Rint, and it is why the family exists as a type: a double-layer capacitor is specified by a capacitance, an equivalent series resistance and a voltage rating, not by an ampere-hour capacity and a measured open-circuit-voltage curve.

Only the immediate branch of [1] is modelled: no voltage-dependent capacitance, no delayed or long-term branch, and no leakage. Over a single charge or discharge of a few minutes the immediate branch is what carries the response, and [2] finds one such R-C pair enough to match a measured charge and discharge; over hours the missing branches and the leakage resistance are what the model gets wrong.

Parameter set keys: "capacitance", "rated voltage", "series resistance" — see EDLCParameters, which builds a set from exactly those three numbers. The "nominal capacity" of the "overall" section is derived, not read: it is C * V_rated / 3600 A⋅h, the value that makes the shared coulomb counter integrate dq/dt = -I.

The "capacitance" and "rated voltage" entries have to be constants. A (SOC, T) callable is accepted for "series resistance", so a temperature-dependent series resistance costs nothing, but a temperature-dependent capacitance would move the charge the state of charge is counted against, and is rejected rather than quietly integrated wrong.

[1] Luis Zubieta and Richard Bonert. "Characterization of double-layer capacitors for power electronics applications." IEEE Transactions on Industry Applications 36, no. 1 (2000): 199-205. https://doi.org/10.1109/28.821816

[2] Richard L. Spyker and R. M. Nelms. "Classical equivalent circuit parameters for a double-layer capacitor." IEEE Transactions on Aerospace and Electronic Systems 36, no. 3 (2000): 829-836. https://doi.org/10.1109/7.869502

Equivalent circuit models (ECMs) describe a cell as a small electrical network — a voltage source in series with resistances and RC pairs — rather than resolving the electrochemistry the way DFN, SPMe and SPM do. They carry no spatial discretization and no concentrations, so they are orders of magnitude cheaper and are what battery management systems are usually built on, at the cost of parameters that have to be identified per cell and hold only over the conditions they were identified at.

The subtypes are Rint, Thevenin, DP, PNGV and RCModel, the five models compared in [1], and EDLC, which is the same arithmetic for a double-layer capacitor rather than a faradaic cell. They are used with BatteryCell, BatteryPack and CyclingCircuit exactly as the electrochemical models are, with an ECM parameter set as the chemistry (ChenRinconMora2006, He2011LiMn2O4, SaftLiIon6Ah, MaxwellPC2500).

[1] Hongwen He, Rui Xiong and Jinxin Fan. "Evaluation of Lithium-Ion Battery Equivalent Circuit Models for State of Charge Estimation by an Experimental Approach." Energies 4, no. 4 (2011): 582-598. https://doi.org/10.3390/en4040582

One step of a cycling protocol as planned: the operating mode, the input (a setpoint or hold), the maximum time and the step-specific bounds. Built by charge, discharge, voltage, power and rest.

One experiment of a cycling protocol as it ran, from experiment_results: the ExperimentPlan's fields, plus the exit_reason that ended it ("Maximum voltage reached", "Stop time reached", ...), the indices idxs and the times tspan it covers in the solution, and the cycle it belongs to.

ForcedAirCooling(; area = 0.032, case_thickness = 0.001, case_conductivity = 15.0,
    fan_flow = 0.07 / 12, natural_flow = 0.001, flow_area = 0.0011,
    air_density = 1.16, air_heat_capacity = 1009.0, air_mass = 0.0,
    h_reference = 30.0, velocity_reference = 5.0, velocity_exponent = 0.8,
    h_natural = 4.0, T_set = 308.15, hysteresis = 2.0)

The hardware of a PackForcedAir boundary: a module case, a stream of cooling air, and the thermostat that switches the fan. Every field is a parameter of the compiled system. The shipped values are those of the Saft 6 A⋅h lithium-ion module data set of ADVISOR 2003 (NREL, ESS_LI7_temp.m), whose single-node thermal model this boundary reimplements, so they describe one module in a parallel-flow pack rather than a pack of any particular size; scale area, fan_flow and flow_area to the pack being modelled.

• area [m²] is the case surface the air passes over; case_thickness [m] and case_conductivity [W/m/K] give the conduction resistance t / (k A) of the massless case wall.
• fan_flow [kg/s] is the air mass flow with the fan on, and flow_area [m²] the cross-section it passes through, so the air velocity is fan_flow / (air_density * flow_area). natural_flow [kg/s] is the exchange of the air around the module with the surroundings while the fan is off; the source floors its air flow at this value.
• h_reference * (v / velocity_reference)^velocity_exponent is the forced-convection film coefficient [W/m²/K] at velocity v, and h_natural the coefficient with the fan off. The defaults are the correlation ADVISOR fits to Incropera and DeWitt, h = 30 (v / 5)^0.8 with a natural-convection floor of 4.
• air_mass [kg] is the mass of air the node holds. The realistic value for a cooling passage is a fraction of a gram, whose time constant is milliseconds against the minutes of the cells, so the default 0.0 treats the air as quasi-steady, which is also the form of the source; a positive value makes the air temperature a state.
• T_set [K] switches the fan on when the sensed temperature rises through it, and the fan goes off again when the temperature falls through T_set - hysteresis. The source has no hysteresis, but a relay with none chatters as soon as the fan's cooling exceeds the heating and the integration stalls at the setpoint, so hysteresis must be positive and defaults to 2 K.

LookupTable(; soc = nothing, temperature = nothing, values)

A gridded, linearly interpolated table over the state of charge and the cell temperature, usable wherever an EquivalentCircuitParameters set accepts a callable: as any "circuit" entry ((SOC, T) -> value), and, with only a temperature axis, as the "nominal capacity" or "coulombic efficiency" of the "overall" section (T -> value). It is the data format of the Rint tables of ADVISOR [1], whose battery files give Voc(SOC, T), R_dis(SOC, T), R_chg(SOC, T), C(T) and η(T) on exactly such a grid, and which interpolates them piecewise-linearly as this does.

soc and temperature are the strictly increasing breakpoints of the two axes; temperature may carry a Unitful unit (u"°C" is converted) and is stored in kelvin. Either axis may be left out, in which case the table is constant along it and values is a vector over the axis that is given; with both axes values is a matrix with one row per state of charge and one column per temperature. The values are plain numbers in the unit the entry expects — SI for a circuit element, A⋅h for the capacity — exactly as any other callable entry. A LookupTable is callable as table(SOC, T), and as table(T) when it has no state-of-charge axis.

Between breakpoints the value is bilinear, the piecewise-linear lookup that both ADVISOR and Modelica.Blocks.Tables use. Outside the grid it is held at the nearest edge, the HoldLastPoint extrapolation linear_ocv also follows: extrapolating a measured resistance or voltage table past its last breakpoint has no basis in the data, and a resistance extrapolated to zero or below would make the circuit meaningless. Bilinear interpolation is continuous but its slope is not, so the Jacobian of a cell using it jumps at every breakpoint; a stiff solver handles that as it handles any table-driven model, and a smoother interpolant would invent curvature the measurements do not support.

The table enters the model as a registered symbolic function with its own derivative rules, so it survives mtkcompile and the Jacobian is exact rather than finite-differenced. Inside a pack it is broadcast over the cells like every other callable entry, so it does not change the equation count.

R_dis = LookupTable(; soc = [0.0, 0.5, 1.0], temperature = [0.0, 25.0]u"°C",
    values = [0.0419 0.0720; 0.0143 0.0050; 0.0162 0.0057])   # Ω; rows: SOC, columns: T
Q = LookupTable(; temperature = [0.0, 25.0, 41.0]u"°C", values = [5.943, 7.035, 7.405]) # A⋅h
R_dis(0.25, 285.65)   # bilinear
Q(298.15)             # a temperature-only table takes one argument

[1] Valerie H. Johnson. "Battery performance models in ADVISOR." Journal of Power Sources 110, no. 2 (2002): 321-329. https://doi.org/10.1016/S0378-7753(02)00194-5

PNGV()

The PNGV capacitance model of [1] and [2]: a first-order Thevenin whose open-circuit voltage is a constant U_oc, with the drift of the open-circuit voltage carried by an extra series capacitor C_ocv = 1 / U'_oc instead,

V = U_oc - U_d - U_1 - I * R_0,    dU_d/dt = I / C_ocv

U_d is the accumulated open-circuit-voltage change, so the model is a local linearization of the OCV curve about the state of charge it was identified at, and "open-circuit voltage" must therefore be a constant rather than a function of the state of charge — a full OCV(SOC) alongside U_d would count the same drift twice. It is named after the Partnership for a New Generation of Vehicles, whose test manual [1] defines the pulse test it is identified from.

Parameter set keys: "open-circuit voltage" (constant), "series resistance", "OCV capacitance", "polarization resistance" and "polarization capacitance" (one entry each).

[1] PNGV Battery Test Manual, Revision 3. DOE/ID-10597, Idaho National Engineering and Environmental Laboratory, February 2001. https://avt.inl.gov/sites/default/files/pdf/battery/pngvmanualrev3b.pdf

[2] Valerie H. Johnson. "Battery performance models in ADVISOR." Journal of Power Sources 110, no. 2 (2002): 321-329. https://doi.org/10.1016/S0378-7753(02)00194-5

PackThermalNetwork(; conductance = 1.0, conductance_lateral = conductance,
    coolant_conductance = 1.0, coolant_conductance_lateral = 0.0)

A lumped thermal network over the cells of a BatteryPack, in which every cell exchanges heat with its geometric neighbours and only the cells on the outside of the block reach the coolant. A cell in the middle of a pack is surrounded by other heat sources and has no face on the outside, so it runs hotter than a cell at the edge.

Each cell already carries its own heat capacity and heat generation, so the network supplies only the couplings, in the standard lumped-module form

C_i dT_i/dt = Q_i + Σ_j G_ij (T_j - T_i) + G_coolant,i (T_coolant - T_i)

which is the model of Pozzi et al. ([doi:10.1109/TCST.2020.2995308] (https://doi.org/10.1109/TCST.2020.2995308)), who note that any arrangement of the cells is described thermally by the choice of the resistances alone. Abbas et al. resolve a module of 3 to 10 pouch cells this way and report the mechanism directly: heat accumulates in the middle of the module, "where the cells are less exposed to air compared to the external cells, since they are surrounded by insulation layers on both sides" (doi:10.3390/batteries10030098). Reniers and Howey give the other half of it — the middle cells "exchange heat conductively with two adjacent hot cells, while cells one and five benefit from some conductive cooling to the wall of the block" — and find that leaving the coupling out changes the predicted spread of cell capacities over 10000 cycles substantially (doi:10.1016/j.apenergy.2023.120774).

The cells sit on the pack's own series × parallel grid. The parallel axis is the direction the cells are stacked face to face, so its coupling runs through the cell's own heatport_left/heatport_right and its conductance is conductance. The series axis is the direction the rows sit side by side, coupled through the casing, holders and busbars with the conductance conductance_lateral; that path reaches both ends of the cell, half of it to each. coolant_conductance and coolant_conductance_lateral are the conductances from one exposed face of a boundary cell to the coolant, per axis; a cell in the interior of the grid has no exposed face and so no direct path to the coolant at all. All four are in W/K, they are parameters of the compiled system, and they are pairwise conductances, not conductivities.

The defaults are order-of-magnitude values from the literature, not a parameterization of any particular pack, and a quantitative study should replace them. conductance = 1.0 W/K is the reciprocal of the 1 K/W default inter-cell thermal resistance of Simscape Battery, whose quoted range is 0.01–10 K/W for pouch cells and 1–100 K/W for cylindrical ones ([Simscape Battery, "Model Heat Exchange Between Cells"] (https://www.mathworks.com/help/simscape-battery/ug/inter-cell-thermal-path-workflow.html)). coolant_conductance = 1.0 W/K is of the order of the measured surface cooling coefficients of pouch cells — 1.00 W/K for a 5 Ah Kokam K50, 2.99–7.33 W/K for larger cells (Russell et al., [doi:10.1016/j.ohx.2022.e00257] (https://doi.org/10.1016/j.ohx.2022.e00257)) — and is also the pre-existing heat_transfer_coefficient default of CyclingCircuit, so a pack of one cell is unchanged. coolant_conductance_lateral = 0.0 cools the pack only through the two ends of each stack; raise it to model a pack that also sits on a cold plate.

A pack built with a network exposes the single heat port heatport_coolant in place of the per-row heatport_left/heatport_right, so the coolant can be an ambient, a cold plate or a fluid loop; CyclingCircuit holds it at T_ambient, or cools it with a PackForcedAir boundary when given cooling.

@named circuit = CyclingCircuit(; model = Thevenin(), series = 4, parallel = 3,
    protocol = charge(1C), thermal_network = PackThermalNetwork())

Limitations

Thermal coupling follows geometry while current sharing follows the circuit, and the two are in general separate specifications: mapping the same series × parallel circuit onto the same physical block in two different ways changes the current and ageing distribution measurably (He et al., [doi:10.1038/s44172-024-00222-3] (https://doi.org/10.1038/s44172-024-00222-3)). This network takes the physical grid to be the pack's own series × parallel grid, which is the conventional assembly order but not the only one; an arbitrary permutation of cells onto grid positions is not expressible here, because it would destroy the banded structure the array equations rely on.

The single coolant node is the model's other main limitation. It is the right picture for natural convection or a symmetric cold plate, which is the regime in which the middle of a pack is the hottest part. Under a directional coolant flow the dominant gradient runs from inlet to outlet instead, because the coolant itself heats up as it passes the cells, and reproducing that needs a chain of coolant nodes rather than one.

The network requires a cell model with a single lumped temperature, which is every equivalent-circuit model. The distributed thermal models, whose cells carry separate left and right face temperatures, keep the ideal interfaces of the shared thermal path.

RCModel(; soc = :coulomb)

The RC (capacitance) model of [1] and [2], due to SAFT and shipped in ADVISOR: two capacitors in parallel branches — a very large bulk capacitor C_b behind the end resistance R_e, standing for the charge the cell stores chemically, and a small surface capacitor C_c behind the capacitor resistance R_c, standing for surface effects — with the terminal resistance R_t in series to the pins:

i_b + i_c = I,    U_b - i_b R_e = U_c - i_c R_c,
dU_b/dt = -i_b / C_b,    dU_c/dt = -i_c / C_c,    V = U_b - i_b R_e - I * R_t

The cell's charge lives in U_b, not in an OCV curve, so "open-circuit voltage" is used only to set U_b and U_c at t = 0 (both equal the rest voltage at SOC_initialₒcell). By default (soc = :coulomb) the SOC variable is coulomb-counted for the stop conditions and the pack interface and is not what drives the terminal voltage, so the two can drift apart over a long simulation. Of the five models [2] compares, this one has the second-largest terminal-voltage error under a dynamic load (0.234 V mean), behind only the Rint model.

soc = :capacitor defines the state of charge from the capacitor voltages instead, the way [1] does (its equation 2): each capacitor voltage is read back through the open-circuit voltage curve, OCV(SOC_b, T) = U_b and OCV(SOC_c, T) = U_c, and the cell's state of charge is the capacitance-weighted mean

SOC = (C_b SOC_b + C_c SOC_c) / (C_b + C_c)

which for a linear curve is the fraction of the charge the two capacitors hold over the curve. [1] fixes the weights at 20:1, the capacitance ratio of the Saft cell its model was written for (SaftHighPower12Ah, 82 kF against 4.074 kF); the weighting here reduces to that ratio for that cell and follows the capacitances for any other, where a fixed 20:1 would be arbitrary (He2011LiMn2O4 has a ratio near 2350). A rested cell has U_b = U_c = OCV(SOC, T), so this state of charge cannot drift from the terminal voltage, and a set whose capacitances and capacity disagree, as He2011LiMn2O4's do, shows the disagreement as a difference between the two definitions rather than hiding it.

The inversion is written as one implicit algebraic equation per capacitor, so no closed-form inverse is needed and the equation count of a pack stays independent of its size. It needs an "open-circuit voltage" that is a (SOC, T) callable and strictly increasing in the state of charge over [0, 1] at the initial temperature; the curve is sampled when the cell is built and a constant, or a curve held flat outside its window (linear_ocv with clamped = true over a sub-window), is rejected there rather than solved for a state of charge it does not determine. A capacitor voltage outside the curve's range over [0, 1] extrapolates the curve. "self-discharge current", "coulombic efficiency" and ECMDegradation.PrescribedHealth act on the coulomb counter, so they are rejected with this option rather than read and ignored. A temperature-dependent "nominal capacity" is accepted: the state of charge still comes from the capacitor voltages, and the capacity sets only the C-rate and the reported cell capacity.

Parameter set keys: "open-circuit voltage", "terminal resistance", "end resistance", "capacitor resistance", "bulk capacitance", "surface capacitance". See He2011LiMn2O4 and SaftHighPower12Ah.

[1] Valerie H. Johnson. "Battery performance models in ADVISOR." Journal of Power Sources 110, no. 2 (2002): 321-329. https://doi.org/10.1016/S0378-7753(02)00194-5

[2] Hongwen He, Rui Xiong and Jinxin Fan. "Evaluation of Lithium-Ion Battery Equivalent Circuit Models for State of Charge Estimation by an Experimental Approach." Energies 4, no. 4 (2011): 582-598. https://doi.org/10.3390/en4040582

Rint()

The internal-resistance (Rint) model: an open-circuit voltage in series with a single resistance, V = OCV(SOC, T) - I * R_0. It has no dynamics beyond the state of charge, so it reproduces the steady-state discharge curve and the instantaneous voltage step of a current pulse but none of the relaxation that follows. It is the least accurate of the five models [2] compares, with the largest terminal-voltage error under a dynamic load (0.394 V mean, against 0.043 V for the DP model).

Parameter set keys: "open-circuit voltage", "series resistance" (or the "discharge resistance" / "charge resistance" pair selected by the sign of the current; see EquivalentCircuitParameters).

[1] Valerie H. Johnson. "Battery performance models in ADVISOR." Journal of Power Sources 110, no. 2 (2002): 321-329. https://doi.org/10.1016/S0378-7753(02)00194-5

[2] Hongwen He, Rui Xiong and Jinxin Fan. "Evaluation of Lithium-Ion Battery Equivalent Circuit Models for State of Charge Estimation by an Experimental Approach." Energies 4, no. 4 (2011): 582-598. https://doi.org/10.3390/en4040582

SPM(chemistry; options...)
SPM()

The Single-Particle Model (`SPM`) model is a simplified version of the `SPMe` model, commonly used by technical battery engineers for quick and computationally efficient simulations. It represents the battery as single particles in both electrodes without considering the electrolyte dynamics. While less detailed than the `DFN` or `SPMe` models, the `SPM` model is effective for initial assessments, rapid battery analysis, and large-scale pack simulations.

SPMe(chemistry; options...)
SPMe()

The Single-Particle Model with electrolyte (`SPMe`) is a popular model to understand lithium-ion battery behavior. It simplifies the battery into a single particle for each electrode, considering electrolyte dynamics within the cell. This model allows for efficient simulations and provides valuable insights into cell-level behavior and degradation mechanisms.

Thevenin(; n = 1)
Thevenin(n)

The Thevenin model: Rint with n parallel RC pairs in series, which give the voltage relaxation a sum of n exponentials,

V = OCV(SOC, T) - Σₖ Uₖ - I * R_0,    dUₖ/dt = -Uₖ / (Rₖ Cₖ) + I / Cₖ

n = 1 is the first-order model of [1]; n = 2 is the second-order model, which is also what DP is. Of the twelve lumped models [2] compares on two cells, it prefers the first-order RC model for a LiNMC cell and the first-order RC model with one-state hysteresis — which is not one of the models here — for a LiFePO₄ one.

Parameter set keys: "open-circuit voltage", "series resistance", "polarization resistance" and "polarization capacitance" (a vector of n entries each).

[1] Hongwen He, Rui Xiong and Jinxin Fan. "Evaluation of Lithium-Ion Battery Equivalent Circuit Models for State of Charge Estimation by an Experimental Approach." Energies 4, no. 4 (2011): 582-598. https://doi.org/10.3390/en4040582

[2] Xiaosong Hu, Shengbo Li and Huei Peng. "A comparative study of equivalent circuit models for Li-ion batteries." Journal of Power Sources 198 (2012): 359-367. https://doi.org/10.1016/j.jpowsour.2011.10.013

ArrayBatteryPack(; name, family = BatteryModelFamily.EquivalentCircuit(),
    topology = ECMTopology.Thevenin(), series = 1, parallel = 1, kwargs...)

The Dyad interface to the shared array pack. family, topology, parameter_set, thermal, degradation, sei, sei_parameters and lam are structural enums. Electrochemical SEI/LAM selections specify electrodes, and sei_parameters names the published SEI parameter set (see SEI_degradation_default_params); ECM degradation selects no degradation or externally prescribed capacity health and resistance growth.

R_branch has shape (series, parallel) and R_link has length series + 1. Equivalent circuits give each RC branch its own (series, parallel) arrays: the polarization voltages U_1, U_2, … and the branch elements R_1, C_1, …. The equation count follows the topology and the RC order, not the pack dimensions. SOC_initial, T_initial and the thermal ECM parameter heat_capacity have shape (series, parallel); initial SOC and temperature also accept a scalar in Julia. The default heat capacity is one J/K, a generic component parameter rather than a value identified by the electrical literature. Set it for a thermal cell model.

The pins use the shared passive connector convention and I is discharge-positive. Thermal models expose two ArrayHeatPorts. Use cell_views for individual cell fields. Numerical assembly must retain array equations; the ordinary scalarizing mtkcompile route does not preserve pack compilation scaling.

Thermal boundary for a battery pack, with one independent temperature and inward heat flow per series row.

BatteryCell(; name, model = SPM(), chemistry = default_parameters(model), kwargs...)

A BatteryPack with series = parallel = 1, using exactly the same array representation, electrical pins and thermal connectors. Constitutive options are forwarded to the pack builder. Electrochemical models are thermal by default; ECMs are isothermal unless a thermal model and heat capacity are supplied.

Use only(cell_views(cell)) for the cell's symbolic states and parameters, including SOC_initialₒcell and T_cell. The component itself exposes pack quantities such as V, I, SOC and T. Compile its circuit with mtkcompile and build an ODEProblem as for any ModelingToolkit component.

BatteryPack(; name, model = SPM(), chemistry = default_parameters(model),
    series = 1, parallel = 1, R_connection = 0.0, wiring = :parallel_groups,
    kwargs...)

A shared array pack with scalar electrical pins p and n. ECM and SPM/SPMe/DFN constitutive models use the same network. A cell is the 1×1 case. Current entering p charges the pack; reported I = -p.i is discharge-positive.

Cell fields and parameters retain (series, parallel) pack axes. Access individual cells with cell_views. Thermal variants expose two ArrayHeatPorts with (series, 1) temperatures and heat flows. Parallel neighbors exchange heat within each series row. R_connection defaults each cell branch and each of the series + 1 series links; R_branch and R_link can provide separate arrays.

wiring chooses the order in which the grid is connected, the choice Modelica.Electrical.Batteries makes with useAllParallelConnections:

• :parallel_groups (the default) wires parallel cells in parallel and those groups in series, so every cell of a series row shares a row voltage and the groups share the pack current;
• :series_strings wires series cells in series and those strings in parallel, so every cell of a string carries the same string current and the strings share the pack voltage.

Identical cells split the current evenly under either wiring, so with ideal connections the two differ only when the cells do — which is the case a mixed pack is built to study. R_branch stays in series with its cell either way; R_link does not, because the links move, and that separates the two wirings even for identical cells. With :parallel_groups all series + 1 links carry the pack current. With :series_strings the interior links R_link[2:series] sit inside each string and carry that string's current, and only R_link[1] and R_link[series + 1] carry the pack current. The thermal coupling describes physical adjacency in the grid and is unaffected by wiring.

The pack reports V, I, P, SOC, SOC_abs, SOH, T, Q, Q_theoretical and C_rate. Q_interconnect reports connection-resistor loss. The remaining options are those of the constitutive model. The symbolic model is a fixed set of array equations whose size does not depend on series × parallel; mtkcompile currently scalarizes them, so compiled and numerical work grow with the cell count.

BulkSurfaceCircuit(; name, degradation, capacity, SOC_initial, U0)

SAFT bulk/surface topology with supplied element signals and initial rest voltage U0.

Parameters:

Connectors

• capacity_health - This connector represents a real signal as an input to a component (RealInput)
• resistance_growth - This connector represents a real signal as an input to a component (RealInput)
• p - This connector represents an electrical pin with voltage and current as the potential and flow variables, respectively. (Pin)
• n - This connector represents an electrical pin with voltage and current as the potential and flow variables, respectively. (Pin)
• r_t - This connector represents a real signal as an input to a component (RealInput)
• r_e - This connector represents a real signal as an input to a component (RealInput)
• r_c - This connector represents a real signal as an input to a component (RealInput)
• c_b - This connector represents a real signal as an input to a component (RealInput)
• c_c - This connector represents a real signal as an input to a component (RealInput)

Variables

BulkSurfaceECM(; name, degradation, capacity, SOCinitial, U0, Rt, Re, Rc, Cb, Cc)

SAFT RC cell with constant elements; He et al. (2011), equation (2).

Parameters:

Connectors

• capacity_health - This connector represents a real signal as an input to a component (RealInput)
• resistance_growth - This connector represents a real signal as an input to a component (RealInput)
• p - This connector represents an electrical pin with voltage and current as the potential and flow variables, respectively. (Pin)
• n - This connector represents an electrical pin with voltage and current as the potential and flow variables, respectively. (Pin)
• r_t - This connector represents a real signal as an input to a component (RealInput)
• r_e - This connector represents a real signal as an input to a component (RealInput)
• r_c - This connector represents a real signal as an input to a component (RealInput)
• c_b - This connector represents a real signal as an input to a component (RealInput)
• c_c - This connector represents a real signal as an input to a component (RealInput)

Variables

ChenRinconMora2006()

Equivalent circuit parameters for the 850 mA⋅h TCL PL-383562 polymer lithium-ion cell of [1], at room temperature. Every element is a function of the state of charge, fitted in [1] (its equations 2-7) to pulse-discharge data at 80, 160, 320 and 640 mA:

The two RC pairs are the short and the long time constant of the step response, in that order, which makes the set the natural one for DP (or Thevenin(2)); Thevenin with the default n = 1 keeps the short pair alone and Rint neither. It parameterizes no PNGV capacitor and none of the RCModel elements — see He2011LiMn2O4 for those.

The stop conditions are the cell's test limits from [1]: 4.1 V constant-voltage charge with a 10 mA end-of-charge current, charge current below 800 mA, 3.0 V end of discharge. The SOC_min bound of 0.02 is not from [1]: the fitted capacitances of its equations 5 and 7 cross zero at about 0.5% and 1.1% state of charge, so the model has to be kept above that, and [1] reports the fits degrading below 10% state of charge in any case.

temperature = true needs a "heat capacity", which [1] does not report.

[1] Min Chen and Gabriel A. Rincón-Mora. "Accurate Electrical Battery Model Capable of Predicting Runtime and I-V Performance." IEEE Transactions on Energy Conversion 21, no. 2 (2006): 504-511. https://doi.org/10.1109/TEC.2006.874229

ChenRinconMoraECM(; name, degradation, nrc, capacity, SOCinitial)

Chen and Rincon-Mora (2006), equations (2)-(7), 850 mAh polymer Li-ion cell at room temperature. Use within SOC 0.02-1; no aging or self-discharge is fitted. DOI: 10.1109/TEC.2006.874229.

Parameters:

Connectors

• capacity_health - This connector represents a real signal as an input to a component (RealInput)
• resistance_growth - This connector represents a real signal as an input to a component (RealInput)
• p - This connector represents an electrical pin with voltage and current as the potential and flow variables, respectively. (Pin)
• n - This connector represents an electrical pin with voltage and current as the potential and flow variables, respectively. (Pin)
• ocv - This connector represents a real signal as an input to a component (RealInput)
• r0 - This connector represents a real signal as an input to a component (RealInput)
• r - This connector represents a real signal as an input to a component (RealInput)
• c - This connector represents a real signal as an input to a component (RealInput)

Variables

Cycler(; name, protocol, capacity, bounds = (;))
Cycler(; name, state = CyclerState())

A battery cycler as a ModelingToolkit component: an electrical source with the pins p and n that imposes a current, a voltage or a power on the connected battery and switches between the steps of a cycling protocol on events. CyclingCircuit wires one up with a BatteryPack and a ground; build the circuit by hand when the battery is part of a larger model.

protocol is an experiment or a vector of experiments (charge, discharge, voltage, power, rest); C-rates in it are converted with capacity (A⋅h, see capacity_pack). bounds are the default stop conditions, e.g. (V_min = 2.7, V_max = 4.2, SOC_min = 0.0, SOC_max = 1.0). state is the CyclerState the cycler logs into; pass one in and read it back with experiment_results to get the exit reasons.

@named cell = BatteryCell(; model = SPM(), chemistry = NMC(), temperature = false)
@named cycler = Cycler(; protocol = [charge(1C), voltage(hold), rest(time = 600)],
    capacity = 5.0, bounds = (V_max = 4.2, I_min = 0.25))
@named ground = Ground()
eqs = [connect(cell.p, cycler.p); connect(cycler.n, cell.n); connect(cell.n, ground.g);
       cycler.SOC_in.u ~ cell.SOC; cycler.T_in.u ~ cell.T]
sys = mtkcompile(System(eqs, t; systems = [cell, cycler, ground], name = :circuit))
prob = ODEProblem(sys, [only(cell_views(cell)).SOC_initialₒcell => 0.2], (0.0, 1e5))
sol = solve(prob, FBDF())

All battery models use the same passive electrical connectors. Positive cycler current enters its p pin and leaves the battery's positive pin during discharge.

Variables: I (positive when the connected battery discharges), v (voltage across the pins) and P = I v. The inputs SOC_in and T_in (RealInputs) take the state of charge and the temperature the stop conditions refer to.

Parameters: the default stop conditions I_min, I_max, V_min, V_max, P_min, P_max, T_min, T_max, SOC_min, SOC_max (NaN disables one; current and power bounds apply to the magnitude), the current step step, its mode (1 current, 2 voltage, 3 power), setpoint X_app and end time t_end, and the stop conditions in force during the step (I_min_step, ...).

Events: a step ends when its end time is reached or when one of its stop conditions is hit (continuous events on t - t_end, |I| - I_max_step, V_min_step - V, ...). The affect logs the end of the step in state and loads the parameters of the next step of state.steps, skipping steps whose stop conditions are already violated, and terminates the integration after the last step. The DAE is re-initialized with BrownFullBasicInit after every switch.

CyclingCircuit(; name, model = SPM(), chemistry = default_parameters(model),
    series = 1, parallel = 1, protocol, bounds = (;), R_connection = 0.0,
    T_ambient = 298.15, heat_transfer_coefficient = 1.0, cooling = nothing,
    state = CyclerState(), kwargs...)

A BatteryPack, the shared Cycler, ground and optional native PackAmbient boundaries. Thermal coupling uses two array connectors, independently of pack dimensions. T_ambient accepts a scalar or a (series, 1) array. The same electrical convention and protocol apply to every model family.

cooling = ForcedAirCooling(...) replaces the fixed ambient with a PackForcedAir boundary named cooler: a fan switched by a thermostat on the pack's hottest cell temperature, blowing air at T_ambient over a case. With the per-row heat ports each row face reaches the case node through heat_transfer_coefficient; with a thermal_network the case node is the network's coolant.

Compile with mtkcompile and solve with a stiff ODE/DAE algorithm such as FBDF. For example:

@named circuit = CyclingCircuit(; model = SPM(), series = 2, parallel = 3,
    temperature = false, SEI_degradation = false,
    protocol = [discharge_current(0.3; time = 10), rest(time = 5)])
cells = cell_views(circuit)
sys = mtkcompile(circuit)
prob = ODEProblem(sys, [c.SOC_initialₒcell => 0.6 for c in cells], (0.0, 30.0))
sol = solve(prob, FBDF())

The circuit exposes the pack quantities directly. Per-cell states and parameters are available through cell_views; it contains no cell_s_p subsystems. The integration terminates after the final protocol step, and state records the step boundaries for experiment_results.

DualPolarizationECM(; name, degradation, nrc, capacity, SOCinitial, R0, R, C)

Dual polarization is the two-branch Thevenin topology.

Parameters:

Connectors

• capacity_health - This connector represents a real signal as an input to a component (RealInput)
• resistance_growth - This connector represents a real signal as an input to a component (RealInput)
• p - This connector represents an electrical pin with voltage and current as the potential and flow variables, respectively. (Pin)
• n - This connector represents an electrical pin with voltage and current as the potential and flow variables, respectively. (Pin)
• ocv - This connector represents a real signal as an input to a component (RealInput)
• r0 - This connector represents a real signal as an input to a component (RealInput)
• r - This connector represents a real signal as an input to a component (RealInput)
• c - This connector represents a real signal as an input to a component (RealInput)

Variables

ECMBulkSurface(; name, U_initial)

SAFT bulk/surface capacitor network: He et al. (2011), equation (2).

Parameters:

Connectors

• I - This connector represents a real signal as an input to a component (RealInput)
• R_t - This connector represents a real signal as an input to a component (RealInput)
• R_e - This connector represents a real signal as an input to a component (RealInput)
• R_c - This connector represents a real signal as an input to a component (RealInput)
• C_b - This connector represents a real signal as an input to a component (RealInput)
• C_c - This connector represents a real signal as an input to a component (RealInput)
• OCV - This connector represents a real signal as an output from a component (RealOutput)
• V - This connector represents a real signal as an output from a component (RealOutput)
• Q - This connector represents a real signal as an output from a component (RealOutput)

Variables

ECMCharge(; name, capacity, SOC_initial)

Coulomb counting in seconds and ampere-hours, with discharge-positive current.

Parameters:

Connectors

• I - This connector represents a real signal as an input to a component (RealInput)
• health - This connector represents a real signal as an input to a component (RealInput)

Variables

ECMHealth(; name, degradation)

Health interface for independently calibrated aging laws. SOH is available/nominal capacity; resistance_factor scales resistances only.

Parameters:

Connectors

• capacity_health - This connector represents a real signal as an input to a component (RealInput)
• resistance_growth - This connector represents a real signal as an input to a component (RealInput)

Variables

ECMOCVDrift(; name)

Series storage capacitor; positive discharge current increases the voltage loss.

Connectors

• I - This connector represents a real signal as an input to a component (RealInput)
• C - This connector represents a real signal as an input to a component (RealInput)

Variables

ECMOhmic(; name)

Ohmic voltage loss and resistor dissipation, with discharge-positive current.

Connectors

• I - This connector represents a real signal as an input to a component (RealInput)
• OCV - This connector represents a real signal as an input to a component (RealInput)
• R - This connector represents a real signal as an input to a component (RealInput)
• V - This connector represents a real signal as an output from a component (RealOutput)
• Q - This connector represents a real signal as an output from a component (RealOutput)

ECMPolarization(; name, U_initial)

Polarization branch: He et al. (2011), equation (3). R and C may vary with SOC.

Parameters:

Connectors

• I - This connector represents a real signal as an input to a component (RealInput)
• R - This connector represents a real signal as an input to a component (RealInput)
• C - This connector represents a real signal as an input to a component (RealInput)
• Q - This connector represents a real signal as an output from a component (RealOutput)

Variables

ECMThermalMass(; name, Cth, Tinitial)

Lumped thermal balance; Q is an explicitly supplied heat law, not inferred from fitted RC storage.

Parameters:

Connectors

• Q - This connector represents a real signal as an input to a component (RealInput)
• left - This connector represents a thermal port with temperature and heat flow as the potential and flow variables, respectively. (HeatPort)
• right - This connector represents a thermal port with temperature and heat flow as the potential and flow variables, respectively. (HeatPort)

Variables

EDLCParameters(; capacitance, rated_voltage, series_resistance,
    minimum_voltage = rated_voltage / 2, initial_state_of_charge = 1.0,
    initial_temperature = 298.15u"K", heat_capacity = nothing)

The parameter set of an EDLC cell, built from the three numbers a double-layer capacitor is actually sold by: a capacitance [F], a rated_voltage [V] and an equivalent series_resistance [Ω]. This is the constructor to reach for when modelling a device from its datasheet; MaxwellPC2500 is a worked example of its use.

capacitance and rated_voltage must be constants, since together they fix the charge C V_rated that the state of charge counts against. series_resistance is an ordinary circuit element and may also be a (SOC, T) callable in SI units, which is how a temperature-dependent equivalent series resistance is supplied.

The stop conditions are the voltage window minimum_voltage to rated_voltage; no current, power, state-of-charge or temperature bound is set, since a capacitor datasheet states none that maps onto one. minimum_voltage defaults to half the rated voltage, the conventional floor that leaves three quarters of the stored energy delivered and, being V_oc / 2, is also where a series-resistance-limited discharge reaches its maximum power. Pass heat_capacity [J/K] to build the cell with temperature = true.

EquivalentCircuitCell(; name, topology, degradation, nrc, capacity, SOCinitial, R0, R, C, Rdp, Cdp, U0, Cocv, Rt, Re, Rc, Cb, Cc)

Native Dyad ECM selector. All circuit alternatives are native components. Parameters are SI except capacity in Ah. PrescribedHealth requires two health signals; it is not a fitted aging law.

Parameters:

Connectors

• p - This connector represents an electrical pin with voltage and current as the potential and flow variables, respectively. (Pin)
• n - This connector represents an electrical pin with voltage and current as the potential and flow variables, respectively. (Pin)
• ocv - This connector represents a real signal as an input to a component (RealInput)
• capacity_health - This connector represents a real signal as an input to a component (RealInput)
• resistance_growth - This connector represents a real signal as an input to a component (RealInput)

Variables

EquivalentCircuitParameters(; overall, circuit, bounds = Dict{String, Any}())

An equivalent circuit parameter set, the chemistry of a cell built with one of the EquivalentCircuitModels. See ChenRinconMora2006 and He2011LiMn2O4 for the two faradaic sets shipped here and MaxwellPC2500 for the capacitor, and copy one to write your own.

overall holds the cell as a whole, all of it optional: "nominal capacity" [A⋅h, the capacity the state of charge is counted against, derived rather than read for an EDLC], "initial state of charge", "initial temperature" [K, the temperature of an isothermal cell], "heat capacity" [J/K, needed only for temperature = true] and "entropic coefficient" [V/K, dOCV/dT, zero by default].

Two further entries act on the coulomb counter and are off unless the set asks for them. "self-discharge current" [A] is the current the cell loses to itself at full charge, the way Modelica.Electrical.Batteries parameterizes its parallel conductor: the conductance is that current over the open-circuit voltage at full charge, so the loss falls with the state of charge and its power is dissipated in the cell. "coulombic efficiency" [1, one by default] is the fraction of a charging current that reaches the stored charge; the rest becomes heat at the terminal voltage, and a discharging current is unaffected.

"nominal capacity" and "coulombic efficiency" may also be callables T -> value of the cell temperature, in A⋅h and as a fraction, such as a LookupTable over temperature — the C(T) and η(T) of ADVISOR's Rint model. A temperature-dependent capacity changes the bookkeeping the way ADVISOR's does: the cell then integrates the charge drawn from full, q_drawn [A⋅h], and reports SOC = 1 - q_drawn / (C(T) SOH), starting from "initial state of charge" at the initial temperature. Charge is conserved, and a cell at rest changes its state of charge when a temperature change moves its capacity; integrating the state of charge against a moving capacity instead would make the charge a cycle returns depend on the temperatures it was drawn at. cell_capacity, theoretical_capacity and C_rate follow C(T). With a constant capacity the state of charge itself is the integrated state, as before. Either callable is evaluated at "initial temperature" unless the cell is built with temperature = true.

circuit holds the circuit elements, which keys depend on the model — see Rint, Thevenin, DP, PNGV, RCModel and EDLC. Each entry is either a constant, with or without a Unitful unit, which becomes a parameter of the component that a problem can override, or a callable (SOC, T) -> value in SI units, which is inlined as an expression in the state of charge and the cell temperature and cannot be overridden; a LookupTable is such a callable, interpolating a measured grid. Where the set identifies elements per model, as He2011LiMn2O4 does, a subsection named after the model ("DP", "PNGV", …) overrides the common entries.

The models with a series resistance (Rint, Thevenin, DP, PNGV, EDLC) take it either as one "series resistance" or as a "discharge resistance" and a "charge resistance" pair, selected by the sign of the current the way ADVISOR's Rint tables are: R_0 is the discharge value while the reported current I is positive (discharging) and the charge value while it is negative. Both keys are needed, and a set that gives the pair as well as "series resistance" is rejected rather than read two ways. Every shipped set but SaftLiIon6Ah uses the single entry.

bounds holds the default stop conditions of a Cycler driving the cell, keyed "voltage maximum", "current minimum", … over voltage, current, power, state of charge and temperature. A bound left out is disabled.

He2011LiMn2O4()

Equivalent circuit parameters for the 100 A⋅h, 57.6 V nominal LiMn₂O₄ battery module of [1], identified with a genetic algorithm from a hybrid pulse power characterization (HPPC) test. It is the one published set that covers all five topologies of the same cell, which is what makes them comparable, and the only one here that parameterizes PNGV and RCModel.

The identification is local. [1] reports one parameter set per model at 50% and at 60% state of charge (its tables 1-5) and nothing outside that window, so:

• the elements here are the 50% row, held constant. How far the 60% row moves is a fair measure of how local the fit is: under 2% for the ohmic resistances and for every DP element, but 4% and 12% for the resistance and the capacitance of the Thevenin RC pair, and 21% and 12% for the bulk and the surface capacitance of the RCModel;
• the open-circuit voltage is the straight line through the two reported points, which means the module's real curvature is missing and extrapolating outside 0.5-0.6 is meaningless. The default SOC_min/SOC_max bounds are 0.5 and 0.6 for that reason, and the default initial state of charge is 0.55;
• every other bound is NaN, i.e. disabled: an HPPC test reports no cut-off voltages, currents or temperatures, so there are none to take from [1].

Each model gets its own subsection, since [1] identifies the elements per model — across the Rint, Thevenin, PNGV and DP tables the U_oc values agree to 0.3% and the R_0 values to 3%, but they are not the same numbers. Thevenin(n) for n > 1 has no entry: use DP for the second-order fit.

temperature = true needs a "heat capacity", which [1] does not report.

[1] Hongwen He, Rui Xiong and Jinxin Fan. "Evaluation of Lithium-Ion Battery Equivalent Circuit Models for State of Charge Estimation by an Experimental Approach." Energies 4, no. 4 (2011): 582-598. https://doi.org/10.3390/en4040582

LCO()

Default parameters for a lithium cobalt oxide (LCO) cell.

This is the reference cell of the LIONSIMBA toolbox [1] — there called the "Northrop cell". The electrode, separator, electrolyte and thermal values below are those of Table IV of [1] and Table III of [2] (the active-material fractions as one minus porosity minus filler fraction), and the physics functions those of Table II of [1] and Tables II and VII of [2]; all of them also match Parameters_init.m and the physics routines of LIONSIMBA. [1] states that the parameters describing the chemistry are taken from [2]. Not printed in either paper:

• the stoichiometry limits, which are those of LIONSIMBA's Parameters_init.m; the papers give only the initial concentrations, 25751 and 26128 mol/m³
• the zero initial film resistance and the SEI exchange current density, which belong to this package's SEI submodel (see SEI_degradation_default_params)
• the nominal capacity, which is LIONSIMBA's 1C current density of 29.23 A/m² re-expressed as a capacity over the 1 m² cross-section
• the heat transfer coefficient, the voltage bounds and the two current collectors, which are this package's own; LIONSIMBA's collectors differ slightly (copper 8940 kg/m³ and 5.96e7 S/m, aluminium 3.55e7 S/m)

The individual correlations and values, and where they come from:

• electrode and separator geometry, transport and kinetics: [2] takes them from Subramanian et al. (2009), https://doi.org/10.1149/1.3065083. Table I of [3] has the same thicknesses, conductivities, porosities, Bruggeman exponent, particle radius, solid diffusivities and negative-electrode maximum concentration, and rate constants of 4.854e-6 and 2.252e-6 (A/m²)(m³/mol)^1.5, the values used here. It differs in the positive-electrode maximum concentration (51555 rather than 51554 mol/m³), the negative-electrode active-material fraction (0.49 rather than 0.4824) and the transference number (0.363 rather than 0.364).

• thermal conductivities: Kumaresan, Sikha & White (2008), https://doi.org/10.1149/1.2817888, according to [2]; densities, specific heats and activation energies are marked as assumed values in [2]

• open-circuit potentials, both electrodes: [3], Eqs. A-1 and A-2

• entropic coefficients ∂U/∂T, both electrodes: [2] Table VII attributes both fits to Guo, Sikha & White (2011), https://doi.org/10.1149/1.3521314. [2] prints the θ⁷ term of the negative-electrode numerator with a minus sign; [1] Table II and the function here have a plus, the only one of the two that gives values of the size of a graphite entropic coefficient (at most 2.5e-4 V/K rather than tens of V/K).

• electrolyte diffusivity and ionic conductivity: [4], as printed in [2] Table VII and [1] Table II

  [1] Torchio, M., Magni, L., Gopaluni, R. B., Braatz, R. D., & Raimondo, D. M. (2016). LIONSIMBA: A Matlab framework based on a finite volume model suitable for Li-ion battery design, simulation, and control. Journal of The Electrochemical Society, 163(7), A1192–A1205. https://doi.org/10.1149/2.0291607jes

  [2] Northrop, P. W. C., Ramadesigan, V., De, S., & Subramanian, V. R. (2011). Coordinate transformation, orthogonal collocation, model reformulation and simulation of electrochemical-thermal behavior of lithium-ion battery stacks. Journal of The Electrochemical Society, 158(12), A1461. https://doi.org/10.1149/2.058112jes

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

  [4] Valøen, L. O., & Reimers, J. N. (2005). Transport properties of LiPF6-based Li-ion battery electrolytes. Journal of The Electrochemical Society, 152(5), A882. https://doi.org/10.1149/1.1872737

LFP()

Default parameters for a lithium iron phosphate (LFP) cell: an A123 LFP/graphite cylindrical cell. Every electrode, separator and electrolyte value below matches the Prada2013 parameter set of PyBaMM as it stood up to and including PyBaMM v23.5, except the two reaction rate constants (see below); that set was replaced upstream on 2023-07-04 and today's PyBaMM Prada2013 differs in most of its values, so [1]-[5] rather than "PyBaMM Prada2013" are the citations to follow. The cell-level entries are this package's own: the electrode height and nominal capacity are both scaled by a factor of 8.656359827565312, and the voltage bounds are 2.5/4.2 V where the upstream set had 2.0/4.4 V.

The upstream exchange-current prefactors are 6.48e-7 and 6e-7 (A/m²)(m³/mol)^1.5, in the same form as this package's reaction rate constant. The values here are those multiplied by F / (c_max √c_e0) with c_e0 = 1000 mol/m³, the conversion for a BPX normalised rate constant, which makes them 0.092 and 0.134 times upstream.

Like most parameter sets of this kind it is assembled from several sources, one or two per physical quantity:

• cell format and capacity: [1]

• negative electrode (graphite) and separator: [2]

• positive electrode (LFP): [3]

• negative electrode open-circuit potential: [2]

• positive electrode open-circuit potential: [4]

• electrolyte diffusivity and ionic conductivity: [5]

  [1] Lain, M. J., Brandon, J., & Kendrick, E. (2019). Design strategies for high power vs. high energy lithium ion cells. Batteries, 5(4), 64. https://doi.org/10.3390/batteries5040064

  [2] Chen, C.-H., Brosa Planella, F., O'Regan, K., Gastol, D., Widanage, W. D., & Kendrick, E. (2020). Development of experimental techniques for parameterization of multi-scale lithium-ion battery models. Journal of The Electrochemical Society, 167(8), 080534. https://doi.org/10.1149/1945-7111/ab9050

  [3] Prada, E., Di Domenico, D., Creff, Y., Bernard, J., Sauvant-Moynot, V., & Huet, F. (2013). A simplified electrochemical and thermal aging model of LiFePO4-graphite Li-ion batteries: power and capacity fade simulations. Journal of The Electrochemical Society, 160(4), A616–A628. https://doi.org/10.1149/2.053304jes

  [4] Afshar, S., Morris, K., & Khajepour, A. (2017). Efficient electrochemical model for lithium-ion cells. arXiv preprint arXiv:1709.03970. https://arxiv.org/abs/1709.03970

  [5] Nyman, A., Behm, M., & Lindbergh, G. (2008). Electrochemical characterisation and modelling of the mass transport phenomena in LiPF6-EC-EMC electrolyte. Electrochimica Acta, 53(22), 6356–6365. https://doi.org/10.1016/j.electacta.2008.04.023

LFP2()

Alternative parameters for a lithium iron phosphate (LFP) cell: an LFP/graphite 2 Ah cylindrical 18650 cell, parameterised by About:Energy Limited (aboutenergy.io) in December 2022 from cell cycling data and post-teardown electrode data, and published as the lfp_18650_cell_BPX.json example of the Faraday Institution's BPX standard [1]. The geometry, transport, stoichiometry and activation-energy values of the electrodes and separator, the electrolyte, and both open-circuit potentials match that file, with these differences:

• the two reaction rate constants are [1]'s normalised rate constants k [mol/(m²⋅s)], 6.872e-6 and 9.736e-7, entered unconverted as this package's exchange-current prefactor; the conversion F k / (c_max √c_e0) that NMC applies to the same kind of value gives 6.678e-7 and 1.401e-7
• the electrode and separator thermal properties are not from [1], which gives only lumped cell values; they are those of LFP
• capacity and area are normalised to a 1 m² cross-section, and the voltage bounds are 2.0/4.4 V where [1] gives 2.0/3.65 V

Its own sources, as stated in the BPX header:

• electrolyte properties: [2]
• negative electrode entropic coefficient: [3]
• positive electrode entropic coefficient: [4] (tabulated in [1]; fitted to a cubic here)
• other thermal properties: estimated

The two open-circuit potentials are the fitted expressions given directly in [1]; they are not taken from any of [2]-[4]. In particular the negative electrode OCP here is not the Chen et al. (2020) LG M50 graphite fit used by LFP, despite an earlier version of this file citing it as such.

[1] Faraday Institution BPX standard, `examples/lfp_18650_cell_BPX.json`,
<https://github.com/FaradayInstitution/BPX>

[2] Nyman, A., Behm, M., & Lindbergh, G. (2008). Electrochemical characterisation
and modelling of the mass transport phenomena in LiPF6-EC-EMC electrolyte.
Electrochimica Acta, 53(22), 6356–6365.
<https://doi.org/10.1016/j.electacta.2008.04.023>

[3] O'Regan, K., Brosa Planella, F., Widanage, W. D., & Kendrick, E. (2022).
Thermal-electrochemical parameters of a high energy lithium-ion cylindrical battery.
Electrochimica Acta, 425, 140700.
<https://doi.org/10.1016/j.electacta.2022.140700>

[4] Gerver, R. E., & Meyers, J. P. (2011). Three-dimensional modeling of
electrochemical performance and heat generation of lithium-ion batteries in tabbed
planar configurations. Journal of The Electrochemical Society, 158(7), A835.
<https://doi.org/10.1149/1.3591799>

MaxwellPC2500()

EDLC parameters for the 2.5 V Maxwell PC2500 double-layer capacitor, from the measurements [1] reports at NREL's battery thermal management testing facility and ships as the data file of the ultracapacitor block of [2]; the device's own datasheet is [3].

[1] measures capacitance and series resistance on a grid of three temperatures (0, 25 and 40 °C) and six currents (±56.3, ±112.5 and ±225 A), following the test procedure of [4]. An EDLC has one constant of each, so this set takes the 25 °C row at the +112.5 A discharge current, the breakpoint nearest the 100 A rated current of [3]. Across that whole row the measured capacitance spans 2880-2926 F and the resistance 0.890-0.952 mΩ, so the current dependence the single constant drops is under 2% and under 7% respectively. Across all three temperatures it is wider, 2842-2926 F and 0.831-1.182 mΩ; a temperature-dependent series resistance can be passed to EDLCParameters as a (SOC, T) callable if that 42% spread matters.

The measured capacitance sits above the 2700 F ±20% of [3], which is expected: [2] integrates the whole charge of the test including the tapered region rather than the constant-current portion alone, and reports it as a total-charge capacitance. Note also that [1] gives the module mass as 0.71 kg where [3] rates it at 725 g; the heat capacity here uses [1]'s mass and its mean specific heat, 0.71 kg × 1543 J/(kg⋅K).

No "coulombic efficiency" is set, so charge is counted losslessly. [1] does tabulate one over the same (temperature, current) grid, 0.990 to 0.999, but as a two-dimensional table against a current the shared scalar "coulombic efficiency" key has no axis for; the alternative would be to pick one cell of it, which for a 1% effect is not worth the pretence. Set the key yourself if the charge accounting matters more than that.

The stop conditions are 2.5 V to 1.25 V. [1] itself sets its minimum voltage to zero, with a comment that the operating window should be imposed by limiting the state-of-charge range to 0.5-1.0 instead; since SOC = V_oc / V_rated for an EDLC, the half-rated voltage bound here is that same window written once rather than twice.

[1] Tony Markel and Matt Zolot. ESS_UC2_Maxwell.m, "Maxwell PC2500 Ultracapacitor, tested at NREL", National Renewable Energy Laboratory, 1 November 2001.

[2] ADVISOR 2003-00-r0116, Alliance for Sustainable Energy, LLC. https://sourceforge.net/projects/adv-vehicle-sim/

[3] BOOSTCAP Ultracapacitor PC2500 Data Sheet, document 1003992 Rev. 5, Maxwell Technologies. 2700 F ±20%, 2.5 V, 1.0 mΩ DC ±25%, 725 g. https://web.archive.org/web/20060317025924if_/http://www.maxwell.com/pdf/uc/datasheets/PC2500.pdf

[4] Electric Vehicle Capacitor Test Procedure Manual, Revision 0. DOE/ID-10491, Idaho National Engineering Laboratory, October 1994.

NCA()

Default parameters for a lithium nickel cobalt aluminum oxide (NCA) cell [1].

[1] Kim, G. H., Smith, K., Lee, K. J., Santhanagopalan, S., & Pesaran, A.
(2011). Multi-domain modeling of lithium-ion batteries encompassing
multi-physics in varied length scales. Journal of The Electrochemical
Society, 158(8), A955-A969. <https://doi.org/10.1149/1.3597614>

NMC()

Default parameters for a lithium nickel manganese cobalt oxide (NMC) cell: an NMC111/graphite 12.5 Ah pouch cell, parameterised by About:Energy Limited (aboutenergy.io) in December 2022 from cell cycling data and post-teardown electrode data, and published as the nmc_pouch_cell_BPX.json example of the Faraday Institution's BPX standard [1].

Every electrode, separator and electrolyte value below, both open-circuit potentials, the positive electrode entropic coefficient, the activation energies and the voltage bounds match that file. The reaction rate constants are the file's normalised rate constants k [mol/(m²⋅s)] converted to this package's exchange-current prefactor, F k / (c_max √c_e0) with c_e0 = 1000 mol/m³. The capacity and area are those of one of the cell's 34 electrode pairs, both scaled to a 1 m² cross-section.

Not taken from [1]:

• the negative electrode entropic coefficient is zero here; [1] gives a fit of up to 3.8e-4 V/K, which it attributes to O'Regan et al. (2022)
• the electrode and separator thermal properties (thermal conductivity, density, specific heat capacity), which [1] gives only as lumped cell values; these are identical to those of the Marquis2019 set of PyBaMM [4]

The sources [1] itself states:

• electrolyte diffusivity and ionic conductivity: [2]; the activation energy of both, 17100 J/mol, is [1]'s

• positive electrode entropic coefficient: [3]

  [1] Faraday Institution BPX standard, examples/nmc_pouch_cell_BPX.json, https://github.com/FaradayInstitution/BPX

  [2] Nyman, A., Behm, M., & Lindbergh, G. (2008). Electrochemical characterisation and modelling of the mass transport phenomena in LiPF6-EC-EMC electrolyte. Electrochimica Acta, 53(22), 6356–6365. https://doi.org/10.1016/j.electacta.2008.04.023

  [3] Viswanathan, V. V., Choi, D., Wang, D., Xu, W., Towne, S., Williford, R. E., Zhang, J.-G., Liu, J., & Yang, Z. (2010). Effect of entropy change of lithium intercalation in cathodes and anodes on Li-ion battery thermal management. Journal of Power Sources, 195(11), 3720–3729. https://doi.org/10.1016/j.jpowsour.2009.11.103

  [4] Marquis, S. G., Sulzer, V., Timms, R., Please, C. P., & Chapman, S. J. (2019). An asymptotic derivation of a single particle model with electrolyte. Journal of The Electrochemical Society, 166(15), A3693–A3706. https://doi.org/10.1149/2.0341915jes

NMC_LiMetal()

Default parameters for an NMC-Li metal cell.

PNGVCircuit(; name, degradation, capacity, SOC_initial)

PNGV topology with supplied element signals; ocv is the fixed local linearization voltage.

Parameters:

Connectors

• capacity_health - This connector represents a real signal as an input to a component (RealInput)
• resistance_growth - This connector represents a real signal as an input to a component (RealInput)
• p - This connector represents an electrical pin with voltage and current as the potential and flow variables, respectively. (Pin)
• n - This connector represents an electrical pin with voltage and current as the potential and flow variables, respectively. (Pin)
• ocv - This connector represents a real signal as an input to a component (RealInput)
• r0 - This connector represents a real signal as an input to a component (RealInput)
• r1 - This connector represents a real signal as an input to a component (RealInput)
• c1 - This connector represents a real signal as an input to a component (RealInput)
• c_ocv - This connector represents a real signal as an input to a component (RealInput)

Variables

PNGVECM(; name, degradation, capacity, SOCinitial, U0, R0, R1, C1, Cocv)

PNGV local OCV linearization; U0 is fixed and the drift capacitor accounts for OCV change.

Parameters:

Connectors

• capacity_health - This connector represents a real signal as an input to a component (RealInput)
• resistance_growth - This connector represents a real signal as an input to a component (RealInput)
• p - This connector represents an electrical pin with voltage and current as the potential and flow variables, respectively. (Pin)
• n - This connector represents an electrical pin with voltage and current as the potential and flow variables, respectively. (Pin)
• ocv - This connector represents a real signal as an input to a component (RealInput)
• r0 - This connector represents a real signal as an input to a component (RealInput)
• r1 - This connector represents a real signal as an input to a component (RealInput)
• c1 - This connector represents a real signal as an input to a component (RealInput)
• c_ocv - This connector represents a real signal as an input to a component (RealInput)

Variables

PackAmbient(; name, series, temperature, conductance)

Convective boundary applied independently to every series row of an array pack.

Parameters:

Connectors

• port - Thermal boundary for a battery pack, with one independent temperature and inward heat flow per series row. (ArrayHeatPort)

PackForcedAir(; name, cooling = ForcedAirCooling(), temperature = 298.15,
    series = nothing, conductance = 1.0)

A forced-air convective boundary for a battery pack: one massless case node, an air node, and a thermostat-controlled fan. It is the third thermal boundary next to PackAmbient (a fixed-coefficient convection per series row) and the ideal coolant temperature a PackThermalNetwork drains into by default, and CyclingCircuit selects it with cooling = ForcedAirCooling(...). The model is the single-node thermal model of ADVISOR 2003 (NREL, ess_therm), with its correlations as the shipped defaults of ForcedAirCooling and every number a parameter.

With series = nothing the boundary has one scalar port, for the heatport_coolant of a networked pack, and the case node is the port: the network already holds the conductances from each exposed cell face to it. With series = S it has the two row ports port_left and port_right of an array pack, each row face reaching the case node through conductance [W/K] as it reaches the ambient of a PackAmbient. The thermostat reads the real input T_sense, which CyclingCircuit wires to the pack's hottest cell temperature T; a hand-built circuit must connect it.

Heat leaves the case node through the case wall and the air film in series,

Q_case = (T_case - T_air) / R_eff,    R_eff = t / (k A) + 1 / (h A),
h = h_reference (v / velocity_reference)^velocity_exponent  (fan on),  h_natural  (fan off),
v = fan_flow / (air_density * flow_area),

and the air node carries the energy balance of a well-mixed volume with a through flow ṁ (fan_flow with the fan on, natural_flow with it off). The module sees the mean of the inlet and the outlet air, T_air = (temperature + T_out) / 2, which is the source's statement that half of the rejected heat goes into warming the air:

air_mass * c_p * dT_air/dt = Q_case - Q_out,    Q_out = ṁ c_p (T_out - temperature),
T_out = 2 T_air - temperature.

With air_mass = 0 (the default) the left-hand side vanishes and the air is quasi-steady, T_air = temperature + Q_case / (2 ṁ c_p), exactly the source's relation; the heat that leaves the cells then leaves with the flow at every instant, and with a positive air_mass part of it is stored in the air first. Both are reported as Q_case and Q_out, with T_out the exhaust temperature.

The fan is a discrete variable fan_on, 1 or 0, switched by two continuous events: it turns on when T_sense rises through T_set and off when it falls through T_set - hysteresis. It is an event rather than a smooth switch because a fan is either running or not, and a smoothed step would leave the fan half on and the film coefficient in between whenever the temperature sits near the setpoint. Its initial value is solved with the initial state, on when the pack starts at or above T_set. After every switch the DAE is re-initialized and the integrator's proposed step is capped, as Cycler does, so the jump in h is not carried across a large step. Read the fan state from a solution through h or air_flow at chosen times, sol(t; idxs = cooler.h): they depend on the discrete alone, so sol[cooler.h] holds one value per switch rather than one per saved time.

Limitations

The one air node models parallel flow, in which every module sees the same inlet air; the inlet-to-outlet gradient of a series flow needs a chain of nodes. The case has no thermal mass, radiation is not separated from convection, and the fan has a single speed. The thermostat is ideal: no sensor lag, and no minimum run time beyond what hysteresis imposes.

RintCircuit(; name, degradation, capacity, SOC_initial)

Rint topology with a supplied OCV and resistance signal.

Parameters:

Connectors

• capacity_health - This connector represents a real signal as an input to a component (RealInput)
• resistance_growth - This connector represents a real signal as an input to a component (RealInput)
• p - This connector represents an electrical pin with voltage and current as the potential and flow variables, respectively. (Pin)
• n - This connector represents an electrical pin with voltage and current as the potential and flow variables, respectively. (Pin)
• ocv - This connector represents a real signal as an input to a component (RealInput)
• r0 - This connector represents a real signal as an input to a component (RealInput)

Variables

RintECM(; name, degradation, capacity, SOC_initial, R0)

Rint cell with constant series resistance; He et al. (2011), equation (1).

Parameters:

Connectors

• capacity_health - This connector represents a real signal as an input to a component (RealInput)
• resistance_growth - This connector represents a real signal as an input to a component (RealInput)
• p - This connector represents an electrical pin with voltage and current as the potential and flow variables, respectively. (Pin)
• n - This connector represents an electrical pin with voltage and current as the potential and flow variables, respectively. (Pin)
• ocv - This connector represents a real signal as an input to a component (RealInput)
• r0 - This connector represents a real signal as an input to a component (RealInput)

Variables

SaftHighPower12Ah()

RCModel parameters for the 12 A⋅h high-power lithium-ion cell of Saft America: the five elements of Saft's own two-capacitance model of that cell as figure 3 of [1] prints them, R_e = 1.1 mΩ, R_c = 0.4 mΩ, R_t = 1.2 mΩ, C_b = 82 kF and C_c = 4.074 kF. [1] translated the model from P-Spice into the RC block of the ADVISOR vehicle simulator and verified the translation on a single 18 s, 200 A discharge pulse (its figure 4): the voltage begins at 3.86 V, drops to 3.561 V at 0 s, falls further to 3.386 V after 18 s, and recovers to a steady state of 3.818 V after 100 s. test/ecm_bulk_surface.jl replays that pulse through RCModel and asserts those four voltages, so this set doubles as the published regression check of the bulk/surface circuit. With the elements as printed, the circuit gives 3.5613 V at the onset and 3.8182 V after recovery, on the printed digits, and 3.3847 V at the end of the pulse, 1.3 mV below the printed 3.386 V. The difference is inside the precision the elements are printed to: R_e = 1.0922 mΩ, which prints as 1.1 mΩ, puts all three voltages on their printed digits. The set keeps the printed values.

The "open-circuit voltage" is the constant 3.86 V of that run. [1] shows the cell's open-circuit voltage against state of charge only as a plot (its figure 6, for the 6 A⋅h cell of the same construction), so there is no curve to transcribe, and the constant does one thing: it sets U_b and U_c at t = 0 to the rest voltage of the verification pulse. Consequences: the state of charge is coulomb-counted against the 12 A⋅h nominal capacity from the default initial state of charge of one, since [1] states none for the pulse; the set cannot be used with RCModel(; soc = :capacitor), which needs a curve to invert and rejects the constant; and the rest voltage carries no state-of-charge dependence beyond what the two capacitors accumulate. Replace the entry by a measured curve before using the set for anything but the circuit's pulse response.

No bounds are set, as [1] gives no cut-off voltages, currents or temperatures for this cell; its nominal voltage is stated as 3.6 V. The elements are constants: [1] reports that Saft supplied the bulk capacitance as a function of temperature and the bulk impedance as a function of state of charge and temperature, but tabulates neither. temperature = true needs a "heat capacity", which [1] does not report.

For the model's accuracy against a cell rather than against P-Spice, [1] runs a 600 s US06-derived power profile on a three-cell module and finds the RC model within 1.2% average (0.7% standard deviation) and 5% maximum terminal-voltage error; that module was built from the 6 A⋅h cells, so the figure is for the RC model, not for this parameter set.

[1] Valerie H. Johnson, Ahmad A. Pesaran and Thomas Sack. "Temperature-Dependent Battery Models for High-Power Lithium-Ion Batteries." 17th Electric Vehicle Symposium (EVS-17), Montreal, 15-18 October 2000. NREL/CP-540-28716. https://www.nrel.gov/docs/fy01osti/28716.pdf

SaftLiIon6Ah()

Rint parameters for the Saft 6 A⋅h high-power lithium-ion cell tested at NREL in 1999 [1], as gridded LookupTables over the state of charge (0, 10, 20, 40, 60, 80 and 100 %) and the cell temperature (0, 25 and 41 °C): the open-circuit voltage, a separate discharge and charge resistance, the capacity and the coulombic efficiency, the last two against temperature alone. It is the Rint-format battery data file of ADVISOR [2] that the model's published accuracy figures were established on — 3 % average and 12 % maximum voltage error over US06-derived cycles [1] — and it exercises every entry the temperature-dependent Rint model has:

The data file describes a three-cell module and multiplies every per-cell table by three; this set is the cell, i.e. the tables as printed before that factor, with the voltage window 2.0–3.9 V and a heat capacity of 0.37824 kg × 795 J/(kg⋅K) = 300.7 J/K from the file's module mass and specific heat. The tables were built by NREL's batmodel tool from capacity, open-circuit-voltage and resistance tests on cell 72 at 0, 20 and 40 °C in May and July 1999; the file itself places its temperature breakpoints at 0, 25 and 41 °C, and those are what is transcribed here. The capacity is the C/3 capacity. The file sets no initial state of charge (ADVISOR takes it from the vehicle file), so this set starts full.

The temperature dependence is only active in a cell built with temperature = true; the isothermal default evaluates every table at the "initial temperature", 25 °C.

The set is provided under the licence of [2], reproduced beside the data in the source; the tables are the measurements as published there and nothing has been refitted.

[1] Valerie H. Johnson. "Battery performance models in ADVISOR." Journal of Power Sources 110, no. 2 (2002): 321-329. https://doi.org/10.1016/S0378-7753(02)00194-5

[2] Valerie H. Johnson. ESS_LI7_temp.m, "6 Ah Saft Lithium Ion battery", National Renewable Energy Laboratory, 12 April 2000, released as non-proprietary by Saft 30 May 2000. In ADVISOR 2003-00-r0116, Alliance for Sustainable Energy, LLC, https://sourceforge.net/projects/adv-vehicle-sim/ (advisor/data/energy_storage/).

TheveninCircuit(; name, degradation, nrc, capacity, SOCinitial)

N-RC topology with supplied element signals, allowing SOC and temperature dependent maps.

Parameters:

Connectors

• capacity_health - This connector represents a real signal as an input to a component (RealInput)
• resistance_growth - This connector represents a real signal as an input to a component (RealInput)
• p - This connector represents an electrical pin with voltage and current as the potential and flow variables, respectively. (Pin)
• n - This connector represents an electrical pin with voltage and current as the potential and flow variables, respectively. (Pin)
• ocv - This connector represents a real signal as an input to a component (RealInput)
• r0 - This connector represents a real signal as an input to a component (RealInput)
• r - This connector represents a real signal as an input to a component (RealInput)
• c - This connector represents a real signal as an input to a component (RealInput)

Variables

TheveninECM(; name, degradation, nrc, capacity, SOCinitial, R0, R, C)

N-RC Thevenin cell with constant elements; He et al. (2011), equations (3) and (5).

Parameters:

Connectors

• capacity_health - This connector represents a real signal as an input to a component (RealInput)
• resistance_growth - This connector represents a real signal as an input to a component (RealInput)
• p - This connector represents an electrical pin with voltage and current as the potential and flow variables, respectively. (Pin)
• n - This connector represents an electrical pin with voltage and current as the potential and flow variables, respectively. (Pin)
• ocv - This connector represents a real signal as an input to a component (RealInput)
• r0 - This connector represents a real signal as an input to a component (RealInput)
• r - This connector represents a real signal as an input to a component (RealInput)
• c - This connector represents a real signal as an input to a component (RealInput)

Variables

aluminum_current_collector()

Default parameters for an aluminum current collector.

capacity_cell(cell)

The capacity of one cell [A⋅h], from the parameters of a BatteryCell, BatteryPack or CyclingCircuit component. It is the value the cell variable cell_capacity takes, i.e. the chemistry's nominal capacity where it defines one and the theoretical capacity otherwise.

capacity_pack(pack)

The capacity of a BatteryPack or CyclingCircuit component [A⋅h]: the cell capacity times the number of cells in parallel, the value of the pack variable Q. It converts the C-rates of a cycling protocol, so charge(1C) on the pack is charge(capacity_pack(pack)) amperes.

cell_views(pack)

Return a series × parallel matrix of CellViews for an array pack or a circuit containing one. For example, cell_views(pack)[2, 3].SOC indexes the state of charge of cell (2, 3). The views share the pack's array fields.

charge(input; time, bounds)

Setup for a charge experiment.

Arguments:

• input: Current input with units of A or C (C-rate) or power input with units of W.
• time: Optional argument to set a maximum experiment time.
• bounds: Optional experiment-specific stop conditions, e.g. bounds = (V_max = 4.2,) or bounds = :V_max => 4.2, overriding the defaults of the Cycler (see default_bounds); bounds = false disables all stop conditions for this experiment.

charge_current(input; time, bounds)

Setup for a current experiment to charge the battery.

Arguments:

• input: Current input with units of A or C (C-rate).
• time: Optional argument to set a maximum experiment time.
• bounds: Optional experiment-specific stop conditions, e.g. bounds = (V_max = 4.2,) or bounds = :V_max => 4.2, overriding the defaults of the Cycler (see default_bounds); bounds = false disables all stop conditions for this experiment.

charge_power(input; time, bounds)

Setup for a power experiment to charge the battery.

Arguments:

• input: Power input with units of W.
• time: Optional argument to set a maximum experiment time.
• bounds: Optional experiment-specific stop conditions, e.g. bounds = (V_max = 4.2,) or bounds = :V_max => 4.2, overriding the defaults of the Cycler (see default_bounds); bounds = false disables all stop conditions for this experiment.

copper_current_collector()

Default parameters for a copper current collector.

current(input; time, bounds)

Setup for a current experiment. By convention, positive current is discharging and negative current is charging.

Arguments:

• input: Current input with units of A or C (C-rate).
• time: Optional argument to set a maximum experiment time.
• bounds: Optional experiment-specific stop conditions, e.g. bounds = (V_max = 4.2,) or bounds = :V_max => 4.2, overriding the defaults of the Cycler (see default_bounds); bounds = false disables all stop conditions for this experiment.

default_bounds(battery)

The default stop conditions of a BatteryCell, BatteryPack or CyclingCircuit component, as a NamedTuple of I_min, I_max, V_min, V_max, P_min, P_max, T_min, T_max, SOC_min and SOC_max: the chemistry's own bounds, scaled to the pack (voltages add in series, currents in parallel). A bound the chemistry does not define is NaN, i.e. disabled. They are what CyclingCircuit gives its Cycler unless its bounds keyword overrides them.

default_parameters(model)

The parameter set BatteryCell, BatteryPack and CyclingCircuit use for model when no chemistry is given: NMC for the electrochemical models, and for the equivalent circuit models the published set that covers the topology — ChenRinconMora2006 for Rint, Thevenin(2) and DP, He2011LiMn2O4 for first-order Thevenin, PNGV and RCModel, which are covered by its model-specific parameter fits, and MaxwellPC2500 for EDLC.

discharge(input; time, bounds)

Setup for a discharge experiment.

Arguments:

• input: Current input with units of A or C (C-rate) or power input with units of W.
• time: Optional argument to set a maximum experiment time.
• bounds: Optional experiment-specific stop conditions, e.g. bounds = (V_max = 4.2,) or bounds = :V_max => 4.2, overriding the defaults of the Cycler (see default_bounds); bounds = false disables all stop conditions for this experiment.

discharge_current(input; time, bounds)

Setup for a current experiment to discharge the battery.

Arguments:

• input: Current input with units of A or C (C-rate).
• time: Optional argument to set a maximum experiment time.
• bounds: Optional experiment-specific stop conditions, e.g. bounds = (V_max = 4.2,) or bounds = :V_max => 4.2, overriding the defaults of the Cycler (see default_bounds); bounds = false disables all stop conditions for this experiment.

discharge_power(input; time, bounds)

Setup for a power experiment to discharge the battery.

Arguments:

• input: Power input with units of W.
• time: Optional argument to set a maximum experiment time.
• bounds: Optional experiment-specific stop conditions, e.g. bounds = (V_max = 4.2,) or bounds = :V_max => 4.2, overriding the defaults of the Cycler (see default_bounds); bounds = false disables all stop conditions for this experiment.

experiment_results(sol, state, SOC)

The ExperimentResults of a solution sol of a circuit driven by a Cycler: one per step of the protocol that ran, in order, with the reason that ended it, the indices it covers in the solution and the cycle it belongs to. state is the CyclerState the cycler logged into and SOC the state of charge over the solution (sol[circuit.SOC]), which tells a charge from a discharge where the step itself does not say.

state = CyclerState()
@named circuit = CyclingCircuit(; protocol = [charge(1C), voltage(hold)], state)
sys = mtkcompile(circuit)
prob = ODEProblem(sys, [], (0.0, 1e5))
sol = solve(prob, FBDF())
results = experiment_results(sol, state, sol[sys.SOC])
[e.exit_reason for e in results]

Steps that were skipped because their stop conditions were already met are in state.log but are not results. The cycler appends to the log, so empty!(state.log) before solving the same problem a second time.

find_variables(cell, description)

The variables of a cell component (see BatteryCell, or one of cell_views) whose description metadata is description, ordered by their grid index. Variables discretized along the cell are addressed one grid point at a time and their descriptions are qualified with the section, so "negative electrode particle concentration" returns the particles of the negative electrode and the unqualified "electrolyte concentration" returns the electrolyte concentration of every section. Parameters are qualified likewise ("negative electrode thickness").

gridvariables(cell, var)

The position variables (x_i(t) or x_e_i(t) of the same cell) of a variable var of cell that is discretized along the cell, e.g. of cell_views(circuit)[1].c_e_3. Used by the plot recipe to plot a profile against the position in the cell.

linear_ocv(; OCV_max, OCV_min, SOC_max = 1, SOC_min = 0, clamped = true)

The "open-circuit voltage" entry of an EquivalentCircuitParameters set that rises linearly from OCV_min at SOC_min to OCV_max at SOC_max — the cell treated as a capacitor, and the default open-circuit voltage of Modelica.Electrical.Batteries, whose useLinearSOCDependency = true builds the table OCV_SOC[:,2] = [SOCmin, OCVmin/OCVmax; SOCmax, 1] from exactly these four numbers.

Outside SOC_min .. SOC_max the value is held at the nearer endpoint, matching the HoldLastPoint extrapolation Modelica's table lookup uses. clamped = false extends the line instead, which is what a two-point identification such as He2011LiMn2O4 does, since holding a value the fit never saw is no more meaningful than extending it. Holding leaves a kink at each endpoint, as Modelica's LinearSegments table does, so a run that spends time at the edge of the window is better bounded away from it by the parameter set's "state of charge minimum" and "maximum".

Values may carry Unitful units. The result is a (SOC, T) callable and so is inlined as an expression in the cell's state of charge rather than becoming an overridable parameter; it ignores temperature, as Modelica's one-dimensional table does.

circuit = Dict{String, Any}(
    "open-circuit voltage" => linear_ocv(; OCV_max = 4.2u"V", OCV_min = 2.5u"V"),
    "series resistance" => 3.0u"mΩ")

linear_resistance(R_ref; alpha = 0, T_ref = 293.15)

The entry of an EquivalentCircuitParameters "circuit" section for a resistance that depends linearly on the cell temperature, R = R_ref * (1 + alpha * (T - T_ref)) — the law Modelica.Electrical.Batteries applies to its inner resistance and to the resistors of its RC elements, parameterized there by Ri/R, alpha and T_ref.

alpha is in 1/K and T_ref in K; both may carry Unitful units. Use it for any resistance entry, so each RC branch can carry its own coefficient the way Modelica's rcData records do:

circuit = Dict{String, Any}("open-circuit voltage" => linear_ocv(; OCV_max = 4.2u"V", OCV_min = 2.5u"V"),
    "series resistance" => linear_resistance(3.0u"mΩ"; alpha = 0.004u"K^-1"),
    "polarization resistance" => [linear_resistance(1.0u"mΩ"; alpha = 0.006u"K^-1")],
    "polarization capacitance" => [1000.0u"F"])

The temperature it reads is the cell temperature, so it is constant unless the cell is built with temperature = true; with an isothermal cell it evaluates at "initial temperature" and is simply a constant resistance.

power(input; time, bounds)

Setup for a power experiment. By convention, positive power is discharging and negative power is charging.

Arguments:

• input: Power input with units of W.
• time: Optional argument to set a maximum experiment time.
• bounds: Optional experiment-specific stop conditions, e.g. bounds = (V_max = 4.2,) or bounds = :V_max => 4.2, overriding the defaults of the Cycler (see default_bounds); bounds = false disables all stop conditions for this experiment.

rest(; time, bounds)

Setup for a rest experiment. This is a special case of a current experiment where the current is zero.

Arguments:

• time: Required argument to set a maximum experiment time.
• bounds: Optional experiment-specific stop conditions, e.g. bounds = (V_max = 4.2,) or bounds = :V_max => 4.2, overriding the defaults of the Cycler (see default_bounds); bounds = false disables all stop conditions for this experiment.

voltage(input; time, bounds)

Setup for a voltage experiment.

Arguments:

• input: Voltage input with units of V.
• time: Optional argument to set a maximum experiment time.
• bounds: Optional experiment-specific stop conditions, e.g. bounds = (V_max = 4.2,) or bounds = :V_max => 4.2, overriding the defaults of the Cycler (see default_bounds); bounds = false disables all stop conditions for this experiment.