Merge pull request #2828 to improve RMS and Julia installation.

Overhaul the install_rms.sh script to make RMS (ReactionMechanismSimulator) installation more robust and user-friendly:

Add zsh compatibility and fix Julia heredoc escaping issues
Fix detection of conda executable
Support RMS_PATH and RMS_INSTALLER environment variables
Make standard mode the default; add "developer" option for dev installs
Add conda environment check and initialize Julia environment before installing
Reorganize code with better documentation and variable grouping
Update Dockerfile for the new install_rms script
Also adds installation instructions for the new script to the developer documentation.

Author: rwest

.github/workflows/CI.yml

@@ -2,7 +2,7 @@
 # This file contains the script used by GitHub actions to execute the Continuous Integration (CI)
 # for RMG-Py. This includes building RMG and its dependencies, executing the unit tests,
 # functional tests, database tests, and regression tests.
-# 
+#
 # This will run automatically on any push to any branch, but will only run one instance of
 # itself at a time per branch (to avoid spawning tons of runners, which prevents them from
 # executing).
@@ -14,7 +14,7 @@
 #
 #
 # Changelog:
-# 2023-04    - Jackson Burns - Added this header, regression tests, cleanup of action in 
+# 2023-04    - Jackson Burns - Added this header, regression tests, cleanup of action in
 #              in general, and documentation throughout the file.
 # 2023-05    - added Docker build steps
 # 2023-05-12 - added changes to allow running on forks
@@ -54,6 +54,8 @@ env:
   RMG_DATABASE_BRANCH: main
   # RMS branch to use for ReactionMechanismSimulator installation
   RMS_BRANCH: for_rmg
+  # RMS mode used for install_rms.sh
+  RMS_INSTALLER: continuous
   # julia parallel pre-compilation leads to race conditions and hangs, so we limit it to run in serial
   JULIA_NUM_PRECOMPILE_TASKS: 1
 
@@ -131,7 +133,7 @@ jobs:
     name: Regression Test
     # skip scheduled runs from forks
     if: ${{ !( github.repository != 'ReactionMechanismGenerator/RMG-Py' && github.event_name == 'schedule' ) }}
-    env: 
+    env:
       # This is true only if this is a reference case for the regression testing:
       REFERENCE_JOB: ${{ github.ref == 'refs/heads/main' && github.repository == 'ReactionMechanismGenerator/RMG-Py' }}
     defaults:
@@ -167,7 +169,7 @@ jobs:
 
       # RMG build step
       - run: make install
-      
+
       - name: Make separate No-RMS conda env
         run: |
           conda create --name rmg_env_without_rms --clone rmg_env
@@ -270,7 +272,7 @@ jobs:
           REFERENCE: stable_regression_results
         run: |
           conda activate rmg_env_without_rms
-          
+
           exec 2> >(tee -a regression.stderr >&2) 1> >(tee -a regression.stdout)
           mkdir -p "test/regression-diff"
           for regr_test in aromatics liquid_oxidation nitrogen oxidation sulfur superminimal RMS_constantVIdealGasReactor_superminimal RMS_CSTR_liquid_oxidation fragment RMS_constantVIdealGasReactor_fragment minimal_surface;

Dockerfile

@@ -77,9 +77,11 @@ RUN make
 # setting this env variable fixes an issue with Julia precompilation on Windows
 ENV JULIA_CPU_TARGET="x86-64,haswell,skylake,broadwell,znver1,znver2,znver3,cascadelake,icelake-client,cooperlake,generic"
 ENV RMS_BRANCH=${RMS_Branch}
+ENV RMS_INSTALLER=continuous
 # Usually this is set automatically, but we're not actually running
 # in an active conda environment when building the Docker so we need to set it manually
 ENV PYTHON_JULIAPKG_PROJECT="/miniconda/envs/rmg_env/julia_env"
+ENV JULIA_PYTHONCALL_EXE="/miniconda/envs/rmg_env/bin/python"
 RUN source install_rms.sh
 
 # RMG-Py should now be installed and ready - trigger precompilation and test run

