Skip to content

Installation

While Melissa was originally designed for use on supercomputers, it can also be installed and run on a local machine. In fact, users are encouraged to begin with a local installation to familiarize themselves with the framework before deploying it at scale.

Starting with version 3.0.0, Melissa's installation process has been unified. Previously divided into separate C and Python workflows, the entire framework—including the API, Server, and Launcher—is now managed through a single integrated build system.

  • Unified Build System: Melissa uses scikit-build-core as its backend. This allows the C API to be compiled and the Python components to be installed simultaneously using standard Python tooling.

  • Integrated API & Launcher: When you install Melissa via pip, the C-based API is automatically compiled and bundled into the Python package structure, ensuring that all components are version-matched and ready to use.

The optimal installation method depends on your environment and requirements (e.g., whether you need the full server with Deep Learning support or just the lightweight launcher). This tutorial provides step-by-step guidance for each approach, helping you choose the most suitable method for your needs.

Availability

Melissa is currently supported for linux systems only. Windows and MacOS are unsupported. Although, it is possible to create a docker cluster with SLURM. (see Creating a SLURM-docker cluster).

Before building Melissa

The following dependencies must be installed before building Melissa:

  • PIP 23.1+
  • CMake 3.22+
  • A C99 compiler
  • MPI (OpenMPI 3+)
  • Python 3.11-3.12
  • ZeroMQ 4.1.5+ (optionally pkgconfig for searching)

On Debian based systems with root access, these dependencies can be installed via:

sudo apt-get install \
  cmake \
  build-essential \
  libopenmpi-dev \
  python3 \
  python3-dev \
  python3-venv \
  libzmq5-dev \
  pkg-config

Note

If the module system is not available or if it does not contain all the required dependencies, this procedure can easily be supplemented (or substituted) with other package managers (e.g. spack or conda).

Melissa's Python dependencies are categorized into optional extras defined within the unified package metadata. These are automatically resolved and installed by pip based on your specific use case:

Feature Group Install Command Description
Sensitivity Analysis pip install .[sa] For Sensitivity Analysis.
Deep Learning (PyTorch) pip install .[dl] For Deep Learning with PyTorch support.
Deep Learning (Base) pip install .[dl-no-torch] For Deep Learning without PyTorch.
Development pip install .[dev] Additional Development tools.
All pip install .[all] melissa[launcher,sa,dl,dev]
Base / Launcher pip install -Ccmake.define.LAUNCHER_ONLY=ON .[launcher] Minimal installation for the Launcher.

Quick Installation

To install the full framework (Launcher, Server, and C API) with Deep Learning support:

python3 -m pip install --upgrade pip
python3 -m pip install \
    "melissa[dl] @ git+https://gitlab.inria.fr/melissa/melissa.git@develop"

Dependency Specifics

  • External/Existing MPI: To build mpi4py against available MPI implementation. For instance, a cluster-specific optimized version. First, ensure MPICC is set and then pass --no-binary mpi4py with pip.
  • PyTorch for CPU: Pass --extra-index-url https://download.pytorch.org/whl/cpu with pip.

Passing CMake Options via Pip

scikit-build-core can process CMake configuration options directly through pip using the -C (or --config-settings) flag.

To Install the Launcher Only

python3 -m pip install \
    -Ccmake.define.LAUNCHER_ONLY=ON \
    "melissa[launcher] @ git+https://gitlab.inria.fr/melissa/melissa.git@develop"

To Toggle Internal ZeroMQ Installation

If you want Melissa to install its own managed version of ZeroMQ:

python3 -m pip install \
   -Ccmake.define.INSTALL_ZMQ=ON \
    "melissa[dl] @ git+https://gitlab.inria.fr/melissa/melissa.git@develop"

Local Development of Melissa

  • Editable Installation As a Melissa developer, you can install the package in editable mode. This allows your Python changes to take effect immediately without needing a reinstall: 

    git clone https://gitlab.inria.fr/melissa/melissa.git
cd melissa
python3 -m pip install -e .[all]

  • Automated Setup Script The build_and_install.sh script provides a streamlined way to set up your development environment. When executed, the script performs the following:

    • Cleans the workspace by removing any existing build/ directories.
    • Installs the Melissa package in editable mode using --no-deps to maintain environment stability.
    • Automatically builds the Heat-PDE examples and links them to your local build. 
      # Usage: ./build_and_install.sh [optional/path/to/melissa]
./build_and_install.sh

  • Environment Management To expose the editable installation and its associated paths, you can manually run source .envrc. Alternatively, use direnv by running direnv allow to automatically manage the loading and unloading of your environment variables whenever you enter the directory.

Warning

direnv may not work properly with batch scheduler submission scripts. In that case, stick with source .envrc.

  • Rebuilding C/Fortran Components In editable mode, only the Python melissa module reflects changes instantly. If you modify the client-side codebase (located in api/, common/, etc.), you must re-run the installation or the build script to recompile the shared libraries and update the API.

After a successful installation, test the launcher installation:

melissa-launcher -h

Linking Melissa to Your Solver with CMake

To use Melissa's Client API in your simulation code, you must point CMake to the correct configuration files.

1. Locate the Melissa Prefix

The required MelissaConfig.cmake file is located within your Python site-packages. You can find the path by running:

python3 -c "import melissa; import os; print(os.path.join(melissa.__path__[0], 'share', 'cmake', 'Melissa'))"

2. Configure Your Project

Add the discovered path to your CMAKE_PREFIX_PATH when configuring your simulation.

For standard installations:

cmake -DCMAKE_PREFIX_PATH=$(python3 -c "import melissa; print(melissa.__path__[0])") ..

For local development: If you are developing Melissa locally and haven't installed it into site-packages, simply point to the build/ directory generated during your compilation:

cmake -DCMAKE_PREFIX_PATH=/path/to/melissa/build ..
3. In Your CMakeLists.txt

Once the prefix is set, you can link Melissa to your simulation as follows:

find_package(Melissa REQUIRED)
target_include_libraries(solver_executable PRIVATE ${Melissa_INCLUDE_DIR})
target_link_libraries(solver_executable PRIVATE Melissa::melissa)

Nix (Flakes) Installation

Melissa provides a flake.nix to ensure a fully reproducible development and execution environment. This method automatically handles complex dependencies such as MPI, CUDA, and PyTorch without polluting the global system state.

  1. Enter the Development Shell: To drop into a shell with all dependencies (compilers, Python libraries, and MPI) pre-configured, run: 
    nix develop --impure git+https://gitlab.inria.fr/melissa/melissa.git?ref=develop

Note

The --impure flag is recommended to allow Nix to interface with the NVIDIA kernel drivers on the host system for CUDA support.

  1. Build the Package: To build Melissa as a standalone Nix package and add the launcher/server binaries to your result path: 

    nix build git+https://gitlab.inria.fr/melissa/melissa.git?ref=develop

  2. Runtime Configuration: The Nix environment automatically sets the CMAKE_PREFIX_PATH and PYTHONPATH so that Melissa’s API and Python modules are discoverable by your simulation code and scripts immediately upon entering the shell.

Spack Installation

Availability

New installation approach will be available once the packages are published on spack.