Update documentation and clarify ambiguities (#3673)

Description of changes: - remove CUDA installation instructions on OSX (follow-up to #3652) - update links to dockerfiles for non-Ubuntu OSes - correct the Coulomb prefactor formula (fixes #3633) - in electrostatics scripts, replace magic values by their full expressions - document the difference between serial and parallel versions of `libhdf5-dev` (fixes #3656) - improve documentation of the script that shows the effect of MPI and `node_grid` on domain decomposition (see mailing list email "dividing simulation box using MPI" from 2020-04-20)
espressomd · Apr 20, 2020 · f49d3b1 · f49d3b1
2 parents 7f90057 + 135a717
commit f49d3b1
Show file tree

Hide file tree

Showing 9 changed files with 45 additions and 31 deletions.
diff --git a/doc/sphinx/electrostatics.rst b/doc/sphinx/electrostatics.rst
@@ -7,7 +7,7 @@ The Coulomb (or electrostatic) interaction is defined as
 follows. For a pair of particles at distance :math:`r` with charges
 :math:`q_1` and :math:`q_2`, the interaction is given by
 
-.. math:: U_C(r)=C \cdot \frac{q_1 q_2}{r}.
+.. math:: U_C(r)=C \cdot \frac{q_1 q_2}{r}
 
 where
 
@@ -16,10 +16,10 @@ where
    :label: coulomb_prefactor
 
 is a prefactor which can be set by the user. The commonly used Bjerrum length
-:math:`l_B = e_o^2 / (4 \pi \varepsilon_0 \varepsilon_r k_B T)` is the length at
+:math:`l_B = e^2 / (4 \pi \varepsilon_0 \varepsilon_r k_B T)` is the length at
 which the Coulomb energy between two unit charges is equal to the thermal
 energy :math:`k_B T`.
-Based on the this length, the prefactor is given by :math:`C=l_B k_B T`.
+Based on this length, the prefactor is given by :math:`C=l_B k_B T / e^2`.
 
 Computing electrostatic interactions is computationally very expensive.
 |es| features some state-of-the-art algorithms to deal with these

diff --git a/doc/sphinx/installation.rst b/doc/sphinx/installation.rst
@@ -126,10 +126,10 @@ Installing requirements on other Linux distributions
 Please refer to the following Dockerfiles to find the minimum set of packages
 required to compile |es| on other Linux distributions:
 
-* `CentOS 7 <https://github.com/espressomd/docker/blob/master/docker/centos-python3/Dockerfile-7>`_
-* `Fedora 30 <https://github.com/espressomd/docker/blob/master/docker/centos-python3/Dockerfile-next>`_
-* `Debian 10 <https://github.com/espressomd/docker/blob/master/docker/debian-python3/Dockerfile-10>`_
-* `OpenSUSE Leap 15.1 <https://github.com/espressomd/docker/blob/master/docker/opensuse/Dockerfile-15.1>`_
+* `CentOS <https://github.com/espressomd/docker/blob/master/docker/Dockerfile-centos>`_
+* `Fedora <https://github.com/espressomd/docker/blob/master/docker/Dockerfile-fedora>`_
+* `Debian <https://github.com/espressomd/docker/blob/master/docker/Dockerfile-debian>`_
+* `OpenSUSE <https://github.com/espressomd/docker/blob/master/docker/Dockerfile-opensuse>`_
 
 
 .. _Installing requirements on Mac OS X:
@@ -217,12 +217,6 @@ Installing packages using Homebrew
     brew link --force cython
     pip install PyOpenGL matplotlib
 
-Installing CUDA
-"""""""""""""""
-
-If your Mac has an Nvidia graphics card, you should also download and install the
-CUDA SDK [6]_ to make use of GPU computation.
-
 .. _Quick installation:
 
 Quick installation
@@ -874,6 +868,3 @@ use one tool at a time.
 
 .. [5]
    http://www.fftw.org/
-
-.. [6]
-   https://developer.nvidia.com/cuda-downloads
diff --git a/doc/sphinx/io.rst b/doc/sphinx/io.rst
@@ -121,7 +121,10 @@ Writing H5MD-files
 
 .. note::
 
-    Requires ``H5MD`` external feature, enabled with ``-DWITH_HDF5=ON``.
+    Requires ``H5MD`` external feature, enabled with ``-DWITH_HDF5=ON``. Also
+    requires a parallel version of HDF5. On Ubuntu, this can be installed via
+    either ``libhdf5-openmpi-dev`` for OpenMPI or ``libhdf5-mpich-dev`` for
+    MPICH, but not ``libhdf5-dev`` which is the serial version.
 
 For large amounts of data it's a good idea to store it in the hdf5 (H5MD
 is based on hdf5) file format (see https://www.hdfgroup.org/ for

diff --git a/doc/sphinx/system_setup.rst b/doc/sphinx/system_setup.rst
@@ -118,7 +118,8 @@ The properties of the cell system can be accessed by
     * :py:attr:`~espressomd.cellsystem.CellSystem.node_grid`
 
     (int[3]) 3D node grid for real space domain decomposition (optional, if
-    unset an optimal set is chosen automatically).
+    unset an optimal set is chosen automatically). The domain decomposition
+    can be visualized with :file:`samples/visualization_cellsystem.py`.
 
     * :py:attr:`~espressomd.cellsystem.CellSystem.skin`
 

diff --git a/doc/tutorials/02-charged_system/02-charged_system-2.ipynb b/doc/tutorials/02-charged_system/02-charged_system-2.ipynb
@@ -101,8 +101,11 @@
     "time_step = 0.001823\n",
     "temp = 1198.3\n",
     "gamma = 50\n",
-    "#l_bjerrum = 0.885^2 * e^2/(4*pi*epsilon_0*k_B*T)\n",
-    "l_bjerrum = 130878.0 / temp\n",
+    "k_B = 1.380649e-23  # units of [J/K]\n",
+    "q_e = 1.602176634e-19  # units of [C]\n",
+    "epsilon_0 = 8.8541878128e-12  # units of [C^2/J/m]\n",
+    "coulomb_prefactor = q_e**2 / (4 * numpy.pi * epsilon_0) * 1e10\n",
+    "l_bjerrum = 0.885**2 * coulomb_prefactor / (k_B * temp)\n",
     "wall_margin = 0.5\n",
     "Ez = 0\n",
     "\n",

diff --git a/doc/tutorials/02-charged_system/scripts/nacl_units.py b/doc/tutorials/02-charged_system/scripts/nacl_units.py
@@ -37,8 +37,11 @@
 time_step = 0.001823
 temp = 298.0
 gamma = 4.55917
-#l_bjerrum = 0.885^2 * e^2/(4*pi*epsilon_0*k_B*T)
-l_bjerrum = 130878.0 / temp
+k_B = 1.380649e-23  # units of [J/K]
+q_e = 1.602176634e-19  # units of [C]
+epsilon_0 = 8.8541878128e-12  # units of [C^2/J/m]
+coulomb_prefactor = q_e**2 / (4 * numpy.pi * epsilon_0) * 1e10
+l_bjerrum = 0.885**2 * coulomb_prefactor / (k_B * temp)
 
 num_steps_equilibration = 9000
 num_configs = 50

diff --git a/doc/tutorials/02-charged_system/scripts/nacl_units_vis.py b/doc/tutorials/02-charged_system/scripts/nacl_units_vis.py
@@ -75,8 +75,11 @@ def decreaseTemp():
 time_step = 0.001823
 temp = 298.0
 gamma = 20.0
-#l_bjerrum = 0.885^2 * e^2/(4*pi*epsilon_0*k_B*T)
-l_bjerrum = 130878.0 / temp
+k_B = 1.380649e-23  # units of [J/K]
+q_e = 1.602176634e-19  # units of [C]
+epsilon_0 = 8.8541878128e-12  # units of [C^2/J/m]
+coulomb_prefactor = q_e**2 / (4 * numpy.pi * epsilon_0) * 1e10
+l_bjerrum = 0.885**2 * coulomb_prefactor / (k_B * temp)
 
 num_steps_equilibration = 30
 

diff --git a/samples/visualization_cellsystem.py b/samples/visualization_cellsystem.py
@@ -16,7 +16,11 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 """
 Visualize the system cells and MPI domains. Run ESPResSo in parallel
-to color particles by node.
+to color particles by node. With OpenMPI, this can be achieved using
+``mpiexec -n 4 ./pypresso ../samples/visualization_cellsystem.py``.
+Set property ``system.cell_system.node_grid = [i, j, k]`` (with ``i * j * k``
+equal to the number of MPI ranks) to change the way the cellsystem is
+partitioned. Only the domain of MPI rank 0 will be shown in wireframe.
 """
 
 import espressomd
@@ -41,6 +45,7 @@
 system.time_step = 0.0005
 system.cell_system.set_domain_decomposition(use_verlet_lists=True)
 system.cell_system.skin = 0.4
+#system.cell_system.node_grid = [i, j, k]
 
 for i in range(100):
     system.part.add(pos=box * np.random.random(3))

diff --git a/samples/visualization_charged.py b/samples/visualization_charged.py
@@ -45,12 +45,17 @@
 kb_kjmol = 0.0083145
 temperature = SI_temperature * kb_kjmol
 
-# COULOMB PREFACTOR (elementary charge)^2 / (4*pi*epsilon_0) in Angstrom *
-# kJ/mol
-epsilon_r = 4.0
-coulomb_prefactor = 1.67101e5 * kb_kjmol / epsilon_r
+# COULOMB PREFACTOR (elementary charge)^2 / (4*pi*epsilon) in Angstrom*kJ/mol
+epsilon_r = 4.0  # dimensionless
+epsilon_0 = 8.8541878128e-12  # units of [C^2/J/m]
+q_e = 1.602176634e-19  # units of [C]
+avogadro = 6.022e23  # units of [mol]
+prefactor = q_e**2 / (4 * np.pi * epsilon_r * epsilon_0)  # units of [J.m]
+# convert energies to kJ/mol, with distances in Angstroms
+coulomb_prefactor = prefactor * avogadro / 1000 * 1e10
 
 # FORCE FIELDS
+# distances in Angstroms, epsilons in kBT, masses in g/mol
 species = ["Cl", "Na", "Colloid", "Solvent"]
 types = {"Cl": 0, "Na": 1, "Colloid": 2, "Solvent": 3}
 charges = {"Cl": -1.0, "Na": 1.0, "Colloid": -3.0, "Solvent": 0.0}
@@ -114,11 +119,11 @@ def combination_rule_sigma(rule, sig1, sig2):
             epsilon=lj_eps, sigma=lj_sig, cutoff=lj_cut, shift="auto")
 
 energy = system.analysis.energy()
-print("Before Minimization: E_total = {}".format(energy['total']))
+print("Before Minimization: E_total = {:.2e}".format(energy['total']))
 steepest_descent(system, f_max=1000, gamma=30.0, max_steps=1000,
                  max_displacement=0.01)
 energy = system.analysis.energy()
-print("After Minimization: E_total = {}".format(energy['total']))
+print("After Minimization: E_total = {:.2e}".format(energy['total']))
 
 print("Tune p3m")
 p3m = electrostatics.P3M(prefactor=coulomb_prefactor, accuracy=1e-1)