idefix-code · glesur · Oct 19, 2025 · Dec 3, 2024 · Dec 12, 2024 · Dec 14, 2024
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.2.02] 2025-10-18
+### Changed
+
+- Added a module to add explicit units (#338)
+- fixed a bug that could lead to incorrect profiling information on non-blocking cuda loops (#341)
+- fixed a bug that could lead to incorrect energy budget when shearing box and fargo were both enabled (#346)
+- fixed a bug that led to incorrect BX2 reconstruction when axis is not used on both sides of the domain (#345)
+- fixed a bug that led to incorrect reflective boundary conditions on B when DIMENSIONS < 3 (#345)
+- fixed a bug that led to incorrect dust stopping time when the adiabatic equation of state is used with "size" drag law (#353)
+
+### Added
+
+- documentation for the continuous integration (#354)
+
 ## [2.2.01] 2025-04-16
 ### Changed
 

diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -6,9 +6,9 @@ set (CMAKE_CXX_STANDARD 17)
 
 set(Idefix_VERSION_MAJOR 2)
 set(Idefix_VERSION_MINOR 2)
-set(Idefix_VERSION_PATCH 01)
+set(Idefix_VERSION_PATCH 02)
 
-project (idefix VERSION 2.2.01)
+project (idefix VERSION 2.2.02)
 option(Idefix_MHD "enable MHD" OFF)
 option(Idefix_MPI "enable Message Passing Interface parallelisation" OFF)
 option(Idefix_HIGH_ORDER_FARGO "Force Fargo to use a PPM reconstruction scheme" OFF)

diff --git a/doc/source/conf.py b/doc/source/conf.py
@@ -23,7 +23,7 @@
 author = 'Geoffroy Lesur'
 
 # The full version, including alpha/beta/rc tags
-release = '2.2.00'
+release = '2.2.02'
 
 
 

diff --git a/doc/source/faq.rst b/doc/source/faq.rst
@@ -61,9 +61,18 @@ How can I stop the code without loosing the current calculation?
 I'm doing performance measures. How do I disable all outputs in *Idefix*?
   Add ``-nowrite`` when you call *Idefix* executable.
 
+VTK output appears corrupted when running with MPI (OpenMPI)
+    Some OpenMPI configurations (notably OpenMPI 4 with the ompio component) can produce corrupted VTK/VTU output when running with MPI enabled. This appears to be caused by bugs in OpenMPI's ompio I/O component.
+    Disable ompio so OpenMPI falls back to ROMIO (MPICH's MPI-IO), which is typically more stable:
 
-Developement
-------------
+    .. code-block:: console
+
+       mpirun --mca io ^ompio ...
+
+    This has resolved intermittent corruption for several users. See issue #348 for discussion and reports.
+
+Development
+-----------
 
 I have a serious bug (e.g. segmentation fault), in my setup, how do I proceed?
   Add ``-DIdefix_DEBUG=ON`` to ``cmake`` and recompile to find out exactly where the code crashes (see :ref:`debugging`).

diff --git a/doc/source/index.rst b/doc/source/index.rst
@@ -122,6 +122,7 @@ The Idefix collaboration benefited from funding from the “Programme National d
    reference
    modules
    programmingguide
+   testing
    performances
    kokkos
    contributing

diff --git a/doc/source/reference/idefix.ini.rst b/doc/source/reference/idefix.ini.rst
@@ -265,8 +265,10 @@ section as followed:
 +----------------+-------------------------+---------------------------------------------------------------------------------------------+
 | Mcentral       | real                    | | Mass of the central object when a central potential is enabled (see above). Default is 1. |
 +----------------+-------------------------+---------------------------------------------------------------------------------------------+
-| gravCst        | real                    | | Set the value of the gravitational constant :math:`G_c` used by the central               |
+| gravCst        | real or string          | | Set the value of the gravitational constant :math:`G_c` used by the central               |
 |                |                         | | mass potential and self-gravitational potential (when enabled) ). Default is 1.           |
+|                |                         | | If set to "units", Idefix will compute the gravitational constant from the user units     |
+|                |                         | | defined in the units section (see :ref:`unitsSection`).                                   |
 +----------------+-------------------------+---------------------------------------------------------------------------------------------+
 | bodyForce      | string                  | | Adds an acceleration vector to each cell of the domain. The only value allowed            |
 |                |                         | | is ``userdef``. The ``Gravity`` class then expects a user-defined bodyforce function to   |
@@ -310,7 +312,28 @@ of gravitational potential in the ``Gravity`` section (see :ref:`gravitySection`
 |                |                         | | Default is 1 (i.e. self-gravity is computed at every cycle).                              |
 +----------------+-------------------------+---------------------------------------------------------------------------------------------+
 
+.. _unitsSection:
 
+``Units`` section
+------------------
+
+This optional section controls how the code handles units. By default, Idefix work "unit free" and this section is not useful.
+However, some physical processes like self-gravity or radiative transfer require the explicit use of units to define natural constants.
+These entries define how one code units should be converted to CGS units. When used, the following values should be set:
+
++----------------+--------------------+-----------------------------------------------------------------------------------------------------------+
+|  Entry name    | Parameter type     | Comment                                                                                                   |
++================+====================+===========================================================================================================+
+| length         | float              | The code unit length: 1 code unit = `length` cm. 1 by default.                                            |
++----------------+--------------------+-----------------------------------------------------------------------------------------------------------+
+| velocity       | float              | The code unit velocity: 1 code unit = `velocity` cm/s. 1 by default.                                      |
++----------------+--------------------+-----------------------------------------------------------------------------------------------------------+
+| density        | float              | The code unit density: 1 code unit = `density` g/cm^3. 1 by default.                                      |
++----------------+--------------------+-----------------------------------------------------------------------------------------------------------+
+
+.. note::
+    The units module automatically reconstruct all of the units (time, temperature, magnetic field, etc.) from the above 3 fundamental constants. These can
+    all be obtained from the global object ``idfx::units``. Note however that the code outputs remain in code units, even if `[Units]` are defined.
 
 ``RKL`` section
 ------------------

diff --git a/doc/source/testing.rst b/doc/source/testing.rst
@@ -0,0 +1,117 @@
+Continuous Integration (CI) tests
+================================
+
+This document describes the GitHub Actions continuous-integration setup used to run the Idefix
+test-suite. The CI is implemented by two workflows checked in .github/workflows:
+
+- .github/workflows/idefix-ci.yml
+- .github/workflows/idefix-ci-jobs.yml
+
+Overview
+--------
+
+The CI is split in two layers:
+
+- A top-level workflow (.github/workflows/idefix-ci.yml) that:
+
+  - runs a Linter job (pre-commit) on push / PR / manual dispatch,
+  - then calls a reusable workflow for different compiler/backends (intel, gcc, cuda)
+    providing two inputs: TESTME_OPTIONS and IDEFIX_COMPILER.
+
+- A reusable workflow (.github/workflows/idefix-ci-jobs.yml) that:
+
+  - defines the actual test jobs grouped by physics domain (ShocksHydro, ParabolicHydro,
+    ShocksMHD, ParabolicMHD, Fargo, ShearingBox, SelfGravity, Planet, Dust, Braginskii,
+    Examples, Utils),
+  - runs test scripts on self-hosted runners,
+  - expects the repository to be checked out with submodules,
+  - invokes the repository-provided CI helper scripts to configure / build / run tests.
+
+Key configuration points
+------------------------
+
+- Inputs passed from the top-level workflow:
+
+  - TESTME_OPTIONS (string): flags forwarded to the per-test runner (examples: -cuda, -Werror,
+    -intel, -all).
+  - IDEFIX_COMPILER (string): which compiler the tests should use (e.g. icc, gcc, nvcc).
+
+- Environment variables set by the reusable workflow:
+
+  - IDEFIX_COMPILER, TESTME_OPTIONS, PYTHONPATH, IDEFIX_DIR
+
+- Linter job:
+
+  - Runs only when repository is the main project (not arbitrary forks).
+  - Uses actions/setup-python and runs pre-commit (pre-commit/action@v3 and pre-commit-ci/lite).
+  - Prevents regressions in style and common mistakes before running heavy test jobs.
+
+- Test execution:
+
+  - All test jobs call the repository script scripts/ci/run-tests with a test directory
+    and the TESTME_OPTIONS flags. Example invocation (from the workflows):
+      scripts/ci/run-tests $IDEFIX_DIR/test/HD/sod -all $TESTME_OPTIONS
+
+  - The reusable workflow is written to execute many test directories in separate job steps,
+    so each physics group is kept logically separated in CI logs.
+
+Runners and prerequisites
+-------------------------
+
+- The heavy numerical tests run on self-hosted runners (see runs-on: self-hosted).
+  The CI assumes appropriate hardware and dependencies are available on those runners
+  (compilers, MPI, GPUs when CUDA/HIP flags are used, required system libraries).
+
+- The workflows check out the repository and its submodules. Submodules must be available
+  on the CI machines.
+
+How tests are driven (testme scripts)
+-------------------------------------
+
+Each test directory contains a small Python "testMe" driver that uses the helper Python
+class documented in the repository:
+
+- See the test helper documentation: :doc:`idfxTest <testing/idfxTest>`
+
+That helper (idfxTest) is responsible for:
+
+- parsing TESTME_OPTIONS-like flags (precision, MPI, CUDA, reconstruction, vector potential, etc.),
+- calling configure / compile / run,
+- performing standard python checks and non-regression (RMSE) comparisons against
+  reference dumps,
+- optionally creating / updating reference dumps (init mode).
+
+Practical examples
+------------------
+
+- Example of a CI invocation (triggered by workflows):
+
+  - Top-level workflow calls the reusable jobs workflow for each compiler/back-end, e.g.
+    TESTME_OPTIONS="-cuda -Werror" IDEFIX_COMPILER=nvcc
+
+- Running tests locally (developer machine)
+  - You can mimic what CI does by calling the repository helper script directly. Example:
+    scripts/ci/run-tests /path/to/idefix/test/HD/sod -all -mpi -dec 2 2 -reconstruction 3 -single
+
+Notes for maintainers
+---------------------
+
+- The reusable jobs workflow contains a commented concurrency block for optional cancellation
+  of in-flight runs — consider enabling it if you want to auto-cancel redundant CI runs.
+- Because tests are run on self-hosted runners, ensure the pools have the required compilers,
+  MPI stacks and GPU drivers for the requested TESTME_OPTIONS.
+- Keep TESTME_OPTIONS in sync with the options understood by the test helper documented in
+  :doc:`idfxTest <testing/idfxTest>`.
+
+Relevant files
+--------------
+
+- Workflow entry point: .github/workflows/idefix-ci.yml
+- Reusable jobs: .github/workflows/idefix-ci-jobs.yml
+- Test helper documentation: :doc:`idfxTest <testing/idfxTest>`
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   testing/idfxTest.rst