Installation#

Prerequisites#

  • Python 3.7 or later

  • Basic familiarity with command-line operations

  • Basic familiarity with virtual environments (Conda or pip)

  • If using pip, a working MPI implementation with headers and a C compiler.

Installing#

To avoid conflicts with existing Python setups, install RockVerse in a dedicated virtual environment.

If you’re unfamiliar with virtual environments, refer to:

In this guide, the virtual environment is named rockverse-env.

Note

Choose either Conda or pip for the installation process. Using pip requires a working MPI implementation with headers and a C compiler. Ensure mpicc and mpiexec or mpirun point to the desired MPI installation. If MPI or a C compiler is unavailable, Conda is recommended.

1. Create a Virtual Environment#

Update Conda (optional but recommended). Ensure you’re using Conda 23.10 or later for improved speed:

conda update -n base conda

Create and activate the environment:

conda create --name rockverse-env
conda activate rockverse-env

Create and activate a virtual environment:

On Windows:

cd path\to\my\environment
python -m venv rockverse-env
.\rockverse-env\Scripts\activate

On Linux/macOS (bash example):

cd path/to/my/environment
python -m venv rockverse-env
source ./rockverse-env/bin/activate

2. Install Scipy#

Test if you have a C compiler properly installed. Try to install Scipy in the environment.

conda install -c conda-forge "scipy<=1.13.1"

pip install "scipy<=1.13.1"

If you get errors using pip, you must install a C compiler or use Conda for the installation process.

3. Configure MPI#

If you lack a system MPI installation, use one of the MPI implementations available on conda-forge. This step requires the Conda environment.

Installs Open MPI with command-line executable mpirun:

conda install -c conda-forge openmpi

Installs MPICH with command-line executable mpiexec:

conda install -c conda-forge mpich

Installs Intel MPI with both command-line executables mpirun and mpiexec:

conda install -c conda-forge impi_rt

Installs Microsoft MPI and command-line executable mpiexec:

conda install -c conda-forge msmpi

If you prefer a system-installed MPI (e.g., on cluster computers), ensure mpicc and mpirun or mpiexec point to the correct installation.

Now install mpi4py:

conda install -c conda-forge mpi4py

pip install --no-cache-dir mpi4py

Test your MPI installation:

mpirun -n 5 python -m mpi4py.bench helloworld

mpiexec -n 5 python -m mpi4py.bench helloworld

You should get an output similar to this (‘localhost’ will be replaced by the hostname in your machine):

Hello, World! I am process 0 of 5 on localhost.
Hello, World! I am process 1 of 5 on localhost.
Hello, World! I am process 2 of 5 on localhost.
Hello, World! I am process 3 of 5 on localhost.
Hello, World! I am process 4 of 5 on localhost.

4. Install RockVerse#

Install RockVerse and its dependencies

conda install -c conda-forge rockverse

pip install rockverse

pip install git+https://github.com/rodolfovictor/rockverse.git

git clone https://github.com/rodolfovictor/rockverse.git
cd rockverse
pip install -e .

5. (Optional) Configure Numba access to GPUs#

RockVerse supports accelerated computations on CUDA-enabled GPUs using Numba. Multiple GPUs can be utilized simultaneously through RockVerse’s MPI-based distribution strategies. By default, RockVerse prioritizes GPU devices when available. To enable GPU support, ensure that:

  1. You have CUDA-capable hardware and drivers installed. Refer to Numba’s CUDA documentation for hardware compatibility.

  2. Install the appropriate CUDA toolkit:

Install CUDA 12 support:

conda install -c conda-forge cuda-nvcc cuda-nvrtc "cuda-version>=12.0"

Install CUDA 11 toolkit:

conda install -c conda-forge cudatoolkit "cuda-version>=11.2,<12.0"

Install NVIDIA bindings:

pip install cuda-python

Set environment variables:

export NUMBA_CUDA_USE_NVIDIA_BINDING="1"  # Linux
set NUMBA_CUDA_USE_NVIDIA_BINDING="1"     # Windows

Test Numba’s GPU detection:

python -c "from numba import cuda; print(cuda.is_available())"

If the output is True, you can list the devices running

python -c "from numba import cuda; print([d.name for d in cuda.gpus])"

Updating RockVerse#

conda update -c conda-forge rockverse

pip install --upgrade rockverse

pip install --upgrade git+https://github.com/rodolfovictor/rockverse.git

Just pull the last updates from Github:

cd /path/to/local/rockverse/git/repository
git pull

Troubleshooting#

If you encounter build issues with Pandoc, try reinstalling from Conda:

pip uninstall pandoc
conda install pandoc