getting_started
After you followed the requirements and installation pages, you are now ready to run simulations of Li-ion cells in your Matlab or Octave environment.
The first thing to do, is to define a structure containing the parameters for the cell to be simulated. In order to do this, the user must type
param{1} = Parameters_init;Note that the returned structure must be put in a cell variable.
The cell will contain a structure, with all the parameter values that are defined inside the Parameters_init.m file. The user has the freedom to change such parameters, according to different needs and requirements.
LIONSIMBA supports also the simulation of a battery pack with series-connected cells. In order to run a simulation for a battery pack, the user is required to create a cell array of n elements (to run a simulation of n series connected cells). For example:
param{1} = Parameters_init;
param{2} = Parameters_init;
...
param{n} = Parameters_init;Note: Each signe entry of the resulting cell array may per customized. This enables the possibility to have cells with independent parameters.
The access to the prameters values is done following the syntax of Matlab/Octave. Therefore a syntax of the following type
param{1}.cs_p_initfollowed by an Enter keystroke, will print the default value for the initial ionic concentration in the cathode.
If the user wants to modify a specific parameter, this can be done either directly from the Parameters_init.m file, or according to the syntax
param{1}.cs_p_init=10000;followed by an Enter keystroke.
A simulation is started by invoking the following method
out = startSimulation(t0,tf,initial_states, I_density, param);where
- t0 and tf represent the initial and final time of the simulation (usually t0=0, and tf equalizes the duration of the particular simulation). These quantities are expressed in seconds.
- initial_states is a structure that contains the initial states for the simulator. If not provided (i.e., an empty array is provided), the simulator will start from the default conditions that are given according to the param structure.
-
I_density represents the applied current density. If negative, the cell discharges, if positive the cell charges. This quantity is expressed in
- param is a cell array containing data structures as discussed above.
When running, a simulation displays the progresses on screen:
Different useful data are provided:
- Number of cells that are currently simulated
- The evolving time of the simulation
- The applied current density (this index may vary during a simulation, see the examples)
- The cell terminal voltage (if a battery pack is simulated, the overall voltage is displayed)
- The cell temperature The cell State Of Charge (SOC)
- Cutoff and cutover voltage (these quantities can be set and customized to stop the simulation whenever the voltage goes below or above such indices)
- An estimation of the internal resistance
- The relative and absolute tolerances used by the numerical solver to run the simulation
- The initial and final simulation times (i.e., the t0 and tf discussed above)
- The total number of unknowns (and equations) composing the overall model being simulated
Once a simulation ends, the results are returned as a structure. In the above example, the results are provided in the out variable.
This variable is a structure, in which each entry is a cell array. By indexing the specific variable of the structure, it is possible to get access to the data of a given cell. This is useful if a simulation of a battery pack is run.
By convention, the results are stored in matrices. Each row represents a variation in time of a variable of interest, whereas each column represents a variation in space of a variable of interest.
For example, if we want to get access to the electrolytic ionic concentration , it would be as simple as typing:
out.ce{1}follwoed by an Enter keystroke.
The user can have the entire list of variables of the out structure by investigating its content.