AMSreport: generate reports

The utility AMSreport ($AMSBIN/amsreport) allows to retrieve the results (including images) computed from the binary output files of either ADF, BAND, ReaxFF, DFTB, UFF, or MOPAC. For ADF this is the .t21 file (TAPE21). It can also be the .runkf file from BAND, the .rxkf file from ReaxFF or the .rkf file from DFTB, MOPAC or UFF.

The selected results are printed out via standard output or, alternatively, either written to a tab separated file or an HTML file. When creating a new output file AMSreport will also generate a line with headers identifying the information. Images are generated using the ADF-GUI.

Also individual KF variables can be retrieved from the file as shown by the following example, which illustrates how to obtain the bonding energy from a .t21 file.

amsreport job.t21 BondingEnergy

Also high-quality pictures of orbitals can be obtained as shown below.

amsreport job.t21 HOMO LUMO+1 -v "-grid Fine" -v "-antialias" -v "-bgcolor #ffffff"

The options of AMSreport are listed when running the module without further command line arguments. At present the following command line options are available

-h
prints the help screen.

Hint

If used with the name of a valid KF file in the command line the -h option lists the names of all data blocks present in that file. It is strongly encouraged to use this option to retrieve the names of the options available in a given situation.

amsreport -h job.t21
-i
specifies the input file (.t21 etc). If the specified input file is not present ADF tries to find a valid input file based on the information in the matching .ams file or the most recent available binary output file.
-usefile
specifies the input file like -i but without attempting to find a matching file if the specified input file does not exist. Typically -usefile is used to avoid reading data from the result file.
-I <pattern>
glob files, and run over all matching result files
-o
the name of the html file in which the output of AMSreport will be stored. The output will be printed to standard output if this option is absent.
-plain
print only output data from AMSreport without any labels and/or units. The same can be achieved by setting the environment variable SCM_AMSREPORT_PLAIN to yes.
-noplain
print output data with tab separators, labels, and units. Used to override the aforementioned variable SCM_AMSREPORT_PLAIN.
-v

command line to pass to amsview (without filenames) to generate images. The image will be generated by AMSview stored in a directory with a name based on the result file, and with extension .jpgs. The result file will contain a path to the image file (directly, or in an IMG tag) After the -v the arguments must be listed, with proper quoting. Repeat the -v flag for multiple arguments. The individual -scmgeometry, -bgcolor, -zoom, -viewplane, -antialias and -grid options will be collected and applied to all view options.

Some shortcuts are predefined (HOMO, HOMO+1, LUMO, Molecule, Density, Potential) and some additional useful flags include