documentation/source/users/rmg/installation/anacondaDeveloper.rst

@@ -129,6 +129,25 @@ Installation by Source Using Anaconda Environment for Unix-based Systems: Linux
     which can involve several steps including restarting your terminal or shell.
     Run the script again, until it finishes installing RMS and all of its dependencies, and reports that ReactionMechanismSimulator is installed.
 
+    **Advanced Usage**:
+    The ``install_rms.sh`` script has options, that can be set as environment variables or variables to the script.
+    By default, it installs the latest release of the ``for_rmg`` branch of RMS, from `the official GitHub fork <https://github.com/ReactionMechanismGenerator/ReactionMechanismSimulator.jl/branches>`_, which is recommended for most users.
+    To install a different branch (from the same github repository) specify ``RMS_BRANCH``.
+    The default installation mode is ``standard``, which prompts the user to confirm their conda environment.
+    In an automated workflow (eg. CI/CD), you may wish to set ``RMS_INSTALLER`` to ``continuous`` to skip the prompt.
+    If you set ``RMS_INSTALLER`` to ``developer`` then it will link to a local version of RMS,
+    so you must also specify ``RMS_PATH`` to point to your local clone of the ReactionMechanismSimulator.jl repository.
+    Exmaple usage: ::
+
+     export RMS_BRANCH=for_rmg
+     export RMS_INSTALLER=continuous
+     source install_rms.sh
+
+    or ::
+
+     RMS_INSTALLER=developer RMS_PATH=$HOME/Code/ReactionMechanismSimulator.jl source install_rms.sh
+
+
 #. Finally, you can run RMG from any location by typing the following (given that you have prepared the input file as ``input.py`` in the current folder). ::
 
     python replace/with/path/to/rmg.py input.py

documentation/source/users/rmg/releaseNotes.rst

@@ -8,7 +8,7 @@ RMG-Py Version 3.3.0
 ====================
 Date: July 10, 2025
 
-The below list is a summary. For a complete list of all changes, see the `Official Release Page <https://github.com/ReactionMechanismGenerator/RMG-Py/releases/tag/3.3.0>`_.
+The below list is a summary. For a complete list of all changes, see the `Official RMG-Py Release Page <https://github.com/ReactionMechanismGenerator/RMG-Py/releases/tag/3.3.0>`_.
 
 - Software Improvements
     - RMG-Py now uses Python 3.9
@@ -33,7 +33,7 @@ RMG-Database Version 3.3.0
 ==========================
 Date: July 10, 2025
 
-The below list is a summary. For a complete list of all changes, see the `Official Release Page <https://github.com/ReactionMechanismGenerator/RMG-database/releases/tag/3.3.0>`_.
+The below list is a summary. For a complete list of all changes, see the `Official RMG-Database Release Page <https://github.com/ReactionMechanismGenerator/RMG-database/releases/tag/3.3.0>`_.
 
 - Features
     - Electrochemistry with Lithium

install_rms.sh

@@ -2,6 +2,43 @@
 #
 # Convenience script to install ReactionMechanismSimulator into an rmg_env conda environment
 #
