Added documentation on HIP (#4672)

* Added documentation on HIP

* Instructions for building HIP on Windows

docs-source/developerguide/07_cuda_platform.rst

@@ -8,23 +8,23 @@
 
 .. _the-cuda-platform:
 
-The CUDA Platform
-#################
+The CUDA and HIP Platforms
+##########################
 
-The CUDA platform is very similar to the OpenCL platform, and most of the
-previous chapter applies equally well to it, just changing “OpenCL” to “Cuda” in
-class names.  There are a few differences worth noting.
+The CUDA and HIP platforms are very similar to the OpenCL platform, and most of the
+previous chapter applies equally well to them, just changing “OpenCL” to “Cuda” or
+"Hip" in class names.  There are a few differences worth noting.
 
 Caching Kernels
 ***************
 
-Like the OpenCL platform, the CUDA platform compiles all its kernels at runtime.
-To improve performance, it tries to cache the compiled kernels on disk for
+Like the OpenCL platform, the CUDA and HIP platforms compile their kernels at runtime.
+To improve performance, they try to cache the compiled kernels on disk for
 later use.  This allows subsequent Contexts to skip compiling some kernels.  To
-make this work, it needs a directory on disk where it can write out temporary
-files.  It is specified by the “CudaTempDirectory” property when you create a
-new Context.  It usually can figure out a suitable value on its own, but
-sometimes it needs help.  See the “Platform-Specific Properties” chapter of the
+make this work, they need a directory on disk where they can write out temporary
+files.  It is specified by the “TempDirectory” property when you create a
+new Context.  They usually can figure out a suitable value on their own, but
+sometimes they need help.  See the “Platform-Specific Properties” chapter of the
 User's Manual for details.
 
 Accumulating Forces
@@ -32,5 +32,5 @@ Accumulating Forces
 
 The OpenCL platform, as described in Section :numref:`computing-forces`\ , uses two types of buffers for
 accumulating forces: a set of floating point buffers, and a single fixed point
-buffer.  In contrast, the CUDA platform uses *only* the fixed point buffer
+buffer.  In contrast, the CUDA and HIP platforms use *only* the fixed point buffer
 (represented by the CUDA type :code:`long` :code:`long`\ ).

docs-source/usersguide/application/01_getting_started.rst

@@ -96,6 +96,6 @@ CUDA version it was compiled with.
     python -m openmm.testInstallation
 
 This command confirms that OpenMM is installed, checks whether GPU acceleration
-is available (via the OpenCL and/or CUDA platforms), and verifies that all
+is available (via the CUDA, OpenCL, and/or HIP platforms), and verifies that all
 platforms produce consistent results.
 

docs-source/usersguide/application/02_running_sims.rst

@@ -414,7 +414,7 @@ Platforms
 =========
 
 When creating a :class:`Simulation`, you can optionally tell it what :class:`Platform` to use.
-OpenMM includes four platforms: :class:`Reference`, :class:`CPU`, :class:`CUDA`, and :class:`OpenCL`.  For a
+OpenMM includes five platforms: :class:`Reference`, :class:`CPU`, :class:`CUDA`, :class:`OpenCL`, and :class:`HIP`.  For a
 description of the differences between them, see Section :numref:`platforms`.  There are three ways in which
 the :class:`Platform` can be chosen:
 
@@ -431,7 +431,7 @@ of the :class:`Platform` to use.  This overrides the default logic.
     platform = Platform.getPlatform('CUDA')
     simulation = Simulation(prmtop.topology, system, integrator, platform)
 
-The platform name should be one of :code:`OpenCL`, :code:`CUDA`, :code:`CPU`, or
+The platform name should be one of :code:`OpenCL`, :code:`CUDA`, :code:`HIP`, :code:`CPU`, or
 :code:`Reference`.
 
 You also can specify platform-specific properties that customize how

docs-source/usersguide/library/01_introduction.rst

@@ -347,7 +347,7 @@ The choice of which platform to use for a simulation depends on various factors:
    (primarily the various “custom” force classes), it may be faster to use the
    OpenCL platform running on the CPU.
 #. The CUDA platform can be used with NVIDIA GPUs.  For using an AMD GPU,
-   use the HIP platform (or the OpenCL platform which is usually slower), for
-   using an Intel GPU, use the OpenCL platform.
+   use the HIP platform (or the OpenCL platform which is usually slower).  For
+   using an Intel or Apple GPU, use the OpenCL platform.
 #. The AMOEBA force field works with all platforms, but the performance
    of the Reference and CPU platforms is usually too slow to be useful.

docs-source/usersguide/library/02_compiling.rst

@@ -56,20 +56,26 @@ changing, may contain bugs, and should never be used for production work.  If
 you want a stable, well tested version of OpenMM, you should download the source
 code for the latest release as described above.
 
-CUDA or OpenCL Support
-----------------------
+CUDA, OpenCL, or HIP Support
+----------------------------
 
 If you want to compile OpenMM with support for running on GPUs, you will need
-CUDA and/or OpenCL.  MacOS comes with OpenCL built in, so nothing else needs to
+CUDA, HIP, or OpenCL.  MacOS comes with OpenCL built in, so nothing else needs to
 be installed.  For Linux, you need an appropriate SDK.
 
-The easiest way is to install the most recent CUDA Toolkit from https://developer.nvidia.com/cuda-downloads.
+The most recent CUDA Toolkit can be obtained from https://developer.nvidia.com/cuda-downloads.
 It includes the headers and libraries needed to compile both CUDA and OpenCL
 applications.  In addition, it has runtime libraries that are needed for running
 CUDA applications.  The runtime components for OpenCL applications are included
 with the GPU drivers from NVIDIA, AMD, and Intel, so make sure you have an
 up-to-date driver.
 
+The headers and libraries needed to build the HIP platform can be installed with
+conda using the following command.
+::
+
+    conda install -c conda-forge hip-devel hipcc rocm-cmake rocm-device-libs
+
 Other Required Software
 -----------------------
 
@@ -130,7 +136,7 @@ Build OpenMM with the command::
 Step 3: Test your build
 =======================
 
-This step is optional but recommended. Tests can take up to several minutes depending on your
+This step is optional but recommended. Tests can take a while depending on your
 hardware configuration.
 
 It is recommended that you make sure your local build of OpenMM works before trying
@@ -241,17 +247,21 @@ changing, may contain bugs, and should never be used for production work.  If
 you want a stable, well tested version of OpenMM, you should download the source
 code for the latest release as described above.
 
-CUDA or OpenCL Support
-----------------------
+CUDA, OpenCL, or HIP Support
+----------------------------
 
 If you want to compile OpenMM with support for running on GPUs, you will need
-CUDA and/or OpenCL.  Install the most recent CUDA Toolkit from https://developer.nvidia.com/cuda-downloads.
+CUDA, HIP, or OpenCL.
+
+The most recent CUDA Toolkit can be obtained from https://developer.nvidia.com/cuda-downloads.
 It includes the headers and libraries needed to compile both CUDA and OpenCL
 applications.  In addition, it has runtime libraries that are needed for running
 CUDA applications.  The runtime components for OpenCL applications are included
 with the GPU drivers from NVIDIA, AMD, and Intel, so make sure you have an
 up-to-date driver.
 
+To build the HIP platform, install the HIP SDK from https://rocm.docs.amd.com/projects/install-on-windows.
+
 Other Required Software
 -----------------------
 
@@ -304,6 +314,10 @@ There are several variables that can be adjusted in the CMake interface:
   "C:/Program Files/NVIDIA GPU Computing Toolkit/CUDA/v11.4/include", except
   with the correct version number for the toolkit you installed) and
   OPENCL_LIBRARY to point to the library (usually "C:/Program Files/NVIDIA GPU Computing Toolkit/CUDA/v11.4/lib/x64/OpenCL.lib").
