cspy-threshold command

The cspy-threshold command is used to perform threshold monte carlo simulations.

cspy-threshold [-h] [-r RES_FILES [RES_FILES ...]] [-c CHARGES] [-m MULTIPOLES] [-a AXIS]
               [-g SPACEGROUPS]
               [-p {fit,fit_disponly,fit_reponly,w99,fit_water_X,Day_halobenzenes,w99_orig_Halogens,w99_orig_H,w99rev_6311,w99rev_6311_s,w99rev_631,w99rev_pcm_6311,w99_s_cl,w99sp,w99rev_pcm_6311_and_Chloride,w99rev_pcm_6311_and_Bromide,w99rev_pcm_6311_and_Iodide,w99rev_pcm_6311_and_Halides,isoPAHAP,PAHAP,nothing,gaff2_LJ,gaff2_fit}]
               [--cutoff CUTOFF] [-t NTHREADS] [-rs RANDOM_SEED]
               [--trials-per-res TRIALS_PER_RES] [--log-level LOG_LEVEL] [--keep-files]
               [--skip-header] [--status-file STATUS_FILE]
               xyz_files [xyz_files ...]

positional arguments

  • xyz_files - Xyz files containing molecules for generation

options

  • -h, --help - show this help message and exit

  • -r RES_FILES, --res_files RES_FILES - Res files containing molecules for generation

  • -c CHARGES, --charges CHARGES - Rank0 multipole file

  • -m MULTIPOLES, --multipoles MULTIPOLES - RankN multipole file

  • -a AXIS, --axis AXIS - Axis filename for structure minimization

  • -g SPACEGROUPS, --spacegroups SPACEGROUPS - Spacegroup set for structure generation (default: fine10)

  • -p POTENTIAL, --potential POTENTIAL - intermolecular potential name (default: fit)

  • --cutoff CUTOFF - dmacrys real space/repulsion-dispersion cutoff (default: calculate)

  • -t NTHREADS, --nthreads NTHREADS - Number of dask worker threads per process to use for local scheduler (default: 1)

  • -rs RANDOM_SEED, --random-seed RANDOM_SEED - Specify seed for random generator. Should be left blank for first runs.The entropy/seed will be logged in the output and can be used to repeat simulations if needed.

  • --trials-per-res TRIALS_PER_RES - number of trials/trajectories initiated for each res provided (default: 1)

  • --log-level LOG_LEVEL - Log level (default: INFO)

  • --keep-files - Keep DMACRYS and NEIGHCRYS files which, for each structure, are stored in a new directory in the pwd.

  • --skip-header - Skip the mol-CSPy header at the start of the job.

  • --status-file STATUS_FILE - Specify output status file (default: status.txt)

Background

The threshold algorithm is a Monte Carlo simulation with an energy threshold, also called the energy lid. This threshold is set relative to the energy of the initial configuration. Monte Carlo moves are then accepted if and only if the energy of the resulting perturbed configuration is below the energy threshold. Effectively, this constrains the MC trajectory to explore only regions accessible below the energy threshold. The threshold can be iteratively increased and barriers between sampled energy minima and the initial configuration can then be estimated as the energy of the threshold when the minima were first sampled. These connections can be presented in a disconnectivity graph, which clusters the minima sampled based on the energy barrier from the initial configuration. By running trajectories from multiple minima can estimate the energy barrier between them.

Note that the configurational space typically increases exponentially with energy. Hence, converging high energy barriers requires extensive sampling. From testing, can reasonably converge energy lids up to 20-30 kJ/mol above the initial structure.

Running Threshold Simulations

For more information on running a threshold simulation, please have a look at the following worked example - Threshold simulation for Benzene.