docs/dev-manual/physical_validation.rst

   1 Physical validation
   2 ===================
   3
   4 Physical validation tests check whether simulation results correspond
   5 to physical (or mathematical) expectations.
   6
   7 Unlike the existing tests, we are not be able to keep these tests in
   8 the "seconds, not minutes" time frame, rather aiming for "hours, not
   9 days".  They should therefore be ran periodically, but probably not
  10 for every build.
  11
  12 Also, given the long run time, it will in many cases be necessary to
  13 separate running of the systems (e.g. to run it at a specific time, or
  14 on a different resource), such that the make script does give the
  15 option to
  16
  17 * prepare run files and an execution script,
  18 * analyze already present simulations,
  19 * or prepare, run and analyze in one go.
  20
  21
  22 Test description
  23 ----------------
  24
  25 Currently, simulation results are tested against three physically /
  26 mathematically expected results:
  27
  28 * *Integrator convergence*: A symplectic integrator can be shown to
  29   conserve a constant of motion (such as the energy in a
  30   micro-canonical simulation) up to a fluctuation that is quadratic in
  31   time step chosen. Comparing two or more constant-of-motion
  32   trajectories realized using different time steps (but otherwise
  33   unchanged simulation parameters) allows a check of the symplecticity
  34   of the integration. Note that lack of symplecticity does not
  35   necessarily imply an error in the integration algorithm, it can also
  36   hint at physical violations in other parts of the model, such as
  37   non-continuous potential functions, imprecise handling of
  38   constraints, etc.
  39 * *Kinetic energy distribution*: The kinetic energy trajectory of a
  40   (equilibrated) system sampling a canonical or an isothermal-isobaric
  41   ensemble is expected to be Maxwell-Boltzmann distributed. The
  42   similarity between the physically expected and the observed
  43   distribution allows to validate the sampled kinetic energy ensemble.
  44 * *Distribution of configurational quantities*: As the distribution of
  45   configurational quantities like the potential energy or the volume
  46   are in general not known analytically, testing the likelihood of a
  47   trajectory sampling a given ensemble is less straightforward than
  48   for the kinetic energy. However, generally, the ratio of the
  49   probability distribution between samples of the same ensemble at
  50   different state points (e.g. at different temperatures, different
  51   pressures) is known. Comparing two simulations at different state
  52   points therefore allows a validation of the sampled ensemble.
  53
  54 The physical validation included in GROMACS tests a range of the
  55 most-used settings on several systems. The general philosophy is to
  56 leave most settings to default values with the exception of the ones
  57 explicitly tested in order to be sensitive to changes in the default
  58 values. The test set will be enlarged as we discover interesting test
  59 systems and corner cases. Under double precision, some additional
  60 tests are ran, and some other tests are ran using a lower tolerance.
  61
  62
  63 Integrator convergence
  64 ^^^^^^^^^^^^^^^^^^^^^^
  65
  66 All simulations performed under NVE on Argon (1000 atoms) and water
  67 (900 molecules) systems. As these tests are very sensitive to
  68 numerical imprecision, they are performed with long-range corrections
  69 for both Lennard-Jones and electrostatic interactions, with a very low
  70 pair-list tolerance (``verlet-buffer-tolerance = 1e-10``), and high
  71 LINCS settings where applicable.
  72
  73 **Argon**:
  74
  75 * *Integrators*:
  76   - ``integrator = md``
  77   - ``integrator = md-vv``
  78 * *Long-range corrections LJ*:
  79   - ``vdwtype = PME``
  80   - ``vdwtype = cut-off``, ``vdw-modifier = force-switch``,
  81     ``rvdw-switch = 0.8``
  82
  83 **Water**:
  84
  85 * *Integrators*:
  86   - ``integrator = md``
  87   - ``integrator = md-vv``
  88 * *Long-range corrections LJ*:
  89   - ``vdwtype = PME``
  90   - ``vdwtype = cut-off``, ``vdw-modifier = force-switch``,
  91     ``rvdw-switch = 0.8``
  92 * *Long-range corrections electrostatics*:
  93   - ``coulombtype = PME``, ``fourierspacing = 0.05``
  94 * *Constraint algorithms*:
  95   - ``constraint-algorithm = lincs``, ``lincs-order = 6``,
  96     ``lincs-iter = 2``
  97   - ``constraint-algorithm = none``
  98   - SETTLE
  99
 100
 101 Ensemble tests
 102 ^^^^^^^^^^^^^^
 103
 104 The generated ensembles are tested with Argon (1000 atoms) and water
 105 (900 molecules, with SETTLE and PME) systems, in the following
 106 combinations:
 107
 108 * ``integrator = md``, ``tcoupl = v-rescale``, ``tau-t = 0.1``,
 109   ``ref-t = 87.0`` (Argon) or ``ref-t = 298.15`` (Water)
 110 * ``integrator = md``, ``tcoupl = v-rescale``, ``tau-t = 0.1``,
 111   ``ref-t = 87.0`` (Argon) or ``ref-t = 298.15`` (Water), ``pcoupl =
 112   parrinello-rahman``, ``ref-p = 1.0``, ``compressibility = 4.5e-5``
 113 * ``integrator = md-vv``, ``tcoupl = v-rescale``, ``tau-t = 0.1``,
 114   ``ref-t = 87.0`` (Argon) or ``ref-t = 298.15`` (Water)
 115 * ``integrator = md-vv``, ``tcoupl = nose-hoover``, ``tau-t = 1.0``,
 116   ``ref-t = 87.0`` (Argon) or ``ref-t = 298.15`` (Water), ``pcoupl =
 117   mttk``, ``ref-p = 1.0``, ``compressibility = 4.5e-5``
 118
 119 All thermostats are applied to the entire system (``tc-grps =
 120 system``). The simulations run for 1ns at 2fs time step with Verlet
 121 cut-off. All other settings left to default values.
 122
 123
 124 Building and testing using the build system
 125 -------------------------------------------
 126
 127 Since these tests can not be ran at the same frequency as the current
 128 tests, they are kept strictly opt-in via
 129 ``-DGMX_PHYSICAL_VALIDATION=ON``, with
 130 ``-DGMX_PHYSICAL_VALIDATION=OFF`` being the default. Independently of
 131 that, all previously existing build targets are unchanged, including
 132 ``make check``.
 133
 134 If physical validation is turned on, a number of additional make
 135 targets can be used:
 136
 137 * ``make check`` is unchanged, it builds the main binaries and the unit
 138   tests, then runs the unit tests and, if available, the regression
 139   tests.
 140 * ``make check-phys`` builds the main binaries, then runs the physical
 141   validation tests. **Warning**: This requires to simulate all systems
 142   and might take several hours on a average machine!
 143 * ``make check-all`` combines ``make check`` and ``make check-phys``.
 144
 145 As the simulations needed to perform the physical validation tests may
 146 take long, it might be advantageous to run them on an external
 147 resource. To enable this, two additional make targets are present:
 148
 149 * ``make check-phys-prepare`` prepares all simulation files under
 150   ``tests/physicalvalidation`` of the build directory, as well as a
 151   rudimentary run script in the same directory.
 152 * ``make check-phys-analyze`` runs the same tests as ``make
 153   check-phys``, but does not simulate the systems. Instead, this
 154   target assumes that the results can be found under
 155   ``tests/physicalvalidation`` of the build directory.
 156
 157 The intended usage of these additional targets is to prepare the
 158 simulation files, then run them on a different resource or at a
 159 different time, and later analyze them. If you want to use this, be
 160 aware *(i)* that the run script generated is very simple and might
 161 need (considerable) tuning to work with your setup, and *(ii)* that
 162 the analysis script is sensitive to the folder structure, so make sure
 163 to preserve it when copying the results to / from another resource.
 164
 165 Additionally to the mentioned make targets, a number of internal make
 166 targets are defined. These are not intended to be used directly, but
 167 are necessary to support the functionality described above, especially
 168 the complex dependencies. These internal targets include
 169 ``run-ctest``, ``run-ctest-nophys``, ``run-ctest-phys`` and
 170 ``run-ctest-phys-analyze`` running the different tests,
 171 ``run-physval-sims`` running the simulations for physical validation,
 172 and ``missing-tests-notice``, ``missing-tests-notice-all``,
 173 ``missing-phys-val-phys``, ``missing-phys-val-phys-analyze`` and
 174 ``missing-phys-val-all`` notifying users about missing tests.
 175
 176
 177 Direct usage of the python script
 178 ---------------------------------
 179
 180 The ``make`` commands mentioned above are calling the python script
 181 ``tests/physicalvalidation/gmx_physicalvalidation.py``, which can be
 182 used independently of the make system. Use the ``-h`` flag for the
 183 general usage information, and the ``--tests`` for more details on the
 184 available physical validations.
 185
 186 The script requires a ``json`` file defining the tests as an input.
 187 Among other options, it allows to define the GROMACS binary and the
 188 working directory to be used, and to decide whether to only prepare
 189 the simulations, prepare and run the simulations, only analyze the
 190 simulations, or do all three steps at once.
 191
 192
 193 Adding new tests
 194 ----------------
 195
 196 The available tests are listed in the ``systems.json`` (tests
 197 standardly used for single precision builds) and ``systems_d.json``
 198 (tests standardly used for double precision builds) files in the same
 199 directory, the GROMACS files are in the folder ``systems/``.
 200
 201 The ``json`` files lists the different test. Each test has a
 202 ``"name"`` attribute, which needs to be unique, a ``"dir"`` attribute,
 203 which denotes the directory of the system (inside the ``systems/``
 204 directory) to be tested, and a ``"test"`` attribute which lists the
 205 validations to be performed on the system. Additionally, the optional
 206 ``"grompp_args"`` and ``"mdrun_args"`` attributes allow to pass
 207 specific arguments to ``gmx grompp`` or ``gmx mdrun``, respectively. A
 208 single test can contain several validations, and several independent
 209 tests can be performed on the same input files.
 210
 211 To add a new test to a present system, add the test name and the
 212 arguments to the ``json`` file(s). To use a new system, add a
 213 subfolder in the ``systems/`` directory containing
 214 ``input/system.{gro,mdp,top}`` files defining your system.