Coulomb Galore

This is a C++ library for calculating the potential, field, forces, and interactions from and between electric multipoles. Focus is on approximate truncation schemes that offer fast alternatives to Ewald summation. All implemented methods are unit tested.

Usage

Requirements

C++14 compiler
The Eigen matrix library
nlohmann::json (optional)
doctest (optional)
doxygen (optional, for building API manual)

Building

The CMake build will automatically download Eigen, json, and doctest.

cmake .
make
make test (optional)
doxygen (optional)

Use in your own code

Simply copy the include/coulombgalore directory to your project. All functions and classes are encapsulated in the CoulombGalore namespace. Vectors are currently handled by the Eigen library, but it should be possible to change to another library. You can import everything with #include "coulombgalore/all.h", or only what you need:

Example

#include "coulombgalore/plain.h"
int main() {
   Eigen::Vector3d R = {0,0,10};                      // distance vector
   CoulombGalore::Plain pot(14.0);                    // cutoff distance as constructor argument
   double u = pot.ion_ion_energy(1.0, 1.0, R.norm()); // potential energy = 1.0 x 1.0 / 10
   Eigen::Vector3d mu = {2,5,2};                      // dipole moment
   Eigen::Vector3d E = pot.dipole_field(mu, R);       // field from dipole at 𝐑
}

Available Truncation Schemes

Class name	S(q)
`Plain`	1
`ReactionField`	$1+\frac{\epsilon_{RF}-\epsilon_r}{2\epsilon_{RF}+\epsilon_r}q^3-3\frac{\epsilon_{RF}}{2\epsilon_{RF}+\epsilon_r}q$
`Poisson`	$(1-\tilde{q})^{D+1}\sum_{c=0}^{C-1}\frac{C-c}{C}{D-1+c\choose c}\tilde{q}^c$
`qPotential`	$\prod_{n=1}^{\text{order}}(1-q^n)$
`Fanourgakis`	$1-\frac{7}{4}q+\frac{21}{4}q^5-7q^6+\frac{5}{2}q^7$
`Fennell`	$\text{erfc}(\eta q)-q\text{erfc}(\eta)+(q-1)q\left(\text{erfc}(\eta)+\frac{2\eta}{\sqrt{\pi}}\text{exp}(-\eta^2)\right)$
`ZeroDipole`	$\text{erfc}(\eta q)-q\text{erfc}(\eta)+\frac{(q^2-1)}{2}q\left(\text{erfc}(\eta)+\frac{2\eta}{\sqrt{\pi}}\text{exp}(-\eta^2)\right)$
`Zahn`	$\text{erfc}(\eta q)-(q-1)q\left(\text{erfc}(\eta)+\frac{2\eta}{\sqrt{\pi}}\text{exp}(-\eta^2)\right)$
`Wolf`	$\text{erfc}(\eta q)-\text{erfc}(\eta)q$
`Ewald`	$\frac{1}{2}\text{erfc}\left(\eta q + \frac{\kappa^}{2\eta}\right)\text{exp}\left(2\kappa^ q\right) + \frac{1}{2}\text{erfc}\left(\eta q - \frac{\kappa^*}{2\eta}\right)$
`EwaldT`	$\frac{\text{erfc}{\left(\eta q\right)} - \text{erfc}{\left(\eta\right)} - (1-q)\frac{2\eta}{\sqrt{\pi}}\exp{\left(-\eta^2\right)}}{1 - \text{erfc}{\left(\eta\right)} - \frac{2\eta}{\sqrt{\pi}}\exp{\left(-\eta^2\right)}}$
`Splined`	Splined version of any of the above

Here

$q=\frac{r}{R_c}\quad\quad \tilde{q}=\frac{1-\exp(2\kappa^*q)}{1-\exp(2\kappa^*)} \quad\quad \eta = \alpha R_c \quad\quad \kappa^*=\kappa R_c.$

Units

It is vital that the units of the input parameters and function input values are consistent, such that correct output units are retrieved. In terms of the charge unit Z, and length unit L, the input parameters and function outputs are listed in tables below. All charges must have units Z, dipoles Z*L, distances L, volumes L^3, and fields Z/L^2. Also note that the input M2V for function calc_dielectric has to be unitless.http://doi.org/10.1021/acs.jpca.0c01684

Input parameter	Unit
`cutoff`	`L`
`debye_length`	`L`
`alpha`	`L^-1`
`order`	`positive integer`
`C`	`positive integer`
`D`	`integer`
`epss`	`unitless`
`epsRF`	`unitless`
`epsr`	`unitless`
`shifted`	`boolean`

Function	Output unit
`ion_potential`	`Z / L`
`dipole_potential`	`Z / L`
`ion_field`	`Z / L^2`
`dipole_field`	`Z / L^2`
`multipole_field`	`Z / L^2`
`ion_ion_energy`	`Z^2 / L`
`ion_dipole_energy`	`Z^2 / L`
`dipole_dipole_energy`	`Z^2 / L`
`multipole_multipole_energy`	`Z^2 / L`
`ion_ion_force`	`Z^2 / L^2`
`ion_dipole_force`	`Z^2 / L^2`
`dipole_dipole_force`	`Z^2 / L^2`
`multipole_multipole_force`	`Z^2 / L^2`
`dipole_torque`	`Z^2 / L`
`self_energy`	`Z^2 / L`
`neutralization_energy`	`Z^2 / L`