From 2cc87f6f44f01c8167eb217cc46f90fce77bb8e3 Mon Sep 17 00:00:00 2001
From: caubet_m <marc.caubet@psi.ch>
Date: Wed, 15 Jan 2025 17:25:04 +0100
Subject: [PATCH] Add OpenMPI page

---
 _data/sidebars/merlin7_sidebar.yml           |  2 +
 pages/merlin7/05-Software-Support/openmpi.md | 80 ++++++++++++++++++++
 2 files changed, 82 insertions(+)
 create mode 100644 pages/merlin7/05-Software-Support/openmpi.md

diff --git a/_data/sidebars/merlin7_sidebar.yml b/_data/sidebars/merlin7_sidebar.yml
index eb068c5..7dc0e6c 100644
--- a/_data/sidebars/merlin7_sidebar.yml
+++ b/_data/sidebars/merlin7_sidebar.yml
@@ -58,6 +58,8 @@ entries:
             url: /merlin7/slurm-examples.html
       - title: Software Support
         folderitems:
+          - title: OpenMPI
+            url: /merlin7/openmpi.html
           - title: ANSYS
             url: /merlin7/ansys.html
           - title: ANSYS RSM
diff --git a/pages/merlin7/05-Software-Support/openmpi.md b/pages/merlin7/05-Software-Support/openmpi.md
new file mode 100644
index 0000000..587b881
--- /dev/null
+++ b/pages/merlin7/05-Software-Support/openmpi.md
@@ -0,0 +1,80 @@
+---
+title: OpenMPI Support
+#tags:
+last_updated: 15 January 2025
+keywords: software, openmpi, slurm
+summary: "This document describes how to use OpenMPI in the Merlin7 cluster"
+sidebar: merlin7_sidebar
+permalink: /merlin7/openmpi.html
+---
+
+## Introduction
+
+This document outlines the supported OpenMPI versions in the Merlin7 cluster.
+
+### OpenMPI supported versionso
+
+The Merlin cluster supports OpenMPI versions across three distinct stages: stable, unstable, and deprecated. Below is an overview of each stage:
+
+#### Stable
+
+Versions in the `stable` stage are fully functional, thoroughly tested, and officially supported by the Merlin administrators.
+These versions are available via [Pmodules](/merlin7/using-modules.html) and [Spack](/merlin7/spack.html), ensuring compatibility and reliability for production use.
+
+#### Unstable
+
+Versions in the `unstable` stage are available for testing and early access to new OpenMPI features.
+While these versions can be used, their compilation and configuration are subject to change before they are promoted to the `stable` stage.
+Administrators recommend caution when relying on `unstable` versions for critical workloads.
+
+#### Deprecated
+
+Versions in the `deprecated` stage are no longer supported by the Merlin administrators.
+Typically, these include versions no longer supported by the official [OpenMPI](https://www.open-mpi.org/software/ompi/v5.0/) project.
+While deprecated versions may still be available for use, their functionality cannot be guaranteed, and they will not receive updates or bug fixes.
+
+### Using srun in Merlin7
+
+In OpenMPI versions prior to 5.0.x, using `srun` for direct task launches was faster than `mpirun`.
+Although this is no longer the case, `srun` remains the recommended method due to its simplicity and ease of use.
+
+Key benefits of `srun`:
+* Automatically handles task binding to cores.
+* In general, requires less configuration compared to `mpirun`.
+* Best suited for most users, while `mpirun` is recommended only for advanced MPI configurations.
+
+Guidelines:
+* Always adapt your scripts to use srun before seeking support.
+* For any module-related issues, please contact the Merlin7 administrators.
+
+Example Usage:
+```bash
+srun ./app
+```
+
+{{site.data.alerts.tip}}
+Always run OpenMPI applications with <b>srun</b> for a seamless experience.
+{{site.data.alerts.end}}
+
+### PMIx Support in Merlin7
+
+Merlin7's SLURM installation includes support for multiple PMI types, including pmix. To view the available options, use the following command:
+
+```bash
+🔥 [caubet_m@login001:~]# srun --mpi=list
+MPI plugin types are...
+        none
+        pmix
+        pmi2
+        cray_shasta
+specific pmix plugin versions available: pmix_v5,pmix_v4,pmix_v3,pmix_v2
+```
+Important Notes:
+* For OpenMPI, always use `pmix` by specifying the appropriate version (`pmix_$version`). 
+When loading an OpenMPI module (via [Pmodules](/merlin7/using-modules.html) or [Spack](/merlin7/spack.html)), the corresponding PMIx version will be automatically loaded.
+* Users do not need to manually manage PMIx compatibility.
+
+{{site.data.alerts.warning}}
+PMI-2 is not supported in OpenMPI 5.0.0 or later releases.
+Despite this, <b>pmi2</b> remains the default SLURM PMI type in Merlin7 as it is the officially supported type and maintains compatibility with other MPI implementations.
+{{site.data.alerts.end}}