Battery--Cantera: Modeling fundamental physical chemistry in batteries using Cantera.
This tool allows you to run battery simulations with eaily editable and extensible thermochemistry via Cantera.
bat_can.py
: this is the main file that runs the code. In general, the code is run on the command line viapython bat_can.py
(more on this below)bat_can_init.py
: reads user inputs and initializes the model. It is called internally bybat_can.py
.- Simluation packages which define different simulation types/routines:
CC_cycle
: constant current galvanostatc cycling.potential_hold
: a series of potentiostatic holds of variable duration.cyclic_voltammetry
: cyclic voltammetry experiment.
- Electrode model packages:
single_particle_electrode
: the standard "single particle model" approach to a porous electrode.dense_electrode
: Model for a dense, thin-film electrode. Currently demonstrated for a lithium metal anode, but could be used for other purposes.
- Electrolyte model packages:
ionic_resistor
: Simple ionic resistor with no chemical composition dynamics.porous_separator
: porous inert separator filled with electrolyte.
- Submodels: functions and routines that are used by multiple parts of the code.
transport
: functions to describe transport phenomena.
inputs
: folder with all input files.derivation_verification
: Notes and documents to describe model development, governing equations, etc. (currently under development)
In order to use the BatCan suite, it is necessary to download and install:
These can all be installed an managed via Anaconda
For example, to create a conda environment bat_can
from which to run this tool, enter the following on a command line, terminal, or Anaconda prompt:
conda create --name bat_can --channel conda-forge cantera scikits.odes matplotlib numpy ruamel.yaml
You can replace bat_can
with whatever name you would like to give this environment. After this completes, activate the environment:
conda activate bat_can
(again, replacing bat_can
, as necessary, if you've named the environment something different). When you're done using the tool and want to switch back to your base software environment, run:
conda deactivate
To run the model, there are two main steps:
The input file provides all the necessary information to bat_can
program so that it may run your simulation.
The input file includes three primary sections:
- A description of the battery components (anode, electrolyte separator, and cathode), including model type for each, geometry and microstructural parameters.
- A description of the simulation to run and parameters to specify the necessary operating conditions.
- A Cantera input section, used to create objects that represent the phases of matter present, the interfaces between then, and the thermodynamic, chemical kinetic, and transport processes involved.
If you would like to create your own input, there are template folders which demonstrate how to specify inputs for the various electrode, separator, and simulation types, as well as a number of relevant Cantera phases. You can copy and paste these snippets into a single input file to customize. There are also a large number of working input files located in the inputs
folder, which are meant to demonstrate and test the minimum functionality of the code. Locate one that you would like to use, modify an existing file to suit your purposes, or copy a file, save it to a new name, and edit as necessary.
At present, the input file must be saved to the inputs
folder.
The model is run from a command line or terminal by invoking python, the bat_can.py
name, and providing the name of your input file (with or wihout the .yaml
suffix) by assigning the keyword --input
. For example, if your input file is located at inputs/my_input.yaml
, you would run:
python bat_can.py --input=my_input
Again including the file extension is optional. The command:
python bat_can.py --input=my_input.yaml
would also work.
Below is an example of the model output, for a Li metal anode, porous separator with liquid carbonate electrolyte, and single-particle model of an LCO cathode, cycled 5 times at a rate of 0.01C (Note that the kinetic and transport parameters have not been tuned or even sourced from literature; this is for demonstration purposes only ๐ ).
(as of 27 July, 2021)
This software is currently in the development phase. Models are configured for either galvanostatic or potentiostatic operation.
- The
ionic_resistor
andporous_separator
separator models are complete. Theporous_separator
model currently only allows dilute solution approximation transport calcualtions, via the Poisson-Nernst-Planck equation. - The
dense_electrode
model is complete - The
single_particle_model
electrode is functional, but is zero-dimensional (there is no discretization of the representative particle in the radial direction). - Simulation models (
CC_cycle
,potential_hold
, andcyclic_voltammetry
) are all complete, but there are always new and more flexible user inputs that can be enabled ๐.
Adding new features is relatively easy, so please click on Issues
above and create a new issue if there is something you would like to see!
If you would like to help contribute to the software, please do! If you are uncertain of what to do, or have an idea and want to run it by us, maybe create an issue on the issues page, where we can discuss. Or else, feel free to fork a copy of this repo, make changes, and make a pull request.