API Documentation

DAE Functions

alg_res(x, param)

Calculates the algebriac residual equations given as g(t,x) = 0, where x includes algebraic and differential variables. The algebraic equations consists of equations for the algebraic variables phis_p, phis_n, phie, jp, and jn.

Parameters

  • x (casadi.SX or double) – A vector containing the values of algebraic and differential variables.

  • param (struct) – A structure containing the model parameters.

Returns

x_tot (casadi.SX or double) – A vector where each element corresponds to the solution of the algebraic residual equations g(t,x)=0.

defineVariableIndex(param)

Defines the indices and calculates the length for the differential and algebraic variables and stores the information in param structure.

Parameters

param (struct) – A structure containing the model parameters.

Returns

param (struct) – A structure containing the model parameters, now inlcuding the variable lengths and indices.

diff_res(t, x, xp, ida_user_data)

This function calculates the differential-algebraic equations (DAEs) in implicit form, depending on the method chosen for determining consistent initial conditions:

  • If using the SUNDIALS IDACalcIC method (param.init_Method = ‘IDACalcIC’), it computes the DAE system F(t, x, x_p) = 0, which includes both the ordinary differential equation (ODE) and algebraic equation (AE) residuals.

  • If using the single-step approach [1] (param.init_Method = ‘SS’), it calculates the implicit ODE system M(t, x, x_p) = 0 [2], consisting of the perturbed AE and original ODEs with the switch function applied.

References:

[1] M. T. Lawder, V. Ramadesigan, B. Suthar, and V. R. Subramanian, “Extending explicit and linearly implicit ODE solvers for index-1 DAEs,” Computers & Chemical Engineering, vol. 82, pp. 283–292, Nov. 2015, doi: 10.1016/j.compchemeng.2015.07.002.

[2] S. Ha and S. Onori, “COBRAPRO: An Open-Source Software for the Doyle-Fuller-Newman Model with Co-Simulation Parameter Optimization Framework,” J. Electrochem. Soc., vol. 171, no. 9, p. 090522, Sep. 2024, doi: 10.1149/1945-7111/ad7292.

Parameters

  • t (casadi.SX or double) – A structure containing the model parameters.

  • x (casadi.SX or double) – A vector containing the values of algebraic and differential variables.

  • xp (casadi.SX or double) – A vector containing the values of derivative of the algebraic and differential variables.

  • ida_user_data (struct) – Structure containing additional functions or parameters for the IDA solver.

Returns

  • dx_tot (casadi.SX or double) – Vector comuting F(t, x, x_p) = 0 for the SUNDIALS IDACalcIC method or M(t, x, x_p) = 0 for the single-step approach.

  • flag (double) – Required by IDA solver but not used in the code.

  • new_data (double) – Required by IDA solver but not used in the code.

getCurrentDensity(t, param)

Takes the variable input current profile defined in param.I and calculates the current density at time t.

Parameters

  • t (double) – Time instance [s].

  • param (struct) – A structure containing the model parameters.

Returns

I (double) – Current density [A.m-2] at time t.

jacobianFn(t, x, xp, ~, cj, data)

Calculates the Jacobian matrix for the discretized DFN model.

Parameters

  • t (double) – A structure containing the model parameters.

  • x (double) – A vector containing the values of algebraic and differential variables.

  • xp (double) – A vector containing the values of derivative of the algebraic and differential variables.

  • cj (double) – Required by IDA to compute Jacobian matrix.

  • data (struct) – Structure containing information required to compute Jacobian matrix.

Returns

  • J (double) – Numerically calculated Jacobian matrix.

  • flag (double) – Required by IDA solver but not used in the code.

  • new_data (double) – Required by IDA solver but not used in the code.

FVM_interpolation

De_eff_constant(ce, param, domain)

Calculates the effective electrolyte diffusivity pertaining to the domain of interest when the electrolyte diffusion coefficient is constant. The domain refers to the positive electrode, separator, or negative electrode.

Parameters

  • ce (casadi.SX or double) – Normalized electrolyte concentration vector in domain (unitless).

  • param (struct) – A structure containing the model parameters.

  • domain (string) – Letter indicating battery domain (‘p’ for positive electrode, ‘s’ for separator, ‘n’ for negative electrode)

Returns

Deff (casadi.SX or double) – Effective electrolyte diffusivity in the domain of interest.

Kappa_eff_constant(ce, param, domain)

Calculates the effective electrolyte conductivity pertaining to the domain of interest when the electrolyte conductivity is constant. The domain refers to the positive electrode, separator, or negative electrode.

Parameters

  • ce (casadi.SX or double) – Normalized electrolyte concentration vector in domain (unitless).

  • param (struct) – A structure containing the model parameters.

  • domain (string) – Letter indicating battery domain (‘p’ for positive electrode, ‘s’ for separator, ‘n’ for negative electrode)

Returns

Kappa_eff (casadi.SX or double) – Effective electrolyte conductivitiy in the domain of interest.

cs_surf_hermite_interp(cs, r_index_Nr, cs_outer_ghost, param, domain)

Estimates the surface particle concentration using 3rd order hermite interpolation [1] when using FVM for the radial discretization of the solid particles.

References:

[1] L. Xu, J. Cooper, A. Allam, and S. Onori, “Comparative Analysis of Numerical Methods for Lithium-Ion Battery Electrochemical Modeling,” J. Electrochem. Soc., vol. 170, no. 12, p. 120525, Dec. 2023, doi: 10.1149/1945-7111/ad1293.

Parameters

  • cs (casadi.SX or double) – Concatenated normalized solid concentration vector along the particle radius direction for all particles in domain (unitless).

  • r_index_Nr (double) – Index of the outer most control volume (closest to particle surface) for the particle of interest.

  • cs_outer_ghost – Normalized solid concentration value at the outer ghost node (Nrp+1).

  • param (struct) – A structure containing the model parameters.

  • domain (string) – Letter indicating battery domain (‘p’ for positive electrode, ‘n’ for negative electrode)

Returns

cs_surf (casadi.SX or double) – Normalized surface particle concentration.