HySoP (Hybrid Simulation with Particles):

HySoP 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. HySoP is written in Python (main user interface and high level functionnalities) and Fortran.

See HySoP documentation for more information, screenshots and animations.

Try online at mybinder

Click to open a jupyter notebook with a Hysop installed and ready to use.

Use a Docker Images (recommended):

Docker Images (CPU and GPU) are provided with HySoP and dependencies installed.

Docker Desktop must be installed on your computer! To find out how to install Docker Desktop click here.

Quick start:

HySoP "CPU_Intel" Docker Image can be retrieved and submitted as a Docker Container.

As a jupyter notebook with the following command:

docker run -p 8888:8888  --rm -ti gricad-registry.univ-grenoble-alpes.fr/particle_methods/hysop/hysoplab-cpu-intel-master

Or to start a terminal session:

docker run -it --rm --entrypoint="/bin/bash" gricad-registry.univ-grenoble-alpes.fr/particle_methods/hysop/hysoplab-cpu-intel-master:latest

In both cases, you will end up with a fully-fonctionnal installation of Hysop software (in a Docker Container ) and will be able to quickly test HySoP using examples in the documentation.

Please note the following:

• If the HySoP Docker Image is not present on your host machine, using the above command, it will be automatically downloaded from the HySoP gitlab container registry. This may take some time, depending on the speed of your Internet connection. HySoP Docker Image size is beetween 3 and 4 Gb.

• A micomamba packaged manager is used as a virtual environment for HySoP.

• *By default, the Docker container is completely isolated from the host machine's disk space! As a result, it's impossible to write or read data on your hard disk. To share a directory between your host and the docker container, update the docker command like this:

  docker run -v HOST_DIRECTORY:/home/hysop-user/shared -p 8888:8888  --rm -ti gricad-registry.univ-grenoble-alpes.fr/particle_methods/hysop/hysoplab-gpu-nvidia-master

  HOST_DIRECTORY (use full path!) will be available in the container in directory 'shared'.

How to improve your HySoP experience:

Git clone HySoP and change directory to 'hysop':

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

Then HySoP Docker Container can run with everything needed to use hysop, but hysop:

docker run -v $(pwd):/home/hysop-user/shared --rm -ti gricad-registry.univ-grenoble-alpes.fr/particle_methods/hysop/[imagename]

Your local directory 'hysop' is then shared inside the Docker Container in shared directory.

• [imgname] is either ci_cpu_intel, which corresponds to Ubuntu 22.04 running with python3.12 and an Intel CPU OpenCL platform, or ci_gpu_nvidia, with an Nvidia GPU OpenCL platform (it requires host system driver compatible with cuda 12.0).

Next step is to install HySoP manually inside this containeri (see installation instruction).

From Sources:

Prerequisites:

Micomamba packaged manager is used to manage HySoP environments.

Download lastest HySoP:

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

We recommend to 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

for Intel CPU OpenCL platform or

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

with Nvidia OpenCL platform.

Installation:

Install HySoP using pip:

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

Install HySoP manually step by step 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 -C ${BUILD_DIR}
meson install -C ${BUILD_DIR}

Configuration options:

Installation configuration may be customized by user overriding default configuration in meson_options.txt:

meson configure ${BUILD_DIR} -DOPTION_NAME=VALUE

‘OPTION_NAME’ being one of the options described below and ‘VALUE’ is either ‘ON’ or ‘OFF’.

Behavior options:

• DOUBLEPREC: Set default HySoP floating point precision. Default=ON, ie double precision else single precision will be used.
• VERBOSE: Enable verbose mode for HySoP (default=ON).
• PROFILE: Enable profiling mode for HySoP (default=OFF).
• DEBUG: Enable debug mode for HySoP (default=OFF).

Components options :

• WITH_FFTW: Link with fftw library (required for some HySoP solvers), (default=ON).
• WITH_EXTRAS: Link with some extra fortran libraries (like arnoldi solver), (default=OFF).
• WITH_GPU: Use of GPU (required for some HySoP solvers), (default=ON)
• WITH_SCALES: to compile an HySoP version including scales (default = ON).
• WITH_TESTS: enable testing (i.e. prepare target “meson test”, default = OFF).
• WITH_DOCUMENTATION: Build Documentation. (default=OFF)

Testing:

HySoP installation:

python3 -c "import hysop; print(hysop); print(dir(hysop))"
python3 -c "from hysop import f2hysop; print(f2hysop);print(dir(f2hysop))"
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:

Installing HySoP dependencies can be a lengthy process. That's why we prefer to use Docker Images to avoid this tedious installation phase. However, Docker utilities are rarely available on cluster computers, in which case all HySoP dependencies will have to be installed.

The quickest and easiest way to discover all the HySoP dependencies and how to install them is to explore the Dockerfile:

./ci/docker_images/ci_user/Dockerfile

NVIDIA driver: Please note that to run HySoP on NVIDIA GPUs, a Nvidia driver corresponding to your graphics card must be installed and running on your host system. Here you'll find the various NVIDIA drivers and how to install them.