+# Usage:
+#   source install_rms.sh
+# Options:
+#   RMS_INSTALLER environment variable can be set to "continuous", "standard", or "developer"
+#     "continuous": non-interactive install for CI environments
+#     "standard": interactive install with user confirmation (default)
+#     "developer": install from local RMS source code (requires RMS_PATH to be set)
+#   RMS_PATH environment variable (required if RMS_INSTALLER="developer")
+#     Path to local ReactionMechanismSimulator.jl source code for developer mode
+#   RMS_BRANCH environment variable (optional), for "standard" or "continuous" modes
+#     Git branch of ReactionMechanismSimulator.jl to install (default: for_rmg)
+# Example:
+#   RMS_INSTALLER=developer RMS_PATH=/path/to/ReactionMechanismSimulator.jl source install_rms.sh
+
+
+# Defaults to "standard" if not already set via RMS_INSTALLER env variable
+RMS_INSTALLER=${RMS_INSTALLER:-standard}
+
+# RMS branch for standard or continuous installs. Set to "for_rmg" by default.
+RMS_BRANCH=${RMS_BRANCH:-for_rmg}
+
+# Get local RMS path if in developer mode
+if [ "$RMS_INSTALLER" = "developer" ]; then
+    echo "Using developer mode for RMS installation"
+    # Check if RMS_PATH is set
+    if [ -z "$RMS_PATH" ]; then
+        printf "Please enter full path to your local RMS source code: "
+        read -r RMS_PATH
+    fi
+    # Validate Project.toml exists
+    if [ ! -f "$RMS_PATH/Project.toml" ]; then
+        echo "ERROR: '$RMS_PATH' does not contain a Project.toml file."
+        echo "Please set RMS_PATH to a valid ReactionMechanismSimulator.jl directory."
+        return 1
+    fi
+    echo "Using local RMS path: $RMS_PATH"
+fi
 
 # Check if juliaup is installed
 if ! command -v juliaup &> /dev/null; then
@@ -39,16 +76,39 @@ echo "Julia 1.10 binary path: $julia_path"
 
 # Get current conda environment name
 current_env=$(conda info --envs | grep -v '^#' | awk '/\*/{print $1}')
-echo "Current conda environment: $current_env"
+
+# Ask the user to confirm RMS is being installed in the correct conda environemnt.
+# Skip confirmation if this is run under continuous mode.
+if [ "$RMS_INSTALLER" = "continuous" ]; then
+    echo "Current conda environment: $current_env"
+else
+    echo "    Please confirm that you want to install RMS into the current conda environment: '$current_env'"
+    echo "    If this is not correct, abort and activate the correct environment before rerunning."
+    printf "Proceed with installation in '%s'? (y/N): " "$current_env"
+    read confirm
+    case "$confirm" in
+    [yY][eE][sS]|[yY])
+        echo "✅ Proceeding with installation in '$current_env'"
+        ;;
+    *)
+        echo "❌ Aborted. Please activate the correct conda environment and try again."
+        return 1
+        ;;
+    esac
+fi
 
 # Set environment variables for the current environment, for future uses
 # https://juliapy.github.io/PythonCall.jl/stable/pythoncall/#If-you-already-have-Python-and-required-Python-packages-installed
+# Find the actual conda executable (not the shell function)
+CONDA_EXE="${CONDA_EXE:-$(conda info --base)/bin/conda}"
 conda env config vars set JULIA_CONDAPKG_BACKEND=Null
+conda env config vars set JULIA_CONDAPKG_EXE="$CONDA_EXE"
 conda env config vars set JULIA_PYTHONCALL_EXE=$CONDA_PREFIX/bin/python
 conda env config vars set PYTHON_JULIAPKG_EXE=$(which julia)
 conda env config vars set PYTHON_JULIAPKG_PROJECT=$CONDA_PREFIX/julia_env
 # Also export for current shell/session (needed for Docker/non-interactive use)
 export JULIA_CONDAPKG_BACKEND=Null
+export JULIA_CONDAPKG_EXE="$CONDA_EXE"
 export JULIA_PYTHONCALL_EXE="$CONDA_PREFIX/bin/python"
 export PYTHON_JULIAPKG_EXE="$(which julia)"
 export PYTHON_JULIAPKG_PROJECT="$CONDA_PREFIX/julia_env"
@@ -58,11 +118,85 @@ conda install -y conda-forge::pyjuliacall
 echo "Environment variables referencing JULIA:"
 env | grep JULIA
 
-# Use RMS_BRANCH environment variable if set, otherwise default to for_rmg
-RMS_BRANCH=${RMS_BRANCH:-for_rmg}
-echo "Installing ReactionMechanismSimulator from branch: $RMS_BRANCH"
+# Initialize the Julia environment from Python using juliacall
+python << EOF || return 1
+import sys
+try:
+    from juliacall import Main
+    Main.seval('println("Active Julia environment: ", Base.active_project())')
+    Main.seval('println("Julia load path: ", Base.load_path())')
+    Main.seval('using Pkg')
+    Main.seval('Pkg.status()')
+except Exception as e:
+    print("❌ Error while initializing Julia environment:")
+    print(e)
+    sys.exit(1)
+EOF
 
