AMSreport: generate reports
***************************

The utility AMSreport ($AMSBIN/amsreport) allows you to retrieve
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, 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.

Individual KF variables can also 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

High-quality pictures of orbitals can also 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 on 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 the 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. Download the C
  sources here.
