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.