llnl / echemfem

Finite Element Method for Electrochemical Transport (EchemFEM)

EchemFEM

This code provides Finite Element solvers for electrochemical transport. Both continuous Galerkin (CG) and discontinuous Galerkin (DG) schemes are provided. The DG scheme for electroneutral Nernst-Planck is described in Roy et al., 2023. The CG scheme uses SUPG for the advection-migration term.

The following transport mechanisms are available: diffusion, advection, electromigration. EchemFEM supports both non-porous and porous cases. The ionic potential can either be described using an electroneutrality constraint or a Poisson equation. In the porous case, the electronic potential can be described by a Poisson equation. Some finite size effects are also implemented. For example, the generalized modified Poisson-Nernst-Planck model (GMPNP) is used in the examples of FireCat, coupling in with a microkinetics model.

LLNL-CODE-837342

Documentation

User guide and API documentation can be found here documentation.

Installation

Please install the open-source finite element library Firedrake.

To install EchemFEM, simply run the following in the parent echemfem folder:

pip install -e .

echemfem's Issues

Installation with Firedrake

Hi @tlroy, this issue is with regards to this review. I am having some trouble with installing Firedrake, which seems to be an important dependency for echemfem.

Please correct me if I am mistaken, but to summarize my understanding: Firedrake requires root access for accessing the package manager (apt/brew) in order to install required packages. There also appear to be several configuration options to install Firedrake through their python installer (with torch, complex, etc). I do not currently see any recommended installation instructions for Firedrake within the install instructions of this package. Could there be more explicit options on tags to pass to the Firedrake installer? Optionally, to make it easier for users, you may provide a set of required packages that can be installed by apt/brew that is required specifically for the features of Firedrake that this package required.

Specifically to my installation troubles, I am attempting to install Firedrake on a (clean) ubuntu virtual machine - allowing root access for the installation. With python3.10, the installer fails with an error that it is not able to install vtk (specifically No matching distribution found for vtk>=9.0.1). It seems like the only way forward to to change firedrake-install, are there any recommendations for what version is needed for echemfem?

Errors in tests and memory requirements

Hello again @tlroy, I am trying to get a gauge for the memory requirements of running all the unit tests. I understand that you recommend running just one of the tests tests/test_advection_diffusion_migration_darcy.py instead of the whole set of tests. But when I run just pytest it seems to segfault, and running each unit test separately seems to give me specific errors such as

FAILED tests/test_advection_diffusion_migration_darcy.py::test_convergence_low_peclet - assert 0.7524928310011721 < (0.29 * 0.6053442046721568)
FAILED tests/test_advection_diffusion_migration_darcy.py::test_convergence_high_peclet - assert 0.27139794880604756 < (0.35 * 0.45044972210083223)

for tests/test_advection_diffusion_migration_darcy.py, for example.

