assembleP2DMatrices

R2026b

Extract finite‑element system matrices from batteryP2DModel

Since R2026b

Syntax

femat = assembleP2DMatrices(batteryP2DModel)

femat = assembleP2DMatrices(batteryP2DModel,state)

Description

femat = assembleP2DMatrices(batteryP2DModel) extracts the finite‑element (FE) system matrices from batteryP2DModel at the initial state.

femat = assembleP2DMatrices(batteryP2DModel,state) extracts finite-element system matrices at the operating point defined by the state structure array.

Examples

Assemble FE matrices for Battery P2D Analysis

Extract finite‑element system matrices from batteryP2DModel.

Specify active material of the anode and cathode of the battery

sNorm = linspace(0.025, 0.975, 39);
ocp_n_vec = [.435;.325;.259;.221;.204; ...
    .194;.179;.166;.155;.145; ...
    .137;.131;.128;.127;.126; ...
    .125;.124;.123;.122;.121; ...
    .118;.117;.112;.109;.105; ...
    .1;.098;.095;.094;.093; ...
    .091;.09;.089;.088;.087; ...
    .086;.085;.084;.083];
ocp_p_vec = [3.598;3.53;3.494;3.474; ...
    3.46;3.455;3.454;3.453; ...
    3.4528;3.4526;3.4524;3.452; ...
    3.4518;3.4516;3.4514;3.4512; ...
    3.451;3.4508;3.4506;3.4503; ...
    3.45;3.4498;3.4495;3.4493; ...
    3.449;3.4488;3.4486;3.4484; ...
    3.4482;3.4479;3.4477;3.4475; ...
    3.4473;3.447;3.4468;3.4466; ...
    3.4464;3.4462;3.4458];

anodeOCP = griddedInterpolant(sNorm,ocp_n_vec,"linear","nearest");
cathodeOCP = griddedInterpolant(sNorm,ocp_p_vec,"linear","nearest");

anodeMaterial = batteryActiveMaterial( ...
    ParticleRadius=5E-6, ...
    MaximumSolidConcentration=30555, ...
    VolumeFraction=0.58, ...
    DiffusionCoefficient=3.0E-15, ...
    ReactionRate=8.8E-11, ...
    OpenCircuitPotential=@(st_ratio) anodeOCP(st_ratio), ...
    StoichiometricLimits=[0.0132 0.811]);

cathodeMaterial = batteryActiveMaterial(...
    ParticleRadius=5E-8, ...
    MaximumSolidConcentration=22806, ...
    VolumeFraction=0.374, ...
    DiffusionCoefficient=5.9E-19, ...
    ReactionRate=2.2E-13, ...
    OpenCircuitPotential=@(st_ratio) cathodeOCP(st_ratio), ...
    StoichiometricLimits=[0.035 0.74]);

Specify the properties of the anode and cathode.

anode = batteryElectrode(...
    Thickness=34E-6, ...
    Porosity=0.3874, ...
    BruggemanCoefficient=1.5, ...
    ElectricalConductivity=100, ...
    ActiveMaterial=anodeMaterial);

cathode = batteryElectrode(...
    Thickness=80E-6, ...
    Porosity=0.5725, ...
    BruggemanCoefficient=1.5, ...
    ElectricalConductivity=0.5, ...
    ActiveMaterial=cathodeMaterial);

Specify the properties of the separator, electrolyte, .

separator = batterySeparator(...
    Thickness=25E-6, ...
    Porosity=0.45, ...
    BruggemanCoefficient=1.5);

electrolyte = batteryElectrolyte(...
    DiffusionCoefficient=2E-10, ...
    TransferenceNumber=0.363, ...
    IonicConductivity=0.29);

Specify the initial conditions of the battery.

ic = batteryInitialConditions(...
    ElectrolyteConcentration=1000, ...
    StateOfCharge=0.05, ...
    Temperature=298.15);

Specify the normalized current.

cycling = batteryCyclingStep(...
    NormalizedCurrent=0.5);

Create a model for the battery P2D analysis.

model = batteryP2DModel(...
    Anode=anode, ...
    Separator=separator, ...
    Cathode=cathode, ...
    Electrolyte=electrolyte, ...
    InitialConditions=ic, ...
    CyclingStep=cycling);

Extract P2D matrices.

femat = assembleP2DMatrices(model)

femat = struct with fields:
               M: [433×433 double]
               K: [433×433 double]
               F: [433×1 double]
               B: [490×433 double]
              ud: [490×1 double]
    InitialState: [490×1 double]
    InitialSlope: [490×1 double]
       Variables: ["LiquidConcentration"    "LiquidPotential"    "SolidPotential"    "SolidConcentration"]
         Scaling: [1×1 struct]
            Mesh: [1×1 batteryMesh]

Input Arguments

