From bfccc835f9ba87deccebc258e76dd303b0fff1ce Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Fri, 21 Nov 2025 14:22:01 -0800 Subject: [PATCH 01/14] updating install recommendations to prioritize miniconda and conda-lock --- docs/installation.rst | 141 ++++++++++++++++++++++-------------------- 1 file changed, 74 insertions(+), 67 deletions(-) diff --git a/docs/installation.rst b/docs/installation.rst index 413e9cdcd..1e56fb556 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -13,10 +13,82 @@ Additionally, if you want to use NAGL to assign partial charges, you must use `` When you install ``openfe`` through any of the methods described below, you will install both the core library and the command line interface (CLI). - -Installation with ``miniforge`` (recommended) +Installation with ``micromamba`` (recommended) ---------------------------------------------- +OpenFE recommends the `mamba` (and the more lightweight `micromamba`) package manager for most users, as it is orders of magnitude faster than the default `conda` package manager. +`mamba` is a drop-in replacement for `conda`, and + +Once you have one of `micromamba `_, + `mamba `_, + or `conda `_ installed, + you can install ``openfe`` with: + +.. parsed-literal:: + + micromamba create -c conda-forge -n openfe_env openfe=\ |version| + micromamba activate openfe_env + +Note that you must run the latter line in each shell session where you want to use ``openfe``. + +Reproducible builds with a ``conda-lock`` file +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. _conda-lock: https://github.com/conda/conda-lock?tab=readme-ov-file#conda-lock + +We recommend the use of a ``conda-lock`` file when the same conda environment is required across different systems. + +A `conda-lock`_ file is a cross-platform way of specifying a conda environment to build packages in a reproducible way. +Unlike the single file installer, an internet connection is required to install from a ``conda-lock`` file. + + +.. note:: + + You will likely need to install ``conda-lock``. + We strongly recommend installing ``conda-lock`` in a new virtual environment. + This will reduce the chance of dependency conflicts :: + + $ # Install conda lock into a virtual environment + $ conda create -n conda-lock -c conda-lock + $ # Activate the environment to use the conda-lock command + $ conda activate conda-lock + +See https://github.com/conda/conda-lock?tab=readme-ov-file#conda-lock for more information on ``conda-lock``. + +The latest version of the `conda-lock` file we provide can be downloaded with :: + + $ curl -LOJ https://github.com/OpenFreeEnergy/openfe/releases/latest/download/openfe-conda-lock.yml + +If a particular version is required, the URL will look like this (using the ``openfe 1.0.1`` release as an example) :: + + $ curl -LOJ https://github.com/OpenFreeEnergy/openfe/releases/download/v1.0.1/openfe-1.0.1-conda-lock.yml + +Create a conda environment from the lock file and activate it:: + + $ conda-lock install -n openfe openfe-conda-lock.yml + $ conda activate openfe + +.. note:: + + micromamba also supports ``conda-lock`` files and can be used to create a virtual environment :: + + $ micromamba create -n openfe --file openfe-conda-lock.yml + $ micromamba activate openfe + +To make sure everything is working, run the tests :: + + $ pytest --pyargs openfe openfecli + +The test suite contains several hundred individual tests. This will take a +few minutes, and all tests should complete with status either passed, +skipped, or xfailed (expected fail). + +With that, you should be ready to use ``openfe``! + + +Installation with ``miniforge`` +------------------------------- + .. _Miniforge: https://github.com/conda-forge/miniforge?tab=readme-ov-file#miniforge We recommend installing ``openfe`` with `Miniforge`_ because it provides easy @@ -128,71 +200,6 @@ hardware intended to run openfe jobs, as it will test GPU specific features. With that, you should be ready to use ``openfe``! -Installation with ``mamba`` ---------------------------- - -If you already have a `Mamba `_ -(or `Micromamba `_ ) installation, you can install ``openfe`` with: - -.. parsed-literal:: - - mamba create -c conda-forge -n openfe_env openfe=\ |version| - mamba activate openfe_env - -Note that you must run the latter line in each shell session where you want to use ``openfe``. OpenFE recommends the Mamba package manager for most users as it is orders of magnitude faster than the default Conda package manager. Mamba is a drop in replacement for Conda. - -Reproducible builds with a ``conda-lock`` file -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. _conda-lock: https://github.com/conda/conda-lock?tab=readme-ov-file#conda-lock - -A `conda-lock`_ file is a cross-platform way of specifying a conda environment to build packages in a reproducible way. -Unlike the single file installer, an internet connection is required to install from a ``conda-lock`` file. -We recommend the use of a ``conda-lock`` file when the same conda environment is required across different systems. - - -.. note:: - - You will likely need to install ``conda-lock``. - We strongly recommend installing ``conda-lock`` in a new virtual environment. - This will reduce the chance of dependency conflicts :: - - $ # Install conda lock into a virtual environment - $ conda create -n conda-lock -c conda-lock - $ # Activate the environment to use the conda-lock command - $ conda activate conda-lock - -See https://github.com/conda/conda-lock?tab=readme-ov-file#conda-lock for more information on ``conda-lock``. - -The latest version of the `conda-lock` file we provide can be downloaded with :: - - $ curl -LOJ https://github.com/OpenFreeEnergy/openfe/releases/latest/download/openfe-conda-lock.yml - -If a particular version is required, the URL will look like this (using the ``openfe 1.0.1`` release as an example) :: - - $ curl -LOJ https://github.com/OpenFreeEnergy/openfe/releases/download/v1.0.1/openfe-1.0.1-conda-lock.yml - -Create a conda environment from the lock file and activate it:: - - $ conda-lock install -n openfe openfe-conda-lock.yml - $ conda activate openfe - -.. note:: - - micromamba also supports ``conda-lock`` files and can be used to create a virtual environment :: - - $ micromamba create -n openfe --file openfe-conda-lock.yml - $ micromamba activate openfe - -To make sure everything is working, run the tests :: - - $ pytest --pyargs openfe openfecli - -The test suite contains several hundred individual tests. This will take a -few minutes, and all tests should complete with status either passed, -skipped, or xfailed (expected fail). - -With that, you should be ready to use ``openfe``! Single file installer --------------------- From 0f4f7c345e5386b6a78aa3f177f4c86314a1d444 Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Mon, 24 Nov 2025 07:37:01 -0800 Subject: [PATCH 02/14] fix formatting --- docs/installation.rst | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/installation.rst b/docs/installation.rst index 1e56fb556..ce396ff89 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -19,10 +19,7 @@ Installation with ``micromamba`` (recommended) OpenFE recommends the `mamba` (and the more lightweight `micromamba`) package manager for most users, as it is orders of magnitude faster than the default `conda` package manager. `mamba` is a drop-in replacement for `conda`, and -Once you have one of `micromamba `_, - `mamba `_, - or `conda `_ installed, - you can install ``openfe`` with: +Once you have one of `micromamba `_, `mamba `_, or `conda `_ installed, you can install ``openfe`` with: .. parsed-literal:: From d18df87d372e22617bb05721acf1c0c15809b9a5 Mon Sep 17 00:00:00 2001 From: Alyssa Travitz <31974495+atravitz@users.noreply.github.com> Date: Mon, 24 Nov 2025 10:39:10 -0800 Subject: [PATCH 03/14] Update docs/installation.rst Co-authored-by: Mike Henry <11765982+mikemhenry@users.noreply.github.com> --- docs/installation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/installation.rst b/docs/installation.rst index ce396ff89..3e1c3b320 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -19,7 +19,7 @@ Installation with ``micromamba`` (recommended) OpenFE recommends the `mamba` (and the more lightweight `micromamba`) package manager for most users, as it is orders of magnitude faster than the default `conda` package manager. `mamba` is a drop-in replacement for `conda`, and -Once you have one of `micromamba `_, `mamba `_, or `conda `_ installed, you can install ``openfe`` with: +once you have one of `micromamba `_, `mamba `_, or `conda `_ installed, you can install ``openfe`` with: .. parsed-literal:: From 90440e2eeaef93e698abfd1b0ac74f7ef41b970d Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Mon, 24 Nov 2025 16:53:12 -0800 Subject: [PATCH 04/14] recommend openfe test --- docs/installation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/installation.rst b/docs/installation.rst index 3e1c3b320..6cf830568 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -74,7 +74,7 @@ Create a conda environment from the lock file and activate it:: To make sure everything is working, run the tests :: - $ pytest --pyargs openfe openfecli + $ openfe test The test suite contains several hundred individual tests. This will take a few minutes, and all tests should complete with status either passed, From 45fe98c2f8a8fb37d5bd10b7c82a32cb3c077063 Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Mon, 24 Nov 2025 16:56:29 -0800 Subject: [PATCH 05/14] remove miniforge --- docs/installation.rst | 116 ------------------------------------------ 1 file changed, 116 deletions(-) diff --git a/docs/installation.rst b/docs/installation.rst index 6cf830568..ae328b5ab 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -82,122 +82,6 @@ skipped, or xfailed (expected fail). With that, you should be ready to use ``openfe``! - -Installation with ``miniforge`` -------------------------------- - -.. _Miniforge: https://github.com/conda-forge/miniforge?tab=readme-ov-file#miniforge - -We recommend installing ``openfe`` with `Miniforge`_ because it provides easy -installation of other software that ``openfe`` needs, such as OpenMM and -AmberTools. We recommend ``miniforge`` because it is faster than ``conda`` and -comes preconfigured to use ``conda-forge``. - -To install and configure ``miniforge``, you need to know your operating -system, your machine architecture (output of ``uname -m``), and your shell -(in most cases, can be determined from ``echo $SHELL``). Select -your operating system and architecture from the tool below, and run the -commands it suggests. - -.. raw:: html - - - - -
-
- - -You should then close your current session and open a fresh login to ensure -that everything is properly registered. - -Next we will create an environment called ``openfe_env`` with the ``openfe`` package and all required dependencies: - -.. parsed-literal:: - - mamba create -n openfe_env openfe=\ |version| - -Now we need to activate our new environment :: - - mamba activate openfe_env - -To quickly check this is working, run the tests :: - - openfe test - -The very first time you run this, the -initial check that you can import ``openfe`` will take a while, because some -code is compiled the first time it is encountered. That compilation only -happens once per installation. - -A more expansive test suite can be run using :: - - openfe test --long - -This test suite contains several hundred individual tests. This may take up to -an hour, and all tests should complete with status either passed, -skipped, or xfailed (expected fail). -This "long" test suite should be run as a job on the compute -hardware intended to run openfe jobs, as it will test GPU specific features. - -With that, you should be ready to use ``openfe``! - - Single file installer --------------------- From 8a0125ea1d3ea47ed28a96f87282eb6675fd3b01 Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Mon, 24 Nov 2025 17:39:06 -0800 Subject: [PATCH 06/14] update language and clean up install instructions --- docs/installation.rst | 104 +++++++++++++++++++++--------------------- 1 file changed, 53 insertions(+), 51 deletions(-) diff --git a/docs/installation.rst b/docs/installation.rst index ae328b5ab..580db293b 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -11,76 +11,78 @@ We try to follow `SPEC0 `_ as fa Note that following SPEC0 means that Python 3.10 support is no longer actively maintained as of ``openfe 1.6.0``. Additionally, if you want to use NAGL to assign partial charges, you must use ``python >= 3.11``. -When you install ``openfe`` through any of the methods described below, you will install both the core library and the command line interface (CLI). +When you install **openfe** through any of the methods described below, you will install both the core library and the command line interface (CLI). Installation with ``micromamba`` (recommended) ---------------------------------------------- -OpenFE recommends the `mamba` (and the more lightweight `micromamba`) package manager for most users, as it is orders of magnitude faster than the default `conda` package manager. -`mamba` is a drop-in replacement for `conda`, and +OpenFE recommends ``mamba`` (and the more lightweight ``micromamba``) as a package manager for most users. +``mamba`` is drop-in replacement for ``conda`` and is orders of magnitude faster than the default ``conda`` package manager. +In the instructions below, we will use the ``micromamba`` command, but you can use ``conda`` or ``mamba`` in the same way. -once you have one of `micromamba `_, `mamba `_, or `conda `_ installed, you can install ``openfe`` with: +Once you have one of `micromamba `_, `mamba `_, or `conda `_ installed, you can continue to the **openfe** installation instructions below. -.. parsed-literal:: - - micromamba create -c conda-forge -n openfe_env openfe=\ |version| - micromamba activate openfe_env - -Note that you must run the latter line in each shell session where you want to use ``openfe``. Reproducible builds with a ``conda-lock`` file ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. _conda-lock: https://github.com/conda/conda-lock?tab=readme-ov-file#conda-lock -We recommend the use of a ``conda-lock`` file when the same conda environment is required across different systems. +We recommend building from **openfe**'s ``conda-lock`` file in most cases, since it allows for building packages in a reproducible way on multiple platforms. -A `conda-lock`_ file is a cross-platform way of specifying a conda environment to build packages in a reproducible way. Unlike the single file installer, an internet connection is required to install from a ``conda-lock`` file. +The ``conda-lock`` files for the latest version of **openfe** can be downloaded with :: + + $ curl -LOJ https://github.com/OpenFreeEnergy/openfe/releases/latest/download/openfe-conda-lock.yml + +If a particular version is required, the URL will look like this (using the ``openfe 1.6.1`` release as an example) :: + + $ curl -LOJ https://github.com/OpenFreeEnergy/openfe/releases/download/v1.6.1/openfe-1.6.1-conda-lock.yml + +``micromamba`` supports ``conda-lock`` files and can be used directly to create a virtual environment :: + + $ micromamba create -n openfe --file openfe-conda-lock.yml + $ micromamba activate openfe + .. note:: - You will likely need to install ``conda-lock``. - We strongly recommend installing ``conda-lock`` in a new virtual environment. + If you are having trouble building from the conda-lock file, you may need to build directly with ``conda-lock``. + We recommend installing ``conda-lock`` in a new virtual environment. This will reduce the chance of dependency conflicts :: $ # Install conda lock into a virtual environment - $ conda create -n conda-lock -c conda-lock + $ micromamba create -n conda-lock conda-lock $ # Activate the environment to use the conda-lock command - $ conda activate conda-lock - -See https://github.com/conda/conda-lock?tab=readme-ov-file#conda-lock for more information on ``conda-lock``. - -The latest version of the `conda-lock` file we provide can be downloaded with :: + $ micromamba activate conda-lock + $ conda-lock install -n openfe openfe-conda-lock.yml + $ micromamba activate openfe - $ curl -LOJ https://github.com/OpenFreeEnergy/openfe/releases/latest/download/openfe-conda-lock.yml +To make sure everything is working, run the tests :: -If a particular version is required, the URL will look like this (using the ``openfe 1.0.1`` release as an example) :: + $ openfe test - $ curl -LOJ https://github.com/OpenFreeEnergy/openfe/releases/download/v1.0.1/openfe-1.0.1-conda-lock.yml -Create a conda environment from the lock file and activate it:: +The test suite contains several hundred individual tests. +This will take a few minutes, and all tests should complete with status either passed, skipped, or xfailed (expected fail). - $ conda-lock install -n openfe openfe-conda-lock.yml - $ conda activate openfe +Note that you must run ``micromamba activate openfe`` in each shell session where you want to use **openfe**. -.. note:: +With that, you should be ready to use **openfe**! - micromamba also supports ``conda-lock`` files and can be used to create a virtual environment :: +Standard Installation with ``micromamba`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - $ micromamba create -n openfe --file openfe-conda-lock.yml - $ micromamba activate openfe +There may be some instances where you don't want to use a lock-file, e.g. you may want to specify a dependency that differs from the lock file. -To make sure everything is working, run the tests :: +In these cases, you can simply install **openfe** from conda-forge: - $ openfe test +.. parsed-literal:: -The test suite contains several hundred individual tests. This will take a -few minutes, and all tests should complete with status either passed, -skipped, or xfailed (expected fail). + micromamba create -c conda-forge -n openfe openfe=\ |version| + micromamba activate openfe -With that, you should be ready to use ``openfe``! Single file installer --------------------- @@ -103,7 +105,7 @@ And the MacOS (arm64) installer :: MacOS x86_64 is no longer supported. -The single file installer contains all of the dependencies required for ``openfe`` and does not require internet access to use. +The single file installer contains all of the dependencies required for **openfe** and does not require internet access to use. Both ``conda`` and ``mamba`` are also available in the environment created by the single file installer and can be used to install additional packages. The installer can be installed in batch mode or interactively :: @@ -295,7 +297,7 @@ The test suite contains several hundred individual tests. This will take a few minutes, and all tests should complete with status either passed, skipped, or xfailed (expected fail). -With that, you should be ready to use ``openfe``! +With that, you should be ready to use **openfe**! .. _installation:containers: @@ -303,7 +305,7 @@ Containerized Distributions ---------------------------- We provide an official docker and Apptainer (formerly Singularity) image. -The docker image is tagged with the version of ``openfe`` on the image and can be pulled with :: +The docker image is tagged with the version of **openfe** on the image and can be pulled with :: $ docker pull ghcr.io/openfreeenergy/openfe:latest @@ -345,7 +347,7 @@ This can be done with the following command :: The ``--nv`` flag is required for the Apptainer image to access the GPU on the host. Your output may produce different values for the forces, but should list the CUDA platform if everything is working properly. -You can access the ``openfe`` CLI from the Singularity image with :: +You can access the **openfe** CLI from the Singularity image with :: $ singularity run --nv openfe_latest-apptainer.sif openfe --help @@ -357,7 +359,7 @@ The test suite contains several hundred individual tests. This will take a few minutes, and all tests should complete with status either passed, skipped, or xfailed (expected fail). -With that, you should be ready to use ``openfe``! +With that, you should be ready to use **openfe**! .. note:: @@ -369,7 +371,7 @@ HPC Environments When using High Performance Computing resources, jobs are typically submitted to a queue from a "login node" and then run at a later time, often on different hardware and in a different software environment. This can complicate installation as getting something working on the login node does not guarantee it will work in the job. -We recommend using `Apptainer (formerly Singularity) `_ when running ``openfe`` workflows in HPC environments. +We recommend using `Apptainer (formerly Singularity) `_ when running **openfe** workflows in HPC environments. This images provide a software environment that is isolated from the host which can make workflow execution easier to setup and more reproducible. See our guide on :ref:`containers ` for how to get started using Apptainer/Singularity. @@ -380,8 +382,8 @@ See our guide on :ref:`containers ` for how to get star .. _virtual packages: https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-virtual.html#managing-virtual-packages -We recommend using a :ref:`container ` to install ``openfe`` in HPC environments. -Nonetheless, ``openfe`` can be installed via Conda Forge on these environments also. +We recommend using a :ref:`container ` to install **openfe** in HPC environments. +Nonetheless, **openfe** can be installed via Conda Forge on these environments also. Conda Forge distributes its own CUDA binaries for interfacing with the GPU, rather than use the host drivers. ``conda``, ``mamba`` and ``micromamba`` all use `virtual packages`_ to detect and specify which version of CUDA should be installed. This is a common point of difference in hardware between the login and job nodes in an HPC environment. @@ -484,24 +486,24 @@ For example :: in this output of ``nvidia-smi`` we can see in the upper right of the output ``CUDA Version: 11.7`` which means the installed driver will support a ``cudatoolkit`` version up to ``11.7`` So on the login node, we can run ``CONDA_OVERRIDE_CUDA=11.7 mamba info`` and see that the "correct" virtual CUDA is listed. -For example, to install a version of ``openfe`` which is compatible with ``cudatoolkit 11.7``, run: +For example, to install a version of **openfe** which is compatible with ``cudatoolkit 11.7``, run: .. parsed-literal:: - $ CONDA_OVERRIDE_CUDA=11.7 mamba create -n openfe_env openfe=\ |version| + $ CONDA_OVERRIDE_CUDA=11.7 mamba create -n openfe openfe=\ |version| Developer install ----------------- -If you're going to be developing for ``openfe``, you will want an +If you're going to be developing for **openfe**, you will want an installation where your changes to the code are immediately reflected in the functionality. This is called a "developer" or "editable" installation. -Getting a developer installation for ``openfe`` first installing the +Getting a developer installation for **openfe** first installing the requirements, and then creating the editable installation. We recommend doing that with ``mamba`` using the following procedure: -First, clone the ``openfe`` repository, and switch into its root directory:: +First, clone the **openfe** repository, and switch into its root directory:: $ git clone https://github.com/OpenFreeEnergy/openfe.git $ cd openfe @@ -511,9 +513,9 @@ specification in that directory:: $ mamba create -f environment.yml -Then activate the ``openfe`` environment with:: +Then activate the **openfe** environment with:: - $ mamba activate openfe_env + $ mamba activate openfe Finally, create the editable installation:: From f06b56e28c6d1a63f1c4bdca5047adcbedf29afc Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Mon, 24 Nov 2025 18:02:26 -0800 Subject: [PATCH 07/14] add link --- docs/installation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/installation.rst b/docs/installation.rst index 580db293b..1b203687e 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -1,7 +1,7 @@ Installation ============ -**openfe** is currently only compatible with POSIX systems (macOS and UNIX/Linux). +**openfe** is currently only compatible with POSIX systems (macOS and UNIX/Linux). See `Supported Hardware`_ for more details. We try to follow `SPEC0 `_ as far as minimum supported dependencies, with the following caveats: From c935c0aa749494c92dac8ecfe185e9ee882e434a Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Mon, 24 Nov 2025 18:04:27 -0800 Subject: [PATCH 08/14] adding news item --- news/install_docs.rst | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 news/install_docs.rst diff --git a/news/install_docs.rst b/news/install_docs.rst new file mode 100644 index 000000000..37637a28e --- /dev/null +++ b/news/install_docs.rst @@ -0,0 +1,23 @@ +**Added:** + +* + +**Changed:** + +* Updated installation docs to recommend ``miniconda`` with ``conda-lock`` as the preferred installation method (PR #1692). + +**Deprecated:** + +* + +**Removed:** + +* + +**Fixed:** + +* + +**Security:** + +* From 31e0a6122f34b306f2921015354a9d293e9e83fc Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Mon, 24 Nov 2025 18:15:10 -0800 Subject: [PATCH 09/14] add back miniforge instructions at the end --- docs/installation.rst | 90 +++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 86 insertions(+), 4 deletions(-) diff --git a/docs/installation.rst b/docs/installation.rst index 1b203687e..76876c23f 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -16,8 +16,10 @@ When you install **openfe** through any of the methods described below, you will Installation with ``micromamba`` (recommended) ---------------------------------------------- -OpenFE recommends ``mamba`` (and the more lightweight ``micromamba``) as a package manager for most users. -``mamba`` is drop-in replacement for ``conda`` and is orders of magnitude faster than the default ``conda`` package manager. +OpenFE recommends ``micromamba`` as a package manager for most users, as it is a lightweight version of ``mamba``, which is a must faster drop-in replacement for ``conda`` . + +If you prefer to use ``mamba`` or ``conda`` instead of ``micromamba`` because of its additional functionality, we suggest following our `Miniforge Installation Guide`_. + In the instructions below, we will use the ``micromamba`` command, but you can use ``conda`` or ``mamba`` in the same way. Once you have one of `micromamba `_, `mamba `_, or `conda `_ installed, you can continue to the **openfe** installation instructions below. @@ -67,7 +69,7 @@ To make sure everything is working, run the tests :: The test suite contains several hundred individual tests. This will take a few minutes, and all tests should complete with status either passed, skipped, or xfailed (expected fail). -Note that you must run ``micromamba activate openfe`` in each shell session where you want to use **openfe**. +Note that you must run ``micromamba activate openfe`` in each shell session where you want to use **openfe**. With that, you should be ready to use **openfe**! @@ -364,7 +366,7 @@ With that, you should be ready to use **openfe**! .. note:: If building a custom docker image, you may need to need to add ``--ulimit nofile=262144:262144`` to the ``docker build`` command. - See this `issue `_ for details. + See this `issue `_ for details. HPC Environments ---------------- @@ -582,3 +584,83 @@ While OpenMM supports OpenCL, we do not regularly test that platform (the CUDA p For production use, we recommend the ``linux-64`` platform with NVIDIA GPUs for optimal performance. When using an OpenMM based protocol on NVIDIA GPUs, we recommend driver version ``525.60.13`` or greater. The minimum driver version required when installing from conda-forge is ``450.36.06``, but newer versions of OpenMM may not support that driver version as CUDA 11 will be removed the build matrix. + + +Miniforge Installation Guide +---------------------------- + +.. _Miniforge: https://github.com/conda-forge/miniforge?tab=readme-ov-file#miniforge + +`Miniforge`_ provides minimal installers for either ``conda`` or ``mamba``, and enables easy installation of other software that ``openfe`` needs, such as OpenMM and AmberTools. +We recommend using ``miniforge`` to install ``mamaba`` because it is faster than ``conda`` and comes preconfigured to use ``conda-forge``. + +To install and configure ``miniforge``, you need to know your operating system, your machine architecture (output of ``uname -m``), and your shell (in most cases, can be determined from ``echo $SHELL``). +Select your operating system and architecture from the tool below, and run the commands it suggests. + +.. raw:: html + + + + +
+
+ + +You should then close your current session and open a fresh login to ensure +that everything is properly registered. +You can now proceed to use ``mamba`` commands as instructed above. From b0dcd91389df72ee0f4f6624f319876c6b29efa2 Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Mon, 24 Nov 2025 18:25:29 -0800 Subject: [PATCH 10/14] make testing its own section --- docs/installation.rst | 55 ++++++++++++++++++++++++++----------------- 1 file changed, 33 insertions(+), 22 deletions(-) diff --git a/docs/installation.rst b/docs/installation.rst index 76876c23f..f31fa28bd 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -25,6 +25,11 @@ In the instructions below, we will use the ``micromamba`` command, but you can u Once you have one of `micromamba `_, `mamba `_, or `conda `_ installed, you can continue to the **openfe** installation instructions below. + .. note:: + + After installing, you must run ``micromamba activate openfe`` in each shell session where you want to use **openfe**! + + Reproducible builds with a ``conda-lock`` file ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -61,15 +66,7 @@ If a particular version is required, the URL will look like this (using the ``op $ conda-lock install -n openfe openfe-conda-lock.yml $ micromamba activate openfe -To make sure everything is working, run the tests :: - - $ openfe test - - -The test suite contains several hundred individual tests. -This will take a few minutes, and all tests should complete with status either passed, skipped, or xfailed (expected fail). - -Note that you must run ``micromamba activate openfe`` in each shell session where you want to use **openfe**. +To make sure everything is working, `run the tests `_. With that, you should be ready to use **openfe**! @@ -289,15 +286,7 @@ Now the CLI tool should work as well :: test Run the OpenFE test suite - - -To make sure everything is working, run the tests :: - - $ pytest --pyargs openfe openfecli - -The test suite contains several hundred individual tests. This will take a -few minutes, and all tests should complete with status either passed, -skipped, or xfailed (expected fail). +To make sure everything is working, `run the tests `_. :: With that, you should be ready to use **openfe**! @@ -355,11 +344,9 @@ You can access the **openfe** CLI from the Singularity image with :: To make sure everything is working, run the tests :: - $ singularity run --nv openfe_latest-apptainer.sif pytest --pyargs openfe openfecli + $ singularity run --nv openfe_latest-apptainer.sif openfe test -The test suite contains several hundred individual tests. This will take a -few minutes, and all tests should complete with status either passed, -skipped, or xfailed (expected fail). +You can also run the long tests with ``openfe test --long``, as explained in `Testing Your Installation`_. With that, you should be ready to use **openfe**! @@ -526,6 +513,30 @@ Finally, create the editable installation:: Note the ``.`` at the end of that command, which indicates the current directory. + +.. testing: + +Testing Your Installation +------------------------- + + $ openfe test + + +The test suite contains several hundred individual tests. +This will take a few minutes, and all tests should complete with status either passed, skipped, or xfailed (expected fail). + +The very first time you run this, the initial check that you can import ``openfe`` will take a while, because some code is compiled the first time it is encountered. +That compilation only happens once per installation. + +A more expansive test suite can be run using :: + + openfe test --long + +This test suite contains several hundred individual tests. +This may take up to an hour, and all tests should complete with status either passed, skipped, or xfailed (expected fail). +This "long" test suite should be run as a job on the compute hardware intended to run openfe jobs, as it will test GPU specific features. + + Troubleshooting Your Installation --------------------------------- From 6148e97df3f778536d4192db24fbd078a0829577 Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Mon, 24 Nov 2025 18:32:38 -0800 Subject: [PATCH 11/14] clearer language and formatting --- docs/installation.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/installation.rst b/docs/installation.rst index f31fa28bd..128212432 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -24,10 +24,9 @@ In the instructions below, we will use the ``micromamba`` command, but you can u Once you have one of `micromamba `_, `mamba `_, or `conda `_ installed, you can continue to the **openfe** installation instructions below. +.. note:: - .. note:: - - After installing, you must run ``micromamba activate openfe`` in each shell session where you want to use **openfe**! + After installing, you must run ``micromamba activate openfe`` in each shell session where you want to use **openfe**! Reproducible builds with a ``conda-lock`` file @@ -66,7 +65,7 @@ If a particular version is required, the URL will look like this (using the ``op $ conda-lock install -n openfe openfe-conda-lock.yml $ micromamba activate openfe -To make sure everything is working, `run the tests `_. +To make sure everything is working, `run the tests <_testing>`_. With that, you should be ready to use **openfe**! @@ -286,7 +285,7 @@ Now the CLI tool should work as well :: test Run the OpenFE test suite -To make sure everything is working, `run the tests `_. :: +To make sure everything is working, `run the tests <_testing>`_. With that, you should be ready to use **openfe**! @@ -514,19 +513,20 @@ Note the ``.`` at the end of that command, which indicates the current directory. -.. testing: +.. _testing: Testing Your Installation ------------------------- - $ openfe test +After installing **openfe**, make sure everything is working as expected by running the test suite with: + $ openfe test The test suite contains several hundred individual tests. This will take a few minutes, and all tests should complete with status either passed, skipped, or xfailed (expected fail). The very first time you run this, the initial check that you can import ``openfe`` will take a while, because some code is compiled the first time it is encountered. -That compilation only happens once per installation. +That compilation only happens once per installation, and so subsequent calls to ``openfe`` will be faster. A more expansive test suite can be run using :: From 895aba14b6506049adc3bde8224ad66abd7f4733 Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Mon, 24 Nov 2025 18:36:41 -0800 Subject: [PATCH 12/14] why is rst like this --- docs/installation.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/installation.rst b/docs/installation.rst index 128212432..b79938284 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -65,7 +65,7 @@ If a particular version is required, the URL will look like this (using the ``op $ conda-lock install -n openfe openfe-conda-lock.yml $ micromamba activate openfe -To make sure everything is working, `run the tests <_testing>`_. +To make sure everything is working, :ref:`run the tests `. With that, you should be ready to use **openfe**! @@ -285,7 +285,7 @@ Now the CLI tool should work as well :: test Run the OpenFE test suite -To make sure everything is working, `run the tests <_testing>`_. +To make sure everything is working, :ref:`run the tests `. With that, you should be ready to use **openfe**! @@ -530,7 +530,7 @@ That compilation only happens once per installation, and so subsequent calls to A more expansive test suite can be run using :: - openfe test --long + $ openfe test --long This test suite contains several hundred individual tests. This may take up to an hour, and all tests should complete with status either passed, skipped, or xfailed (expected fail). From e36b721b035737eac63d26fd926b8bcf6930f799 Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Mon, 24 Nov 2025 18:39:49 -0800 Subject: [PATCH 13/14] why is rst like this?? --- docs/installation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/installation.rst b/docs/installation.rst index b79938284..9a2e2c3a5 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -518,7 +518,7 @@ directory. Testing Your Installation ------------------------- -After installing **openfe**, make sure everything is working as expected by running the test suite with: +After installing **openfe**, make sure everything is working as expected by running the test suite with :: $ openfe test From 008b042be1e641d607fd179bb61d59cc37ff6675 Mon Sep 17 00:00:00 2001 From: Alyssa Travitz <31974495+atravitz@users.noreply.github.com> Date: Mon, 1 Dec 2025 10:13:10 -0800 Subject: [PATCH 14/14] one sentence per line! Co-authored-by: Mike Henry <11765982+mikemhenry@users.noreply.github.com> --- docs/installation.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/installation.rst b/docs/installation.rst index 9a2e2c3a5..18a03aacf 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -1,7 +1,8 @@ Installation ============ -**openfe** is currently only compatible with POSIX systems (macOS and UNIX/Linux). See `Supported Hardware`_ for more details. +**openfe** is currently only compatible with POSIX systems (macOS and UNIX/Linux). +See `Supported Hardware`_ for more details. We try to follow `SPEC0 `_ as far as minimum supported dependencies, with the following caveats: @@ -672,6 +673,5 @@ Select your operating system and architecture from the tool below, and run the c setArchitectureOptions("Linux"); // default -You should then close your current session and open a fresh login to ensure -that everything is properly registered. +You should then close your current session and open a fresh login to ensure that everything is properly registered. You can now proceed to use ``mamba`` commands as instructed above.