Add tutorial on GCMC

doc/tutorials/CMakeLists.txt

@@ -115,6 +115,7 @@ add_subdirectory(ferrofluid)
 add_subdirectory(constant_pH)
 add_subdirectory(widom_insertion)
 add_subdirectory(electrodes)
+add_subdirectory(grand_canonical_monte_carlo)
 
 configure_file(Readme.md ${CMAKE_CURRENT_BINARY_DIR} COPYONLY)
 configure_file(convert.py ${CMAKE_CURRENT_BINARY_DIR})

doc/tutorials/Readme.md

@@ -69,7 +69,9 @@ physical systems.
 * **Widom particle insertion method**  
   Measuring the excess chemical potential of a salt solution using the Widom particle insertion method.  
   [Guide](widom_insertion/widom_insertion.ipynb)
-
+* **Grand-Canonical Monte Carlo**
+  Simulating a polyelectrolyte solution coupled to a reservoir of salt.
+  [Guide](grand_canonical_monte_carlo/grand_canonical_monte_carlo.ipynb)
 
 [comment]: # (End of tutorials landing page)
 

doc/tutorials/constant_pH/constant_pH.ipynb

@@ -1119,7 +1119,7 @@
    "hash": "31f2aee4e71d21fbe5cf8b01ff0e069b9275f58929596ceb00d14d90e3e16cd6"
   },
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -1133,7 +1133,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.10"
+   "version": "3.10.6"
   }
  },
  "nbformat": 4,

doc/tutorials/grand_canonical_monte_carlo/CMakeLists.txt

@@ -0,0 +1,26 @@
+#
+# Copyright (C) 2023 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/>.
+#
+
+configure_tutorial_target(
+  TARGET tutorial_grand_canonical_monte_carlo DEPENDS
+  grand_canonical_monte_carlo.ipynb figures/schematic.svg)
+
+nb_export(TARGET tutorial_grand_canonical_monte_carlo SUFFIX "" FILE
+          "grand_canonical_monte_carlo.ipynb" HTML_RUN VAR_SUBST
+          "\"p3m_params={'mesh':10,'cao':6,'r_cut':8.22}\"")

doc/tutorials/grand_canonical_monte_carlo/NotesForTutor.md

@@ -0,0 +1,14 @@
+# Notes for Tutors: Grand-Canonical Monte Carlo
+
+## Physics learning goals
+
+After the tutorial, students should be able to explain:
+
+* what the grand-canonical ensemble is and where it is applicable
+* how to simulate in the grand-canonical ensemble using GCMC
+
+## ESPResSo learning goals
+
+In the course of this tutorial, students should learn to:
+
+* to set up a GCMC simulation in ESPResSo

testsuite/scripts/tutorials/CMakeLists.txt

@@ -65,6 +65,7 @@ tutorial_test(FILE test_electrodes_1.py)
 # tutorial_test(FILE test_electrodes_2.py) # TODO: unstable, see issue #4798
 tutorial_test(FILE test_constant_pH__interactions.py)
 tutorial_test(FILE test_widom_insertion.py)
+tutorial_test(FILE test_grand_canonical_monte_carlo.py)
 
 add_custom_target(
   check_tutorials

testsuite/scripts/tutorials/test_grand_canonical_monte_carlo.py

@@ -0,0 +1,44 @@
+#
+# Copyright (C) 2023 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/>.
+#
+
+import unittest as ut
+import importlib_wrapper
+import numpy as np
+
+tutorial, skipIfMissingFeatures = importlib_wrapper.configure_and_import(
+    "@TUTORIALS_DIR@/grand_canonical_monte_carlo/grand_canonical_monte_carlo.py",
+    p3m_params={"mesh": 10, "cao": 6, "r_cut": 8.22})
+
+
+@skipIfMissingFeatures
+class Tutorial(ut.TestCase):
+
+    def test(self):
+        ratios = tutorial.c_monomer.magnitude / \
+            (2. * tutorial.salt_concentration_si.magnitude)
+        ref_xi = tutorial.analytical_solution(ratios)
+        sim_xi_minus = tutorial.partition_coefficients_negatives_array
+        sim_xi_plus = tutorial.universal_partion_coefficient_positive
+        np.testing.assert_allclose(
+            sim_xi_minus, sim_xi_plus, rtol=1e-5, atol=1e-5)
+        np.testing.assert_allclose(sim_xi_minus / ref_xi, 2., rtol=0., atol=2.)
+
+
+if __name__ == "__main__":
+    ut.main()