Improve install guide

Author: zhi-wang

CMakeLists.txt

@@ -5,21 +5,47 @@ cmake_minimum_required (VERSION 3.15)
 !!/ Build Tinker9 with CMake
 !!/ ========================
 !!/
+!!/ Quick Start
+!!/ -----------
+!!/
+!!/ For a GPU card with compute capability 7.0,
+!!/ an example to compile the GPU code without OpenACC:
+!!/
+!!/ .. code-block:: bash
+!!/
+!!/    cd tinker9 && mkdir build
+!!/    FC=gfortran compute_capability=70 gpu_lang=cuda cmake ..
+!!/    make
+!!/    make test
+!!/
+!!/ Assuming separate CUDA and NVHPC are properly installed,
+!!/ another example to compile the GPU code with both OpenACC and CUDA:
+!!/
+!!/ .. code-block:: bash
+!!/
+!!/    cd tinker9 && mkdir build
+!!/    cmake -DCMAKE_Fortran_COMPILER=gfortran -DCOMPUTE_CAPABILITY=70 ..
+!!/    make
+!!/    make test
+!!/
+!!/ For the options of other GPU devices and features,
+!!/ please refer to the subsequent sections.
+!!/
 !!/ Configure CMake
 !!/ ---------------
 !!/ You can skip this section if you are familar with CMake.
 !!/
 !!/ Suppose the current working directory is */home/tinker9* and we
-!!/ want to create a build directory called *build-cmake* in
-!!/ */home/tinker9*. We can do *mkdir build-cmake* then *cd build-cmake*.
+!!/ want to create a build directory called *build* in
+!!/ */home/tinker9*. We can do *mkdir build* then *cd build*.
 !!/ Because the top-level CMakeLists.txt file is in the parent directory,
 !!/ if there was nothing else to configure, command *cmake ..* would generate
 !!/ the Makefile. The alternative way is to specify the build and source
 !!/ directories to CMake, e.g.,
 !!/
 !!/ .. code-block:: bash
 !!/
-!!/    cmake -B /home/tinker9/build-cmake -S /home/tinker9
+!!/    cmake -B /home/tinker9/build -S /home/tinker9
 !!/
 !!/ Some CMake installations also provide a command line gui *ccmake* and a
 !!/ simple gui program *cmake-gui* that can replace *cmake* in the commands
@@ -51,32 +77,6 @@ cmake_minimum_required (VERSION 3.15)
 !!/ by its corresponding environmental variable, documented as **(env)** here.
 !!/ Note that there is no **-D** prefix for the environmental variables.
 !!/
-!!/ Here are two equivalent examples to have Tinker9 configured as follows
-!!/
-!!/ =======================  ===================
-!!/ Item                     Value
-!!/ =======================  ===================
-!!/ opt                      release
-!!/ host                     0
-!!/ prec                     m
-!!/ cuda_dir                 /usr/local/cuda
-!!/ compute_capability       75
-!!/ CMakeLists.txt Location  /home/tinker9
-!!/ =======================  ===================
-!!/
-!!/ .. code-block:: bash
-!!/
-!!/    # use environmental variables
-!!/    opt=release host=0 prec=m \
-!!/    cuda_dir=/usr/local/cuda compute_capability=75 \
-!!/    cmake /home/tinker9
-!!/
-!!/    # use cmake -DOPTIONS
-!!/    cmake /home/tinker9 \
-!!/    -DCMAKE_BUILD_TYPE=Release -DHOST=0 -DPREC=m \
-!!/    -DCUDA_DIR=/usr/local/cuda -DCOMPUTE_CAPABILITY=75
-!!/
-!!/
 ]]
 
 

README.md

@@ -10,7 +10,7 @@ Tinker9: Next Generation of Tinker with GPU Support
 Tinker9 is a complete rewrite and extension of the canonical Tinker software, currently Tinker8. Tinker9 is implemented as C++ code with OpenACC directives and CUDA kernels providing excellent performance on GPUs. At present, Tinker9 builds against the object library from Tinker8, and provides GPU versions of the Tinker ANALYZE, BAR, DYNAMIC, MINIMIZE and TESTGRAD programs. Existing Tinker file formats and force field parameter files are fully compatible with Tinker9, and nearly all Tinker8 keywords function identically in Tinker9. Over time we plan to port much or all of the remaining portions of Fortran Tinker8 to the C++ Tinker9 code base.
 
 
-<h2><a href="https://github.com/TinkerTools/tinker9/discussions/197">
+<h2><a href="https://github.com/TinkerTools/tinker9/releases">
 Release Notes
 </a></h2>
 
@@ -28,6 +28,7 @@ The executables included in these images were compiled on a recent computer. It
    2. [Download the Canonical Tinker (important to get the REQUIRED version)](doc/manual/m/install/tinker.rst)
    3. [Build Tinker9 with CMake](doc/manual/m/install/buildwithcmake.rst)
 
