Reorganise documentation (#3165)

* Break user guide into parts

* Break up file I missed

* Add basic .gitignore to suit out-of-tree builds in build, build1, build2 ... build9

* Small changes to autonumber.py for doc compilation

This is a small change designed not to fix the incorrect logic of
autonumber.py, but just to get the docs compiling. While assigning
numbers, the code now just ignores the autonumber_by_chapter
setting for a particular object if it can't find the appropriate
section in section_numbers. This is a temporary fix!

* Include part and chapter in autonumbered objects

* Fix autonumber.py to correctly reference autonumber roles in file-level sections

* Unify and simplify styling across documentation

* Break dev docs down into individual chapter-files

* Correct absolute links to relative

* Disable browser suggestions for lunrsearch box in API docs

* Remove part name from chapter 2.1

* Rename ambiguous 'Home' link to OpenMM.org

* Typo

* Minor fixes and reversions

Reverts some changes I had made and later thought better of,
and fixes some recurring typos across the documentation.

* Number developers guide chapters

* Fix responsiveness

* Remove header.rst and center captions

* Add a level of depth to main TOC and styling to accomodate

* Add third level to Part-level TOCs

* Use :numref: instead of :ref: to number links to sections

* Continuously number chapters in user guide

* navbar links to other docs relative, not absolute

* Improve navbar spacing with new template

* Fix sidebar while allowing it to scroll

* Hard -> Soft links for navigation.html template

* Add navigation.html template to cmakelists

* Add another level of .. to relative links

* Fix flex on C++ and remove layer of ..

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

+.. _platform-specific-properties:
+
+Platform-Specific Properties
+############################
+
+When creating a Context, you can specify values for properties specific to a
+particular Platform.  This is used to control how calculations are done in ways
+that are outside the scope of the generic OpenMM API.
+
+To do this, pass both the Platform object and a map of property values to the
+Context constructor:
+
+.. code-block:: c
+
+    Platform& platform = Platform::getPlatformByName("OpenCL");
+    map<string, string> properties;
+    properties["DeviceIndex"] = "1";
+    Context context(system, integrator, platform, properties);
+
+After a Context is created, you can use the Platform’s \
+:code:`getPropertyValue()` method to query the values of properties.
+
+OpenCL Platform
+***************
+
+The OpenCL Platform recognizes the following Platform-specific properties:
+
+* Precision: This selects what numeric precision to use for calculations.
+  The allowed values are “single”, “mixed”, and “double”.  If it is set to
+  “single”, nearly all calculations are done in single precision.  This is the
+  fastest option but also the least accurate.  If it is set to “mixed”, forces are
+  computed in single precision but integration is done in double precision.  This
+  gives much better energy conservation with only a slight decrease in speed.
+  If it is set to “double”, all calculations are done in double precision.  This
+  is the most accurate option, but is usually much slower than the others.
+* UseCpuPme: This selects whether to use the CPU-based PME
+  implementation.  The allowed values are “true” or “false”.  Depending on your
+  hardware, this might (or might not) improve performance.  To use this option,
+  you must have FFTW (single precision, multithreaded) installed, and your CPU
+  must support SSE 4.1.
+* OpenCLPlatformIndex: When multiple OpenCL implementations are installed on
+  your computer, this is used to select which one to use.  The value is the
+  zero-based index of the platform (in the OpenCL sense, not the OpenMM sense) to use,
+  in the order they are returned by the OpenCL platform API.  This is useful, for
+  example, in selecting whether to use a GPU or CPU based OpenCL implementation.
+* DeviceIndex: When multiple OpenCL devices are available on your
+  computer, this is used to select which one to use.  The value is the zero-based
+  index of the device to use, in the order they are returned by the OpenCL device
+  API.
+
+
+The OpenCL Platform also supports parallelizing a simulation across multiple
+GPUs.  To do that, set the DeviceIndex property to a comma separated list
+of values.  For example,
+
+.. code-block:: c
+
+    properties["DeviceIndex"] = "0,1";
+
+This tells it to use both devices 0 and 1, splitting the work between them.
+
+CUDA Platform
+*************
+
+The CUDA Platform recognizes the following Platform-specific properties:
+
+* Precision: This selects what numeric precision to use for calculations.
+  The allowed values are “single”, “mixed”, and “double”.  If it is set to
+  “single”, nearly all calculations are done in single precision.  This is the
+  fastest option but also the least accurate.  If it is set to “mixed”, forces are
+  computed in single precision but integration is done in double precision.  This
+  gives much better energy conservation with only a slight decrease in speed.
+  If it is set to “double”, all calculations are done in double precision.  This
+  is the most accurate option, but is usually much slower than the others.
+* UseCpuPme: This selects whether to use the CPU-based PME implementation.
+  The allowed values are “true” or “false”.  Depending on your hardware, this
+  might (or might not) improve performance.  To use this option, you must have
+  FFTW (single precision, multithreaded) installed, and your CPU must support SSE
+  4.1.
+* CudaCompiler: This specifies the path to the CUDA kernel compiler.  Versions
+  of CUDA before 7.0 require a separate compiler executable.  If you do
+  not specify this, OpenMM will try to locate the compiler itself.  Specify this
+  only when you want to override the default location.  The logic used to pick the
+  default location depends on the operating system:
+
+  * Mac/Linux: It first looks for an environment variable called
+    OPENMM_CUDA_COMPILER.  If that is set, its value is used.  Otherwise, the
+    default location is set to /usr/local/cuda/bin/nvcc.
+  * Windows: It looks for an environment variable called CUDA_BIN_PATH, then
+    appends \nvcc.exe to it.  That environment variable is set by the CUDA
+    installer, so it usually is present.
+
+* TempDirectory: This specifies a directory where temporary files can be
+  written while compiling kernels.  OpenMM usually can locate your operating
+  system’s temp directory automatically (for example, by looking for the TEMP
+  environment variable), so you rarely need to specify this.
+* DeviceIndex: When multiple CUDA devices are available on your computer,
+  this is used to select which one to use.  The value is the zero-based index of
+  the device to use, in the order they are returned by the CUDA API.
+* UseBlockingSync: This is used to control how the CUDA runtime
+  synchronizes between the CPU and GPU.  If this is set to “true” (the default),
+  CUDA will allow the calling thread to sleep while the GPU is performing a
+  computation, allowing the CPU to do other work.  If it is set to “false”, CUDA
+  will spin-lock while the GPU is working.  Setting it to "false" can improve performance slightly,
+  but also prevents the CPU from doing anything else while the GPU is working.
+* DeterministicForces: In some cases, the CUDA platform may compute forces
+  in ways that are not fully deterministic (typically differing in what order a
+  set of numbers get added together).  This means that if you compute the forces
+  twice for the same particle positions, there may be tiny differences in the
+  results.  In most cases this is not a problem, but certain algorithms depend
+  on forces being exactly reproducible to the last bit.  If you set this
+  property to "true", it will instead do these calculations in a way that
+  produces fully deterministic results, at the cost of a small decrease in
+  performance.
+
+The CUDA Platform also supports parallelizing a simulation across multiple GPUs.
+To do that, set the DeviceIndex property to a comma separated list of
+values.  For example,
+
+.. code-block:: c
+
+    properties["DeviceIndex"] = "0,1";
+
+This tells it to use both devices 0 and 1, splitting the work between them.
+
+CPU Platform
+************
+
+The CPU Platform recognizes the following Platform-specific properties:
+
+* Threads: This specifies the number of CPU threads to use.  If you do not
+  specify this, OpenMM will select a default number of threads as follows:
+
+  * If an environment variable called OPENMM_CPU_THREADS is set, its value is
+    used as the number of threads.
+  * Otherwise, the number of threads is set to the number of logical CPU cores
+    in the computer it is running on.
+
+  Usually the default value works well.  This is mainly useful when you are
+  running something else on the computer at the same time, and you want to
+  prevent OpenMM from monopolizing all available cores.
+
+.. _platform-specific-properties-determinism:
+
+Determinism
+***********
+
+Whether a simulation is deterministic will depend on what plaform you run on in
+addition to what settings/methods you use. For instance, as of this writing,
+using PME on the Reference, OpenCL, and double-precision CUDA will result in
+deterministic simulations. Single-precision CUDA and CPU platforms are not
+deterministic in this case. However, none of this behavior is guaranteed in
+future versions. In many cases it will still result in an identical trajectory.
+If determinism is a critical for your needs, you should carefully check to
+ensure that your settings and platform allow for this.

docs-source/usersguide/library/09_rpmd_plugin.rst

+.. _ring-polymer-molecular-dynamics-plugin:
+
+Ring Polymer Molecular Dynamics (RPMD) Plugin
+#############################################
+
+Ring Polymer Molecular Dynamics (RPMD) provides an efficient approach to include
+nuclear quantum effects in molecular simulations.\ :cite:`Craig2004`  When
+used to calculate static equilibrium properties, RPMD reduces to path integral
+molecular dynamics and gives an exact description of the effect of quantum
+fluctuations for a given potential energy model.\ :cite:`Parrinello1984`  For
+dynamical properties RPMD is no longer exact but has shown to be a good
+approximation in many cases.
+
+For a system with a classical potential energy *E*\ (\ *q*\ ), the RPMD
+Hamiltonian is given by
+
+
+.. math::
+   H=\sum _{k=1}^{n}\left(\frac{{p}_{{k}^{2}}}{2m}+E({q}_{k})+\frac{m({k}_{B}Tn)^{2}}{2\hbar^{2}}({q}_{k}-{q}_{k-1})^{2}\right)
+
+
+This Hamiltonian resembles that of a system of classical ring polymers where
+different copies of the system are connected by harmonic springs.  Hence each
+copy of the classical system is commonly referred to as a “bead”.  The spread of
+the ring polymer representing each particle is directly related to its De
+Broglie thermal wavelength (uncertainty in its position).
+
+RPMD calculations must be converged with respect to the number *n* of beads
+used.  Each bead is evolved at the effective temperature *nT*\ , where *T*
+is the temperature for which properties are required.  The number of beads
+needed to converge a calculation can be estimated using\ :cite:`Markland2008`
+
+
+.. math::
+   n>\frac{\hbar\omega_{max}}{{k}_{B}T}
+
+
+where :math:`\omega_{max}` is the highest frequency in the problem.  For example, for
+flexible liquid water the highest frequency is the OH stretch at around 3000
+cm\ :sup:`-1`\ , so around 24 to 32 beads are needed depending on the accuracy
+required.  For rigid water where the highest frequency is only around 1000
+cm\ :sup:`-1`\ , only 6 beads are typically needed.  Due to the replication needed
+of the classical system, the extra cost of the calculation compared to a
+classical simulation increases linearly with the number of beads used.
+
+This cost can be reduced by “contracting” the ring polymer to a smaller number
+of beads.\ :cite:`Markland2008`  The rapidly changing forces are then computed
+for the full number of beads, while slower changing forces are computed on a
+smaller set.  In the case of flexible water, for example, a common arrangement
+would be to compute the high frequency bonded forces on all 32 beads, the direct
+space nonbonded forces on only 6 beads, and the reciprocal space nonbonded
+forces on only a single bead.
+
+Due to the stiff spring terms between the beads, NVE RPMD trajectories can
+suffer from ergodicity problems and hence thermostatting is highly recommended,
+especially when dynamical properties are not required.\ :cite:`Hall1984`  The
+thermostat implemented here is the path integral Langevin equation (PILE)
+approach.\ :cite:`Ceriotti2010`  This method couples an optimal white noise
+Langevin thermostat to the normal modes of each polymer, leaving only one
+parameter to be chosen by the user which controls the friction applied to the
+center of mass of each ring polymer.  A good choice for this is to use a value
+similar to that used in a classical calculation of the same system.
+