+* If you are building the HIP platform, the SDK may be found automatically.  If
+  it is not, set HIP_DIR to "C:\AMD\ROCm\6.1\lib\cmake\hip" and HIPRTC_DIR to
+  "C:\AMD\ROCm\6.1\lib\cmake\hiprtc" (substituting the correct version number
+  for the SDK you installed).
 
 Press "Configure" again.  Adjust any variables that cause an error.
 

docs-source/usersguide/library/04_platform_specifics.rst

@@ -106,6 +106,12 @@ values.  For example,
 
 This tells it to use both devices 0 and 1, splitting the work between them.
 
+HIP Platform
+************
+
+The HIP Platform recognizes exactly the same Platform-specific properties as
+the CUDA platform.
+
 CPU Platform
 ************
 

docs-source/usersguide/library/08_amoeba_plugin.rst

@@ -11,9 +11,6 @@ accelerate AMOEBA simulations. TINKER-OpenMM can be created from a TINKER
 package using three files made available through the OpenMM home page. OpenMM
 AMOEBA Force and System objects containing AMOEBA forces can be serialized.
 
-At present, AMOEBA is only supported on the CUDA and Reference platforms, not on
-the OpenCL platform.
-
 In the following sections, the individual forces and options available in the
 plugin are listed, and the steps required to build and use the plugin and
 TINKER-OpenMM are outlined. Validation results are also reported.  Benchmarks