+Examples of other successful builds are shown [here](https://github.com/TinkerTools/tinker9/discussions/121).
 
 <h2>User Manual (in progress)</h2>
 

doc/doc.h

@@ -6,12 +6,16 @@
  *
  * \defgroup platform                   Platforms
  * \brief Platforms and platform-specific syntaxes
+ *
  *    \defgroup cpp_syntax              C++ Syntax
  *    \ingroup platform
+ *
  *    \defgroup cuda_syntax             CUDA Syntax
  *    \ingroup platform
+ *
  *    \defgroup acc_syntax              OpenACC Syntax
  *    \ingroup platform
+ *
  *    \defgroup nvidia                  NVIDIA GPU
  *    \ingroup platform
  *
@@ -26,11 +30,37 @@
  *
  * \defgroup egv                        Energy
  * \brief Energy, gradient, virial tensor, and number of interactions
+ *
+ * \defgroup bonded                     Valence
+ * \brief Valence potential energies
+ *
+ *    \defgroup bond                    Bond
+ *    \ingroup bonded
+ *    \brief Bond stretching
+ *
+ *    \defgroup angle                   Angle
+ *    \ingroup bonded
+ *    \brief Angle bending and Out-of-Plane bend
+ *
+ *    \defgroup strbnd                  Stretch-Bend
+ *    \ingroup bonded
+ *    \brief Stretch-bend cross term
+ *
+ *    \defgroup urey                    Urey-Bradley
+ *    \ingroup bonded
+ *    \brief Urey-Bradley term
+ *
+ *    \defgroup torsion                 Torsion
+ *    \ingroup bonded
+ *    \brief Torsion, improper torsion, improper dihedral, Pi-orbital torsion coupling,
+ *           stretch-torsion coupling, angle-torsion coupling, and torsion-torsion coupling
+ *
+ *    \defgroup geom                    Restraint
+ *    \ingroup bonded
+ *    \brief Geometric Restraints
  */
 
 /// \defgroup ff  Force Fields
-///    \defgroup bonded  Valence Terms
-///    \ingroup ff
 ///    \defgroup vdw  Van der Waals (VDW)
 ///    \ingroup ff
 ///    \defgroup charge  Partial Charge Electrostatics

doc/manual/m/install/buildwithcmake.rst

@@ -1,21 +1,47 @@
 Build Tinker9 with CMake
 ========================
 
+Quick Start
+-----------
+
+For a GPU card with compute capability 7.0,
+an example to compile the GPU code without OpenACC:
+
+.. code-block:: bash
+
+   cd tinker9 && mkdir build
+   FC=gfortran compute_capability=70 gpu_lang=cuda cmake ..
+   make
+   make test
+
+Assuming separate CUDA and NVHPC are properly installed,
+another example to compile the GPU code with both OpenACC and CUDA:
+
+.. code-block:: bash
+
+   cd tinker9 && mkdir build
+   cmake -DCMAKE_Fortran_COMPILER=gfortran -DCOMPUTE_CAPABILITY=70 ..
+   make
+   make test
+
+For the options of other GPU devices and features,
+please refer to the subsequent sections.
+
 Configure CMake
 ---------------
 You can skip this section if you are familar with CMake.
 
 Suppose the current working directory is */home/tinker9* and we
-want to create a build directory called *build-cmake* in
-*/home/tinker9*. We can do *mkdir build-cmake* then *cd build-cmake*.
+want to create a build directory called *build* in
+*/home/tinker9*. We can do *mkdir build* then *cd build*.
 Because the top-level CMakeLists.txt file is in the parent directory,
 if there was nothing else to configure, command *cmake ..* would generate
 the Makefile. The alternative way is to specify the build and source
 directories to CMake, e.g.,
 
 .. code-block:: bash
 
-   cmake -B /home/tinker9/build-cmake -S /home/tinker9
+   cmake -B /home/tinker9/build -S /home/tinker9
 
 Some CMake installations also provide a command line gui *ccmake* and a
 simple gui program *cmake-gui* that can replace *cmake* in the commands
@@ -47,32 +73,6 @@ In addition to these two canonical methods, default value can also be set
 by its corresponding environmental variable, documented as **(env)** here.
 Note that there is no **-D** prefix for the environmental variables.
 
-Here are two equivalent examples to have Tinker9 configured as follows
-
-=======================  ===================
-Item                     Value
-=======================  ===================
-opt                      release
-host                     0
-prec                     m
-cuda_dir                 /usr/local/cuda
-compute_capability       75
-CMakeLists.txt Location  /home/tinker9
-=======================  ===================
-
-.. code-block:: bash
-
-   # use environmental variables
-   opt=release host=0 prec=m \
-   cuda_dir=/usr/local/cuda compute_capability=75 \
-   cmake /home/tinker9
-
-   # use cmake -DOPTIONS
-   cmake /home/tinker9 \
-   -DCMAKE_BUILD_TYPE=Release -DHOST=0 -DPREC=m \
-   -DCUDA_DIR=/usr/local/cuda -DCOMPUTE_CAPABILITY=75
-
-
 **-DCMAKE_BUILD_TYPE (opt) = Release**
 
 Standard *CMAKE_BUILD_TYPE* option. Build type is case insensitive and

doc/manual/m/install/preq.rst

@@ -8,33 +8,21 @@ The oldest NVIDIA GPU Tinker9 has been tested on is GeForce GTX 675MX (compute c
 
 **Operating Systems and Compilers**
 
-In order to compile the GPU code with full functionality, a recent
-`NVIDIA HPC SDK <https://www.developer.nvidia.com/hpc-sdk>`_
-is preferred for the OpenACC directives. Due to its limitations,
-the *full* version is unavailable on macOS.
-
-For Linux, we need:
-
-- GNU or Intel Fortran compiler.
-- Recent C++ compiler that supports C++11 syntax.
-- CMake 3.15 or newer.
-- (GPU code only) NVIDIA HPC SDK with OpenACC support, and CUDA with nvcc.
-- If NVIDIA driver has been installed correctly, *nvidia-smi* should be
-  available.
-
-For Windows, we have successfully built Tinker9 on Windows WSL2 Ubuntu with
-CUDA 11.0 and NVHPC 20.9. Please proceed to
-`this NVIDIA webpage <https://docs.nvidia.com/cuda/wsl-user-guide/index.html>`_
-for more details.
-
-The majority of the functionalities are also implemented in CUDA.
-To compile this subset (PureCuda) of the GPU kernels, NVIDIA HPC SDK is not mandatory.
-Please refer to *Build Tinker9 with CMake* for the flags to compile
-the *PureCuda* GPU kernels.
-It is even possible to compile and run the *PureCuda* version on macOS
-(El Capitan 10.13 or earlier), if suitable drivers and CUDA toolkits are installed.
-If the calculation selects one of the missing functionalities that is only implemented
-in OpenACC, the program will throw a runtime error.
+=================  ===========================
+OS and Toolchain   Version
+=================  ===========================
+OS                 Linux, WSL2, macOS <= 10.13
+CMake              >= 3.15
+Fortran            GNU or Intel
+C++                [a]
+CUDA/nvcc          [b]
+OpenACC/NVHPC/PGI  [c]
+=================  ===========================
+
+- [a] Recent C++ compiler that supports C++11 syntax.
+- [b] GPU code only. Version >= 9.0.
+- [c] Optional for the GPU code. A recent `NVIDIA HPC SDK <https://www.developer.nvidia.com/hpc-sdk>`_ is preferred.
+- [d] We have successfully built Tinker9 on Windows WSL2 Ubuntu with CUDA 11.0 and NVHPC 20.9. Please `check this link <https://docs.nvidia.com/cuda/wsl-user-guide/index.html>`_ for more details.
 
 **Using NVIDIA HPC SDK on Clusters**
 

doc/manual/m/install/tinker.rst

@@ -1,35 +1,31 @@
 Download the Canonical Tinker
 =============================
 
+Using the incorrect Tinker version, the executables are likely to fail with segfault.
 Since **d71f4793** (`Dec. 6, 2021 <https://github.com/TinkerTools/tinker9/commit/d71f4793>`_),
 downloading the required Tinker version is automated in the CMake script.
-For versions prior to this commit, please refer to the following paragraphs.
+For versions prior to this commit, please refer to the following.
 
-**Deprecated 1**
+   **Deprecated**
 
-Using the incorrect Tinker version, the executables would be
-very likely to fail with segfault.
+   If this source code was cloned by Git, you can
+   checkout Tinker from the *tinker* Git submodule:
 
-If this source code was cloned by Git, you can
-checkout Tinker from the *tinker* Git submodule:
+   .. code-block:: bash
 
-.. code-block:: bash
+      # checkout Tinker
+      cd tinker9
+      git submodule update --init
 
-   # checkout Tinker
-   cd tinker9
-   git submodule update --init
+   Alternatively, remove the directory *tinker9/tinker* and clone
+   `Tinker from GitHub <https://github.com/tinkertools/tinker>`_
+   to replace the deleted directory,
+   then checkout the required version **3dc966e2**.
 
-**Deprecated 2**
+   .. code-block:: bash
 
-Alternatively, remove the directory *tinker9/tinker* and clone
-`Tinker from GitHub <https://github.com/tinkertools/tinker>`_
-to replace the deleted directory,
-then checkout the required version **3dc966e2**.
-
-.. code-block:: bash
-
-   cd tinker9
-   rm -rf tinker
-   git clone https://github.com/tinkertools/tinker
-   cd tinker
-   git checkout <TheRequiredVersion>
+      cd tinker9
+      rm -rf tinker
+      git clone https://github.com/tinkertools/tinker
+      cd tinker
+      git checkout <TheRequiredVersion>