batteryP2DModel — Fully configured pseudo-2D model for battery analysis

batteryP2DModel object

Fully configured pseudo-2D model for battery analysis, specified as a batteryP2DModel object. A fully configured model defines the physics and discretization required to assemble the finite-element system. When using assembleP2DMatrices you may specify these properties batteryP2DModel:

• Components: Anode, Cathode, Separator, and Electrolyte

• Initial Conditions: InitialConditions

• Solver and discretization settings: SolverOptions

• Load specification: CyclingStep

  Note

  Specifying properties is optional since SolverOptions has default values.

assembleP2DMatrices does not use CyclingStep for time‑marching behavior. It uses CyclingStep only to determine the load formulation during matrix assembly. Therefore, the function requires you to specify one cycling step, defining either.

• NormalizedCurrent for a current‑controlled assembly

• HoldVoltage for a voltage‑controlled assembly

assembleP2DMatrices does not require the following values in the cycling step definition: CutoffTime, CutoffVoltageUpper, CutoffVoltageLower, CutoffNormalizedCurrent, and OutputTimeStep. It ignores these values if they are specified.

To assemble multiple discretized systems, switch the load specification, for example:

• Specify NormalizedCurrent and assemble FE system matrices to obtain a current‑controlled system.

• Set NormalizedCurrent to [] (empty). Specify HoldVoltage and assemble FE system matrices to obtain a voltage‑controlled system.

state — Current simulation state

structure array

Current simulation state, specified in a structure array. The array fields represent the following values:

• state.Time contains the current dimensionless time.

• state.u contains a full dimensionless solution vector.

state.u contains the full discretized solution at the operating point where matrices are assembled. The P2D discretization includes:

• x‑domain variables defined on the 1‑D through‑thickness mesh (for example, electrolyte concentration and potentials)

• r‑domain variables defined on the pseudo‑radial mesh at each x‑location (solid concentration in spherical particles).

state.u is provided as a single dimensionless solution stacked vector that matches the internal DOF ordering used by assembleP2DMatrices. Conceptually, it is organized as:

• All x‑domain variables, stacked according to the ordering in femat.Variables and the x‑mesh DOF layout, followed by

• All r‑domain variables, stacked as columns “per x‑location”, where each x-locations contains the radial DOFs for the solid concentration at that x-location.

Output Arguments

femat — Finite element matrices

structure array

Finite element matrices, returned as a structure array. The returned matrices contain all data required to evolve the P2D system using an external integrator or to construct reduced-order or state‑space representations. The structure array contains these fields:

1. Core finite elements matrices (with incorporated boundary conditions):

   • M is the singular mass matrix for the reduced DAE or ODE form.

   • K is the stiffness operator matrix representing diffusion and constraints.

   • F is the load vector.

   These matrices define the standard semi-discrete system form: $$M\dot{u}=-Ku+F$$

2. Data required for imposing and recovering Dirichlet BC:

   • B is the projection matrix used to eliminate Dirichlet boundary DOFs and form the constrained system.

   • ud is the vector of known Dirichlet DOF values.

   These values support the mapping between the constrained and the full solution: u_constrained = B^'*u_full, u_full = B*u_constrained + ud.

3. Initial conditions computed using the same Consistent Initial Conditions (CIC) procedure as the built‑in solver:

   • InitialState is the full initial state vector obtained from the model’s InitialConditions.

   • InitialSlope is the full initial time derivative computed by the CIC routine.

   Note

   InitialState and InitialSlope would remain empty if user specifies state, as this would correspond to an updated state at t=0.

4. Variables and equation metadata:

   • Variables is a string vector listing all variables included in the assembled system, for example, ["LiquidConcentration","LiquidPotential","SolidPotential","SolidConcentration"] and any additional variable that would be added in the future or conditionally added like "SEIThickness". The ordering of variables in this list defines the ordering used in state.u, InitialState, and all finite element matrices.

5. Scaling is a structure containing reference values used for nondimensionalization.

   All outputs (M, K, F, InitialState, and related quantities) are provided in nondimensional form. Use the following scaling metadata to recover dimensional quantities for analysis and visualization.

   • Scaling.Time – Reference time scale. Dimensional time is obtained as t_dimensional = t_nondimensional*Scaling.Time.

   • Scaling.Length – Reference length scale used for spatial discretization in the x‑direction.

   • Scaling.Radius – Reference particle radius used in the radial (pseudo‑2D) dimension.

   • Scaling.ElectrolyteConcentration – Reference electrolyte concentration.

   • Scaling.ReferencePotential – Reference electric potential.

   • Scaling.SolidConcentrationAnode – Reference solid concentration in the anode.

   • Scaling.SolidConcentrationCathode – Reference solid concentration in the cathode.

6. Mesh is an instance of batteryMesh used for finite element assembly.

Version History

Introduced in R2026b