Installation#
Prerequisites#
Python 3.7 or later
Basic familiarity with command-line operations
Basic familiarity with virtual environments (Conda or pip)
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 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. Configure MPI#
If you lack a system MPI installation, use one of the MPI implementations available on conda-forge. This step requires a 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 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.
3. Install RockVerse#
Install RockVerse and its dependencies (this might take a while…)
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 .
4. (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:
You have CUDA-capable hardware and drivers installed. Refer to Numba’s CUDA documentation for hardware compatibility.
Install the appropriate CUDA toolkit:
Install CUDA 12 support:
conda install -c conda-forge cuda-nvcc cuda-nvrtc
Install CUDA 11 toolkit:
conda install -c conda-forge cudatoolkit
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/installation
git pull
Troubleshooting#
If you encounter build issues with Pandoc, try reinstalling from Conda:
pip uninstall pandoc
conda install pandoc