From d71641df24deded94615f221cb170a2fc9875d3f Mon Sep 17 00:00:00 2001 From: Richard West Date: Thu, 14 May 2026 13:31:04 -0400 Subject: [PATCH 1/4] Pin python=3.11 in environment.yml; update CI to rewrite pin per matrix environment.yml previously used `python >=3.9,<3.12` so that the conda-incubator/setup-miniconda action could safely inject a per-matrix equality pin without creating a contradiction. That broad range forces the solver to consider every compatible package set for all three Python micro-versions simultaneously, which makes fresh environment creation slow and, on some local setups with older libmamba, can cause the solver to hang indefinitely. Changes: - environment.yml: tighten the pin to `=3.11`. Users running `conda env create -f environment.yml` now get a fast solve because the solver only needs to consider packages for a single Python version. - CI.yml (build-and-test): add a "Pin Python version for CI matrix" step immediately after checkout that rewrites `=3.11` to the matrix python-version before setup-miniconda runs. The -i.bak/rm idiom works on both GNU sed (Linux) and BSD sed (macOS). - CI.yml (regression-test): upgrade the hardcoded python-version from 3.9 to 3.11. There is no technical requirement for regression tests to use an older Python; 3.9 was a historical artifact. With the pin already set to 3.11 in the file, setup-miniconda's injected `=3.11` is redundant but harmless. Co-Authored-By: Claude Sonnet 4.6 --- .github/workflows/CI.yml | 12 ++++++++++-- environment.yml | 2 +- 2 files changed, 11 insertions(+), 3 deletions(-) diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml index af1ba44120..ca7cb39bce 100644 --- a/.github/workflows/CI.yml +++ b/.github/workflows/CI.yml @@ -80,6 +80,14 @@ jobs: - name: Checkout RMG-Py uses: actions/checkout@v6 + - name: Pin Python version for CI matrix + # environment.yml pins python=3.11 for fast user installs; rewrite to the + # matrix version here so setup-miniconda can inject the correct pin cleanly. + # The -i.bak / rm pattern works on both GNU sed (Linux) and BSD sed (macOS). + run: | + sed -i.bak "s/conda-forge::python =3\.11/conda-forge::python =${{ matrix.python-version }}/" environment.yml + rm -f environment.yml.bak + - name: Setup Miniforge Python ${{ matrix.python-version }} uses: conda-incubator/setup-miniconda@v3 with: @@ -147,13 +155,13 @@ jobs: - name: Checkout RMG-Py uses: actions/checkout@v6 - - name: Setup Miniforge Python 3.9 + - name: Setup Miniforge Python 3.11 uses: conda-incubator/setup-miniconda@v3 with: environment-file: environment.yml miniforge-variant: Miniforge3 miniforge-version: latest - python-version: 3.9 + python-version: 3.11 activate-environment: rmg_env auto-update-conda: true show-channel-urls: true diff --git a/environment.yml b/environment.yml index 39f4666f0f..751d6e45b2 100644 --- a/environment.yml +++ b/environment.yml @@ -50,7 +50,7 @@ dependencies: - rmg::pysidt-rmg >=1.2 # Python tools - - conda-forge::python >=3.9,<3.12 # leave as GEQ so that GitHub actions can add EQ w/o breaking (contradictory deps) + - conda-forge::python =3.11 # pinned to a single version to keep solver fast; CI rewrites this to the matrix version (see CI.yml) - conda-forge::setuptools <80 - conda-forge::coverage - conda-forge::cython >=0.25.2,<3.1 From 5cf195e96fe4459d32869febc0a19a7823772f46 Mon Sep 17 00:00:00 2001 From: Richard West Date: Thu, 14 May 2026 13:34:17 -0400 Subject: [PATCH 2/4] Update source install docs with build-tool prerequisites and python pin note Two classes of problems encountered during a macOS source install were not covered by the existing documentation: 1. An outdated Xcode Command Line Tools installation (Apple clang 11, from 2019) causes `make` to fail with "clang: error: invalid version number in 'MACOSX_DEPLOYMENT_TARGET'" because that vintage of clang does not recognise macOS deployment targets >= 11.0. Added a warning at the top of the page explaining how to detect and fix this, with the recommended reinstall command. 2. Conda versions older than ~24.0 (particularly libmamba 2.1.x) can hang indefinitely when solving the RMG environment. Added guidance to check and update conda before starting, including the `conda install -n base conda=26.3` workaround for cases where `conda update` fails to advance the version. Also added a brief note alongside the `conda env create` step explaining why environment.yml now pins Python 3.11 (faster solves), and cross-referenced the macOS CLT warning from the compiler prerequisites section. Co-Authored-By: Claude Sonnet 4.6 --- .../rmg/installation/anacondaDeveloper.rst | 45 ++++++++++++++++--- 1 file changed, 39 insertions(+), 6 deletions(-) diff --git a/documentation/source/users/rmg/installation/anacondaDeveloper.rst b/documentation/source/users/rmg/installation/anacondaDeveloper.rst index c3a3ee6cd6..f983d5cb13 100644 --- a/documentation/source/users/rmg/installation/anacondaDeveloper.rst +++ b/documentation/source/users/rmg/installation/anacondaDeveloper.rst @@ -4,6 +4,35 @@ Installation by Source Using Anaconda Environment for Unix-based Systems: Linux and Mac OSX ******************************************************************************************* +.. warning:: + + **Before you begin — check your build tools are up to date.** + + RMG-Py compiles Cython extensions during installation, so your C compiler and + conda installation must be reasonably modern or the build will fail. + + **On macOS:** Ensure your Xcode Command Line Tools are current. An outdated + installation (more than a year or two old) will cause ``make`` to fail with a + ``clang: error: invalid version number`` message. To check:: + + clang --version + + If the reported version is older than Apple clang 13, reinstall the tools:: + + sudo rm -rf /Library/Developer/CommandLineTools + xcode-select --install + + **conda version:** Ensure conda is version 24.0 or newer (run ``conda --version`` + to check). Older versions use a slower solver that can hang indefinitely when + creating the RMG environment. To update:: + + conda update -n base -c conda-forge conda + + If ``conda update`` does not advance the version, install a specific release + explicitly:: + + conda install -n base -c conda-forge conda=26.3 + #. Install the `conda` package manager via `miniforge`, if you do not already have it (or Anaconda), by following the `Miniforge installation instructions `_. #. If your `conda` version is older than 23.10.0, manually switch the solver backend to `libmamba` (or update your conda):: @@ -40,6 +69,7 @@ Installation by Source Using Anaconda Environment for Unix-based Systems: Linux These are a set of packages relevant for software development which have been bundled together by Apple. The easiest way to install this is to simply run one of the commands in the terminal, e.g. ``git``. The terminal will then prompt you to install the Command Line Tools. + See the warning at the top of this page about keeping the tools up to date. #. Install the latest versions of RMG and RMG-database through cloning the source code via Git. Make sure to start in an appropriate local directory where you want both RMG-Py and RMG-database folders to exist. @@ -51,7 +81,7 @@ Installation by Source Using Anaconda Environment for Unix-based Systems: Linux It is still possible to clone the repositories using ``https`` if you are unfamiliar with ``ssh``:: - + git clone https://github.com/ReactionMechanismGenerator/RMG-Py.git git clone https://github.com/ReactionMechanismGenerator/RMG-database.git @@ -61,7 +91,10 @@ Installation by Source Using Anaconda Environment for Unix-based Systems: Linux cd RMG-Py -#. Create the conda environment for RMG-Py:: +#. Create the conda environment for RMG-Py. + + The ``environment.yml`` file pins Python 3.11, so the solver only needs to + consider packages for a single Python version and the solve completes quickly:: conda env create -f environment.yml @@ -89,10 +122,10 @@ Installation by Source Using Anaconda Environment for Unix-based Systems: Linux - nodefaults channel_priority: strict custom_channels: - main: null - r: null - anaconda: null - msys2: null + main: null + r: null + anaconda: null + msys2: null #. Activate conda environment :: From e71214d4a5fb987f05d7379a0dfebcd5247d3b31 Mon Sep 17 00:00:00 2001 From: Richard West Date: Thu, 14 May 2026 13:53:58 -0400 Subject: [PATCH 3/4] Edit the installation instructions (from source in Anaconda environment) Previous version written by Claude. These changes written by me. --- .../rmg/installation/anacondaDeveloper.rst | 45 ++++++------------- 1 file changed, 13 insertions(+), 32 deletions(-) diff --git a/documentation/source/users/rmg/installation/anacondaDeveloper.rst b/documentation/source/users/rmg/installation/anacondaDeveloper.rst index f983d5cb13..3424aca176 100644 --- a/documentation/source/users/rmg/installation/anacondaDeveloper.rst +++ b/documentation/source/users/rmg/installation/anacondaDeveloper.rst @@ -4,41 +4,27 @@ Installation by Source Using Anaconda Environment for Unix-based Systems: Linux and Mac OSX ******************************************************************************************* -.. warning:: - - **Before you begin — check your build tools are up to date.** +#. Before you begin — check your build tools are up to date. RMG-Py compiles Cython extensions during installation, so your C compiler and conda installation must be reasonably modern or the build will fail. - **On macOS:** Ensure your Xcode Command Line Tools are current. An outdated - installation (more than a year or two old) will cause ``make`` to fail with a - ``clang: error: invalid version number`` message. To check:: - - clang --version - - If the reported version is older than Apple clang 13, reinstall the tools:: + **On MacOS:** Ensure your Xcode Command Line Tools are current. If more than a year or two old, reinstall the tools:: sudo rm -rf /Library/Developer/CommandLineTools xcode-select --install - **conda version:** Ensure conda is version 24.0 or newer (run ``conda --version`` - to check). Older versions use a slower solver that can hang indefinitely when - creating the RMG environment. To update:: + **conda version:** Ensure conda is also up to date. To update:: conda update -n base -c conda-forge conda - If ``conda update`` does not advance the version, install a specific release - explicitly:: + If ``conda update`` does not advance the version (which can happen), install a specific release explicitly, e.g.:: conda install -n base -c conda-forge conda=26.3 -#. Install the `conda` package manager via `miniforge`, if you do not already have it (or Anaconda), by following the `Miniforge installation instructions `_. +#. If you do not already have the `conda` package manager (or Anaconda) then install it via `miniforge`, by following the `Miniforge installation instructions `_. -#. If your `conda` version is older than 23.10.0, manually switch the solver backend to `libmamba` (or update your conda):: - conda install -n base conda-libmamba-solver - conda config --set solver libmamba #. There are a few system-level dependencies which are required and should not be installed via Conda. These include `Git `_ for version control, `GNU Make `_, and the C and C++ compilers from the `GNU Compiler Collection (GCC) `_ for compiling RMG. @@ -69,7 +55,7 @@ Installation by Source Using Anaconda Environment for Unix-based Systems: Linux These are a set of packages relevant for software development which have been bundled together by Apple. The easiest way to install this is to simply run one of the commands in the terminal, e.g. ``git``. The terminal will then prompt you to install the Command Line Tools. - See the warning at the top of this page about keeping the tools up to date. + See the warning in step 1 about keeping the tools up to date. #. Install the latest versions of RMG and RMG-database through cloning the source code via Git. Make sure to start in an appropriate local directory where you want both RMG-Py and RMG-database folders to exist. @@ -93,8 +79,7 @@ Installation by Source Using Anaconda Environment for Unix-based Systems: Linux #. Create the conda environment for RMG-Py. - The ``environment.yml`` file pins Python 3.11, so the solver only needs to - consider packages for a single Python version and the solve completes quickly:: + To create an environment called ``rmg_env`` containing all that you need for RMG, run:: conda env create -f environment.yml @@ -102,17 +87,13 @@ Installation by Source Using Anaconda Environment for Unix-based Systems: Linux conda env create -f environment.yml -n rmg_env2 - If either of these commands return an error due to being unable to find the ``conda`` command, - try to either close and reopen your terminal to refresh your environment variables - or type the following command. - - If on Linux or pre-Catalina MacOS (or if you have a bash shell):: - - source ~/.bashrc + If you have a recent version of conda (``conda -V`` reports >= 26.3) then the preferred command is without the ``env`` subcommand:: - If on MacOS Catalina or later (or if you have a Z shell):: + conda create --file environment.yml --name rmg_env - source ~/.zshrc + If any of these commands return an error due to being unable to find the ``conda`` command, + (for example if you only just installed it) + then close and reopen your terminal (or log out and log in again) to refresh your environment variables. NOTE: You may wish to forbid ``conda`` from installing from the Anaconda channels due to licensing restrictions. The ``environment.yml`` file already forbids using default channels, but you may further add the file ``.condarc`` to your RMG-Py directory (or modify the ``.condarc`` in your home directory) with the following contents before running the ``conda env create`` command: :: @@ -152,7 +133,7 @@ Installation by Source Using Anaconda Environment for Unix-based Systems: Linux Installing Julia and ReactionMechanismSimulator.jl (RMS) will enable all the features in RMG that require RMS-based reactors, as well as using ``method='ode'`` when solving the Master Equation with Arkane. - Note that installing RMS can cause errors when running Cantera simulations; this should not affect normal RMG use, but if you wish to run Cantera simulations you will need to maintain a separate conda environment without RMS in it. + Note that installing RMS has sometimes caused errors when running Cantera; this should not affect normal RMG use, but if you wish to run Cantera simulations you might need to use a separate conda environment without RMS in it. Ensure that you have modified your environment variables as described above, and then run the following: :: From f7bd2f2abe2f17ae7ae69656d2cc91b1e5880d3c Mon Sep 17 00:00:00 2001 From: Richard West Date: Thu, 14 May 2026 16:08:50 -0400 Subject: [PATCH 4/4] Avoid telling people to sudo rm -rf anything. You just know someone is going to copy and paste that incorrectly into their terminal.... --- .../source/users/rmg/installation/anacondaDeveloper.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/documentation/source/users/rmg/installation/anacondaDeveloper.rst b/documentation/source/users/rmg/installation/anacondaDeveloper.rst index 3424aca176..5c5d208a62 100644 --- a/documentation/source/users/rmg/installation/anacondaDeveloper.rst +++ b/documentation/source/users/rmg/installation/anacondaDeveloper.rst @@ -9,9 +9,8 @@ Installation by Source Using Anaconda Environment for Unix-based Systems: Linux RMG-Py compiles Cython extensions during installation, so your C compiler and conda installation must be reasonably modern or the build will fail. - **On MacOS:** Ensure your Xcode Command Line Tools are current. If more than a year or two old, reinstall the tools:: + **On MacOS:** Ensure your Xcode Command Line Tools are current. If they are more than a year or two old, either download the latest Command Line Tools from `Apple Developer Downloads `_ (free Apple ID required) or remove them and reinstall them using:: - sudo rm -rf /Library/Developer/CommandLineTools xcode-select --install **conda version:** Ensure conda is also up to date. To update::