Protocol scan

This protocol automates repeating calculations along a series of geometries (geometry keyword should point to .xyz file with multiple entries).

Scan modes

Two different scan modes are available:

Parallel - All the calculations are prepared separately and then run using Cuby's internal queue system. Only after all calculations finish, the results are printed. The points can be calculated in parallel using the cuby_threads keyword.
Serial - One calculation is set up and then called repeatedly while updating the geometry. Therefore, it can use the previous result as a starting point (if the interface supports that). The results are printed to the output one by one as they are calculated. Additionally, if a calculation fails in this mode, a message is printed and the program continues moves to the next point.

Geometry file

The geometry file should be an .xyz wile with multiple entries. A following extension is implemented: if the comment (second line) in the .xyz file starts with "scan:", the rest of the line is printed in the cuby output before each result. If the value of the scanned coordinate is used, the output then becomes a nice table ready for processing / plotting.

Scan generators

Optionally, the scan can be generated by Cuby. The generator is called using keyword scan_generator and set up using keyword scan_generator_setup. Following generators are avilable:

grid_xyz - the selected part of the geometry is moved to points on a cartesian grid (the center of the selection is positioned at the new coordinates). Moreover, the points are filtered by van der Waals distance, points with contact between the moved part and the rest of the system shorter than rvdw_min and longer than rvdw_max are removed (these values are relative to the vdW equilibrium distance).
z-matrix - allows simultaneous setting or scaling of internal coordinates. The geometry has to be in z-matrix format with named variables.
interpolate_zm - Interpolate between two z-matrices (geometry and geometry2).

Examples are provided below for each generator.

Input structure

The protocol requires following blocks in the input:

calculation - Setup for the calculation

Keywords used

Keywords specific for this protocol:

Other keywords used by this protocol:

Examples

The following examples, along with all other files needed to run them, can be found in the directory cuby4/protocols/scan/examples

#===============================================================================
# Scan protocol example 1: simple energy scan
#===============================================================================

job: scan

# The geometry is an .xyz file containing a series of geometries, in this case
# a scan of a stretching vibrational mode
# The file contains the identifier "scan:" and the value of the scanned coordinate
# which is then printed in the output (this is optional).
geometry: water_stretch_scan.xyz

# Scan mode - serial/parallel
scan_mode: serial

# The calculation performed on each geometry
calculation:
  job: energy
  interface: mopac
  method: pm6
  charge: 0

Produces output:

        _______  
       /\______\ 
      / /      / 
     / / Cuby /   Scan
     \/______/   
                 
0.000000	Energy:           -54.130770 kcal/mol
0.447214	Energy:           -53.664500 kcal/mol
0.894427	Energy:           -52.269720 kcal/mol
1.341641	Energy:           -49.956900 kcal/mol
1.788854	Energy:           -46.736690 kcal/mol
2.236068	Energy:           -42.607440 kcal/mol
2.683282	Energy:           -37.530230 kcal/mol

#===============================================================================
# Scan protocol example 2: Use of template geometry
#===============================================================================

# Forcefield calculation of rotation profile of a C-C bond in a model peptide

job: scan

# The forcefield calculation requires a geometry in PDB format. However, the
# scan protocol works with .xyz format which can contain multiple frames more
# easily. The solution is to provide a template PDB into which the actual
# coordinates from .xyz scan are loaded
geometry_template: ace-ala-nme.pdb

# The coordinates from the following file are loaded into the template
geometry: scan.xyz

# Scan mode - serial/parallel
scan_mode: parallel
cuby_threads: 4 # four calculations run simultaneously

# The calculation performed on each geometry
calculation:
  job: energy
  interface: amber
  charge: 0

#===============================================================================
# Scan protocol example 3: cartesian grid generator
#===============================================================================

# Scan of the potential around methane, using argon atom as a probe
# PM6-D3 method is used

job: scan
scan_mode: serial

# Geometry: methane + Ar atom
geometry: |
  C    0.000000000   0.000000000   0.000000000
  H    0.626128590   0.626128590  -0.626128590
  H    0.626128590  -0.626128590   0.626128590
  H   -0.626128590   0.626128590   0.626128590
  H   -0.626128590  -0.626128590  -0.626128590
  Ar   0.000000000   0.000000000   3.000000000

#-------------------------------------------------------------------------------
# Grid generator
#-------------------------------------------------------------------------------
scan_generator: grid_xyz
scan_generator_setup:
  # 2D grid, zero in x axis
  grid_x: 0
  grid_y: seq(-7, 0.3, 7) # series from -7 to 7, spacing 0.3 Angstrom
  grid_z: seq(-7, 0.3, 7)
  # Move the 6th atom, Ar
  selection_move: 6
  # van der Waals distance filter - use only points where the minima is likely
  # to occur
  rvdw_min: 0.9
  rvdw_max: 1.2

#-------------------------------------------------------------------------------
# Calculation: PM6-D3
#-------------------------------------------------------------------------------
calculation:
  job: energy
  interface: mopac
  method: pm6
  charge: 0
  modifiers: dispersion3

#===============================================================================
# Scan protocol example 4: z-matrix scanner
#===============================================================================

# The z-matrix scan generator allows simultaneous changes in multiple internal
# coordinates. It is possible to set the coordinate to a provided values
# or scale them.

# Here, it is applied to setting two distances in the HF dimer.

job: scan
scan_generator: z-matrix

# The geometry must be in z-matrix format with named variables
geometry: HF_dimer.zmat

# Setup for the generator
scan_generator_setup:
  # The keyword variables allow setting a z-matrix variable to a specified value
  variables:
    fh3: [2,3,5] # Discrete list of values
  # The keyword variables_scale allow scaling a z-matrix variable by a value
  variables_scale:
    hf2: seq(1.0,0.1,1.2) # Sequence generator - seq(from,step,to)

# Calculation setup - PM6 in mopac
calculation:
  job: energy
  interface: mopac
  method: pm6
  charge: 0

#===============================================================================
# Scan protocol example 5: z-matrix interpolation
#===============================================================================

# The interpolate_zm generator interpolates between two z-matrices

job: scan
scan_generator: interpolate_zm

# The geometry must be in z-matrix format
geometry: geo1.zmat
# A second z-matrix with the same topology but different values
# of the coordinates must be provided
geometry2: geo2.zmat

# Setup for the generator
scan_generator_setup:
  steps: 10

# Calculation setup - void calculation, we will just look at the resulting geometries
calculation:
  job: energy
  interface: void