-scmgeometry (default 200x200) -bgcolor (default #220000), -zoom (default 1.0) -viewplane (default {1 2 5}) -antialias (off when not present, especially useful with light bgcolors) -grid (Coarse when not present, Medium when specified, or value after flag if a value is present)

examples
HOMO-1 LUMO+1 -v “-viewplane {0 0 1}” -v “-grid Fine” -v “-antialias”
-r

Specifies the result to be retrieved by AMSreport from the binary output file. If this command is omitted all unspecified command line arguments but the first (denotes input file name) will be considered as arguments for this flag.

If -r is present, the desired result is specified as a string either in form of its preset name (see below) or via a section%variable pair (see the KF utilities documentation). The -r flag (or arguments without flag) may be repeated for multiple results. Additional details can be specified after the variable name, separated by “#”. For example

range
“variable#index” or “variable#firstindex:lastindex”, index starts at 1
format
TclTk format string, e.g. 8.3f or 12.6g
examples

prints a formatted table of the coordinates

-r "Geometry%xyz#12.4f##3"

prints a formatted table for the first two atoms only

-r "Geometry%xyz#1:9#12.4f##3"

coordinates of the first two atoms in one line

-r "Geometry%xyz#12.4f#1:9"

print just the first coordinate

-r "Geometry%xyz#1"

print the bond energy

-r "Energys%Bond Energy"

While any proper KF variable can be accessed via a “section%variable” construct, the following predefined keys are available for the KF files resulting from the various programs of the Amsterdam Modeling Suite.

ADF-specific ``-r`` presets for .t21 files

orient*
affine transform (3x4) from input to internal ADF orientation, format after #
iorient*
affine transform (3x4) from internal ADF to input orientation, format after #
title
title of the calculation
type
calculation type (single point, geometry optimization, …)
weight
molecular weight
symmetry
molecular symmetry
natoms
number of atoms
integration
integration accuracy
integration-min
minimum integration accuracy
integration-max
maximum integration accuracy
scfstatus
SCF convergence status
charge
the requested charge
charges
shorthand for Voronoi, Hirshfeld and Mulliken charges
voronoi
Voronoi deformation charges
hirshfeld
Hirshfeld fragment charges, atomic fragment definition required
mdc
All available MDC atom charges
mdc-m
MDC-M charges
mdc-d
MDC-D charges
mdc-q
MDC-Q charges
mulliken
Mulliken charges
bondorders
Mayer bond orders
nmr
NMR shieldings
nmr-shieldings
NMR shieldings
nmr-shielding-tensor
NMR shielding tensor
nmr-j-coupling-tensor
NMR j coupling tensor
nmr-k-coupling-tensor
NMR k coupling tensor
nmr-j-coupling-constant
NMR j coupling constant
nmr-k-coupling-constant
NMR k coupling constant
dipolev*
dipole vector
dipole
dipole moment (length of dipole vector)
quadrupole
quadrupole tensor
orbital-info

orbital info (energy, occupation and label), format for energy after #, range after # with HOMO or LUMO for example:

orbital-info#HOMO, orbital-info#HOMO-1,
orbital-info#HOMO-2:LUMO+2, orbital-info#HOMO#12.8f
orbital-e*
orbital energies, format and range after # as in orbital-info
orbital-o*
orbital occupations, format and range after # as in orbital-info
orbital-l*
orbital labels, format and range after # as in orbital-info
homo-lumo-gap*
HOMO-LUMO gap, format after #
atomlabels
name of atoms with sequence number, starting at 0
atomlabels-from0
name of atoms with sequence number, starting at 0
atomlabels-from1
name of atoms with sequence number, starting at 1
nstep
number of steps in history / LT / IRC data, type (h,lt,ircf,ircb) after #
spin
the requested spin polarization
step

use coordinates from history / LT / IRC data, step number after # with h for history, lt for LT, ircf/ircb for forward/backward IRC if no letter after #, history data will be used (if not, last step will be used) for example:

step#23 (or step#h23), step#lt4, step#ircf3
geometry, geometry-a*, geometry-b*
geometry (element type and coordinates), in input order, in angstrom or bohr (default)
sdf
geometry in SDF format
bgf
geometry in BGF format
distance

distance between two atoms, in angstrom. Input separated by #

labels (optional): include atom labels in output

format (optional): format field

atom numbers, starting at 1, in input order

examples

distance#2#3, distance#labels#2#3, distance#-8.3f#5#8,
distance#labels#8.4f#1#2, distance#2#3#4#5, distance#labels#1#2#3#4
angle
angle between three atoms, in degrees. Input see distance, but with three atoms per angle
dihedral
dihedral between four atoms, in degrees. Input see distance, but with our atoms per dihedral
hessian*
Hessian matrix (from GeoOpt%Hessian_CART), fmt and nperline options after #
gradients*
gradients with respect to nuclear displacements (from GeoOpt%Gradients), fmt and nperline options after #
energies*
all available energies (bonding up to xc, with labels), fmt option after #
bonding
total bonding energy
pauli
total pauli repulsion
steric
total steric interaction
orbital
total orbital interaction
electrostatic
electrostatic energy
kinetic
kinetic energy
coulomb
electrostatic (steric and orbital interaction) energy
xc
exchange-correlation energy
dispersion
dispersion energy
frequencies*
IR Frequencies, format, nperline and range (n, or n:n, start at 1) after #
freqint*
IR Intensities, format, nperline and range (n, or n:n, start at 1) after #
freqlabel*
IR Frequencies label (symmetry), format, nperline and range (n, or n:n, start at 1) after #
normalmode*
normal modes (mass weighted), format, nperline and range (n, or n:n, start at 1) after #
zeropoint*
zero-point energy
excitation*
Excitation energies, format, nperline and range (n, or n:n, start at 1) after #
oscillatorstrength*
Oscillator strengths for the excitation energies format, nperline and range (n, or n:n, start at 1) after #
excitlabel*
Excitation labels (symmetry), format, nperline and range (n, or n:n, start at 1) after #

BAND specific ``-r`` presets for .runkf files

natoms
number of atoms
geometry, geometry-a*, geometry-b*
geometry (element type and coordinates), in input order, in angstrom or bohr (default)
sdf
geometry in SDF format
bgf
geometry in BGF format
distance

distance between two atoms, in angstrom. Input separated by #

labels (optional): include atom labels in output

format (optional): format field

atom numbers, starting at 1, in input order

examples

distance#2#3, distance#labels#2#3, distance#-8.3f#5#8,
distance#labels#8.4f#1#2, distance#2#3#4#5, distance#labels#1#2#3#4
angle
angle between three atoms, in degrees. #4 Input see distance, but with three atoms per angle
dihedral
dihedral between four atoms, in degrees. Input see distance, but with our atoms per dihedral
atomlabel, atomlabel-from0
name of atoms with sequence number, starting at 0
atomlabel-from1
name of atoms with sequence number, starting at 1

ReaxFF specific presets for .rxkf files

natoms
number of atoms
geometry, geometry-a*, geometry-b*
geometry (element type and coordinates), in input order, in angstrom or bohr (default)
distance

distance between two atoms, in angstrom. Input separated by #

labels (optional): include atom labels in output

format (optional): format field

atom numbers, starting at 1, in input order

examples

distance#2#3, distance#labels#2#3, distance#-8.3f#5#8,
distance#labels#8.4f#1#2, distance#2#3#4#5, distance#labels#1#2#3#4
angle
angle between three atoms, in degrees. #4 Input see distance, but with three atoms per angle
dihedral
dihedral between four atoms, in degrees. Input see distance, but with our atoms per dihedral
atomlabel, atomlabel-from0
name of atoms with sequence number, starting at 0
atomlabel-from1
name of atoms with sequence number, starting at 1
rx-frame n options

information for a particular reaxff frame. Note the spaces, you will need to quote this key.

n: frame number 0, 1, 2, ... (is not the ReaxFF step number)

options: combination of the following (if omitted, all will be reported)

   nframes: total number of frames

   step: the ReaxFF step number for the specified frame

   nats: number of atoms

   xyz: the xyz coordinates

   names: element names (C, H etc) for each atom in the same order as the coordinates

   neighbors: bond information

   cell: cell information

example

amsreport water.rxkf "rx-frame 20 step xyz cell"
pdbtrajectory
the trajectory information (including molecule details) as a sequence of PDB models due to limitations of the PDB format to less than 100000 atoms and it will not be a standard conforming PDB file

pdbtrajectory-(nobonds|usepdbinfo)

nobonds: as pdbtrajectory, but no bond info (CONECT records)

usepdbinfo: as pdbtrajectory, but use pdb residue info from first step instead of reaxff mol info

xmol: the trajectory information (only element, xyz) in xmol format

gro: trajectory as .gro file (xyz and velocities) options after a - sign:

   m : print list of molecule names and formulas only

   x : allow xyz only frames (missing velocities)

   f : add forces if available

   tf : add the time step, f is a floating point number that is the time per step in ps

examples: gro-x, gro-f, gro-xf,  gro-ft0.0001, gro-xt0.001, etc.

Special features for ReaxFF parameter optimization: a geo file in biograph format can be converted from a DFT result file using the bfg option above.
example

Input file: geo (biograph format)

-rxtrainset: run over frames in the input file (should be a bgf BIOGRAPH file), put all charges, bonds and angles in the trainset.in (on stdout).

Input file: ffield (reaxff force field file). The source ffield file determines which atoms, bonds etc are present.

-ffield-min: generate ffield file with all values replaced by min values

-ffield-max: generate ffield file with all values replaced by max values

-ffield-bool: generate ffield file with all values replaced by bool values

-minmax filename: use data from filename for min and max values,

format: see RxParRange.txt in atomicdata/ForceFields/ReaxFF

General presets for .rkf files

natoms
number of atoms
geometry, geometry-a*, geometry-b*
geometry (element type and coordinates), in input order, in angstrom or bohr (default)
sdf
geometry in SDF format
bgf
geometry in BGF format
distance

distance between two atoms, in angstrom. Input separated by #

labels (optional): include atom labels in output

format (optional): format field

atom numbers, starting at 1, in input order

examples

distance#2#3, distance#labels#2#3, distance#-8.3f#5#8,
distance#labels#8.4f#1#2, distance#2#3#4#5, distance#labels#1#2#3#4
angle
angle between three atoms, in degrees. #4 Input see distance, but with three atoms per angle
dihedral
dihedral between four atoms, in degrees. Input see distance, but with our atoms per dihedral
hessian*
Hessian matrix (from GeoOpt%Hessian_CART), fmt and nperline options after #
gradients*
gradients with respect to nuclear displacements (from GeoOpt%Gradients), fmt and nperline options after #
energies
all available energies (bonding up to xc, with labels), fmt option after #

Additional notes

  • SDF and BGF records can be produced from from ANY file that can be read by AMSinput.
  • KFreader is a free (LGPL) alternative to AMSreport. The C sources are available in our download section and can be modified for more specific needs.