Merge remote-tracking branch 'origin/v2.x' into v2.x

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)

examples/README.md

@@ -3,8 +3,6 @@ In these folders you will find a lot of examples showcasing the different capabi
 
 UAMMD is presented with two distinct identities, it can work as a standalone molecular simulation GPU code (such as gromacs or hoomd) or as a library exposing GPU algorithms for you to use to accelerate your own code. Keep in mind that UAMMD is designed to be hackable and copy pastable, so feel free to take what you want and give nothing back!  
 
-The Makefile in this folder simply goes into each folder and runs the Makefiles there.  
-
 This folder is organized in the following way:  
 
 ### basic_concepts  
@@ -16,8 +14,7 @@ Stuff not covered by the basic tutorial with more complex and obscure functional
 
 ### generic_md  
 This code has almost every module that UAMMD offers in a single file that you can compile and then tweak via a data.main parameter file.  
-If you are not looking to learn how UAMMD works and how to modify it or extend it get in here.  
-You might be able to encode your simulation by tweaking the data.main.  
+If you are not looking to learn how UAMMD works and how to modify it or extend it get in here. You might be able to encode your simulation by tweaking the data.main.  
 
 ### integration_schemes  
 The basic tutorial covers only a couple of integration modules, in this folder you will find copy pastable functions to create any UAMMD Integrator. From Brownian Dynamics to Smoothed Particle Hydrodynamics.  
@@ -31,3 +28,27 @@ This family of examples shows off want you can do outside the UAMMD simulation e
 ### misc  
 Examples that do not fit in the other categories.  
 
+## Compiling the examples
+
+For convenience and learning purposes the examples can be compiled either with Make or CMake. This folder contains both a Makefile and a CMakeLists.txt.  
+
+I suggest using the CMake system, as it tends to be more robust regarding install locations of the different dependencies. When running cmake a Makefile will be generated.  
+
+To compile every example, run:  
+
+```bash
+	mkdir -p build
+	cd build
+	cmake ..
+	make -j3
+```
+
+Binaries for the examples will be available under the created `bin` folder.  
+
+Refer to [Compiling UAMMD](https://github.com/RaulPPelaez/UAMMD/wiki/Compiling-UAMMD) for additional information if the building process fails.  
+
+You can pass to CMake any UAMMD related definitions, for instance:  
+
+```shell
+cmake -DDOUBLE_PRECISION ..
+```

examples/generic_md/README.md

@@ -29,10 +29,8 @@ With this components as-is one can simulate systems from a microscale LJ-liquid
 
 
 ### USAGE  
-Compile with ```$ make```, you might have to customize the Makefile first to adapt it to your system.  
-If you are having trouble with it, start by going into [Compiling UAMMD](https://github.com/RaulPPelaez/UAMMD/wiki/Compiling-UAMMD)  
 
-Then execute ```$ ./generic```. If you have a valid CUDA environment this will generate an example data.main file and then halt.  
+After compiling, execute ```$ ./generic```. If you have a valid CUDA environment this will generate an example data.main file and then halt.  
 Modify this file as desired and then run ```$ ./generic``` again.  
 
 The default data.main will perform a LJ-liquid simulation with a VerletNVT integrator.  
@@ -50,11 +48,11 @@ If you need to create a BD integrator, you can copy paste the function createInt
 Need to read parameters from a file? just copy paste the function readParameters.  
 And so on.  
 
-If you would like a more bottom up approach to UAMMD, you can surf the examples/basic folder, which will give you through UAMMD with an increasingly complex set of example codes.  
-Additionally, you can drop by the wiki:   
-https://github.com/RaulPPelaez/UAMMD/wiki  
+If you would like a more bottom up approach to UAMMD, you can surf the `examples/basic_concepts` folder, which will give you through UAMMD with an increasingly complex set of example codes.  
+Additionally, you can drop by the docs:   
+https://uammd.readthedocs.io/  
 Which has a lot of information. From basic functionality to descriptions and references for the algorithms implemented by each module.    
 
 This code is an example on how to work inside UAMMD's simulation ecosystem, however UAMMD is not restricted to this kind of usage.  
 It is designed to be as hackable as possible and exposes a lot of the core functionality as stand alone with the intention of making it work as an external GPU accelerator in other codes.  
-See the folder examples/uammd_as_a_library for examples on how to do this.  
+See the folder `examples/uammd_as_a_library` for examples on how to do this.