-julia -e "using Pkg; Pkg.add(Pkg.PackageSpec(name=\"ReactionMechanismSimulator\", url=\"https://github.com/ReactionMechanismGenerator/ReactionMechanismSimulator.jl.git\", rev=\"$RMS_BRANCH\")); using ReactionMechanismSimulator; println(read(joinpath(dirname(pathof(ReactionMechanismSimulator)), \"..\", \"Project.toml\"), String)); Pkg.instantiate()" || echo "RMS install error - continuing anyway."
+# Install RMS
+if [ "$RMS_INSTALLER" = "standard" ] || [ "$RMS_INSTALLER" = "continuous" ]; then
+    echo "Installing RMS from branch: $RMS_BRANCH"
+    julia << 'EOF' || echo "RMS standard install error - continuing anyway ¯\\_(ツ)_/¯"
+    using Pkg
+    Pkg.activate(ENV["PYTHON_JULIAPKG_PROJECT"])
+    Pkg.add(Pkg.PackageSpec(name="ReactionMechanismSimulator", url="https://github.com/ReactionMechanismGenerator/ReactionMechanismSimulator.jl.git", rev=ENV["RMS_BRANCH"]))
+    println(read(joinpath(dirname(pathof(ReactionMechanismSimulator)), "..", "Project.toml"), String))
+    Pkg.instantiate()
+    try
+        @info "Loading RMS"
+        using ReactionMechanismSimulator
+        @info "RMS loaded successfully!"
+    catch err
+        @error "Failed to load RMS" exception=err
+        Base.show_backtrace(stderr, catch_backtrace())
+        exit(1)
+    end
+EOF
+elif [ "$RMS_INSTALLER" = "developer" ]; then
+    echo "Installing RMS in developer mode from path: $RMS_PATH"
+    julia << 'EOF' || echo "RMS developer install error - continuing anyway ¯\\_(ツ)_/¯"
+    using Pkg
+    println(ENV["PYTHON_JULIAPKG_PROJECT"])
+    Pkg.activate(ENV["PYTHON_JULIAPKG_PROJECT"])
+    Pkg.develop(path=ENV["RMS_PATH"])
+    Pkg.instantiate()
+    try
+        @info "Loading RMS"
+        using ReactionMechanismSimulator
+        @info "RMS loaded successfully!"
+    catch err
+        @error "Failed to load RMS" exception=err
+        Base.show_backtrace(stderr, catch_backtrace())
+        exit(1)
+    end
+EOF
+else
+    echo "Unknown RMS_INSTALLER mode: $RMS_INSTALLER. Must be either 'continuous', 'standard' or 'developer'."
+    return 1
+fi
+
+julia_status=$?
+if [ $julia_status -ne 0 ]; then
+    echo "RMS installation failed!"
+    return $julia_status
+fi
 
 echo "Checking if ReactionMechanismSimulator is installed in the current conda environment for Python usage..."
-python -c "from juliacall import Main; import sys; sys.exit(0 if Main.seval('Base.identify_package(\"ReactionMechanismSimulator\") !== nothing') and print('ReactionMechanismSimulator is installed in $current_env') is None else 1)"
+
+python << EOF
+import sys
+try:
+    from juliacall import Main
+    RMS_Pkg = Main.seval('Base.identify_package("ReactionMechanismSimulator")')
+    print("Package identify result: ", RMS_Pkg)
+    if RMS_Pkg is Main.nothing:
+        print("❌ ReactionMechanismSimulator is NOT installed correctly.")
+        sys.exit(1)
+    else:
+        print("✅ ReactionMechanismSimulator is succesfully installed!")
+        sys.exit(0)
+except Exception as e:
+    print("❌ Error while checking ReactionMechanismSimulator installation:")
+    print(e)
+    sys.exit(1)
+EOF