Merge branch 'python' into python

espressomd · Aug 26, 2024 · 6f0494c · 6f0494c
2 parents 1e9fddb + 8db11b0
commit 6f0494c
Show file tree

Hide file tree

Showing 26 changed files with 589 additions and 395 deletions.
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
@@ -223,6 +223,7 @@ cuda12-coverage:
      with_stokesian_dynamics: 'true'
   script:
     - bash maintainer/CI/build_cmake.sh
+  timeout: 90m
   tags:
     - espresso
     - cuda
@@ -252,6 +253,7 @@ cuda12-maxset:
     paths:
     - build/
     expire_in: 1 week
+  timeout: 90m
   tags:
     - espresso
     - cuda

diff --git a/doc/doxygen/CMakeLists.txt b/doc/doxygen/CMakeLists.txt
@@ -1,5 +1,5 @@
 #
-# Copyright (C) 2015-2022 The ESPResSo project
+# Copyright (C) 2015-2024 The ESPResSo project
 #
 # This file is part of ESPResSo.
 #
@@ -28,25 +28,23 @@ if(DOXYGEN_FOUND)
   set(DOXYGEN_BIB_IN ${CMAKE_SOURCE_DIR}/doc/bibliography.bib)
   set(DOXYGEN_BIB_OUT ${CMAKE_CURRENT_BINARY_DIR}/bibliography.bib)
 
-  # transform BibTeX DOI fields into URL fields (bibliographic styles available
-  # to Doxygen do not process the DOI field)
   add_custom_command(
     OUTPUT ${DOXYGEN_BIB_OUT}
     COMMAND
-      sed -r "'s_^ *doi *= *([^0-9]+)(10\\.[0-9]+)_url=\\1https://doi.org/\\2_'"
-      ${DOXYGEN_BIB_IN} > ${DOXYGEN_BIB_OUT}
+      ${CMAKE_COMMAND} -DINPUT=${DOXYGEN_BIB_IN} -DOUTPUT=${DOXYGEN_BIB_OUT} -P
+      ${CMAKE_CURRENT_SOURCE_DIR}/bibtex_preprocess.cmake
     DEPENDS ${DOXYGEN_BIB_IN})
 
   set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
   set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
-  set(CITELIST ${CMAKE_CURRENT_BINARY_DIR}/html/citelist.html)
+  set(DOXYGEN_CITELIST ${CMAKE_CURRENT_BINARY_DIR}/html/citelist.html)
 
   configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)
 
   add_custom_target(
     doxygen COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}
-    COMMAND sed -ri "s/ textsuperscript (\\S+) /<sup>\\1<\\/sup> /" ${CITELIST}
-    COMMAND sed -ri "s/ textsubscript (\\S+) /<sub>\\1<\\/sub> /" ${CITELIST}
+    COMMAND ${CMAKE_COMMAND} -DBIBLIOGRAPHY=${DOXYGEN_CITELIST} -P
+            ${CMAKE_CURRENT_SOURCE_DIR}/bibtex_postprocess.cmake
     WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
     COMMENT "Generating API documentation with Doxygen"
     DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/doxy-features ${DOXYGEN_BIB_OUT}

