diff --git a/.trunk/trunk.yaml b/.trunk/trunk.yaml index 882aad83..53c261b5 100644 --- a/.trunk/trunk.yaml +++ b/.trunk/trunk.yaml @@ -40,7 +40,7 @@ lint: - linters: [prettier] paths: - examples/Advanced_Sampling_Introduction.md - - examples/Install_PySAGES_Environment.md + - examples/Installing_a_PySAGES_Environment.md - examples/openmm/Harmonic_Bias.md - examples/hoomd-blue/ann/Butane_ANN.md - examples/hoomd-blue/harmonic_bias/Harmonic_Bias.md @@ -54,7 +54,7 @@ lint: - linters: [black] paths: - examples/Advanced_Sampling_Introduction.ipynb - - examples/Install_PySAGES_Environment.ipynb + - examples/Installing_a_PySAGES_Environment.ipynb - examples/openmm/Harmonic_Bias.ipynb - examples/hoomd-blue/ann/Butane_ANN.ipynb - examples/hoomd-blue/harmonic_bias/Harmonic_Bias.ipynb diff --git a/README.md b/README.md index b468311d..ff8b3083 100644 --- a/README.md +++ b/README.md @@ -81,4 +81,4 @@ page](https://docs.trunk.io/docs). [Colab Badge]: https://colab.research.google.com/assets/colab-badge.svg -[Install Notebook]: https://colab.research.google.com/github/SSAGESLabs/PySAGES/blob/main/examples/Install_PySAGES_Environment.ipynb +[Install Notebook]: https://colab.research.google.com/github/SSAGESLabs/PySAGES/blob/main/examples/Installing_a_PySAGES_Environment.ipynb diff --git a/docs/source/installation.md b/docs/source/installation.md index 6736dcb6..ee10d67b 100644 --- a/docs/source/installation.md +++ b/docs/source/installation.md @@ -42,4 +42,4 @@ and OpenMM can be built and installed in such an environment: [Install Notebook] -[Install Notebook]: https://colab.research.google.com/github/SSAGESLabs/PySAGES/blob/main/examples/Install_PySAGES_Environment.ipynb +[Install Notebook]: https://colab.research.google.com/github/SSAGESLabs/PySAGES/blob/main/examples/Installing_a_PySAGES_Environment.ipynb diff --git a/examples/Install_PySAGES_Environment.md b/examples/Install_PySAGES_Environment.md deleted file mode 100644 index 50a79ecc..00000000 --- a/examples/Install_PySAGES_Environment.md +++ /dev/null @@ -1,321 +0,0 @@ ---- -jupyter: - jupytext: - formats: ipynb,md - main_language: python - text_representation: - extension: .md - format_name: markdown - format_version: '1.3' - jupytext_version: 1.16.4 - kernelspec: - display_name: Python 3 - name: python3 ---- - - - - - -# Installation of the environment - - - - - -First, we are setting up our environment, by installing HOOMD-blue and installing the dlext plugin for it. The first step is to update cmake to a version that is compatible with our installation process. In this case, we are using a newer version of CMake that is required by the HOOMD-dlext plugin. -This is special to the underlying (older) Ubuntu system of this Colab (18.04) and should not be required for newer installations. - - - - - -# Update CMake - - - -```bash id="anZqRa7pxGpK" - -wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc 2> /dev/null | gpg --dearmor - | tee /usr/share/keyrings/kitware-archive-keyring.gpg > /dev/null -echo 'deb [signed-by=/usr/share/keyrings/kitware-archive-keyring.gpg] https://apt.kitware.com/ubuntu/ bionic main' | tee /etc/apt/sources.list.d/kitware.list > /dev/null -apt-get -qq update -apt-get -qq remove cmake > /dev/null -apt-get -qq install cmake > /dev/null - -# The following lines are specific to Colab installation environment -[[ -f /usr/local/bin/cmake && ! -f /usr/local/bin/cmake-default ]] && mv /usr/local/bin/cmake /usr/local/bin/cmake-default -ln -sf /usr/bin/cmake /usr/local/bin/cmake -``` - - - -##### \_\_\_ - -We set up a directory that we will use as an installation prefix (this can be different depending on where you want to install everything). - - - -```python id="YQplbeQbsvg_" -import os -import sys - -ver = sys.version_info - -os.environ["PYSAGES_ENV"] = "/env/pysages" -os.environ["PREFIX"] = "/env/pysages/lib/python" + str(ver.major) + "." + str(ver.minor) + "/site-packages" -``` - -```python id="f4YUpAAD_ECn" -!mkdir -p $PREFIX -``` - - - -## HOOMD-blue - -With this dependency updated, we can install HOOMD-blue. -The following cell clones and compiles HOOMD-blue manually. -We also make use of disabling components of the HOOMD-blue installation to save some installation time. - -**This may take some time, be mindful of not inadvertently re-running the cell.** - - - - - -# Build and install HOOMD-blue - - - -```bash id="r_eiHnV5K6HI" - -# Get HOOMD-blue source code -rm -rf hoomd-blue -git clone https://github.com/glotzerlab/hoomd-blue.git &>/dev/null -cd hoomd-blue -git checkout v2.9.7 &> /dev/null - -# Compile and install -BUILD_PATH=/tmp/build/hoomd -rm -rf $BUILD_PATH -cmake -S . -B $BUILD_PATH \ - -DCMAKE_INSTALL_PREFIX=$PREFIX \ - -DENABLE_CUDA=ON \ - -DBUILD_CGCMM=OFF \ - -DBUILD_DEM=OFF \ - -DBUILD_DEPRECATED=OFF \ - -DBUILD_HPMC=OFF \ - -DBUILD_METAL=OFF \ - -DBUILD_MPCD=OFF \ - -DBUILD_TESTING=OFF &> /dev/null - -cmake --build $BUILD_PATH --target install -j8 &> /dev/null -# Or alternately to the line above -# cd /tmp/build/hoomd -# make install -j8 &> /dev/null -``` - - - -##### \_\_\_ - -After the successful installation of HOOMD-blue, we make the installation visible to the python system. We installed HOOMD-blue into a custom location that is not checked by python for software out of the box. -In this Colab, this happens in two steps. - -First, we extend the environment variable `PYTHONPATH`. This helps newly started python environments to find the HOOMD-blue installation. This is important for the installation of the plugin later. In none-notebook environments, this is the only step necessary. - - - -```python id="MuDzJEpFzev3" -import os -os.environ["PYTHONPATH"] = os.environ["PREFIX"] + ":" + os.environ["PYTHONPATH"] -``` - - - -##### \_\_\_ - -Because the notebook environment has already a running python we need to let this one know about the new package location. We achieve this by appending the `sys.path` with the location of our package. - - - -```python id="he413SCN-qKb" -import os -import sys -sys.path.append(os.environ["PREFIX"]) -``` - - - -## HOOMD-dlext plugin - -Now we can install the `dlext` plugin for HOOMD-blue. So we clone the hoomd-dlext repository and install the package via `cmake` as well. -This cell is significantly faster than the HOOMD-blue installation. - - - - - -##### Build and install HOOMD-dlext plugin - - - -```bash id="-imFRwdKfDvq" - -# Get the plugin -rm -rf hoomd-dlext -git clone https://github.com/SSAGESLabs/hoomd-dlext.git &> /dev/null -cd hoomd-dlext - -# Build and install -BUILD_PATH=/tmp/build/hoomd-dlext -rm -rf $BUILD_PATH -cmake -S . -B $BUILD_PATH &> /dev/null -cmake --build $BUILD_PATH --target install > /dev/null -``` - - - -##### \_\_\_ - -This concludes the installation of the HOOMD-blue and its Plugin for PySAGES. We quickly test the installation and, if successful, we proceed to also build and install OpenMM. - - - -```python id="xJC1ebpqrKC8" -import hoomd -import hoomd.dlext -``` - - - -## OpenMM - -Having previously set up the environment variables for the HOOMD-blue installation, we can now just simply install some required dependencies and build and install OpenMM. - - - - - -##### \_\_\_ - -Installing dependencies will be different depending on your operating system and python environment. - - - -```bash id="USDPtmzmBckY" - -apt-get -qq install doxygen swig > /dev/null -python -m pip install -q --upgrade pip setuptools wheel Cython &> /dev/null -``` - - - -##### Build and install OpenMM - - - -```bash id="OLmZh8mF8QQx" - -# Get OpenMM source code -rm -rf openmm -git clone https://github.com/openmm/openmm.git &> /dev/null -cd openmm && git checkout 7.6.0 &> /dev/null - -# Compile and install -BUILD_PATH=/tmp/build/openmm -rm -rf $BUILD_PATH -cmake -S . -B $BUILD_PATH \ - -DCMAKE_INSTALL_PREFIX=$PYSAGES_ENV \ - -DBUILD_TESTING=OFF \ - -Wno-dev &> /dev/null - -cmake --build $BUILD_PATH -j8 &> /dev/null -cmake --install $BUILD_PATH &> /dev/null - -# Install python package -export OPENMM_INCLUDE_PATH=$PYSAGES_ENV/include -export OPENMM_LIB_PATH=$PYSAGES_ENV/lib -cd $BUILD_PATH/python -pip install --target $PREFIX . &> /dev/null -``` - - - -## OpenMM-dlext plugin - -Similarly we build and install the corresponding `openmm_dlext` plugin. - - - - - -##### Build and install openmm-dlext - - - -```bash id="mCUYSTLp9M-C" - -# Get the plugin -rm -rf openmm-dlext -git clone https://github.com/SSAGESLabs/openmm-dlext.git &> /dev/null -cd openmm-dlext - -# Build and install -BUILD_PATH=/tmp/build/openmm-dlext -rm -rf $BUILD_PATH -cmake -S . -B $BUILD_PATH -Wno-dev &> /dev/null -cmake --build $BUILD_PATH --target install > /dev/null -``` - - - -##### \_\_\_ - -Again, we test the installation and, if successful, we proceed to copy the environment to Google Drive to avoid building everything again in the future. - - - -```python id="5Ty-Jnm09gnu" -import openmm -import openmm_dlext -``` - - - -## Upload environment to Google Drive - - - - - -**This step can only be successfully executed by PySAGES maintainers.** - -These steps are not necessary to understand the setup of the environment. If you want to build your own environment, modify the lines such that it uploads to your own Google Drive. - -We upload the data to the shared Google Drive. First, we mount our Google Drive file system to a local directory. - - - -```python colab={"base_uri": "https://localhost:8080/"} id="yic9Joq5tlGh" outputId="6a516f55-ec92-4228-b0bb-f5f0fe9b43ec" -from google.colab import drive -drive.mount('/content/mnt') -``` - - - -We then compress the environment into a zip file and copy it to a folder within Google Drive. Here we are choosing an existing Shared Drive, but if you were to do this you should choose a folder you have access to and write permissions. - - - -```python colab={"base_uri": "https://localhost:8080/"} id="QmXbqp9Pqp-a" outputId="046b3c5b-1980-43d4-bd6d-91d5d1b211a1" -%env PYSAGES_SHARED_ENV=/content/mnt/Shareddrives/pysages-env -``` - -```bash id="ufo9WHoQqzuW" - -cd $PYSAGES_ENV -zip -qr pysages-env.zip . -cp -f pysages-env.zip $PYSAGES_SHARED_ENV -rm -f pysages-env.zip -``` diff --git a/examples/Install_PySAGES_Environment.ipynb b/examples/Installing_a_PySAGES_Environment.ipynb similarity index 51% rename from examples/Install_PySAGES_Environment.ipynb rename to examples/Installing_a_PySAGES_Environment.ipynb index 514b33d6..091f587e 100644 --- a/examples/Install_PySAGES_Environment.ipynb +++ b/examples/Installing_a_PySAGES_Environment.ipynb @@ -2,8 +2,8 @@ "cells": [ { "cell_type": "markdown", - "id": "fb18f873", "metadata": { + "id": "fb18f873", "lines_to_next_cell": 0 }, "source": [ @@ -18,89 +18,95 @@ }, "source": [ "\n", - "# Installation of the environment\n" + "# Setting up the Environment\n" ] }, { "cell_type": "markdown", "metadata": { - "id": "WM_9PpDwKuoA" + "id": "0opWLiz1shLz" }, "source": [ - "\n", - "First, we are setting up our environment, by installing HOOMD-blue and installing the dlext plugin for it. The first step is to update cmake to a version that is compatible with our installation process. In this case, we are using a newer version of CMake that is required by the HOOMD-dlext plugin.\n", - "This is special to the underlying (older) Ubuntu system of this Colab (18.04) and should not be required for newer installations.\n" + "We set up a directory that we will use as an installation prefix. If you are not running in an interactive environment and you don't want to install packages in a custom path, the steps in this section are unnecessary.\n" ] }, { - "cell_type": "markdown", + "cell_type": "code", + "execution_count": 1, "metadata": { - "id": "Bj0t7S1rcPoT" + "id": "YQplbeQbsvg_" }, + "outputs": [], "source": [ + "import os\n", + "import sys\n", + "\n", + "ver = sys.version_info\n", "\n", - "# Update CMake\n" + "os.environ[\"PYSAGES_ENV\"] = os.environ[\"PREFIX\"] = \"/env/pysages\"\n", + "os.environ[\"PYTHON_SITE_INSTALL_DIR\"] = f\"lib/python{str(ver.major)}.{str(ver.minor)}/site-packages\"\n", + "os.environ[\"PREFIX_USER_SITE\"] = os.environ[\"PREFIX\"] + \"/\" + os.environ[\"PYTHON_SITE_INSTALL_DIR\"]\n", + "\n", + "# The following lines are to prevent python packages being looked up from certain paths in this Colab instance\n", + "for path in (\"/content\", \"\"):\n", + " if path in sys.path:\n", + " sys.path.remove(path)" ] }, { "cell_type": "code", - "execution_count": null, + "execution_count": 2, "metadata": { - "id": "anZqRa7pxGpK" + "id": "f4YUpAAD_ECn" }, "outputs": [], "source": [ - "%%bash\n", - "\n", - "wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc 2> /dev/null | gpg --dearmor - | tee /usr/share/keyrings/kitware-archive-keyring.gpg > /dev/null\n", - "echo 'deb [signed-by=/usr/share/keyrings/kitware-archive-keyring.gpg] https://apt.kitware.com/ubuntu/ bionic main' | tee /etc/apt/sources.list.d/kitware.list > /dev/null\n", - "apt-get -qq update\n", - "apt-get -qq remove cmake > /dev/null\n", - "apt-get -qq install cmake > /dev/null\n", - "\n", - "# The following lines are specific to Colab installation environment\n", - "[[ -f /usr/local/bin/cmake && ! -f /usr/local/bin/cmake-default ]] && mv /usr/local/bin/cmake /usr/local/bin/cmake-default\n", - "ln -sf /usr/bin/cmake /usr/local/bin/cmake" + "!mkdir -p $PREFIX_USER_SITE" ] }, { "cell_type": "markdown", "metadata": { - "id": "0opWLiz1shLz" + "id": "V3bkQyaIerAM" }, "source": [ + "We want to make the installation visible to the python system, but we will be installing packages into a custom location that is not checked by python by default. In this Colab, we achieve this in two steps.\n", "\n", - "##### \\_\\_\\_\n", - "\n", - "We set up a directory that we will use as an installation prefix (this can be different depending on where you want to install everything).\n" + "First, we extend the environment variable `PYTHONPATH`. This helps newly started python environments to find packages.\n" ] }, { "cell_type": "code", - "execution_count": null, + "execution_count": 3, "metadata": { - "id": "YQplbeQbsvg_" + "id": "rK5eqf1Efd5U" }, "outputs": [], "source": [ "import os\n", - "import sys\n", - "\n", - "ver = sys.version_info\n", - "\n", - "os.environ[\"PYSAGES_ENV\"] = \"/env/pysages\"\n", - "os.environ[\"PREFIX\"] = \"/env/pysages/lib/python\" + str(ver.major) + \".\" + str(ver.minor) + \"/site-packages\"" + "os.environ[\"PYTHONPATH\"] = os.environ[\"PREFIX_USER_SITE\"] + \":\" + os.environ[\"PYTHONPATH\"]" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "WJpB7JxLflFa" + }, + "source": [ + "Because the notebook environment has already a running python we need to let it know about the new location. We achieve this by appending the `sys.path` with such location." ] }, { "cell_type": "code", - "execution_count": null, + "execution_count": 4, "metadata": { - "id": "f4YUpAAD_ECn" + "id": "UeVmb0cZfl8-" }, "outputs": [], "source": [ - "!mkdir -p $PREFIX" + "import os\n", + "import sys\n", + "sys.path.append(os.environ[\"PREFIX_USER_SITE\"])" ] }, { @@ -110,13 +116,20 @@ }, "source": [ "\n", - "## HOOMD-blue\n", - "\n", - "With this dependency updated, we can install HOOMD-blue.\n", - "The following cell clones and compiles HOOMD-blue manually.\n", - "We also make use of disabling components of the HOOMD-blue installation to save some installation time.\n", + "# Adding HOOMD-blue Support\n", "\n", - "**This may take some time, be mindful of not inadvertently re-running the cell.**\n" + "We first install some dependencies necessary to build HOOMD-blue. These may vary in number and names based on your environment and operating system." + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "metadata": { + "id": "tlM4nMxwXFKO" + }, + "outputs": [], + "source": [ + "!apt-get -qq install libeigen3-dev pybind11-dev > /dev/null" ] }, { @@ -126,14 +139,16 @@ }, "source": [ "\n", - "# Build and install HOOMD-blue\n" + "## Building and Installing HOOMD-blue\n", + "\n", + "The following clones the HOOMD-blue repo and sets the version to `v4.7.0` (this is the newest version that builds with the system dependencies available in Ubuntu 22.04, which is the OS used in Colab as of the end of 2024)." ] }, { "cell_type": "code", - "execution_count": null, + "execution_count": 6, "metadata": { - "id": "r_eiHnV5K6HI" + "id": "bEvgKS5EZDW1" }, "outputs": [], "source": [ @@ -141,80 +156,82 @@ "\n", "# Get HOOMD-blue source code\n", "rm -rf hoomd-blue\n", - "git clone https://github.com/glotzerlab/hoomd-blue.git &>/dev/null\n", + "git clone -q https://github.com/glotzerlab/hoomd-blue.git\n", "cd hoomd-blue\n", - "git checkout v2.9.7 &> /dev/null\n", - "\n", - "# Compile and install\n", - "BUILD_PATH=/tmp/build/hoomd\n", - "rm -rf $BUILD_PATH\n", - "cmake -S . -B $BUILD_PATH \\\n", - " -DCMAKE_INSTALL_PREFIX=$PREFIX \\\n", - " -DENABLE_CUDA=ON \\\n", - " -DBUILD_CGCMM=OFF \\\n", - " -DBUILD_DEM=OFF \\\n", - " -DBUILD_DEPRECATED=OFF \\\n", - " -DBUILD_HPMC=OFF \\\n", - " -DBUILD_METAL=OFF \\\n", - " -DBUILD_MPCD=OFF \\\n", - " -DBUILD_TESTING=OFF &> /dev/null\n", - "\n", - "cmake --build $BUILD_PATH --target install -j8 &> /dev/null\n", - "# Or alternately to the line above\n", - "# cd /tmp/build/hoomd\n", - "# make install -j8 &> /dev/null" + "git checkout -q v4.7.0\n", + "git submodule update -q --init" ] }, { "cell_type": "markdown", "metadata": { - "id": "8ZxdRrN1rrtU" + "id": "Q-XrmUMJZF2N" }, "source": [ + "#### \\_\\_\\_\n", "\n", - "##### \\_\\_\\_\n", - "\n", - "After the successful installation of HOOMD-blue, we make the installation visible to the python system. We installed HOOMD-blue into a custom location that is not checked by python for software out of the box.\n", - "In this Colab, this happens in two steps.\n", - "\n", - "First, we extend the environment variable `PYTHONPATH`. This helps newly started python environments to find the HOOMD-blue installation. This is important for the installation of the plugin later. In none-notebook environments, this is the only step necessary.\n" + "We need to patch `CMake/hoomd/HOOMDPythonSetup.cmake` to being able to install\n", + "in a custom `site-packages` path within this Colab instance. This is also done\n", + "for hoomd conda builds (see for example [here](https://github.com/conda-forge/hoomd-feedstock/pull/106)).\n", + "In general you shouldn't need to do this." ] }, { "cell_type": "code", - "execution_count": null, + "execution_count": 7, "metadata": { - "id": "MuDzJEpFzev3" + "id": "kbfWJ0bGZsAt" }, "outputs": [], "source": [ - "import os\n", - "os.environ[\"PYTHONPATH\"] = os.environ[\"PREFIX\"] + \":\" + os.environ[\"PYTHONPATH\"]" + "%%bash\n", + "cd hoomd-blue\n", + "wget -q -O- https://raw.githubusercontent.com/conda-forge/hoomd-feedstock/4eb9b8ecd47f6780fcdbcde90ad99c180b5e2f51/recipe/fix-python-site-dir.patch | patch -p1 -s" ] }, { "cell_type": "markdown", "metadata": { - "id": "fQkzEJWgzhCp" + "id": "pxQu1nVbc45X" }, "source": [ + "#### \\_\\_\\_\n", "\n", - "##### \\_\\_\\_\n", + "We first disable some HOOMD-blue components to save on installation time, and then, we compile and install the package.\n", "\n", - "Because the notebook environment has already a running python we need to let this one know about the new package location. We achieve this by appending the `sys.path` with the location of our package.\n" + "**This may take a while, so be mindful of not inadvertently re-running the cell.**" ] }, { "cell_type": "code", "execution_count": null, "metadata": { - "id": "he413SCN-qKb" + "id": "r_eiHnV5K6HI" }, "outputs": [], "source": [ - "import os\n", - "import sys\n", - "sys.path.append(os.environ[\"PREFIX\"])" + "%%bash\n", + "\n", + "cd hoomd-blue\n", + "\n", + "# Compile and install\n", + "BUILD_PATH=/tmp/build/hoomd\n", + "rm -rf $BUILD_PATH\n", + "cmake -S . -B $BUILD_PATH \\\n", + " -DCMAKE_INSTALL_PREFIX=$PREFIX \\\n", + " -DBUILD_HPMC=OFF \\\n", + " -DBUILD_METAL=OFF \\\n", + " -DBUILD_MPCD=OFF \\\n", + " -DBUILD_TESTING=OFF \\\n", + " -DENABLE_GPU=ON \\\n", + " -DENABLE_TBB=ON \\\n", + " -DPLUGINS=\"\" \\\n", + " -DPYTHON_SITE_INSTALL_DIR=$PYTHON_SITE_INSTALL_DIR/hoomd > /dev/null\n", + "\n", + "cmake --build $BUILD_PATH --target install -j8 > /dev/null\n", + "# Or alternately to the line above\n", + "# cd $BUILD_PATH\n", + "# make install -j8 > /dev/null" ] }, { @@ -224,10 +241,20 @@ }, "source": [ "\n", - "## HOOMD-dlext plugin\n", + "## Building and Installing the HOOMD-dlext Plugin\n", "\n", - "Now we can install the `dlext` plugin for HOOMD-blue. So we clone the hoomd-dlext repository and install the package via `cmake` as well.\n", - "This cell is significantly faster than the HOOMD-blue installation.\n" + "Now we can install the `dlext` plugin for HOOMD-blue. But, we need to get some dependecies first.\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "id": "fAgQT1rRKsLf" + }, + "outputs": [], + "source": [ + "!python -m pip install -q setuptools_scm > /dev/null" ] }, { @@ -237,7 +264,7 @@ }, "source": [ "\n", - "##### Build and install HOOMD-dlext plugin\n" + "We then clone the hoomd-dlext repository and install the package via `cmake` as well. This cell is significantly faster than the HOOMD-blue installation.\n" ] }, { @@ -252,13 +279,13 @@ "\n", "# Get the plugin\n", "rm -rf hoomd-dlext\n", - "git clone https://github.com/SSAGESLabs/hoomd-dlext.git &> /dev/null\n", + "git clone -q https://github.com/SSAGESLabs/hoomd-dlext.git\n", "cd hoomd-dlext\n", "\n", "# Build and install\n", "BUILD_PATH=/tmp/build/hoomd-dlext\n", "rm -rf $BUILD_PATH\n", - "cmake -S . -B $BUILD_PATH &> /dev/null\n", + "cmake -S . -B $BUILD_PATH -DCMAKE_FIND_ROOT_PATH=$PREFIX &> /dev/null\n", "cmake --build $BUILD_PATH --target install > /dev/null" ] }, @@ -269,9 +296,7 @@ }, "source": [ "\n", - "##### \\_\\_\\_\n", - "\n", - "This concludes the installation of the HOOMD-blue and its Plugin for PySAGES. We quickly test the installation and, if successful, we proceed to also build and install OpenMM.\n" + "This concludes the installation of the HOOMD-blue and its plugin for PySAGES. We quickly test the installation.\n" ] }, { @@ -293,21 +318,11 @@ }, "source": [ "\n", - "## OpenMM\n", + "# Adding OpenMM Support\n", "\n", - "Having previously set up the environment variables for the HOOMD-blue installation, we can now just simply install some required dependencies and build and install OpenMM.\n" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "id": "t8d3toizoQe9" - }, - "source": [ + "Having previously set our the environment, we can now just simply install some required dependencies and build and install OpenMM.\n", "\n", - "##### \\_\\_\\_\n", - "\n", - "Installing dependencies will be different depending on your operating system and python environment.\n" + "Again, installing dependencies will be different depending on your operating system and python environment." ] }, { @@ -321,7 +336,7 @@ "%%bash\n", "\n", "apt-get -qq install doxygen swig > /dev/null\n", - "python -m pip install -q --upgrade pip setuptools wheel Cython &> /dev/null" + "python -m pip install -qq setuptools wheel Cython" ] }, { @@ -331,14 +346,18 @@ }, "source": [ "\n", - "##### Build and install OpenMM\n" + "## Building and Installing OpenMM\n", + "\n", + "The following clones the OpenMM repo and sets the version to `v8.1.2` (the newest available when this notebook was last updated). Then, it configures and builds OpenMM.\n", + "\n", + "**This may take a while, so be mindful of not inadvertently re-running the cell.**" ] }, { "cell_type": "code", "execution_count": null, "metadata": { - "id": "OLmZh8mF8QQx" + "id": "OPsrb1RqmD-p" }, "outputs": [], "source": [ @@ -346,47 +365,64 @@ "\n", "# Get OpenMM source code\n", "rm -rf openmm\n", - "git clone https://github.com/openmm/openmm.git &> /dev/null\n", - "cd openmm && git checkout 7.6.0 &> /dev/null\n", + "git clone -q https://github.com/openmm/openmm.git\n", + "cd openmm\n", + "git checkout -q 8.1.2\n", "\n", "# Compile and install\n", "BUILD_PATH=/tmp/build/openmm\n", "rm -rf $BUILD_PATH\n", "cmake -S . -B $BUILD_PATH \\\n", - " -DCMAKE_INSTALL_PREFIX=$PYSAGES_ENV \\\n", + " -DCMAKE_INSTALL_PREFIX=$PREFIX \\\n", " -DBUILD_TESTING=OFF \\\n", - " -Wno-dev &> /dev/null\n", + " -DOPENMM_PYTHON_USER_INSTALL=ON \\\n", + " -Wno-dev > /dev/null\n", "\n", "cmake --build $BUILD_PATH -j8 &> /dev/null\n", - "cmake --install $BUILD_PATH &> /dev/null\n", - "\n", - "# Install python package\n", - "export OPENMM_INCLUDE_PATH=$PYSAGES_ENV/include\n", - "export OPENMM_LIB_PATH=$PYSAGES_ENV/lib\n", - "cd $BUILD_PATH/python\n", - "pip install --target $PREFIX . &> /dev/null" + "cmake --install $BUILD_PATH > /dev/null" ] }, { "cell_type": "markdown", "metadata": { - "id": "zPZpzuaq9CIW" + "id": "R8dVbeEdVyin" + }, + "source": [ + "The OpenMM python library needs to be build and installed separately. We also need to point for the library to be installed in our custom path." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "id": "WoEFi8P7XlVP" }, + "outputs": [], "source": [ + "%%bash\n", "\n", - "## OpenMM-dlext plugin\n", + "export OPENMM_INCLUDE_PATH=$PREFIX/include\n", + "export OPENMM_LIB_PATH=$PREFIX/lib\n", + "BUILD_PATH=/tmp/build/openmm\n", + "\n", + "# Install python package\n", + "cd $BUILD_PATH\n", + "make PythonInstall &> /dev/null\n", "\n", - "Similarly we build and install the corresponding `openmm_dlext` plugin.\n" + "cd $BUILD_PATH/python\n", + "pip install --target $PREFIX_USER_SITE . &> /dev/null" ] }, { "cell_type": "markdown", "metadata": { - "id": "N87ZPlxqZ-eS" + "id": "zPZpzuaq9CIW" }, "source": [ "\n", - "##### Build and install openmm-dlext\n" + "## Building and Installing the OpenMM-dlext Plugin\n", + "\n", + "Similarly as shown for HOOMD-blue above, for OpenMM we need to build and install the corresponding `openmm-dlext` plugin.\n" ] }, { @@ -401,14 +437,14 @@ "\n", "# Get the plugin\n", "rm -rf openmm-dlext\n", - "git clone https://github.com/SSAGESLabs/openmm-dlext.git &> /dev/null\n", + "git clone -q https://github.com/SSAGESLabs/openmm-dlext.git\n", "cd openmm-dlext\n", "\n", "# Build and install\n", "BUILD_PATH=/tmp/build/openmm-dlext\n", "rm -rf $BUILD_PATH\n", - "cmake -S . -B $BUILD_PATH -Wno-dev &> /dev/null\n", - "cmake --build $BUILD_PATH --target install > /dev/null" + "cmake -S . -B $BUILD_PATH -Wno-dev > /dev/null\n", + "cmake --build $BUILD_PATH --target install &> /dev/null" ] }, { @@ -417,10 +453,7 @@ "id": "cm5xnNrM9P20" }, "source": [ - "\n", - "##### \\_\\_\\_\n", - "\n", - "Again, we test the installation and, if successful, we proceed to copy the environment to Google Drive to avoid building everything again in the future.\n" + "If everything worked as expected, the following should run without issuing any errors." ] }, { @@ -432,7 +465,7 @@ "outputs": [], "source": [ "import openmm\n", - "import openmm_dlext" + "import openmm.dlext" ] }, { @@ -451,23 +484,22 @@ "id": "3a_zSXJatWUY" }, "source": [ - "\n", - "**This step can only be successfully executed by PySAGES maintainers.**\n", - "\n", "These steps are not necessary to understand the setup of the environment. If you want to build your own environment, modify the lines such that it uploads to your own Google Drive.\n", "\n", - "We upload the data to the shared Google Drive. First, we mount our Google Drive file system to a local directory.\n" + "We upload the data to a shared Google Drive so we can reuse our environment in other notebooks.\n", + "\n", + "First, we mount our Google Drive file system to a local directory.\n" ] }, { "cell_type": "code", - "execution_count": null, + "execution_count": 78, "metadata": { "colab": { "base_uri": "https://localhost:8080/" }, "id": "yic9Joq5tlGh", - "outputId": "6a516f55-ec92-4228-b0bb-f5f0fe9b43ec" + "outputId": "9ea110d5-8f45-4de2-e917-6c48d047acf9" }, "outputs": [ { @@ -483,6 +515,28 @@ "drive.mount('/content/mnt')" ] }, + { + "cell_type": "markdown", + "metadata": { + "id": "lKHxKVDRYEpP" + }, + "source": [ + "We clean the cache of the code generated by python for our built packages such that the upload size is smaller." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "id": "Tl248P32YH8O" + }, + "outputs": [], + "source": [ + "%%bash\n", + "python -m pip install -q pyclean > /dev/null\n", + "pyclean -q $PREFIX_USER_SITE" + ] + }, { "cell_type": "markdown", "metadata": { @@ -495,13 +549,13 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 79, "metadata": { "colab": { "base_uri": "https://localhost:8080/" }, "id": "QmXbqp9Pqp-a", - "outputId": "046b3c5b-1980-43d4-bd6d-91d5d1b211a1" + "outputId": "483ad6a2-2042-4a96-9eb1-964eb16c6c36" }, "outputs": [ { @@ -518,7 +572,7 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 80, "metadata": { "id": "ufo9WHoQqzuW" }, @@ -537,13 +591,10 @@ "accelerator": "GPU", "colab": { "collapsed_sections": [ - "Bj0t7S1rcPoT", - "0opWLiz1shLz", - "t8d3toizoQe9" + "Q-XrmUMJZF2N" ], - "name": "Install_PySAGES_Environment.ipynb", - "provenance": [], - "toc_visible": true + "name": "Installing_a_PySAGES_Environment.ipynb", + "provenance": [] }, "jupytext": { "formats": "ipynb,md", diff --git a/examples/Installing_a_PySAGES_Environment.md b/examples/Installing_a_PySAGES_Environment.md new file mode 100644 index 00000000..8b12285c --- /dev/null +++ b/examples/Installing_a_PySAGES_Environment.md @@ -0,0 +1,329 @@ +--- +jupyter: + jupytext: + formats: ipynb,md + main_language: python + text_representation: + extension: .md + format_name: markdown + format_version: '1.3' + jupytext_version: 1.16.4 + kernelspec: + display_name: Python 3 + name: python3 +--- + + + + + + + +# Setting up the Environment + + + + +We set up a directory that we will use as an installation prefix. If you are not running in an interactive environment and you don't want to install packages in a custom path, the steps in this section are unnecessary. + + + +```python id="YQplbeQbsvg_" +import os +import sys + +ver = sys.version_info + +os.environ["PYSAGES_ENV"] = os.environ["PREFIX"] = "/env/pysages" +os.environ["PYTHON_SITE_INSTALL_DIR"] = f"lib/python{str(ver.major)}.{str(ver.minor)}/site-packages" +os.environ["PREFIX_USER_SITE"] = os.environ["PREFIX"] + "/" + os.environ["PYTHON_SITE_INSTALL_DIR"] + +# The following lines are to prevent python packages being looked up from certain paths in this Colab instance +for path in ("/content", ""): + if path in sys.path: + sys.path.remove(path) +``` + +```python id="f4YUpAAD_ECn" +!mkdir -p $PREFIX_USER_SITE +``` + + +We want to make the installation visible to the python system, but we will be installing packages into a custom location that is not checked by python by default. In this Colab, we achieve this in two steps. + +First, we extend the environment variable `PYTHONPATH`. This helps newly started python environments to find packages. + + + +```python id="rK5eqf1Efd5U" +import os +os.environ["PYTHONPATH"] = os.environ["PREFIX_USER_SITE"] + ":" + os.environ["PYTHONPATH"] +``` + + +Because the notebook environment has already a running python we need to let it know about the new location. We achieve this by appending the `sys.path` with such location. + + +```python id="UeVmb0cZfl8-" +import os +import sys +sys.path.append(os.environ["PREFIX_USER_SITE"]) +``` + + + +# Adding HOOMD-blue Support + +We first install some dependencies necessary to build HOOMD-blue. These may vary in number and names based on your environment and operating system. + + +```python id="tlM4nMxwXFKO" +!apt-get -qq install libeigen3-dev pybind11-dev > /dev/null +``` + + + +## Building and Installing HOOMD-blue + +The following clones the HOOMD-blue repo and sets the version to `v4.7.0` (this is the newest version that builds with the system dependencies available in Ubuntu 22.04, which is the OS used in Colab as of the end of 2024). + + +```bash id="bEvgKS5EZDW1" + +# Get HOOMD-blue source code +rm -rf hoomd-blue +git clone -q https://github.com/glotzerlab/hoomd-blue.git +cd hoomd-blue +git checkout -q v4.7.0 +git submodule update -q --init +``` + + +#### \_\_\_ + +We need to patch `CMake/hoomd/HOOMDPythonSetup.cmake` to being able to install +in a custom `site-packages` path within this Colab instance. This is also done +for hoomd conda builds (see for example [here](https://github.com/conda-forge/hoomd-feedstock/pull/106)). +In general you shouldn't need to do this. + + +```bash id="kbfWJ0bGZsAt" +cd hoomd-blue +wget -q -O- https://raw.githubusercontent.com/conda-forge/hoomd-feedstock/4eb9b8ecd47f6780fcdbcde90ad99c180b5e2f51/recipe/fix-python-site-dir.patch | patch -p1 -s +``` + + +#### \_\_\_ + +We first disable some HOOMD-blue components to save on installation time, and then, we compile and install the package. + +**This may take a while, so be mindful of not inadvertently re-running the cell.** + + +```bash id="r_eiHnV5K6HI" + +cd hoomd-blue + +# Compile and install +BUILD_PATH=/tmp/build/hoomd +rm -rf $BUILD_PATH +cmake -S . -B $BUILD_PATH \ + -DCMAKE_INSTALL_PREFIX=$PREFIX \ + -DBUILD_HPMC=OFF \ + -DBUILD_METAL=OFF \ + -DBUILD_MPCD=OFF \ + -DBUILD_TESTING=OFF \ + -DENABLE_GPU=ON \ + -DENABLE_TBB=ON \ + -DPLUGINS="" \ + -DPYTHON_SITE_INSTALL_DIR=$PYTHON_SITE_INSTALL_DIR/hoomd > /dev/null + +cmake --build $BUILD_PATH --target install -j8 > /dev/null +# Or alternately to the line above +# cd $BUILD_PATH +# make install -j8 > /dev/null +``` + + + +## Building and Installing the HOOMD-dlext Plugin + +Now we can install the `dlext` plugin for HOOMD-blue. But, we need to get some dependecies first. + + + +```python id="fAgQT1rRKsLf" +!python -m pip install -q setuptools_scm > /dev/null +``` + + + +We then clone the hoomd-dlext repository and install the package via `cmake` as well. This cell is significantly faster than the HOOMD-blue installation. + + + +```bash id="-imFRwdKfDvq" + +# Get the plugin +rm -rf hoomd-dlext +git clone -q https://github.com/SSAGESLabs/hoomd-dlext.git +cd hoomd-dlext + +# Build and install +BUILD_PATH=/tmp/build/hoomd-dlext +rm -rf $BUILD_PATH +cmake -S . -B $BUILD_PATH -DCMAKE_FIND_ROOT_PATH=$PREFIX &> /dev/null +cmake --build $BUILD_PATH --target install > /dev/null +``` + + + +This concludes the installation of the HOOMD-blue and its plugin for PySAGES. We quickly test the installation. + + + +```python id="xJC1ebpqrKC8" +import hoomd +import hoomd.dlext +``` + + + +# Adding OpenMM Support + +Having previously set our the environment, we can now just simply install some required dependencies and build and install OpenMM. + +Again, installing dependencies will be different depending on your operating system and python environment. + + +```bash id="USDPtmzmBckY" + +apt-get -qq install doxygen swig > /dev/null +python -m pip install -qq setuptools wheel Cython +``` + + + +## Building and Installing OpenMM + +The following clones the OpenMM repo and sets the version to `v8.1.2` (the newest available when this notebook was last updated). Then, it configures and builds OpenMM. + +**This may take a while, so be mindful of not inadvertently re-running the cell.** + + +```bash id="OPsrb1RqmD-p" + +# Get OpenMM source code +rm -rf openmm +git clone -q https://github.com/openmm/openmm.git +cd openmm +git checkout -q 8.1.2 + +# Compile and install +BUILD_PATH=/tmp/build/openmm +rm -rf $BUILD_PATH +cmake -S . -B $BUILD_PATH \ + -DCMAKE_INSTALL_PREFIX=$PREFIX \ + -DBUILD_TESTING=OFF \ + -DOPENMM_PYTHON_USER_INSTALL=ON \ + -Wno-dev > /dev/null + +cmake --build $BUILD_PATH -j8 &> /dev/null +cmake --install $BUILD_PATH > /dev/null +``` + + +The OpenMM python library needs to be build and installed separately. We also need to point for the library to be installed in our custom path. + + +```bash id="WoEFi8P7XlVP" + +export OPENMM_INCLUDE_PATH=$PREFIX/include +export OPENMM_LIB_PATH=$PREFIX/lib +BUILD_PATH=/tmp/build/openmm + +# Install python package +cd $BUILD_PATH +make PythonInstall &> /dev/null + +cd $BUILD_PATH/python +pip install --target $PREFIX_USER_SITE . &> /dev/null +``` + + + +## Building and Installing the OpenMM-dlext Plugin + +Similarly as shown for HOOMD-blue above, for OpenMM we need to build and install the corresponding `openmm-dlext` plugin. + + + +```bash id="mCUYSTLp9M-C" + +# Get the plugin +rm -rf openmm-dlext +git clone -q https://github.com/SSAGESLabs/openmm-dlext.git +cd openmm-dlext + +# Build and install +BUILD_PATH=/tmp/build/openmm-dlext +rm -rf $BUILD_PATH +cmake -S . -B $BUILD_PATH -Wno-dev > /dev/null +cmake --build $BUILD_PATH --target install &> /dev/null +``` + + +If everything worked as expected, the following should run without issuing any errors. + + +```python id="5Ty-Jnm09gnu" +import openmm +import openmm.dlext +``` + + + +## Upload environment to Google Drive + + + + +These steps are not necessary to understand the setup of the environment. If you want to build your own environment, modify the lines such that it uploads to your own Google Drive. + +We upload the data to a shared Google Drive so we can reuse our environment in other notebooks. + +First, we mount our Google Drive file system to a local directory. + + + +```python colab={"base_uri": "https://localhost:8080/"} id="yic9Joq5tlGh" outputId="9ea110d5-8f45-4de2-e917-6c48d047acf9" +from google.colab import drive +drive.mount('/content/mnt') +``` + + +We clean the cache of the code generated by python for our built packages such that the upload size is smaller. + + +```bash id="Tl248P32YH8O" +python -m pip install -q pyclean > /dev/null +pyclean -q $PREFIX_USER_SITE +``` + + + +We then compress the environment into a zip file and copy it to a folder within Google Drive. Here we are choosing an existing Shared Drive, but if you were to do this you should choose a folder you have access to and write permissions. + + + +```python colab={"base_uri": "https://localhost:8080/"} id="QmXbqp9Pqp-a" outputId="483ad6a2-2042-4a96-9eb1-964eb16c6c36" +%env PYSAGES_SHARED_ENV=/content/mnt/Shareddrives/pysages-env +``` + +```bash id="ufo9WHoQqzuW" + +cd $PYSAGES_ENV +zip -qr pysages-env.zip . +cp -f pysages-env.zip $PYSAGES_SHARED_ENV +rm -f pysages-env.zip +``` diff --git a/examples/README.md b/examples/README.md index 38fa1abe..d61dfaf4 100644 --- a/examples/README.md +++ b/examples/README.md @@ -62,7 +62,7 @@ Examples for Methods using OpenMM can be found in the subfolder [openmm](openmm) We have a Google Colab that shows how the MD engines and PySAGES can be installed together as a guide to install PySAGES. This notebook has a final step that sets up precompiled environments for all the other notebooks as well. -[![Install Env](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/SSAGESLabs/PySAGES/blob/main/examples/Install_PySAGES_Environment.ipynb) +[![Install Env](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/SSAGESLabs/PySAGES/blob/main/examples/Installing_a_PySAGES_Environment.ipynb) ## For Developers