Skip to content

Commit 549bc94

Browse files
mgasteggermgastegger
authored
Moved and adapted CLI docs for MD. (#447)
1 parent ed88ace commit 549bc94

File tree

2 files changed

+703
-366
lines changed

2 files changed

+703
-366
lines changed

Diff for: ‎docs/userguide/md.rst

+267-5
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,270 @@
1-
===============================
2-
Run MD simulations with the CLI
3-
===============================
1+
===================================
2+
Running MD simulations with the CLI
3+
===================================
44
.. _md:
55

6+
Similar to the basic SchNetPack usage, it is also possible to quickly set up molecular dynamics (MD) simulations using
7+
a combination of the `Hydra <https://hydra.cc/>`_ command line interface (CLI) and predefined config files. The latter
8+
can be found in ``src/schnetpack/md/md_configs``.
9+
In the following, we will give a short introduction on how to use the CLI and/or config files for performing
10+
MD simulations with the ``spkmd`` script.
11+
12+
Basic command line input
13+
========================
14+
15+
The inputs which need to be provided for every ``spkmd`` run are:
16+
17+
* a simulation directory (``simulation_dir``)
18+
* the initial molecular geometry in an ASE readable format (``system.molecule_file``)
19+
* the path to a trained ML model (``calculator.model_file``)
20+
* and the cutoff used in the neighbor list (``calculator.neighbor_list.cutoff``)
21+
22+
Assuming the model and structure file are present in the local directory, the command line call would be::
23+
24+
spkmd simulation_dir=mdtut_cli system.molecule_file=md_ethanol.xyz calculator.model_file=md_ethanol.model calculator.neighbor_list.cutoff=5.0
25+
26+
This command would carry out a classical NVE simulation in the ``mdtut_cli`` directory, running on the GPU for 1000000
27+
steps, using a time step of 0.5 fs (the device can be switched by appending ``device=cpu``). It would further
28+
automatically set up checkpointing and logging to HDF5 and tensorboard as described above.
29+
30+
Running the command will print out the full config used for the simulation::
31+
32+
⚙ Running with the following config:
33+
├── device
34+
│ └── cuda
35+
├── precision
36+
│ └── 32
37+
├── seed
38+
│ └── None
39+
├── simulation_dir
40+
│ └── mdtut_cli
41+
├── overwrite
42+
│ └── False
43+
├── restart
44+
│ └── None
45+
├── calculator
46+
│ └── neighbor_list:
47+
│ _target_: schnetpack.md.neighborlist_md.NeighborListMD
48+
│ cutoff: 5.0
49+
│ cutoff_shell: 2.0
50+
│ requires_triples: false
51+
│ base_nbl: schnetpack.transform.ASENeighborList
52+
│ collate_fn: schnetpack.data.loader._atoms_collate_fn
53+
│ _target_: schnetpack.md.calculators.SchNetPackCalculator
54+
│ required_properties:
55+
│ - energy
56+
│ - forces
57+
│ model_file: md_ethanol.model
58+
│ force_key: forces
59+
│ energy_unit: kcal / mol
60+
│ position_unit: Angstrom
61+
│ energy_key: energy
62+
│ stress_key: null
63+
│ script_model: false
64+
├── system
65+
│ └── initializer:
66+
│ _target_: schnetpack.md.UniformInit
67+
│ temperature: 300
68+
│ remove_center_of_mass: true
69+
│ remove_translation: true
70+
│ remove_rotation: true
71+
│ wrap_positions: false
72+
│ molecule_file: md_ethanol.xyz
73+
│ load_system_state: null
74+
│ n_replicas: 1
75+
│ position_unit_input: Angstrom
76+
│ mass_unit_input: 1.0
77+
├── dynamics
78+
│ └── integrator:
79+
│ _target_: schnetpack.md.integrators.VelocityVerlet
80+
│ time_step: 0.5
81+
│ n_steps: 1000000
82+
│ thermostat: null
83+
│ barostat: null
84+
│ progress: true
85+
│ simulation_hooks: []
86+
└── callbacks
87+
└── checkpoint:
88+
_target_: schnetpack.md.simulation_hooks.Checkpoint
89+
checkpoint_file: checkpoint.chk
90+
every_n_steps: 10
91+
hdf5:
92+
_target_: schnetpack.md.simulation_hooks.FileLogger
93+
filename: simulation.hdf5
94+
buffer_size: 100
95+
data_streams:
96+
- _target_: schnetpack.md.simulation_hooks.MoleculeStream
97+
store_velocities: true
98+
- _target_: schnetpack.md.simulation_hooks.PropertyStream
99+
target_properties:
100+
- energy
101+
every_n_steps: 1
102+
precision: 32
103+
tensorboard:
104+
_target_: schnetpack.md.simulation_hooks.TensorBoardLogger
105+
log_file: logs
106+
properties:
107+
- energy
108+
- temperature
109+
every_n_steps: 10
110+
111+
As can be seen, the config is structured into different blocks, e.g. ``calculator``, ``system``,
112+
``dynamics`` and ``callbacks`` specifying the machine learning model, the system to be simulated, the settings for the
113+
MD simulation and logging instructions.
114+
115+
Customizing the simulation
116+
==========================
117+
118+
In the following, we will describe how to configure a simulation by overwriting existing configurations and loading
119+
additional settings from predefined configs. As an example, we will carry out a MD run using a Langevin thermostat.
120+
121+
For this, we first need to change the number of simulation steps from 1000000 to 20000.
122+
Since the corresponding config entry is ``n_steps`` in the ``dynamics`` block, this can be done by adding
123+
``dynamics.n_steps=20000`` to the command line. Changing other existing config entries can be done in a similar manner.
124+
125+
We also need to add a thermostat to the simulation.
126+
For convenience, several thermostats are preconfigured in ``src/schnetpack/md/md_configs/dynamics/thermostat``.
127+
To load the Langevin thermostat (``langevin``), we add the ``+dynamics/thermostat=langevin`` option to the command line
128+
call::
129+
130+
spkmd simulation_dir=mdtut_cli system.molecule_file=md_ethanol.xyz calculator.model_file=md_ethanol.model calculator.neighbor_list.cutoff=5.0 dynamics.n_steps=20000 +dynamics/thermostat=langevin
131+
132+
The simulation config will now show a different entry for the ``thermostat`` option in the ``dynamics`` block::
133+
134+
│ thermostat:
135+
│ _target_: schnetpack.md.simulation_hooks.LangevinThermostat
136+
│ temperature_bath: 300.0
137+
│ time_constant: 100.0
138+
139+
Here, the thermostat temperature is already set to the desired 300 K.
140+
Similar to the simulation steps, it could e.g. be changed to 500 K with the option
141+
``dynamics.thermostat.temperature_bath=500``
142+
143+
We could also easily use another preconfigured thermostat (e.g. Nosé-Hover chains, ``+dynamic/thermostat=nhc``)
144+
or add a barostat if we wanted to perform a constant pressure simulation (e.g. an isotropic Nosé-Hoover barostat,
145+
``+dynamic/barostat=nhc_iso``). A similar syntax can be used to modify the neighbor list in the calculator
146+
(e.g. to use a torch based implementation add ``calculator/neighbor_list=torch``) You might have noticed, that some
147+
modifications use a ``+`` where others do not. A general rule is, that the ``+`` is required if the corresponding entry
148+
did not exists before or was empty (e.g. ``thermostat: null`` in the very first config).
149+
150+
Using the CLI, it is also possible to perform more extensive modifications to the simulation.
151+
To carry out a ring polymer molecular dynamics (RPMD) simulation via the CLI for example, we have to:
152+
153+
* switch the integrator from Velocity Verlet to a suitable RPMD integrator (``dynamics/integrator=rpmd``)
154+
* set the number of beads/replicas (``system.n_replicas=4``)
155+
* add a suitable thermostat (``+dynamics/thermostat=pile_local``)
156+
* and change the number of steps to 50000 (``dynamics.n_steps=50000``)
157+
158+
We should also change the simulation directory.
159+
The corresponding command would be
160+
161+
spkmd simulation_dir=mdtut_cli_rpmd system.molecule_file=md_ethanol.xyz calculator.model_file=md_ethanol.model calculator.neighbor_list.cutoff=5.0 dynamics/integrator=rpmd system.n_replicas=4 +dynamics/thermostat=pile_local dynamics.n_steps=50000
162+
163+
A quick look at the ``dynamics.integrator`` block confirms that it has changed and also uses reasonable defaults for the
164+
time step and bead temperature::
165+
166+
│ └── integrator:
167+
│ _target_: schnetpack.md.integrators.RingPolymer
168+
│ time_step: 0.2
169+
│ temperature: 300.0
170+
171+
Running simulations from config files
172+
=====================================
173+
174+
In some cases, it can be useful to run simulations using config files as input.
175+
These can for example be created using the ``spkmd`` CLI and then fine-tuned to suit one's needs.
176+
177+
Full configs for the MD can either be found in the simulation directories (``mdtut_cli/.hydra/config.yaml``) or
178+
generated with ``spkmd`` by adding the ``--cfg job`` option and redirecting the output to a ``yaml`` file. This can then
179+
be saved, modified and used to run simulations.
180+
181+
The config file for the MD with the Langevin thermostat would look something like this::
182+
183+
calculator:
184+
neighbor_list:
185+
_target_: schnetpack.md.neighborlist_md.NeighborListMD
186+
cutoff: 5.0
187+
cutoff_shell: 2.0
188+
requires_triples: false
189+
base_nbl: schnetpack.transform.ASENeighborList
190+
collate_fn: schnetpack.data.loader._atoms_collate_fn
191+
_target_: schnetpack.md.calculators.SchNetPackCalculator
192+
required_properties:
193+
- energy
194+
- forces
195+
model_file: md_ethanol.model
196+
force_key: forces
197+
energy_unit: kcal / mol
198+
position_unit: Angstrom
199+
energy_key: energy
200+
stress_key: null
201+
script_model: false
202+
system:
203+
initializer:
204+
_target_: schnetpack.md.UniformInit
205+
temperature: 300
206+
remove_center_of_mass: true
207+
remove_translation: true
208+
remove_rotation: true
209+
wrap_positions: false
210+
molecule_file: md_ethanol.xyz
211+
load_system_state: null
212+
n_replicas: 1
213+
position_unit_input: Angstrom
214+
mass_unit_input: 1.0
215+
dynamics:
216+
integrator:
217+
_target_: schnetpack.md.integrators.VelocityVerlet
218+
time_step: 0.5
219+
n_steps: 20000
220+
thermostat:
221+
_target_: schnetpack.md.simulation_hooks.LangevinThermostat
222+
temperature_bath: 300.0
223+
time_constant: 100.0
224+
barostat: null
225+
progress: true
226+
simulation_hooks: []
227+
callbacks:
228+
checkpoint:
229+
_target_: schnetpack.md.simulation_hooks.Checkpoint
230+
checkpoint_file: checkpoint.chk
231+
every_n_steps: 10
232+
hdf5:
233+
_target_: schnetpack.md.simulation_hooks.FileLogger
234+
filename: simulation.hdf5
235+
buffer_size: 100
236+
data_streams:
237+
- _target_: schnetpack.md.simulation_hooks.MoleculeStream
238+
store_velocities: true
239+
- _target_: schnetpack.md.simulation_hooks.PropertyStream
240+
target_properties:
241+
- energy
242+
every_n_steps: 1
243+
precision: ${precision}
244+
tensorboard:
245+
_target_: schnetpack.md.simulation_hooks.TensorBoardLogger
246+
log_file: logs
247+
properties:
248+
- energy
249+
- temperature
250+
every_n_steps: 10
251+
device: cuda
252+
precision: 32
253+
seed: null
254+
simulation_dir: mdtut_cli
255+
overwrite: false
256+
restart: null
257+
258+
Settings can then be changed by modifying the corresponding entries.
259+
E.g. to increase the simulation temperature to 500 K, the ``temperature_bath`` entry in the ``thermostat`` block can be
260+
changed to 500.
261+
262+
Assuming the config file is e.g. stored in ``md_input_langevin.yaml``, it can be used to run the MD with the command::
263+
264+
spkmd simulation_dir=md_from_config load_config=md_input_langevin.yaml
265+
266+
The ``simulation_dir`` option is still required, due to how hydra resolves configs.
267+
Any ``simulation_dir`` entries in the provided config file will be ignored.
268+
269+
Since the ``hydra`` parser operates on classes from python modules, they can also be easily adapted to integrate external modules, e.g. custom calculators for simulations.
6270

7-
TODO
8-
====

0 commit comments

Comments
 (0)