diff --git a/doc/doxygen/bibtex_postprocess.cmake b/doc/doxygen/bibtex_postprocess.cmake
@@ -0,0 +1,26 @@
+#
+# Copyright (C) 2023-2024 The ESPResSo project
+#
+# This file is part of ESPResSo.
+#
+# ESPResSo is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ESPResSo is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+if(EXISTS "${BIBLIOGRAPHY}")
+  file(READ "${BIBLIOGRAPHY}" FILE_CONTENTS)
+  # convert unsupported LaTeX formatting commands to HTML
+  string(REGEX REPLACE " textsuperscript ([^ ]+) " "<sup>\\1</sup> " FILE_CONTENTS "${FILE_CONTENTS}")
+  string(REGEX REPLACE " textsubscript ([^ ]+) " "<sub>\\1</sub> " FILE_CONTENTS "${FILE_CONTENTS}")
+  file(WRITE "${BIBLIOGRAPHY}" "${FILE_CONTENTS}")
+endif()
diff --git a/doc/doxygen/bibtex_preprocess.cmake b/doc/doxygen/bibtex_preprocess.cmake
@@ -0,0 +1,29 @@
+#
+# Copyright (C) 2019-2024 The ESPResSo project
+#
+# This file is part of ESPResSo.
+#
+# ESPResSo is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ESPResSo is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+file(READ "${INPUT}" FILE_CONTENTS)
+
+# transform BibTeX DOI fields into URL fields (bibliographic styles available
+# to Doxygen do not process the DOI field)
+string(REGEX REPLACE
+       "([\r\n])[\t ]*doi *= *([\\{\"]+)(10\\.[0-9]+)"
+       "\\1url=\\2https://doi.org/\\3"
+       FILE_CONTENTS "${FILE_CONTENTS}")
+
+file(WRITE "${OUTPUT}" "${FILE_CONTENTS}")
diff --git a/doc/sphinx/installation.rst b/doc/sphinx/installation.rst
@@ -132,7 +132,7 @@ To install the ZnDraw visualizer:
 
 .. code-block:: bash
 
-    python3 -m pip install --user -c requirements.txt 'zndraw==0.4.5'
+    python3 -m pip install --user -c requirements.txt 'zndraw==0.4.6'
 
 .. _Nvidia GPU acceleration:
 

diff --git a/doc/sphinx/visualization.rst b/doc/sphinx/visualization.rst
@@ -303,7 +303,7 @@ ZnDraw visualizer
 
 |es| supports the ZnDraw visualizer :cite:`elijosius24a` in Jupyter Notebooks.
 With ZnDraw [1]_, you can visualize your simulation live in a notebook or
-web browser. The visualizer is based on ``THREE.js``.
+web browser.
 
 .. _ZnDraw General usage:
 
@@ -316,6 +316,9 @@ colors like ``red``, ``black`` etc., but one can also use hex colors like ``#ff0
 Then write your integration loop in a separate function, and call the update function of the visualizer to capture
 the current state of the system and visualize it. Note that the visualizer needs to be started by pressing space.
 
+Note that due to the need of a server running in the background, the visualizer is currently not able to run in multiple notebooks at once.
+Make sure only one kernel is running the visualizer at a time.
+
 Example code::
 
     import espressomd
@@ -351,6 +354,10 @@ as a criterium. The ``normalize`` boolean which normalizes the color to the larg
 ``normalize`` is false and describes the range to what the colorrange is applied to. ``scale_vector_thickness`` is a boolean and changes
 the thickness scaling of the vectors and ``opacity`` is a float value that sets the opacity of the vectors.
 
+The ``ZnDraw``-object used for visualization is wrapped inside the visualizer object and is exposed by the attribute ``vis.zndraw``.
+
+When the ``jupyter`` visualization-window comes up as a blank page, make sure to allow third party cookies in your browser settings.
+
 An example code snippet containing the :class:`~espressomd.zn.LBField` object::
 
     import espressomd.zn

diff --git a/doc/tutorials/constant_pH/constant_pH.ipynb b/doc/tutorials/constant_pH/constant_pH.ipynb
@@ -153,6 +153,7 @@
     "import espressomd.electrostatics\n",
     "import espressomd.reaction_methods\n",
     "import espressomd.polymer\n",
+    "import espressomd.zn\n",
     "from espressomd.interactions import HarmonicBond"
    ]
   },
@@ -569,7 +570,7 @@
     "\n",
     "# add thermostat and short integration to let the system relax further\n",
     "system.thermostat.set_langevin(kT=KT_REDUCED, gamma=1.0, seed=7)\n",
-    "system.integrator.run(steps=1000)\n",
+    "system.integrator.run(1000)\n",
     "\n",
     "if USE_ELECTROSTATICS:\n",
     "    COULOMB_PREFACTOR=BJERRUM_LENGTH_REDUCED * KT_REDUCED\n",
