Start using Ranx

Requirements¶

• C++ compiler supporting the C++17 standard (e.g. GCC 9.3 or higher)
• CMake version 3.21 or higher.

And the following optional third-party libraries:

• Catch2 v3.1 or higher for unit testing
• Google Benchmark for benchmarks

The CMake script configured in a way that if it cannot find the optional third-party libraries it tries to fetch and build them automatically. So, there is no need to do anything if they are missing but you need an internet connection for that to work.

Building from source¶

Once you have all the requirements you can build and install it using the following commands:

git clone https://github.com/arminms/ranx.git
cd ranx
cmake -S . -B build && cmake --build build
cmake --install build

cd build && ctest

cd build && perf/benchmarks --benchmark_counters_tabular=true

Developing with Ranx¶

To start using Ranx in your code, you just need to include the header:

#include <ranx/random>

That will also include all the engines and the distributions that come with it.

Ranx exports four (namespaced) CMake targets and also CMake config scripts for downstream applications:

• ranx::cuda
• ranx::oneapi
• ranx::openmp
• ranx::rocm

Linking against them adds the proper include paths and links your target with proper libraries depending on the API. This means if your project also relies on CMake and Ranx has been installed on your system, a better option is to use find_package() in your project’s CMakeLists.txt as shown below:

find_package(ranx CONFIG COMPONENTS openmp cuda)

# link test.cpp with ranx using OpenMP API
add_executable(test_openmp test.cpp)
target_link_libraries(test_openmp PRIVATE ranx::openmp)

# link test.cu with ranx using CUDA API
add_executable(test_cuda test.cu)
target_link_libraries(test_cuda PRIVATE ranx::cuda)

Rapid prototyping with Jupyter¶

You can experiment with Ranx in Jupyter notebooks with Xeus-Cling kernel. That’s a very convenient way for rapid prototyping.

Depending on your preference, you can use one/all of the following methods to work with Ranx in Jupyter.

Creating a Conda/Mamba environment¶

The easiest way to install Xeus-Cling is to create an environment named cling using Mamba:

mamba create -n cling
mamba activate cling

Then you can install Xeus-Cling in this environment and its dependencies:

mamba install xeus-cling -c conda-forge

Next, you can use mamba env list command to find where the cling environment is installed and use the following commands to install Ranx in the cling environment:

wget https://github.com/arminms/ranx/releases/latest/download/install.zip
unzip install.zip -d <PATH/TO/CLING/ENV>

Creating a Python environment¶

If you’re more adventurous, you can build Xeus-Cling along with all the dependencies from the source in a Python virtual environment using the bash script available here. As a bonus, you will get a newer version of cling (v1.1) based on llvm 16.0 that supports C++20, OpenMP, CUDA.

Once done, you can install Ranx in your Python environment by unpacking the zip file or using CMake:

git clone https://github.com/arminms/ranx.git
cd ranx
cmake -S . -B build && cmake --build build
cmake --install build --prefix /path/to/python/virtual/environment

The same approach was used to build the container images below.

Using pre-built container images¶

Docker¶

docker run -p 8888:8888 -it --rm asobhani/ranx

If you like to work with your notebooks outside the container (e.g. current folder), you can use the following command instead:

docker run -v $PWD:/home/jovyan -p 8888:8888 -it --rm asobhani/ranx

You can also use the above container image as the starting point for your custom-made docker image (e.g. FROM asobhani/ranx:latest).

Apptainer¶

If you’re working on an HPC cluster, you can use Apptainer instead:

apptainer run docker://asobhani/ranx:latest