diff --git a/docs/installation.rst b/docs/installation.rst index 413e9cdcd..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). +**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: @@ -11,188 +12,76 @@ 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 ``miniforge`` (recommended) +Installation with ``micromamba`` (recommended) ---------------------------------------------- -.. _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: +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`` . -.. parsed-literal:: +If you prefer to use ``mamba`` or ``conda`` instead of ``micromamba`` because of its additional functionality, we suggest following our `Miniforge Installation Guide`_. - mamba create -n openfe_env openfe=\ |version| +In the instructions below, we will use the ``micromamba`` command, but you can use ``conda`` or ``mamba`` in the same way. -Now we need to activate our new environment :: +Once you have one of `micromamba `_, `mamba `_, or `conda `_ installed, you can continue to the **openfe** installation instructions below. - mamba activate openfe_env - -To quickly check this is working, run the tests :: +.. note:: - openfe test + After installing, you must run ``micromamba activate openfe`` in each shell session where you want to use **openfe**! -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 :: +Reproducible builds with a ``conda-lock`` file +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - openfe test --long +.. _conda-lock: https://github.com/conda/conda-lock?tab=readme-ov-file#conda-lock -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. +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. -With that, you should be ready to use ``openfe``! +Unlike the single file installer, an internet connection is required to install from a ``conda-lock`` file. -Installation with ``mamba`` ---------------------------- +The ``conda-lock`` files for the latest version of **openfe** can be downloaded with :: -If you already have a `Mamba `_ -(or `Micromamba `_ ) installation, you can install ``openfe`` with: + $ curl -LOJ https://github.com/OpenFreeEnergy/openfe/releases/latest/download/openfe-conda-lock.yml -.. parsed-literal:: +If a particular version is required, the URL will look like this (using the ``openfe 1.6.1`` release as an example) :: - mamba create -c conda-forge -n openfe_env openfe=\ |version| - mamba activate openfe_env + $ curl -LOJ https://github.com/OpenFreeEnergy/openfe/releases/download/v1.6.1/openfe-1.6.1-conda-lock.yml -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. +``micromamba`` supports ``conda-lock`` files and can be used directly to create a virtual environment :: -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. + $ 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 :: - - $ curl -LOJ https://github.com/OpenFreeEnergy/openfe/releases/latest/download/openfe-conda-lock.yml + $ micromamba activate conda-lock + $ conda-lock install -n openfe openfe-conda-lock.yml + $ micromamba activate openfe -If a particular version is required, the URL will look like this (using the ``openfe 1.0.1`` release as an example) :: +To make sure everything is working, :ref:`run the tests `. - $ curl -LOJ https://github.com/OpenFreeEnergy/openfe/releases/download/v1.0.1/openfe-1.0.1-conda-lock.yml +With that, you should be ready to use **openfe**! -Create a conda environment from the lock file and activate it:: +Standard Installation with ``micromamba`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - $ conda-lock install -n openfe openfe-conda-lock.yml - $ conda 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. -.. note:: +In these cases, you can simply install **openfe** from conda-forge: - 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 +.. 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 --------------------- @@ -215,7 +104,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 :: @@ -397,17 +286,9 @@ Now the CLI tool should work as well :: test Run the OpenFE test suite +To make sure everything is working, :ref:`run the tests `. - -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``! +With that, you should be ready to use **openfe**! .. _installation:containers: @@ -415,7 +296,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 @@ -457,31 +338,29 @@ 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 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``! +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 ---------------- 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. @@ -492,8 +371,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. @@ -596,24 +475,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 @@ -623,9 +502,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:: @@ -634,6 +513,31 @@ Finally, create the editable installation:: Note the ``.`` at the end of that command, which indicates the current directory. + +.. _testing: + +Testing Your Installation +------------------------- + +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, and so subsequent calls to ``openfe`` will be faster. + +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 --------------------------------- @@ -692,3 +596,82 @@ 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. 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:** + +*