Run Monte Carlo¶
To run a Monte Carlo simulation, use:
mc.run(
system=system,
moveset=moveset,
run_type="equilibration",
run_length=1000,
temperature=300.0 * u.K
)
The run
function has five required arguments: a System
,
MoveSet
, a choice of run_type
, the run_length
,
and the temperature
. Other optional arguments can be specified
individually or with a dictionary. For example, if we were performing
and NPT simulation and needed to specify the pressure, we could do the
following:
mc.run(
system=system,
moveset=moveset,
run_type="equilibration",
run_length=1000,
temperature=300.0 * u.K,
pressure=1.0 * u.bar
)
or, if we wished to use a dictionary:
custom_args = {
'pressure' : 1.0 * u.bar
}
mc.run(
system=system,
moveset=moveset,
run_type="equilibration",
run_length=1000,
temperature=300.0 * u.K,
**custom_args
)
The dictionary-based approach is easier to read when specifying a larger number of custom options. For example:
custom_args = {
'pressure' : 1.0 * u.bar,
'cutoff_style' : 'cut_shift',
'vdw_cutoff' : 14.0 * u.angstrom,
'units' : 'sweeps',
'prop_freq' : 10,
'coord_freq' : 100
}
mc.run(
system=system,
moveset=moveset,
run_type="equilibration",
run_length=1000,
temperature=300.0 * u.K,
**custom_args
)
Restart a Simulation¶
MoSDeF Cassandra also supports restarting from a Cassandra checkpoint file. The checkpoint file contains the coordinates, box information, and state of the random number generator required for an exact restart. In order for the restart to work correctly, the directory must contain: (1) the original Cassandra input (.inp) file, (2) the Cassandra MCF files and fragment libraries, (3) the checkpoint (.chk) file that will be used for the restart.
Note
It is easiest if the restart is performed from within the same directory as the original simulation. If no files have been deleted since the original run, all of the required items should be present.
The restart function accepts four arguments: (1) the total simulation
length, (2) the prefix for the files you wish to use for the restart,
restart_from
, (3) the prefix for the files generated by the new
simulation, run_name
, and (4) the run_type
, “equilibration”
or “production”. Depending on the specific use-case,
some or all of the arguments may be optional.
There are a few scenarios where it is useful to use the restart capability.
Switch from equilibration to production¶
One of the most common use-cases for the restart function is switching from an equilibration to production simulation. In equilibration mode, Cassandra actively adjusts the maximum translation, rotation, and volume move sizes to achieve a 50% acceptance ratio. In production mode, the maximum move sizes are fixed. If we use a restart and switch from equilibration to production mode, Cassandra will take the optimized translation, rotation, and volume move sizes from the checkpoint file.
mc.run(
system=system,
moveset=moveset,
run_type="equilibration",
run_length=1000,
temperature=300.0 * u.K,
run_name="equil",
)
mc.restart(
restart_from="equil",
run_name="prod",
run_type="production",
total_run_length=2000
)
Note that the total_run_length
is the sum of the equilibration
and production run lengths – so in this example we are running
a 1000 MC step production following a 1000 MC step equilibration.
Restart a simulation that has not completed¶
Sometimes a simulation is terminated prematurely. In this case, the goal is to restart the simulation from the checkpoint file and complete the original simulation. Here, we can simply use:
mc.restart()
The new run_name
will be the original with .rst.001
appended.
If there are multiple .inp
files in the current directory, you will
need to specify the restart_from
option. E.g., if the current directory
contains both equil.inp
and prod.inp
and we wish to restart
the simulation created by prod.inp
:
mc.restart(restart_from="prod")
The new run_name
will be prod.rst.001
.
Extend a simulation¶
Sometimes it is necessary to extend a simulation. In this case,
we must specify the total_run_length
. Once again, note this is the
total number of simulation steps. For example, imagine our
initial simulation is 1000 steps:
mc.run(
system=system,
moveset=moveset,
run_type="equilibration",
run_length=1000,
temperature=300.0 * u.K,
run_name="example",
)
Now we wish to extend the simulation by an additional 1000 steps. We use:
mc.restart(total_run_length=2000)
If we needed to again extend the simulation by 1000 steps:
mc.restart(total_run_length=3000)
The prefix for the files from the three simulations would be
example
, example.rst.001
, and example.rst.002
.
We could alternatively manually specify the run_name
for
the extended simulations if we wished:
mc.restart(
restart_from="example",
run_name="my_example_restart",
total_run_length=2000,
)