DL_MG Documentation

DL_MG - a hybrid parallel (MPI+OpenMP), high order finite difference multigrid solver for the Poisson Boltzmann Equation on 3D cuboid domains

Version

4.2.0 (17/10/2023)

Authors

Lucian Anton, James Womack, Jacek Dziedzic and others

Overview

DL_MG solves the Poisson-Boltzmann Equation defined by the following general expression

\[ \nabla[\epsilon(\vec r)\nabla\phi(\vec r)] = \alpha \rho(\vec r) + \lambda \sum_i c_i q_i \exp[-\beta (q_i \phi(\vec r) + V(\vec r))] \ , \]

in 3D over a cuboid domain with periodic, Dirichlet and mixed boundary conditions. In the above equation \(\epsilon(\vec r)\) is the relative permittivity, \(\phi(\vec r)\) is the electric potential, \(\rho(\vec r)\) is the charge density, \( q_i\) and \(c_i\) are the electric charge and the average bulk concentration ( \( N_i/V \)) for the ion type \( i\) of the electrolyte respectively, \(\beta=1/k_BT\) is the inverse temperature, \(V(\vec r)\) is the steric potential which accounts for the short range repulsion effect between electrolyte ions and solute, \(\alpha\) and \(\lambda\) are constants which depend on the used units systems.

Main features:

• Specialised algorithms are used to solve the Poisson Equation

  \[ \nabla[\epsilon(\vec r)\nabla\phi(\vec r)] = \alpha \rho(\vec r) \ , \]

  and for the linearised Poisson Boltzmann Equation,

  \[ \nabla[\epsilon(\vec r)\nabla\phi(\vec r)] +\lambda \beta \sum_i c_i q_{i}^2 \exp[-\beta V(\vec r)]\phi(\vec r) = \alpha \rho(\vec r) \ . \]

• Several choices for the charge neutralisation procedure are available, see Periodic boundary conditions (PBC) for PBE.
• High order discretisation of the derivatives up to order 12, see Defect correction layer.
• The linear systems are handled with fast multigrid or multigrid precondition conjugate gradient solvers, but see Grid Size Constrains.
• It can handle arbitrary 3D MPI Cartesian topologies for domain decomposition.
• Automatic OpenMP domain partition (which can be overruled by the user).

More information on the algorithms used in the solver is available in Implementation Details.

Build

The source code is available at dlmg.org .

The easiest way to use DL_MG is to build it as a library and link it to your application. A few make variable must be defined in a platforms/<name>.inc file. For guidance the user is advised to inspect the files platforms/archer.inc, which is for a HPC system that offers several compilers via the module environment, or platforms/parallel_laptop.inc, platforms/serial_gnu.inc which were used on workstations.

The following make variables control the build:

• FC : fortran compile command
• BUILD : must be set to opt or debug.
• USE_OPENMP : 'yes' enables OpenMP, 'no' disables it
• USE_MPI : if defined enables the MPI build
  • the default access to MPI library entities is done with "use mpi" statement.
  • if USE_INCLUDE_MPIF make variable is defined the MPI library is accessed with "include 'mpif.h'"
  • if USE_MPI_F08 make variable is defined the MPI library is accessed with "use mpi_f08"