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,
)