Merge branch 'RaulPPelaez:v2.x' into v2.x

.github/workflows/ci.yml

@@ -2,9 +2,9 @@ name: CI
 
 on:
   push:
-    branches: [ v2.x ]
+    branches: [ master, v2.x ]
   pull_request:
-    branches: [ v2.x ]
+    branches: [ master, v2.x ]
   schedule:
     # Run every Sunday at midnight
     - cron:  '0 0 * * 0'
@@ -25,45 +25,72 @@ jobs:
           # Oldest supported versions
           - name: Linux (CUDA 10.2)
             cuda: "10.2.89"
-            gcc: "8.5.*"
-            nvcc: "10.2"
+            gcc: "7.*"
+            cuda12: 'false'
 
           # Latest supported versions
-          - name: Linux (CUDA 11.8)
-            cuda: "11.8.0"
-            gcc: "10.3.*"
-            nvcc: "11.8"
-
+          - name: Linux (CUDA 12)
+            cuda: "12.*"
+            gcc: "11.*"
+            cuda12: 'true'
     steps:
     - name: Check out
       uses: actions/checkout@v2
-
-    - name: Install Mamba
-      uses: mamba-org/provision-with-micromamba@main
-      with:
-        environment-file: false
-        extra-specs: ""
-        cache-env: true
-        cache-downloads: true
+    - name: Manage disk space
+      run: |
+          sudo mkdir -p /opt/empty_dir || true
+          for d in \
+                   /opt/ghc \
+                   /opt/hostedtoolcache \
+                   /usr/lib/jvm \
+                   /usr/local/.ghcup \
+                   /usr/local/lib/android \
+                   /usr/local/share/powershell \
+                   /usr/share/dotnet \
+                   /usr/share/swift \
+                   ; do
+            sudo rsync --stats -a --delete /opt/empty_dir/ $d || true
+          done
+          sudo apt-get purge -y -f firefox \
+                                   google-chrome-stable \
+                                   microsoft-edge-stable gcc
+          sudo apt-get autoremove -y >& /dev/null
+          sudo apt-get autoclean -y >& /dev/null
+          sudo docker image prune --all --force
+          df -h
 
     - name: Install CUDA Toolkit
+      # CUDA 12 can be installed with mamba
+      if: ${{ matrix.cuda12 == 'false' }}
       uses: Jimver/[email protected]
       with:
         cuda: ${{ matrix.cuda }}
-        linux-local-args: '["--toolkit", "--override"]' 
+        linux-local-args: '["--toolkit", "--override"]'
 
-    - name: Prepare dependencies
+    - name: Prepare dependencies (CUDA <12)
+      if: ${{ matrix.cuda12 == 'false'}}
       run: |
-        sed -i -e "/cudatoolkit/c\  - cudatoolkit ${{ matrix.cuda }}" \
-               -e "/gxx_linux-64/c\  - gxx_linux-64 ${{ matrix.gcc }}" \
-               -e "/nvcc_linux-64/c\  - nvcc_linux-64 ${{ matrix.nvcc }}" \
+        sed -i -e "/cuda-version/d" \
+               -e "/cuda-libraries-dev/d" \
+               -e "/cuda-nvcc/d" \
+               -e "/gxx_linux-64/c\  - gxx_linux-64 ${{ matrix.gcc }}\n  - gcc_linux-64" \
                environment.yml
 
+    - name: Prepare dependencies (CUDA >=12)
+      if: ${{ matrix.cuda12 == 'true' }}
+      run: |
+        sed -i -e "/cuda-version/c\  - cuda-version ${{ matrix.cuda }}" \
+               -e "/gxx_linux-64/c\  - gxx_linux-64 ${{ matrix.gcc }}" \
+               environment.yml
     - name: Show dependency file
       run: cat environment.yml
