Useful Tools in BattMo
Before we dive into how to set up and run simulations, it's helpful to get familiar with some of the built-in tools provided by BattMo. These utilities can save time and improve your workflow, and we'll be using most of them throughout the tutorials.
julia
using BattMoSaving Default Parameter Sets Locally
BattMo includes several default parameter sets that you can use as a starting point. If you want to explore or customize them, you can easily save them to your local disk using:
julia
path = pwd()
folder_name = "default_parameter_sets"
generate_default_parameter_files(path, folder_name)🛠 JSON files successfully written! Path:
/home/runner/work/BattMo.jl/BattMo.jl/docs/build/tutorials/default_parameter_setsThis will create a folder in your current working directory containing the default parameter files.
Viewing Parameter Set Information
To quickly inspect which default parameter sets are included with BattMo and what each contains, you can use:
julia
print_default_input_sets()
====================================================================================================
📋 Overview of Available Default Sets
====================================================================================================
📁 cell_parameters: chayambuka_2022, chen_2020, xu_2015
📁 cycling_protocols: cc_charge, cc_cycling, cc_discharge, cccv, user_defined_current_function
📁 full_simulation_input: chen_2020, chen_2020_p4d
📁 model_settings: p2d, p4d_cylindrical, p4d_pouch
📁 simulation_settings: p2d, p2d_fine_resolution, p4d_cylindrical, p4d_pouch
📁 solver_settings: default, direct, iterative
====================================================================================================
📖 Detailed Descriptions
====================================================================================================
📂 cell_parameters
----------------------------------------------------------------------------------------------------
chayambuka_2022
🔹 Cell name: -
🔹 Cell case: Pouch
🔹 Source: ]8;;(Invalid metadata format)\visit]8;;\
🔹 Suitable for:
• RampUp: Sinusoidal
• TransportInSolid: FullDiffusion
• ModelFramework: P2D
🔹 Description: Parameter set for a Sodium ion cell based on Chayambuka et al. The positive electrode open circuit potential has been retrieved from a [COMSOL example](https://www.comsol.com/model/1d-isothermal-sodium-ion-battery-117341).
chen_2020
🔹 Cell name: LG INR 21700 M50
🔹 Cell case: Cylindrical
🔹 Source: ]8;;https://doi.org/10.1149/1945-7111/ab9050\visit]8;;\
🔹 Suitable for:
• CurrentCollectors: Generic
• SEIModel: Bolay
• RampUp: Sinusoidal
• TransportInSolid: FullDiffusion
• ModelFramework: P2D
🔹 Description: Parameter set of a cylindrical 21700 commercial cell (LGM50), for an electrochemical pseudo-two-dimensional (P2D) model, after calibration. SEI parameters are from Bolay2022: https://doi.org/10.1016/j.powera.2022.100083 .
xu_2015
🔹 Cell name: LP2770120
🔹 Cell case: Pouch
🔹 Source: ]8;;https://doi.org/10.1016/j.energy.2014.11.073\visit]8;;\
🔹 Suitable for:
• CurrentCollectors: Generic
• RampUp: Sinusoidal
• TransportInSolid: FullDiffusion
• ModelFramework: P2D, P4D Pouch
🔹 Description: Parameter set of a commercial Type LP2770120 prismatic LiFePO4/graphite cell, for an electrochemical pseudo-two-dimensional (P2D) model.
📂 cycling_protocols
----------------------------------------------------------------------------------------------------
cc_charge
🔹 Description: Parameter set for a constant current charging protocol.
cc_cycling
🔹 Description: Parameter set for a constant current cycling protocol.
cc_discharge
🔹 Description: Parameter set for a constant current discharging protocol.
cccv
🔹 Description: Parameter set for a constant current constant voltage cyling protocol.
user_defined_current_function
🔹 Description: Parameter set that shows an example of how to include a user defined function in the cycling protocol parameters.
📂 full_simulation_input
----------------------------------------------------------------------------------------------------
chen_2020
🔹 Source: ]8;;https://doi.org/10.1149/1945-7111/ab9050\visit]8;;\
🔹 Description: Parameter set of a cylindrical 21700 commercial cell (LGM50), for an electrochemical pseudo-two-dimensional (P2D) model, after calibration. SEI parameters are from Bolay2022: https://doi.org/10.1016/j.powera.2022.100083 .
chen_2020_p4d
🔹 Source: ]8;;https://doi.org/10.1149/1945-7111/ab9050\visit]8;;\
🔹 Description: Parameter set of a cylindrical 21700 commercial cell (LGM50), for an electrochemical pseudo-two-dimensional (P2D) model, after calibration. SEI parameters are from Bolay2022: https://doi.org/10.1016/j.powera.2022.100083 .
📂 model_settings
----------------------------------------------------------------------------------------------------
p2d
🔹 Description: Default model settings for a P2D simulation including a current ramp up, excluding current collectors and SEI effects.
p4d_cylindrical
🔹 Description: Default model settings for a P4D cylindrical cell with a current ramp up.
p4d_pouch
🔹 Description: Default model settings for a P4D pouch simulation including a current ramp up, current collectors.
📂 simulation_settings
----------------------------------------------------------------------------------------------------
p2d
🔹 Suitable for:
• SEIModel: Bolay
• RampUp: Sinusoidal
• TransportInSolid: FullDiffusion
• ModelFramework: P2D
🔹 Description: Default simulation settings for a P2D simulation including a current ramp up, excluding current collectors and SEI effects.
p2d_fine_resolution
🔹 Suitable for:
• SEIModel: Bolay
• RampUp: Sinusoidal
• TransportInSolid: FullDiffusion
• ModelFramework: P2D
🔹 Description: Default simulation settings for a P2D simulation including a current ramp up, excluding current collectors and SEI effects for a finer resolution.
p4d_cylindrical
p4d_pouch
🔹 Suitable for:
• SEIModel: Bolay
• RampUp: Sinusoidal
• TransportInSolid: FullDiffusion
• CurrentCollector: Generic
• ModelFramework: P2D, P4D Pouch
🔹 Description: Default simulation settings for a P4D pouch simulation including a current ramp up, current collectors.
📂 solver_settings
----------------------------------------------------------------------------------------------------
default
direct
iterativeInspecting Individual Parameters
If you're unsure how a specific parameter should be defined or what it represents, you can print detailed information about it. For example, for cell parameters and cycling protocol parameters:
julia
parameter_name = "OpenCircuitPotential"
print_info(parameter_name; view = "CellParameters")
----------------------------------------------------------------------------------------------------
🔋 Cell Parameter: OpenCircuitPotential
----------------------------------------------------------------------------------------------------
🔹 Name OpenCircuitPotential
🔹 Category CellParameters
🔹 Description The open-circuit potential of the active material under a given intercalant stoichimetry and temperature.
🔹 Type String, Dict{String, Vector}, Real
🔹 Unit V
🔹 Documentation ]8;;https://battmo.org/BattMo.jl/dev/manuals/user_guide/simulation_dependent_input\visit]8;;\
🔹 Ontology link ]8;;https://w3id.org/emmo/domain/electrochemistry#electrochemistry_9c657fdc_b9d3_4964_907c_f9a6e8c5f52b\visit]8;;\
========================================================================================================================An example for model or simulation settings:
julia
parameter_name = "ModelFramework"
print_info(parameter_name; view = "ModelSettings")
----------------------------------------------------------------------------------------------------
🕸️ Model Setting: ModelFramework
----------------------------------------------------------------------------------------------------
🔹 Name ModelFramework
🔹 Category ModelSettings
🔹 Description Framework defining the dimensionality of the electrochemical model. Examples: "P2D", "P4D Pouch".
🔹 Type String
🔹 Options P2D, P4D Pouch, P4D Cylindrical
🔹 Documentation ]8;;https://battmoteam.github.io/BattMo.jl/dev/manuals/user_guide/pxd_model\visit]8;;\
🔹 Ontology link ]8;;https://w3id.org/emmo/domain/battery#battery_b1921f7b_afac_465a_a275_26f929f7f936\visit]8;;\
========================================================================================================================An example for output variables:
julia
parameter_name = "Concentration"
print_info(parameter_name; view = "OutputVariable")
----------------------------------------------------------------------------------------------------
📈 Output Variable: NegativeElectrodeActiveMaterialSurfaceConcentration
----------------------------------------------------------------------------------------------------
🔹 Name NegativeElectrodeActiveMaterialSurfaceConcentration
🔹 Category OutputVariable
🔹 Description Concentration of lithium ions at the surface of negative electrode particles.
🔹 Type Vector{Real}
🔹 Shape (nTime, nPosition)
🔹 Unit mol·L⁻¹
----------------------------------------------------------------------------------------------------
📈 Output Variable: PositiveElectrodeActiveMaterialParticleConcentration
----------------------------------------------------------------------------------------------------
🔹 Name PositiveElectrodeActiveMaterialParticleConcentration
🔹 Category OutputVariable
🔹 Description Radial distribution of lithium concentration in positive electrode particles.
🔹 Type Vector{Real}
🔹 Shape (nTime, nPosition, nPositiveElectrodeActiveMaterialRadius)
🔹 Unit mol·L⁻¹
----------------------------------------------------------------------------------------------------
📈 Output Variable: ElectrolyteConcentration
----------------------------------------------------------------------------------------------------
🔹 Name ElectrolyteConcentration
🔹 Category OutputVariable
🔹 Description Concentration of lithium ions in the electrolyte.
🔹 Type Vector{Real}
🔹 Shape (nTime, nPosition)
🔹 Unit mol·m⁻³
----------------------------------------------------------------------------------------------------
📈 Output Variable: PositiveElectrodeActiveMaterialSurfaceConcentration
----------------------------------------------------------------------------------------------------
🔹 Name PositiveElectrodeActiveMaterialSurfaceConcentration
🔹 Category OutputVariable
🔹 Description Concentration of lithium ions at the surface of positive electrode particles.
🔹 Type Vector{Real}
🔹 Shape (nTime, nPosition)
🔹 Unit mol·L⁻¹
----------------------------------------------------------------------------------------------------
📈 Output Variable: NegativeElectrodeActiveMaterialParticleConcentration
----------------------------------------------------------------------------------------------------
🔹 Name NegativeElectrodeActiveMaterialParticleConcentration
🔹 Category OutputVariable
🔹 Description Radial distribution of lithium concentration in negative electrode particles.
🔹 Type Vector{Real}
🔹 Shape (nTime, nPosition, nNegativeElectrodeActiveMaterialRadius)
🔹 Unit mol·L⁻¹
========================================================================================================================And a general example, find variables with charge in the name.
julia
print_info("charge")
----------------------------------------------------------------------------------------------------
🔋 Cell Parameter: ChargeNumber
----------------------------------------------------------------------------------------------------
🔹 Name ChargeNumber
🔹 Category CellParameters
🔹 Description Electric charge of an ion divided by the elementary charge.
🔹 Type Int64
🔹 Unit 1
🔹 Minimum value 1
🔹 Maximum value 4
🔹 Ontology link ]8;;https://w3id.org/emmo#EMMO_dc467621_3b49_4f31_9b09_82290f29da52\visit]8;;\
----------------------------------------------------------------------------------------------------
🔋 Cell Parameter: ChargeTransferCoefficient
----------------------------------------------------------------------------------------------------
🔹 Name ChargeTransferCoefficient
🔹 Category CellParameters
🔹 Description Constant alpha in the Butler-Volmer equation. It represents the fraction of the electrostatic potential energy affecting the reduction rate in an electrode reaction, with the remaining fraction affecting the corresponding oxidation rate.
🔹 Type Real
🔹 Unit -
🔹 Minimum value 0.1
🔹 Maximum value 0.9
🔹 Ontology link ]8;;https://w3id.org/emmo/domain/electrochemistry#electrochemistry_a4dfa5c1_55a9_4285_b71d_90cf6613ca31\visit]8;;\
----------------------------------------------------------------------------------------------------
🚴 Cycling Protocol: RestingTimeAfterDischarge
----------------------------------------------------------------------------------------------------
🔹 Name RestingTimeAfterDischarge
🔹 Category CyclingProtocol
🔹 Description Time during which the cell is kept at open-circuit conditions after completing a discharging step.
🔹 Type Real
🔹 Unit s
🔹 Minimum value 0.0
🔹 Maximum value 1.0e6
🔹 Ontology link ]8;;https://w3id.org/emmo/domain/electrochemistry#electrochemistry_2678a656_4a27_4706_8dde_b0a93e9b92fa\visit]8;;\
----------------------------------------------------------------------------------------------------
🚴 Cycling Protocol: InitialStateOfCharge
----------------------------------------------------------------------------------------------------
🔹 Name InitialStateOfCharge
🔹 Category CyclingProtocol
🔹 Description State of charge of the cell at the start of a simulation.
🔹 Type Real
🔹 Unit 1
🔹 Minimum value 0.0
🔹 Maximum value 1.0
🔹 Ontology link ]8;;https://w3id.org/emmo/domain/electrochemistry#electrochemistry_8b2aaa50_bbe1_45da_8778_8898326246a2\visit]8;;\
----------------------------------------------------------------------------------------------------
🚴 Cycling Protocol: RestingTimeAfterCharge
----------------------------------------------------------------------------------------------------
🔹 Name RestingTimeAfterCharge
🔹 Category CyclingProtocol
🔹 Description Time during which the cell is kept at open-circuit conditions after completing a charging step.
🔹 Type Real
🔹 Unit s
🔹 Minimum value 0.0
🔹 Maximum value 1.0e6
🔹 Ontology link ]8;;https://w3id.org/emmo/domain/electrochemistry#electrochemistry_2678a656_4a27_4706_8dde_b0a93e9b92fa\visit]8;;\
----------------------------------------------------------------------------------------------------
📈 Output Variable: DischargeCapacity
----------------------------------------------------------------------------------------------------
🔹 Name DischargeCapacity
🔹 Category OutputVariable
🔹 Description Total amount of charge delivered during the discharge phase.
🔹 Type Vector{Real}
🔹 Shape (nCycleIndex,)
🔹 Unit Ah
----------------------------------------------------------------------------------------------------
📈 Output Variable: NegativeElectrodeActiveMaterialCharge
----------------------------------------------------------------------------------------------------
🔹 Name NegativeElectrodeActiveMaterialCharge
🔹 Category OutputVariable
🔹 Description Charge stored in the negative electrode.
🔹 Type Vector{Real}
🔹 Shape (nTime, nPosition)
🔹 Unit C
----------------------------------------------------------------------------------------------------
📈 Output Variable: ElectrolyteCharge
----------------------------------------------------------------------------------------------------
🔹 Name ElectrolyteCharge
🔹 Category OutputVariable
🔹 Description Charge carried by the ions in the electrolyte.
🔹 Type Vector{Real}
🔹 Shape (nTime, nPosition)
🔹 Unit C
----------------------------------------------------------------------------------------------------
📈 Output Variable: DischargeEnergy
----------------------------------------------------------------------------------------------------
🔹 Name DischargeEnergy
🔹 Category OutputVariable
🔹 Description Total energy output from the battery during discharge.
🔹 Type Vector{Real}
🔹 Shape (nCycleIndex,)
🔹 Unit J
----------------------------------------------------------------------------------------------------
📈 Output Variable: PositiveElectrodeActiveMaterialCharge
----------------------------------------------------------------------------------------------------
🔹 Name PositiveElectrodeActiveMaterialCharge
🔹 Category OutputVariable
🔹 Description Charge stored in the positive electrode.
🔹 Type Vector{Real}
🔹 Shape (nTime, nPosition)
🔹 Unit C
----------------------------------------------------------------------------------------------------
📈 Output Variable: ChargeEnergy
----------------------------------------------------------------------------------------------------
🔹 Name ChargeEnergy
🔹 Category OutputVariable
🔹 Description Total energy input to the battery during charging.
🔹 Type Vector{Real}
🔹 Shape (nCycleIndex,)
🔹 Unit J
----------------------------------------------------------------------------------------------------
📈 Output Variable: ChargeCapacity
----------------------------------------------------------------------------------------------------
🔹 Name ChargeCapacity
🔹 Category OutputVariable
🔹 Description Total amount of charge accepted during the charge phase.
🔹 Type Vector{Real}
🔹 Shape (nCycleIndex,)
🔹 Unit Ah
========================================================================================================================This is especially useful when building or editing custom parameter sets.
Listing Available Submodels
BattMo supports a modular submodel architecture. To view all available submodels you can integrate into your simulation, run:
julia
print_submodels()====================================================================================================
ℹ️ Submodels Information
====================================================================================================
Parameter Options Documentation
----------------------------------------------------------------------------------------------------
ButlerVolmer Standard, Chayambuka ]8;;https://battmoteam.github.io/BattMo.jl/dev/manuals/user_guide/pxd_model\visit]8;;\
CurrentCollectors Standard -
SEIModel Bolay ]8;;https://battmoteam.github.io/BattMo.jl/dev/manuals/user_guide/sei_model\visit]8;;\
RampUp Sinusoidal ]8;;https://battmoteam.github.io/BattMo.jl/dev/manuals/user_guide/ramp_up\visit]8;;\
TemperatureDependence Arrhenius ]8;;https://battmoteam.github.io/BattMo.jl/dev/manuals/user_guide/arrhenius\visit]8;;\
PotentialFlowDiscretization GeneralAD, TwoPointDiscretization -
TransportInSolid FullDiffusion -
ModelFramework P2D, P4D Pouch, P4D Cylindrical ]8;;https://battmoteam.github.io/BattMo.jl/dev/manuals/user_guide/pxd_model\visit]8;;\Write a parameter set object to a JSON file
You can use the following function to save your ParameterSet object to a JSON file:
julia
file_path = "path_to_json_file/file.json"
parameter_set = CellParameters(Dict("NegativeElectrode" => Dict("Coating" => Dict("Thickness" => 100e-6))))
write_to_json_file(file_path, parameter_set)An error occurred while writing to the file: SystemError("opening file \"path_to_json_file/file.json\"", 2, nothing)Get quick information on a cell parameter set
Let's load a default cell parameter set.
julia
cell_parameters = load_cell_parameters(; from_default_set = "chen_2020")You can easily print some handy quantities and metrics for debugging:
julia
quick_cell_check(cell_parameters)════════════════════════════════════════════════════════════════════════════════════════════════════════════
🔋 Quick Cell Check
════════════════════════════════════════════════════════════════════════════════════════════════════════════
Cell 1: Chen2020
Quantity Cell 1 | Unit | Source
────────────────────────────────────────────────────────────────────────────────────────────────────────────
Nominal Voltage 3.71 | V | [INPUT]
Nominal Capacity 4.8 | Ah | [INPUT]
Cell Theoretical Capacity 5.09 | Ah | [EQUILIBRIUM CALCULATION]
Cell N:P Ratio 0.9131 | - | [EQUILIBRIUM CALCULATION]
Cell Mass 0.04745 | kg | [EQUILIBRIUM CALCULATION]
Positive Electrode Mass Loading 24.89 | mg/cm² | [EQUILIBRIUM CALCULATION]
Negative Electrode Mass Loading 14.44 | mg/cm² | [EQUILIBRIUM CALCULATION]
════════════════════════════════════════════════════════════════════════════════════════════════════════════If there are functional parameters present within the parameter set, like the OCP or electrolyte diffusion coefficient, you can easily plot those parameters against a realistic x-quantity range:
julia
plot_cell_curves(cell_parameters)
Example on GitHub
If you would like to run this example yourself, it can be downloaded from the BattMo.jl GitHub repository as a script.
This page was generated using Literate.jl.