Run.py Inputs and Arguments

The run.py program controls the MD or BD simulations in a SEEKR2 calculation, ensuring that they are run with the correct dynamics settings and milestone boundary definitions, while also generating restart checkpoints. Upon failure, run.py can restart a simulation automatically from a saved checkpoint.

As its primary input, the run.py program takes an INSTRUCTION and the path to a file named “model.xml” (generated by prepare.py). Other options control various aspects of the simulations.

usage:

python run.py [-h] [-c CUDA_DEVICE_INDEX] [-t MIN_TOTAL_SIMULATION_LENGTH]
            [-T MAX_TOTAL_SIMULATION_LENGTH] [-C CONVERGENCE_CUTOFF]
            [-m MINIMUM_ANCHOR_TRANSITIONS] [-d DIRECTORY] [-f] [-s] [-S]
            [-n NAMD_COMMAND] [-a NAMD_ARGUMENTS]
            [-b MINIMUM_B_SURFACE_TRAJECTORIES]
            [-y MIN_B_SURFACE_ENCOUNTERS] [-L NUM_REV_LAUNCHES] [-u]
            INSTRUCTION MODEL_FILE

Required Arguments

INSTRUCTION

This argument defines which type of dynamics for which anchor (region of the calculation) should be run. The possible arguments for INSTRUCTION are listed below:

any - Instruct run.py to run any anchor, whether MD or BD, that still needs more sampling. The run.py program will attempt to do this in a “smart” manner, by focusing attention on anchors and regions that are undersampled, based on transition counts and/or convergence criteria.

any_md - Instruct run.py to run any MD anchor (excluding BD) that still needs more sampling. This feature can be useful if MD simulations must be run on a supercomputer or cluster (or a GPU node), while BD must be run on a different machine (or a CPU node). As with the any instruction, run.py will attempt to be smart about this, and focus on running undersampled anchors.

any_bd - Instruct run.py to run any unfinished BD simulations (at this time, this is only the b-surface). As mentioned with the any_md instruction above, this argument can be useful if one wishes to run BD on a separate machine than MD.

(integer value) - By entering an integer value (Examples: “0”, “1”, “2”, etc.), the MD anchor with that index will be run to completion or interruption.

b_surface - Run the b-surface BD simulations.

MODEL_FILE

Provide a path to a file named “model.xml” which can be found in the <root_directory> tag of the model input file provided to prepare.py.

Optional Arguments

-h, –help: Show help message and exit.
-c CUDA_DEVICE_INDEX, –cuda_device_index CUDA_DEVICE_INDEX: Modify which cuda_device_index to run the MD simulation on. For example, the number 0 would instruct the MD engine to run using the GPU with the assigned index of 0. To run on multiple GPU indices, simply enter comma separated indices. Example: ‘0,1’. If a value is not supplied, the value in the MODEL_FILE will be used by default.
-t MIN_TOTAL_SIMULATION_LENGTH, –minimum_total_simulation_length MIN_TOTAL_SIMULATION_LENGTH: Enter a minimum MD simulation length (in time steps) to run the simulation if a different number of steps are desired than what is in the “<num_production_steps>” (MMVT) or “<num_umbrella_stage_steps>” (Elber) tags in the MODEL_FILE. Be aware: A longer simulation may still occur if other specified criteria are not met, such as the –convergence_cutoff, for example.
-T MAX_TOTAL_SIMULATION_LENGTH, –maximum_total_simulation_length MAX_TOTAL_SIMULATION_LENGTH: Enter the maximum number of MD simulation timesteps. Simulations will not exceed this length, even if other criteria, such as –convergence_cutoff are not met.
-C CONVERGENCE_CUTOFF, –convergence_cutoff CONVERGENCE_CUTOFF: Enter a target convergence for each anchor. See the documentation of converge.py for more detail about how convergence is calculated.
-m MINIMUM_ANCHOR_TRANSITIONS, –minimum_anchor_transitions MINIMUM_ANCHOR_TRANSITIONS: Enter a minimum number of transitions that must be observed per milestone in a given anchor as a criteria for the simulations.
-d DIRECTORY, –directory DIRECTORY: Provide the location of the directory which contains the anchors. If this argument is omitted, then the directory within the anchor_rootdir setting of the MODEL_FILE will be used.
-f, –force_overwrite: Toggle whether to overwrite existing files within an anchor. If this option is enabled then the anchor’s production directory will be emptied of all output, trajectory, and backup files for the new simulation.
-s, –save_state_for_all_boundaries: Toggle whether to save at least one state file for each boundary until every boundary has been bounced against. Warning: can generate very large numbers of files.
-S, –save_state_file: Toggle whether to save a state file every time a bounce occurs. Warning: can generate very large numbers of files.
-n NAMD_COMMAND, –namd_command NAMD_COMMAND: Define a different NAMD command. This allows users to define a path to NAMD or to use a ‘charmrun namd2’ command. By default, ‘namd2’ is used. Only valid for NAMD runs.
-a NAMD_ARGUMENTS, –namd_arguments NAMD_ARGUMENTS: Additional arguments for NAMD can be entered here. Note: this will require quotation marks around the arguments. Example: -a ‘+p8 +devices 0,2’. Only valid for NAMD runs.
-b MINIMUM_B_SURFACE_TRAJECTORIES, –minimum_b_surface_trajectories MINIMUM_B_SURFACE_TRAJECTORIES: Enter a minimum number of BD trajectories to run for the b-surface if a different number of trajectories are desired than what is indicated in the <b_surface_num_trajectories> tag in the MODEL_FILE. A longer simulation may be run if other specified criteria are not met, such as the –min_b_surface_encounters, for example.
-y MIN_B_SURFACE_ENCOUNTERS, –min_b_surface_encounters MIN_B_SURFACE_ENCOUNTERS: Enter a minimum number of encounters that must be observed for the b-surface as a criteria to finish running simulations.
-L NUM_REV_LAUNCHES, –num_rev_launches NUM_REV_LAUNCHES: In Elber milestoning, this parameter defines how many reversals to launch for each equilibrium configuration generated by the umbrella stage. For each launch, the positions will be identical, but the velocities will be resampled from a Maxwell-Boltzmann distribution.
-u, –umbrella_restart_mode: In Elber milestoning, this option allows one to use the umbrella simulations that already exist in the anchor, and just re-run the reversals and forwards simulations.