@@ -739,6 +740,40 @@
    "outputs": [],
    "source": []
   },
+  {
+   "cell_type": "markdown",
+   "id": "cd417295-bab3-46a5-a574-fc60d06371a5",
+   "metadata": {},
+   "source": [
+    "We will initialize ZnDraw to visualize the simulation for increasing pH values:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "04dd303c",
+   "metadata": {
+    "scrolled": false
+   },
+   "outputs": [],
+   "source": [
+    "color = {TYPES[\"HA\"]: \"#7fc454\", #green\n",
+    "         TYPES[\"A\"]: \"#225204\", #dark green\n",
+    "         TYPES[\"B\"]: \"#fca000\", #orange\n",
+    "         TYPES[\"Na\"]: \"#ff0000\", #red\n",
+    "         TYPES[\"Cl\"]: \"#030ffc\" #blue\n",
+    "        }\n",
+    "radii = {TYPES[\"HA\"]: 2,\n",
+    "         TYPES[\"A\"]: 2,\n",
+    "         TYPES[\"B\"]: 2,\n",
+    "         TYPES[\"Na\"]: 2,\n",
+    "         TYPES[\"Cl\"]: 2\n",
+    "        }\n",
+    "\n",
+    "vis = espressomd.zn.Visualizer(system, colors=color, radii=radii)\n",
+    "vis.update()"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "07daa583",
@@ -778,11 +813,14 @@
    "outputs": [],
    "source": [
     "# SOLUTION CELL\n",
-    "def perform_sampling(type_A, num_samples, num_As:np.ndarray, reaction_steps, \n",
+    "def perform_sampling(type_A, num_samples, num_As:np.ndarray, reaction_steps,\n",
     "                     prob_integration=0.5, integration_steps=1000):\n",
     "    for i in range(num_samples):\n",
     "        if USE_WCA and np.random.random() < prob_integration:\n",
-    "            system.integrator.run(integration_steps)\n",
+    "            for _ in range(integration_steps):\n",
+    "                system.integrator.run(1)\n",
+    "            global vis\n",
+    "            vis.update()\n",
     "        # we should do at least one reaction attempt per reactive particle\n",
     "        RE.reaction(steps=reaction_steps)\n",
     "        num_As[i] = system.number_of_particles(type=type_A)"

diff --git a/doc/tutorials/electrodes/electrodes_part2.ipynb b/doc/tutorials/electrodes/electrodes_part2.ipynb
@@ -214,6 +214,7 @@
     "import espressomd.observables\n",
     "import espressomd.accumulators\n",
     "import espressomd.shapes\n",
+    "import espressomd.zn\n",
     "\n",
     "espressomd.assert_features(['WCA', 'ELECTROSTATICS'])\n",
     "rng = np.random.default_rng(42)\n",
@@ -476,20 +477,20 @@
    "source": [
     "# SOLUTION CELL\n",
     "offset = LJ_SIGMA # avoid unfavorable overlap at close distance to the walls\n",
-    "init_part_btw_z1 = offset \n",
+    "init_part_btw_z1 = offset\n",
     "init_part_btw_z2 = box_l_z - offset\n",
-    "ion_pos = np.empty((3), dtype=float)\n",
+    "ion_pos = np.empty((3,), dtype=float)\n",
     "\n",
-    "for i in range (N_IONPAIRS):\n",
-    "    ion_pos[0] = rng.random(1) * system.box_l[0]\n",
-    "    ion_pos[1] = rng.random(1) * system.box_l[1]\n",
-    "    ion_pos[2] = rng.random(1) * (init_part_btw_z2 - init_part_btw_z1) + init_part_btw_z1\n",
+    "for i in range(N_IONPAIRS):\n",
+    "    ion_pos[0] = rng.random(1)[0] * system.box_l[0]\n",
+    "    ion_pos[1] = rng.random(1)[0] * system.box_l[1]\n",
+    "    ion_pos[2] = rng.random(1)[0] * (init_part_btw_z2 - init_part_btw_z1) + init_part_btw_z1\n",
     "    system.part.add(pos=ion_pos, type=types[\"Cation\"], q=charges[\"Cation\"])\n",
-    "    \n",
-    "for i in range (N_IONPAIRS):\n",
-    "    ion_pos[0] = rng.random(1) * system.box_l[0]\n",
-    "    ion_pos[1] = rng.random(1) * system.box_l[1]\n",
-    "    ion_pos[2] = rng.random(1) * (init_part_btw_z2 - init_part_btw_z1) + init_part_btw_z1\n",
+    "\n",
+    "for i in range(N_IONPAIRS):\n",
+    "    ion_pos[0] = rng.random(1)[0] * system.box_l[0]\n",
+    "    ion_pos[1] = rng.random(1)[0] * system.box_l[1]\n",
+    "    ion_pos[2] = rng.random(1)[0] * (init_part_btw_z2 - init_part_btw_z1) + init_part_btw_z1\n",
     "    system.part.add(pos=ion_pos, type=types[\"Anion\"], q=charges[\"Anion\"])"
    ]
   },
@@ -1008,7 +1009,41 @@
     "\n",
     "With the above knowledge, we can now assess the \n",
     "differential capacitance of the system, by changing the applied voltage\n",
-    "difference and determining the corresponding surface charge density."
+    "difference and determining the corresponding surface charge density.\n",
+    "We will use ZnDraw to visualize our system:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "ef5d908f-a7f0-4845-9555-34822128c141",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "color = {\n",
+    "    types[\"Cation\"]: \"#ff0000\", #red\n",
+    "    types[\"Anion\"]: \"#030ffc\" #blue\n",
+    "    }\n",
+    "    \n",
+    "radii = {\n",
+    "    types[\"Cation\"]: LJ_SIGMA,\n",
+    "    types[\"Anion\"]: LJ_SIGMA\n",
+    "    }\n",
+    "\n",
+    "vis = espressomd.zn.Visualizer(system, colors=color, radii=radii)\n",
+    "#vis.draw_constraints([floor, ceiling])\n",
+    "\n",
+    "# note: you may need to zoom out since the ELC gap region takes a significant portion of\n",
+    "# the box along the non-periodic direction. The particles are only in the smaller subsystem.\n",
+    "# note: The particles are shown bigger for visualization purpose."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "21da58e8-e666-4d06-8538-a8d6af521148",
+   "metadata": {},
+   "source": [
+    "Do the sampling from high to low potential:"
    ]
   },
   {
@@ -1029,7 +1064,9 @@
     "for potential_diff in tqdm.tqdm(np.linspace(MIN_PHI, MAX_PHI, N_PHI)[::-1]):\n",
     "    system.auto_update_accumulators.clear()\n",
     "    system.electrostatics.solver = setup_electrostatic_solver(potential_diff)\n",
-    "    system.integrator.run(N_SAMPLES_EQUIL_CAP * STEPS_PER_SAMPLE)\n",
+    "    for i in range(N_SAMPLES_EQUIL_CAP * STEPS_PER_SAMPLE//50):\n",
+    "        system.integrator.run(50)\n",
+    "        vis.update()\n",
     "    sigmas = []\n",
     "\n",
     "    for tm in range(N_SAMPLES_CAP):\n",
@@ -1039,7 +1076,9 @@
     "        system.auto_update_accumulators.clear()\n",
     "        system.auto_update_accumulators.add(density_accumulator_cation)\n",
     "        system.auto_update_accumulators.add(density_accumulator_anion)\n",
-    "        system.integrator.run(STEPS_PER_SAMPLE)\n",
+    "        for j in range(int(STEPS_PER_SAMPLE/50)):\n",
+    "            system.integrator.run(50)\n",
+    "            vis.update()\n",
     "\n",
     "        cation_profile_mean = density_accumulator_cation.mean()[0, 0, :]\n",
     "        anion_profile_mean = density_accumulator_anion.mean()[0, 0, :]\n",