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:

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:

Examples are provided below for each generator.

Input structure

The protocol requires following blocks in the input:

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