-
-    - name: Install dependencies
-      run: micromamba env create -n uammd -f environment.yml
+
+    - name: Install Mamba
+      uses: mamba-org/setup-micromamba@v1
+      with:
+        environment-file: environment.yml
+        cache-environment: false
+        cache-downloads: true
       env:
         CONDA_OVERRIDE_CUDA: ${{ matrix.nvcc }}
 

.github/workflows/docs.yaml

@@ -0,0 +1,24 @@
+name: Build Documentation
+
+on:
+  push:
+    branches: [ master, v2.x ]
+  pull_request:
+    branches: [ master, v2.x ]
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Install docs dependencies
+      run: |
+        pip install -r docs/requirements.txt
+      shell: bash -el {0}
+
+    - name: Build Sphinx Documentation
+      run: |
+        cd docs
+        make html
+      shell: bash -el {0}

.readthedocs.yaml

@@ -0,0 +1,17 @@
+
+version: 2
+
+build:
+  os: "ubuntu-22.04"
+  tools:
+    python: "3.11"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+
+formats:
+   - pdf

README.md

@@ -9,13 +9,8 @@
 **See the wiki for more info!**  
 **You can find videos on the youtube channel**  http://bit.ly/2r5WoOn
 
-## DESCRIPTION  
-
 -----------------  
 
-Raul P. Pelaez 2018-2022. (raul.perez(at)uam.es)  
-
-
 A C++14+ header-only fast generic multiscale CUDA Molecular Dynamics framework made with moduarity, expandability and generality in mind. UAMMD is intended to be hackable and copy pastable.  
 
 Although "Molecular Dynamics" is part of the name,the UAMMD framework allows for much more than that. To this moment multiple integrators are implemented allowing it to perform:  
