Update particle access script

.devcontainer/Readme.md

@@ -0,0 +1,53 @@
+# ESPResSo in Codespaces
+
+## Creating a new codespace
+
+Direct link to the default codespace: https://codespaces.new/espressomd/espresso
+
+If you need to create a custom codespace, follow these instructions:
+
+* go to the ESPResSo repository, either the [official project](https://github.com/espressomd/espresso) or your forked project
+* follow the GitHub documentation on [Creating a codespace for a repository](https://docs.github.com/en/codespaces/developing-in-a-codespace/creating-a-codespace-for-a-repository#creating-a-codespace-for-a-repository)
+
+## Building ESPResSo
+
+General workflow:
+
+* load MPI module
+* build ESPResSo
+* create Python environment
+
+Command lines:
+
+```sh
+# load MPI module
+. /etc/profile.d/modules.sh
+module load mpi
+# build ESPResSo
+mkdir build
+cd build
+cmake .. -D ESPRESSO_BUILD_WITH_FFTW=ON -D ESPRESSO_BUILD_WITH_WALBERLA=ON
+make -j$(nproc)
+# create Python environment
+python -m venv --system-site-packages ESPResSo
+. ESPResSo/bin/activate
+realpath src/python > $(python -c 'import sysconfig;print(sysconfig.get_path("platlib"))')/espresso.pth
+pip install -c ../requirements.txt matplotlib pint pandas tqdm
+```
+
+## Running interactive notebooks
+
+Two options:
+
+* run tutorials from subfolder `doc/tutorials` in the top-level directory
+* run `make -j$(nproc) tutorials` to generate notebooks with hidden answers,
+  and then run tutorials from subfolder `build/doc/tutorials`
+
+The IDE needs to know which Python interpreter to use:
+
+* open the Command Palette with F1 (or click on the gears icon)
+* search for "Python: Set Project Environment"
+* hit "Browse"
+* paste `/workspaces/espresso/build/ESPResSo/bin/activate`
+
+When the IDE asks for the interpreter, select the `ESPResSo` environment.

.devcontainer/devcontainer.json

@@ -0,0 +1,26 @@
+{
+  "image": "ghcr.io/espressomd/docker/fedora:3388b293a5e8a9b613b1bfa4220e54dfb4bff245",
+  "customizations": {
+    "vscode": {
+      "settings": {
+        "workbench.editorAssociations": {
+            "*.md": "vscode.markdown.preview.editor"
+        }
+      },
+      "extensions": [
+        "ms-python.python",
+        "ms-python.vscode-pylance",
+        "ms-toolsai.jupyter",
+        "ms-toolsai.jupyter-keymap",
+        "ms-toolsai.jupyter-renderers"
+      ]
+    },
+    "codespaces": {
+      "openFiles": [
+        ".devcontainer/Readme.md",
+        "doc/tutorials/Readme.md"
+      ]
+    }
+  },
+  "features": {}
+}

.github/actions/build_and_check/action.yml

@@ -4,7 +4,7 @@ runs:
   using: "composite"
   steps:
     - run: |
-        export myconfig=maxset with_cuda=false with_gsl=false with_hdf5=false test_timeout=800 check_skip_long=true
+        export myconfig=maxset with_cuda=false with_hdf5=false test_timeout=800 check_skip_long=true
         if test -d venv; then . venv/bin/activate; fi
         bash maintainer/CI/build_cmake.sh
       shell: bash

.github/workflows/push_pull.yml

@@ -24,7 +24,7 @@ jobs:
       - name: Install dependencies
         run: |
          echo '' > Brewfile
-         for dep in boost boost-mpi fftw ccache ninja; do echo "brew \"${dep}\"" >> Brewfile; done
+         for dep in boost boost-mpi fftw gsl ccache ninja; do echo "brew \"${dep}\"" >> Brewfile; done
          brew bundle check >/dev/null 2>&1 || brew bundle --verbose --no-upgrade
          # set up Xcode compiler
          echo "::group::List available Xcode compilers"
@@ -51,6 +51,7 @@ jobs:
           cmake_params: '-D ESPRESSO_TEST_NP=3'
           with_ccache: 'true'
           with_fftw: 'true'
+          with_gsl: 'true'
           with_walberla: 'true'
           with_walberla_avx: 'false'
           with_shared_memory_parallelism: 'false'

CMakeLists.txt

@@ -221,6 +221,7 @@ endmacro()
 espresso_minimal_compiler_version("GNU" 12.2.0)
 espresso_minimal_compiler_version("Clang" 18.1.0)
 espresso_minimal_compiler_version("AppleClang" 17.0.0)
+espresso_minimal_compiler_version("CrayClang" 17.0.0)
 espresso_minimal_compiler_version("IntelLLVM" 2023.1)
 
 set(ESPRESSO_UNSUPPORTED_COMPILERS "Intel;MSVC")
@@ -588,7 +589,7 @@ if(ESPRESSO_BUILD_WITH_FFTW)
 endif()
 
 if(ESPRESSO_BUILD_WITH_SHARED_MEMORY_PARALLELISM)
-  find_package(OpenMP REQUIRED)
+  find_package(OpenMP REQUIRED COMPONENTS CXX)
 
   if(NOT EXISTS ${FETCHCONTENT_BASE_DIR}/kokkos-src)
     find_package(Kokkos 4.3 QUIET)

Readme.md

@@ -3,7 +3,7 @@
 [![GitLab CI](https://gitlab.icp.uni-stuttgart.de/espressomd/espresso/badges/python/pipeline.svg)](https://gitlab.icp.uni-stuttgart.de/espressomd/espresso/-/commits/python)
 [![codecov](https://codecov.io/gh/espressomd/espresso/branch/python/graph/badge.svg)](https://codecov.io/gh/espressomd/espresso)
 [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/jngrad/espresso-binder/HEAD)
-[![Contribute with Gitpod](https://img.shields.io/badge/Contribute%20with-Gitpod-908a85?logo=gitpod)](https://gitpod.io/#https://github.com/espressomd/espresso)
+[![Open in GitHub Codespaces](https://img.shields.io/badge/launch-Codespaces-579aca?logo=github)](https://codespaces.new/espressomd/espresso)
 
 This is the Molecular Dynamics software ESPResSo ("Extensible
 Simulation Package for Research on Soft Matter Systems").
@@ -86,9 +86,9 @@ Common installation issues are addressed in the
 [FAQ](https://github.com/espressomd/espresso/wiki/Installation-FAQ),
 together with contributed patches for compiler-related and library-related issues.
 
-You can also try ESPReSSo in the cloud using
+You can also try ESPResSo in the cloud using
 [Binder](https://mybinder.org/v2/gh/jngrad/espresso-binder/HEAD) or
-[Gitpod](https://gitpod.io/#https://github.com/espressomd/espresso).
+[Codespaces](https://codespaces.new/espressomd/espresso).
 
 ### Join the community
 

doc/bibliography.bib

@@ -719,6 +719,16 @@ @Article{johnson94a
   publisher = {Taylor \& Francis},
 }
 
+@InProceedings{jupyter18a,
+  author    = {{Project Jupyter} and Bussonnier, Matthias and Forde, Jessica and Freeman, Jeremy and Granger, Brian and Head, Tim and Holdgraf, Chris and Kelley, Kyle and Nalvarte, Gladys and Osheroff, Andrew and Pacer, M and Panda, Yuvi and Perez, Fernando and Ragan-Kelley, Benjamin and Willing, Carol},
+  title     = {{Binder}~2.0 - Reproducible, interactive, sharable environments for science at scale},
+  booktitle = {Proceedings of the 17\textsuperscript{th} Python in Science Conference},
+  year      = {2018},
+  editor    = {Akici, Fatih and Lippa, David and Niederhut, Dillon and Pacer, M},
+  pages     = {113--120},
+  doi       = {10.25080/Majora-4af1f417-011},
+}
+
 @Article{kesselheim11a,
   author = {Kesselheim, Stefan and Sega, Marcello and Holm, Christian},
   title = {Applying {ICC}* to {DNA} translocation. {E}ffect of dielectric boundaries},

doc/sphinx/constraints.rst

@@ -80,7 +80,7 @@ invoke the :meth:`~espressomd.constraints.Constraints.add` method::
 All previously listed shapes can be added to the system constraints
 by passing an initialized shape object to :meth:`~espressomd.constraints.Constraints.add`, returning a constraint object ::
 
-    misshaped = Wall(dist=20, normal=[0.1, 0.0, 1])
+    myShape = Wall(dist=20, normal=[0.1, 0.0, 1])
     myConstraint = system.constraints.add(shape=myShape, particle_type=p_type)
 
 The extra argument ``particle_type`` specifies the non-bonded interaction to be used with
@@ -169,17 +169,10 @@ initial configurations.
 Available shapes
 ^^^^^^^^^^^^^^^^
 
-:class:`espressomd.shapes`
+:mod:`espressomd.shapes`
 
-Python syntax::
-
-    import espressomd.shapes
-    shape = espressomd.shapes.<SHAPE>
-
-``<SHAPE>`` can be any of the available shapes.
-
-The surface's geometry is defined via a few available shapes.
-The following shapes can be used as constraints.
+A shape-based constraint surface's geometry is defined by a shape object,
+or by a collection thereof (:ref:`Shape union`).
 
 .. warning::
    When using shapes with concave edges and corners, the fact that a particle
@@ -210,6 +203,17 @@ Pictured is an example constraint with a ``Wall`` shape created with ::
     wall = Wall(dist=20, normal=[0.1, 0.0, 1])
     system.constraints.add(shape=wall, particle_type=0)
 
+When placing two non-penetrable parallel walls in a box, e.g. to simulate a plate capacitor,
+their normal vectors must be collinear but opposite in direction.
+The distance calculation is affected by the sign of the normal vector, like so::
+
+    # two parallel plates oriented such that particles can only be found
+    # on the z-axis in the range [1.5, box_l - 1.5]
+    system.constraints.add(shape=espressomd.shapes.Wall(
+        normal=[0, 0, +1], dist=1.5), particle_type=1)
+    system.constraints.add(shape=espressomd.shapes.Wall(
+        normal=[0, 0, -1], dist=-(system.box_l - 1.5)), particle_type=1)
+
 For penetrable walls, if the ``only_positive`` flag is set to ``True``, interactions
 are only calculated if the particle is on the side of the wall in which the
 normal vector is pointing.
@@ -463,6 +467,8 @@ Note: in the OpenGL visualizer, if the OpenGL Extrusion library is not available
 the shape surface will be rendered with dots.
 
 
+.. _Shape union:
+
 Union
 """""
 
@@ -471,7 +477,6 @@ Union
 A meta-shape which is the union of given shapes. Note that only the regions where
 all shapes have a "positive distance" (see :ref:`Available options`) can be used for the
 union. The distance to the union is defined as the minimum distance to any contained shape.
-This shape cannot be checkpointed when multiple MPI ranks are used.
 
 
 .. _Available options:

doc/sphinx/electrostatics.rst

@@ -67,6 +67,12 @@ Coulomb P3M
 
 :class:`espressomd.electrostatics.P3M`
 
+.. note::
+
+    Requires feature ``ELECTROSTATICS`` and
+    external feature ``FFTW``, enabled with
+    ``-D ESPRESSO_BUILD_WITH_FFTW=ON``.
+
 For this feature to work, you need to have the ``fftw3`` library
 installed on your system. In |es|, you can check if it is compiled in by
 checking for the feature ``FFTW`` with ``espressomd.features``.
@@ -115,6 +121,12 @@ Coulomb P3M on GPU
 
 :class:`espressomd.electrostatics.P3MGPU`
 
+.. note::
+
+    Requires feature ``ELECTROSTATICS`` and
+    external features ``FFTW`` and ``CUDA``, enabled with
+    ``-D ESPRESSO_BUILD_WITH_FFTW=ON -D ESPRESSO_BUILD_WITH_CUDA=ON``.
+
 The GPU implementation of P3M calculates the far field contribution to the
 forces on the GPU. The near-field contribution to the forces, as well as the
 near- and far-field contributions to the energies are calculated on the CPU.
@@ -136,6 +148,10 @@ Debye-Hückel potential
 
 :class:`espressomd.electrostatics.DH`
 
+.. note::
+
+    Requires feature ``ELECTROSTATICS``.
+
 The Debye-Hückel electrostatic potential is defined by
 
 .. math:: U^{C-DH} = C \cdot \frac{q_1 q_2 \exp(-\kappa r)}{r}\quad \mathrm{for}\quad r<r_{\mathrm{cut}}
@@ -157,6 +173,10 @@ Reaction Field method
 
 :class:`espressomd.electrostatics.ReactionField`
 
+.. note::
+
+    Requires feature ``ELECTROSTATICS``.
+
 The Reaction Field electrostatic potential is defined by
 
 .. math:: U^{C-RF} = C \cdot q_1 q_2 \left[\frac{1}{r} - \frac{B r^2}{2r_{\mathrm{cut}}^3} - \frac{1 - B/2}{r_{\mathrm{cut}}}\right] \quad \mathrm{for}\quad r<r_{\mathrm{cut}}
@@ -181,6 +201,10 @@ Dielectric interfaces with the ICC\ :math:`\star` algorithm
 
 :class:`espressomd.electrostatic_extensions.ICC`
 
+.. note::
+
+    Requires feature ``ELECTROSTATICS``.
+
 The ICC\ :math:`\star` algorithm allows to take into account arbitrarily shaped
 dielectric interfaces and dynamic charge induction. For instance, it can be
 used to simulate a curved metallic boundary. This is done by iterating the
@@ -269,6 +293,10 @@ Electrostatic Layer Correction (ELC)
 
 :class:`espressomd.electrostatics.ELC`
 
+.. note::
+
+    Requires feature ``ELECTROSTATICS``.
+
 *ELC* is an extension of the P3M electrostatics solver for explicit 2D periodic
 systems. It can account for different dielectric jumps on both sides of the
 non-periodic direction. In more detail, it is a special procedure that
@@ -340,6 +368,12 @@ MMM1D
 
 :class:`espressomd.electrostatics.MMM1D`
 
+.. note::
+
+    Requires feature ``ELECTROSTATICS`` and
+    external feature ``GSL``, enabled with
+    ``-D ESPRESSO_BUILD_WITH_GSL=ON``.
+
 Please cite :cite:`arnold05b` when using MMM1D. See :ref:`MMM1D theory` for
 the details.
 
@@ -370,6 +404,12 @@ ScaFaCoS electrostatics
 
 :class:`espressomd.electrostatics.Scafacos`
 
+.. note::
+
+    Requires feature ``ELECTROSTATICS`` and
+    external feature ``SCAFACOS``, enabled with
+    ``-D ESPRESSO_BUILD_WITH_SCAFACOS=ON``.
+
 |es| can use the methods from the ScaFaCoS *Scalable fast Coulomb solvers*
 library. The specific methods available depend on the compile-time options of
 the library, and can be queried with