An example for RPC+MTS dynamics in i-PI

Adapted from https://github.com/i-pi/piqm2023-tutorial/tree/main/02-rpc_mts

---------

Co-authored-by: Michele Ceriotti <[email protected]>
Co-authored-by: Michele Ceriotti <[email protected]>

docs/src/software/chemiscope.sec

@@ -17,3 +17,4 @@ repository <https://github.com/lab-cosmo/chemiscope>`_.
 - examples/pi-metad/pi-metad
 - examples/path-integrals/path-integrals
 - examples/thermostats/thermostats
+- examples/pi-mts-rpc/mts-rpc

docs/src/software/i-pi.sec

@@ -12,3 +12,4 @@ it on the `ipi-code website <http://ipi-code.org>`_, the `documentation pages
 - examples/path-integrals/path-integrals
 - examples/pi-metad/pi-metad
 - examples/heat-capacity/heat-capacity
+- examples/pi-mts-rpc/mts-rpc

docs/src/topics/nqes.sec

@@ -9,3 +9,4 @@ statistical sampling to compute accurate statistical and dynamical properties.
 - examples/path-integrals/path-integrals
 - examples/pi-metad/pi-metad
 - examples/heat-capacity/heat-capacity
+- examples/pi-mts-rpc/mts-rpc

docs/src/topics/sampling.sec

@@ -10,3 +10,4 @@ set of configurations of an atomistic system.
 - examples/pi-metad/pi-metad
 - examples/batch-cp2k/reference-trajectory
 - examples/heat-capacity/heat-capacity
+- examples/pi-mts-rpc/mts-rpc

examples/pi-mts-rpc/README.rst

@@ -0,0 +1,30 @@
+Multiple time stepping and ring-polymer contraction
+===================================================
+
+This notebook provides an introduction to two closely-related techniques,
+that are geared towards reducing the cost of calculations by separating
+slowly-varying (and computationally-expensive) components of the potential
+energy from the fast-varying (and hopefully cheaper) ones.
+
+The first is named `multiple time stepping`, and is a well-established technique
+to avoid evaluating the slowly-varying components at every time step of a MD simulation.
+It was first introduced in `LAMMPS <https://lammps.org>`_.
+`M. Tuckerman, B. J. Berne, and G. J. Martyna, JCP 97(3), 1990 (1992) <https://doi.org/10.1063/1.463137>`_
+and can be applied to classical simulations,
+typically to avoid the evaluation of long-range electrostatics in classical potentials. 
+
+The second is named `ring polymer contraction`, first introduced in 
+`T. E. Markland and D. E. Manolopoulos, JCP 129(2), 024105 (2008) <https://doi.org/10.1063/1.2953308>`_
+can be seen as performing a similar simplification `in imaginary time`,
+evaluating the expensive part of the potential on a smaller number of PI replicas. 
+
+The techniques can be combined, which reduces even further the computational effort.
+This dual approach, which was introduced in
+`V. Kapil, J. VandeVondele, and M. Ceriotti, JCP 144(5), 054111 (2016) <(https://doi.org/10.1063/1.4941091>`_
+and `O. Marsalek and T. E. Markland, JCP 144(5), (2016) <https://doi.org/10.1063/1.4941093>`_,
+is the one that we will discuss here, allowing us to showcase two advanced features of i-PI.
+It is worth stressing that MTS and/or RPC can be used very conveniently together with
+machine-learning potentials
+(see e.g. `V. Kapil, J. Behler, and M. Ceriotti, JCP 145(23), 234103 (2016 <https://doi.org/10.1063/1.4971438>`_ 
+for an early application). 
+

examples/pi-mts-rpc/data/h2o_md.xml

@@ -0,0 +1,31 @@
+<simulation verbosity='medium'>
+  <output prefix='md'>
+    <properties filename='out' stride='4'> [step, time{picosecond}, conserved{electronvolt}, temperature{kelvin}, potential{electronvolt}, kinetic_md{electronvolt}, pressure_md{megapascal} ] </properties>
+    <trajectory filename='pos' stride='100' format='xyz' cell_units='angstrom'> positions{angstrom} </trajectory>
+    <checkpoint filename='checkpoint' stride='1000' overwrite='True'/>
+  </output>
+  <total_steps> 10000 </total_steps>
+  <ffsocket mode='unix' name='qtip4pf' pbc='false'>
+      <address>qtip4pf-md</address>
+  </ffsocket>  
+  <system>
+    <initialize nbeads='1'>
+      <file mode='pdb' units='angstrom'> data/water_32.pdb </file>
+      <velocities mode='thermal' units='kelvin'> 300 </velocities>
+    </initialize>
+    <forces>
+      <force forcefield='qtip4pf'></force>
+    </forces>
+    <ensemble>
+      <temperature units='kelvin'> 300 </temperature>
+    </ensemble>
+    <motion mode='dynamics'>
+      <dynamics mode='nvt'>
+          <timestep units='femtosecond'> 0.5 </timestep>
+          <thermostat mode="svr">
+             <tau units="femtosecond"> 400 </tau>
+          </thermostat>
+      </dynamics>
+    </motion>
+  </system>
+</simulation>

examples/pi-mts-rpc/data/h2o_mts.xml

@@ -0,0 +1,40 @@
+<simulation verbosity='medium'>
+  <output prefix='mts'>
+    <properties filename='out' stride='1'> [step, time{picosecond}, conserved{electronvolt}, temperature{kelvin}, potential{electronvolt}, kinetic_md{electronvolt}, pressure_md{megapascal}, pot_component{electronvolt}(0), pot_component{electronvolt}(1) ] </properties>
+    <trajectory filename='pos' stride='100' format='xyz' cell_units='angstrom'> positions{angstrom} </trajectory>
+    <checkpoint filename='checkpoint' stride='1000' overwrite='True'/>
+  </output>
+  <total_steps> 2500 </total_steps>
+  <ffsocket mode='unix' name='qtip4pf' pbc='false'>
+      <address>qtip4pf-mts-full</address>
+  </ffsocket>
+  <ffsocket mode='unix' name='qtip4pf-sr' pbc='false'>
+      <address>qtip4pf-mts-sr</address>
+  </ffsocket>
+  <system>
+      <initialize nbeads='1'>
+      <file mode='pdb' units='angstrom'> data/water_32.pdb </file>    
+      <velocities mode='thermal' units='kelvin'> 300 </velocities>
+    </initialize>
+    <forces>
+      <force forcefield='qtip4pf'>
+        <mts_weights>[1,0]</mts_weights>
+      </force>
+      <force forcefield='qtip4pf-sr'>
+        <mts_weights>[-1,1]</mts_weights>
+      </force>
+    </forces>
+    <ensemble>
+      <temperature units='kelvin'> 300 </temperature>
+    </ensemble>
+    <motion mode='dynamics'>
+      <dynamics mode='nvt'>
+          <timestep units='femtosecond'> 2.0 </timestep>
+          <nmts>[1,4]</nmts>
+          <thermostat mode="svr">
+             <tau units="femtosecond"> 400 </tau>
+          </thermostat>
+      </dynamics>
+    </motion>
+  </system>
+</simulation>