@@ -42,15 +37,40 @@ Hop on to the examples folder for an introduction or check the [documentation](h
 See the documentation page at https://uammd.readthedocs.io for a full list of available modules.  
 
 ----------------------
-## USAGE
+## Usage
 
 -------------------
 
+You can use UAMMD as a library for integration into other codes or as a standalone engine.
+
+#### DEPENDENCIES  
+
+---------------------
+Depends on:
+
+	1. CUDA 9.x+                                :   https://developer.nvidia.com/cuda-downloads
+
+Some modules make use of certain NVIDIA libraries included with CUDA:
+
+	1. cuBLAS
+	2. cuFFT
+
+Some modules also make use of lapacke and cblas (which can be replaced by mkl).  
+Apart from this, any dependency is already included in the repository under the third_party	folder.  
+See [Compiling UAMMD](https://uammd.readthedocs.io/en/latest/Compiling-UAMMD.html) in the documentation for more information.  
+
+Every required dependency can be installed using conda with the environment file provided in the repository. We recommend using [mamba](https://mamba.readthedocs.io/en/latest/installation/mamba-installation.html) as a replacement for conda.  
+
+```bash
+mamba env create -f environment.yml
+```
+
+### Library mode
+
 **UAMMD does not need to be compiled separatedly (it is header only)**.  
 
 Some special flags might be needed to compile codes including with certain UAMMD headers, see [Compiling UAMMD](https://uammd.readthedocs.io/en/latest/Compiling-UAMMD.html).  
-Here you have a short example of how a typical UAMMD code looks like:  
-
+Here you have a short example of how a typical UAMMD code looks like, encoding a simple Brownian dynamics simulation of non interacting particles.:  
 
 ```c++
 //Ideal brownian particles
@@ -79,23 +99,40 @@ int main(int argc, char * argv[]){
 
 ```
 
-Drop by the examples folder to get started with UAMMD or go to the [wiki](https://uammd.readthedocs.io/).  
+Drop by the examples folder to get started with UAMMD or go to the [documentation page for the examples](https://uammd.readthedocs.io/en/latest/Examples.html).  
+
+### Stand alone engine
+
+The example `generic_md` includes almost every module available in UAMMD and can be configured from a parameter file. Go to `examples/generic_md` for instructions.
 
-## DEPENDENCIES  
+## Running Tests  
 
 ---------------------
-Depends on:
 
-	1. CUDA 9.x+                                :   https://developer.nvidia.com/cuda-downloads
+The `tests` folder contains instructions on how to run the UAMMD correctness tests. You can also go to the [documentation page for tests](https://uammd.readthedocs.io/en/latest/Tests.html).
 
-Some modules make use of certain NVIDIA libraries included with CUDA:
-	
-	1. cuBLAS
-	2. cuFFT
-	
-Some modules also make use of lapacke and cblas (which can be replaced by mkl).  
-Apart from this, any dependency is already included in the repository under the third_party	folder.  
-See [Compiling UAMMD](https://uammd.readthedocs.io/en/latest/Compiling-UAMMD.html) in the documentation for more information.  
+
+## Repository structure  
+
+-------------------------
+
+- The `docs` folder contains the documentation source files for [](https://uammd.readthedocs.io/) and scripts to build it.
+
+- The `examples` folder contains several examples of UAMMD usage.
+
+- The `src` folder contains the source code for UAMMD. Inside it, there are the following folders:
+1. `global`: Definitions proper to the whole code.
+2. `Integrator`: Source code for the [integrators](https://uammd.readthedocs.io/en/latest/Integrators.html).
+3. `Interactor`: Source code for the [interactors](https://uammd.readthedocs.io/en/latest/Interactors.html).
+4. `misc`: Miscellaneous source code.
+5. `ParticleData`: Source code for [particle data](https://uammd.readthedocs.io/en/latest/ParticleData.html).
+6. `System`: Source code for [system](https://uammd.readthedocs.io/en/latest/System.html).
+7. `third_party`: Third party source code.
+8. `utils`: Utilities for UAMMD.
+
+- The `test` folder contains the source code for the UAMMD tests.
+
+- The `extensions` is part of the subsystem for UAMMD extensions, currently a work in progress.
 
 ------------------------------------------
 
@@ -112,7 +149,8 @@ Raul P. Pelaez is the main developer of UAMMD.
 Other people that have contributed to UAMMD (thanks!):  
 
 Marc Melendez Schofield  
+Pablo Ibañez Freire (https://github.com/PabloIbannez)  
+Pablo Palacios Alonso (http://github.com/PabloPalaciosAlonso) 
 Sergio Panzuela  
 Nerea Alcazar  
-Pablo Ibañez Freire (https://github.com/PabloIbannez)  
 Salvatore Assenza

docs/Compiling-UAMMD.rst

@@ -7,14 +7,16 @@ UAMMD is header-only, so a module is compiled only when its header is included.
 
   #. CUDA 8.0+  (https://developer.nvidia.com/cuda-downloads )  
   #. A C++ compiler with C++14 support (g++ 5+ will probably do)  
-  #. Thrust (The version shipped with the cuda release will do)  
   #. LAPACKE/CBLAS or Intel MKL (For some modules only)  
 
 The newest compiler versions I have tested are g++-12.x and clang++-13.0 with cuda-12 in Fedora 37.  You can even compile a source containing UAMMD code with clang++-7+ alone, without nvcc.
 
+**These dependencies can be installed using conda with the provided environment.yaml file.**
+
 Additionally, UAMMD makes use of the following external libraries, **which are already included in the repo under third_party**. You can either compile using these or place symlinks to your preferred versions (I have seen recent versions of cub not compiling on some platforms).  
 
-  * Boost Preprocessor (http://www.boost.org/ ) (Extracted using bcp, just a few headers)  
+  * Boost Preprocessor (http://www.boost.org/ ) (Extracted using bcp, just a few headers)
+  * Thrust (https://github.com/thrust/thrust )
   * CUB 1.5.2+ (https://github.com/NVlabs/cub ) (Currently 1.8.0 in third_party/cub_bak*)  
   * nod (https://github.com/fr00b0/nod ) (A lightweight C++11 signal/slot library)
   * SaruPRNG (http://dx.doi.org/10.1016/j.cpc.2012.12.003 ) (A parallel friendly RNG)

docs/Integrator/BrownianHydrodynamics.rst

@@ -989,8 +989,26 @@ In addition to the previous ones, the integrator also requires:
    Both the solver and Integrator will fail if some particle lies beyond the domain limits in the z direction.
 
 
+Computing average velocity in the plane directions
+**************************************************
 
+The class :code:`DPStokesSlab_ns::DPStokes` can also be used to compute the average velocity of a group of particles in the plane directions.
 
+
+.. cpp:function:: template<class PosIterator, class ForceIterator> std::vector<double> DPStokes::computeAverageVelocity(PosIterator pos, ForceIterator forces, int numberParticles, int direction = 0, cudaStream_t st = 0)
+
+
+   Computes the average velocity :math:`\langle v(z) \rangle_{x/y}` a group of particles in the plane directions.
+
+   :param PosIterator pos: Iterator to the positions of the particles.
+   :param ForceIterator forces: Iterator to the forces acting on the particles.
+   :param int numberParticles: Number of particles.
+   :param int direction: Direction of the average velocity. 0 for x, 1 for y.
+   :param cudaStream_t st: CUDA stream where the computation will be performed.
+   :returns: A vector with the average velocity (size n.z).
+
+
+
 .. rubric:: References:
 
 .. [1] An Introduction to Dynamics of Colloids. Dhont, J.K.G. 1996. https://www.elsevier.com/books/an-introduction-to-dynamics-of-colloids/dhont/978-0-444-82009-9

docs/Tests.rst

@@ -3,14 +3,15 @@ Tests
 
 The folder "test" in the main UAMMD repository contains test scripts for the different solvers. Mostly these consist on a bash script accompanied by a readme and an UAMMD code reproducing a certain known solution. The test script will typically generate messages stating the result of the tests in addition to some figures that can be inspected to evaluate the correctness of the solver.
 
-In order to run them simply go into the folder of a certain test and run :code:`bash test.bash`. Note that these tests can typically take a lot of time, as averaging is required. Check the test script for a certain solver for more information and customization. You may have to tweak the Makefiles. Finally, test scripts usually include the possibility of using many GPUs.
+In order to run them go into the folder of a certain test and run :code:`bash test.bash`. Note that these tests can typically take a lot of time, as averaging is required. Check the test script for a certain solver for more information and customization. You may have to tweak the Makefiles. Finally, test scripts usually include the possibility of using many GPUs.
 
-Recent Unit Tests are written using `GTest <https://google.github.io/googletest/primer.html>`. In these instances a CMakeLists.txt file is present. To compile and run the tests use the standard steps:
+Recent Unit Tests are written using `GTest <https://google.github.io/googletest/primer.html>`_. In these instances a CMakeLists.txt file is present. To compile and run the tests use the standard steps:
 
 .. code:: bash
 
 	  mkdir build && cd build
 	  cmake ..
 	  #Solve any dependency issues raised by CMake
-	  make 
 	  make test
+
+Note that some tests are stochastic in nature and can thus fail intermittently. Typically rerunning these tests solves the issue.

environment.yml

@@ -1,12 +1,13 @@
+name: uammd
 channels:
   - conda-forge
 dependencies:
   - cmake >=3.22
-  - cudatoolkit 11.8.*
-  - gxx_linux-64 10.3.*
+  - cuda-version 12.*
+  - gxx_linux-64 11.*
+  - cuda-libraries-dev
+  - cuda-nvcc 
   - make
-  - nvcc_linux-64 11.8
-  - sysroot_linux-64 2.17
   - mkl-devel
   - pybind11
-  - python 3.10.*
+  - python 3.11.*