For reference, I am running a VM with firedrake installed (as you suggested here: #8) on a M1 Mac.

EDIT: based on openjournals/joss-reviews#6531 (comment)

Errors with examples

I am running on linux Ubuntu 22.04.4 LTS
I installed firedrake successfully using the install script here https://www.firedrakeproject.org/download.html
I activated the firedrake virtualenv and tried importing it into a python terminal but got an h5py import error
So I uninstalled it and reinstalled the latest version and import error went away
I installed the latest echemfem code and tried this example but got another error possibly related to H5py

(firedrake) tom@tom:~/code/echemfem/examples$ python simple_flow_battery.py firedrake:WARNING OMP_NUM_THREADS is not set or is set to a value greater than 1, we suggest setting OMP_NUM_THREADS=1 to improve performance Using dimensional Navier-Stokes-Brinkman 0 SNES Function norm 3.719318934070e-09 1 SNES Function norm 2.221647403080e-23 /home/tom/code/firedrake/src/firedrake/firedrake/_deprecation.py:65: UserWarning: The use of Filefor output is deprecated, please update your code to useVTKFilefromfiredrake.output. warn( Traceback (most recent call last): File "simple_flow_battery.py", line 109, in <module> solver = FlowBatterySolver() File "simple_flow_battery.py", line 75, in __init__ super().__init__( File "/home/tom/code/echemfem/echemfem/solver.py", line 383, in __init__ self.set_velocity() File "simple_flow_battery.py", line 105, in set_velocity NSB_solver.solve() File "/home/tom/code/echemfem/echemfem/flow_solver.py", line 109, in solve with CheckpointFile('Velocity_field'+'.h5', 'w') as afile: File "/home/tom/code/firedrake/src/firedrake/firedrake/checkpointing.py", line 538, in __init__ self.set_attr_byte_string("/", "dmplex_storage_version", version) File "/home/tom/code/firedrake/src/firedrake/firedrake/checkpointing.py", line 1692, in set_attr_byte_string grp = self.require_group(path) File "/home/tom/code/firedrake/src/firedrake/firedrake/checkpointing.py", line 1772, in require_group _self = self.h5pyfile File "/home/tom/code/firedrake/src/firedrake/firedrake/checkpointing.py", line 1645, in h5pyfile self._h5pyfile = h5i.get_h5py_file(self.viewer) File "firedrake/cython/hdf5interface.pyx", line 35, in firedrake.cython.hdf5interface.get_h5py_file File "h5py/h5i.pyx", line 33, in h5py.h5i.wrap_identifier File "h5py/h5i.pyx", line 38, in h5py.h5i.wrap_identifier File "h5py/defs.pyx", line 1240, in h5py.defs.H5Iget_type RuntimeError: Unspecified error in H5Iget_type (return value <0)

running another example gives slightly different errors

(firedrake) tom@tom:~/code/echemfem/examples$ python paper_test.py 
firedrake:WARNING OMP_NUM_THREADS is not set or is set to a value greater than 1, we suggest setting OMP_NUM_THREADS=1 to improve performance
Eliminating species: C2
Creating function spaces for an extruded mesh
*** WARNING: Using custom solver options
*** ECHEM
Activated flow components
  advection 	 order = 1
  diffusion 	 order = 1
  migration 	 order = 1
  electroneutrality 	 order = 1
Species information
> C1
  z = 2.0
> C2
  z = -2.0
Solver information
variable 	 #dofs
C1 		 512
C2 		 512
Potential 	 512
Total 		 1536
#ranks 		 1
#dofs/rank 	 1536
Writing solutions. This may take a while...
/home/tom/code/firedrake/src/firedrake/firedrake/_deprecation.py:65: UserWarning: The use of `File` for output is deprecated, please update your code to use `VTKFile` from `firedrake.output`.
  warn(
/home/tom/code/firedrake/src/FInAT/finat/ufl/elementlist.py:441: UserWarning: Discontinuous Lagrange element requested on quadrilateral * interval, creating DQ element.
  warnings.warn("Discontinuous Lagrange element requested on %s, creating DQ element." % cell.cellname())
tsfc:WARNING Estimated quadrature degree 11 more than tenfold greater than any argument/coefficient degree (max (1, 1))
tsfc:WARNING Estimated quadrature degree 11 more than tenfold greater than any argument/coefficient degree (max (1, 1))
cells = 16 L2err = 6.08029E-03 C1err = 3.43798E-03 Uerr = 2.64230E-03
Eliminating species: C2
Creating function spaces for an extruded mesh
*** WARNING: Using custom solver options
*** ECHEM
Activated flow components
  advection 	 order = 1
  diffusion 	 order = 1
  migration 	 order = 1
  electroneutrality 	 order = 1
Species information
> C1
  z = 2.0
> C2
  z = -2.0
Solver information
variable 	 #dofs
C1 		 4096
C2 		 4096
Potential 	 4096
Total 		 12288
#ranks 		 1
#dofs/rank 	 12288
Writing solutions. This may take a while...
/home/tom/code/firedrake/src/firedrake/firedrake/_deprecation.py:65: UserWarning: The use of `File` for output is deprecated, please update your code to use `VTKFile` from `firedrake.output`.
  warn(
/home/tom/code/firedrake/src/FInAT/finat/ufl/elementlist.py:441: UserWarning: Discontinuous Lagrange element requested on quadrilateral * interval, creating DQ element.
  warnings.warn("Discontinuous Lagrange element requested on %s, creating DQ element." % cell.cellname())
cells = 64 L2err = 1.49294E-03 C1err = 8.63412E-04 Uerr = 6.29528E-04
Eliminating species: C2
Creating function spaces for an extruded mesh
*** WARNING: Using custom solver options
*** ECHEM
Activated flow components
  advection 	 order = 1
  diffusion 	 order = 1
  migration 	 order = 1
  electroneutrality 	 order = 1
Species information
> C1
  z = 2.0
> C2
  z = -2.0
Solver information
variable 	 #dofs
C1 		 32768
C2 		 32768
Potential 	 32768
Total 		 98304
#ranks 		 1
#dofs/rank 	 98304
Writing solutions. This may take a while...
/home/tom/code/firedrake/src/firedrake/firedrake/_deprecation.py:65: UserWarning: The use of `File` for output is deprecated, please update your code to use `VTKFile` from `firedrake.output`.
  warn(
/home/tom/code/firedrake/src/FInAT/finat/ufl/elementlist.py:441: UserWarning: Discontinuous Lagrange element requested on quadrilateral * interval, creating DQ element.
  warnings.warn("Discontinuous Lagrange element requested on %s, creating DQ element." % cell.cellname())
cells = 256 L2err = 3.79596E-04 C1err = 2.27132E-04 Uerr = 1.52464E-04
Eliminating species: C2
Creating function spaces for an extruded mesh
*** WARNING: Using custom solver options
*** ECHEM
Activated flow components
  advection 	 order = 1
  diffusion 	 order = 1
  migration 	 order = 1
  electroneutrality 	 order = 1
Species information
> C1
  z = 2.0
> C2
  z = -2.0
Solver information
variable 	 #dofs
C1 		 262144
C2 		 262144
Potential 	 262144
Total 		 786432
#ranks 		 1
#dofs/rank 	 786432
Writing solutions. This may take a while...
/home/tom/code/firedrake/src/firedrake/firedrake/_deprecation.py:65: UserWarning: The use of `File` for output is deprecated, please update your code to use `VTKFile` from `firedrake.output`.
  warn(
/home/tom/code/firedrake/src/FInAT/finat/ufl/elementlist.py:441: UserWarning: Discontinuous Lagrange element requested on quadrilateral * interval, creating DQ element.
  warnings.warn("Discontinuous Lagrange element requested on %s, creating DQ element." % cell.cellname())
cells = 1024 L2err = 1.11179E-04 C1err = 7.37598E-05 Uerr = 3.74192E-05
Eliminating species: C2
Creating function spaces for an extruded mesh
*** WARNING: Using custom solver options
*** ECHEM
Activated flow components
  advection 	 order = 1
  diffusion 	 order = 1
  migration 	 order = 1
  electroneutrality 	 order = 1
Species information
> C1
  z = 2.0
> C2
  z = -2.0
Solver information
variable 	 #dofs
C1 		 2097152
C2 		 2097152
Potential 	 2097152
Total 		 6291456
#ranks 		 1
#dofs/rank 	 6291456
Killed

Justification in paper for using Firedrake

This is a minor point but there is no justification for using Firedrake. Are there any major advantages to using this over FEniCS which seems to be a larger and more developed project with similar functionality?

What needs to be done after subclassing EchemSolver?

I am trying to understand how two examples (https://github.com/LLNL/echemfem/blob/main/examples/catalyst_layer_Cu.py and https://github.com/LLNL/echemfem/blob/main/examples/bicarb_Ag_Cu_tandem_example.py) work in practice. Both seem to subclass an abstract base class, but this abstract base class does not seem to require any required methods to be implemented. Could there be some additional documentation about methods that need to be implemented - or in general some documentation about the use of EchemSolver?

In general, for the examples, it would also be good to explain what they are intended to do and how they interface with echemfem. One suggestion may be to generate YAML files for the inputs (removing clutter at the start of the file) and then keeping post-processing and output towards the very end with a clear label.

Improve examples

You need to improve the examples.
Ideally there would be a getting started example (or more) where the process of creating a new simple model, running it and viewing the results is explained.
I would like to see an index for each example with a short description of what it does - and more commenting in the examples themselves.
It would be nice to see these as jupyter notebooks that could form part of your docs
In general docs are very light