README.md

HySoP (Hybrid Simulation with Particles) is a library dedicated to high performance direct numerical simulation of fluid related problems based on semi-lagrangian particle methods, for hybrid architectures providing multiple compute devices including CPUs, GPUs or MICs. See https://particle_methods.gricad-pages.univ-grenoble-alpes.fr/hysop-doc for more information.

Running Hysop using a docker container (recommended):

Please git clone hysop before to run (or pull) a hysop docker image!

git clone https://gricad-gitlab.univ-grenoble-alpes.fr/hysop.git
cd hysop

The hysop docker images can be run with

./ci/utils/run_user_docker_image.sh [imgname]

This script donwload hysop docker image (if required) and mounts your local hysop directory inside the docker container and prompt a shell (base) xxx@yyyyyyyy:/home/$USER. By default, [imgname] corresponds to hysop_user_cpu_intel, which corresponds to Ubuntu 22.04 running with python3.12 on Intel CPU.

Try out

./ci/utils/run_user_docker_image.sh hysop_user_gpu_nvidia

to run on the Nvidia GPUs version of hysop (requires host system driver compatible with cuda 12.0).

To quickly test hysop inside a docker container you can run

./ci/scripts/hysop_user_tests.sh

script which will build hysop using meson (if needed) and submit tests.

For developers: Root hysop docker images can be build locally by using the ./ci/utils/build_docker_image.sh [imgname] script. It is advised to build docker image only if the pull fails or if you want to add/update dependencies. By default, [imgname] corresponds to ci_cpu_intel, which corresponds to Ubuntu 22.04 running with python3.12 on Intel CPU. ci_gpu_nvidia is also available for Nvidia GPUs. To quickly test hysop inside a docker container you can run ./ci/scripts/build_and_test.sh which will build hysop using meson and submit tests.

There are equivalent *.bat scripts to run on Windows. Please note that the nvidia enabled images currently do not work on Windows due to this bug.

Basics (for developers):

Micromamba is used to manage hysop environments. Everything you need to know to install micromamba is described on the web page at this link: https://mamba.readthedocs.io/en/latest/installation/micromamba-installation.html

Download lastest hysop:

git clone https://gricad-gitlab.univ-grenoble-alpes.fr/hysop.git
cd hysop

Create and activate a micromamba environment for hysop:

micromamba create -n hysop_cpu_intel python=3.12.4 -f ci/hysopenv_cpu_intel.yaml
micromamba activate hysop_cpu_intel

or

micromamba create -n hysop_gpu_nvidia python=3.12.4 -f ci/hysopenv_gpu_nvidia.yaml
micromamba activate hysop_gpu_nvidia

Before installing the hysop library, you may need to install some dependencies! (see below)

Install hysop using pip:

pip install --no-build-isolation --no-deps .

Install hysop using meson:

export BUILD_DIR=builddir
meson setup      ${BUILD_DIR}
meson compile -C ${BUILD_DIR}
meson install -C ${BUILD_DIR}

Install hysop using meson and force a directory of installation: In this case, meson option --python.install-env prefix is needed.

export BUILD_DIR=builddir
meson setup         ${BUILD_DIR} --python.install-env prefix --prefix=${BUILD_DIR}/install
meson compile -v -C ${BUILD_DIR}
meson install    -C ${BUILD_DIR}

Testing:

Hysop installation:

python3 -c "import hysop; print(hysop); print(dir(hysop))"
python3 -c "from hysop import f2hysop; print(f2hysop);print(dir(f2hysop))"

Warning: some tests may FAIL if all dependencies are not installed. See below

Tests:

./ci/scripts/test.sh

Using meson:

meson test    -C ${BUILD_DIR}

To know if Opencl is present?

clinfo

or

python3 -c 'import hysop; from hysop.testsenv import iter_clenv, __HAS_OPENCL_BACKEND__; print(next(iter(iter_clenv())) if __HAS_OPENCL_BACKEND__ else "");'

Dependencies:

Please note that the presence in the LD_LIBRARY_PATH and/or PATH environment variables of paths to libraries or executables such as NVIDIA's mpicc, mpif90 may result in conflict with OpenMPI compilers and in meson error message!

To install hysop dependencies locally on an ubuntu machine (jammy-22.04 LTS):

sudo apt-get install -y wget git-core make pkg-config g++ gfortran libopenmpi-dev libclfft-dev
export FC=mpif90
export CC=mpicc
export MPICC=mpicc

Additionally you may want to provide a working OpenCL platform, HPTT, llvm/llvmlite/numba, FFTW/pyfftw/clFFT/gpyFFT, flint/arb/python-flint and tbb/mklfft. Dive into the docker files to get instructions on how to configure and install these packages (cat ./ci/docker_images/ci_cpu_intel/Dockerfile).