AMSprep: generate (multiple) ADF jobs
*************************************

AMSprep allows one to generate input files for the different programs
of the Amsterdam Modeling Suite by means of console commands. As such,
AMSprep can be used to run the same type of calculation on a series of
different chemical systems. Another important example is automatic
checks of the convergence of the results with respect to the
computational parameters, e.g., by varying input settings such as
basis set choice or numerical integration accuracy while recomputing
the same system.

AMSprep ($AMSBIN/amsprep) generates a job script from a template .ams
file. Such a template file can either be produced by AMSinput or
simply be found among the default templates included. These default
templates are identical to those present in AMSinput.

Two **examples** are presented here to demonstrate the capabilities of
AMSprep:

* In BakersetSP you will see how to use amsprep to run a particular
  job for a test set of molecules. The individual molecular structures
  are provided as xyz-files which contain no ADF specific information.
  AMSreport is used to collect the values of the bonding energies
  resulting from these calculations.

* In ConvergenceTestCH4 you will see how to use AMSprep to test
  convergence of the bonding energy with respect to the basis set and
  the numerical integration grid.

The options of AMSprep are listed when running the module without
further command-line arguments, or with the -h flag:

   % amsprep -h
   AMSprepare (amsprep) generates a job script from a .ams file (the template),
   with user specified changes to input options / method / system.

   Usage: amsprep -t template.ams [-m molecule.(ams|adf|xyz|mol|t21)] [-z charge] [-s spin]
                                  [-runtype SinglePoint|GeometryOptimization|Frequencies]
                                  [-gradientsonly]
                                  [-q quality] [-zlmfit quality] [-kspace quality]
                                  [-lattice v1.x v1.y v1.z ...]
                                  [-i integration] [-b basis] [-c core] [-r relativity]
                                  [-basiscacheid id]
                                  [-x xcpotential] [-e xcenergy] [-bondsonly]
                                  [-dftbmodel DFTB|SCC-DFTB|DFTB3] [-dftbparameters dir]
                                  [-dftbdispersion None|Default|D3-BJ|D2|ULG|UFF]
                                  [-logfile logfile] [-j jobname] [-a amsfile]
                                  [-dist "atom1 atom2 distance ..."]
                                  [-angle "atom1 atom2 atom3 angle ..."]
                                  [-dihed "atom1 atom2 atom3 atom4 angle ..."]
                                  [-atomtype "atom type ..."]
                                  [-structure "atom structure ..."]
                                  [-pointcharges file]
                                  [-efield "Ex Ey Ez"]
                                  [-rxforcefield fname] [-rxniter n] [-rxnrstep n] [-rxtstep T]
                                  [-rxmethod method] [-rxmdtemp T] [-rxmdpres p]
                                  [-region "name at1 at2... "]
                                  [-fragments prefix] [-onejob]
                                  [-g "key value"]


   Start with a job template, adjust it for this particular job, and write the resulting job
   to standard output. Values specified should match exactly the values as you would specify
   using AMSinput, also for menu choices.

   TEMPLATE
   -t: the .ams file (saved by AMSinput) to be used as template, defining the whole job
       All other options override values from this job

       Instead of a .ams file, you may also specify the name of one of the standard templates
       as defined in AMSinput: "Single Point", Frequencies, "Geometry Optimization", etc
       A special option for energy and gradients
       for the current geometry: EG (see also -gradientsonly)

       Some shortcuts: SP, EG, GO, FREQ, optionally prefixed by (ADF|BAND|DFTB|UFF|MOPAC)-
       For example: ADF-FREQ, BAND-SP, DFTB-GO, MOPAC-EG

       Some ReaxFF shortcuts: REAXFF-EG for a single ReaxFF iteration

   CHANGES TO TEMPLATE
   -m: the molecule to use, element types and coordinates
       This can be taken from anything that AMSinput can import,
       for example .ams, .mol, xyz or .t21 files

       The -m flag may be repeated, each molecule added will be in its own region
       This may be used for fragment calculations, but it does not work with .ams files

       If you specify an .sdf file, you can select which frames to import:
           conformers.sdf#1-10         loop over the first 10 frames
           conformers.sdf#e2.0         loop over all frames with energy below 2.0
              (units as in the file, wrt the lowest energy of all frames in the file,
              energies from comment lines)
           conformers.sdf#1-10e2.0     loop over the first 10 frames,
                                       and use only those  with energy below 2.0
           conformers.sdf              use the first frame of the sdf file

       If you specify a .t21 file, you can select which frames or range of frames to import:
           ajob.t21#ircf3               3rd frame in the IRC forward path
           ajob.t21#ircb2               2nd frame in the IRC backward path
           ajob.t21#h7                  7th frame in the history
           ajob.t21#lt8                 8th frame in the LT path
           ajob.t21#ircf3-10            IRCForward frame 3, 4, ... 10
           ajob.t21#ircf                IRCForward all frames, starting at 1
           ajob.t21#ircf0-              IRCForward all frames, starting at 0
                                        (original geometry, before first step)

       If you specify a .cry file, the compound to import may be specified:
           $AMSHOME/atomicdata/Molecules/Crystals/Cubic/CsCl.cry#MgTl

       When looping, all resulting jobs will be joined together, the job name and AMS files
       get the frame sequence number appended after an _
       When looping only one -m flag may be specified

   -xyz: use xyz coordinates from specified file, not touching anything else
         it is applied after -t and -m
         the elements and number of atoms should match
         currently works with KF and xyz files
   -smiles: use smiles to describe the molecule

   -irc: when using IRC frames in the -m flag, revert the backwards order

   -dist: change the distance between atom1 and atom2 to the specified distance
          the arguments must be enclosed in quotes, and may be repeated for multiple distances
   -angle: change the angle (atom1, atom2, atom3) to the specified angle
          the arguments must be enclosed in quotes, and may be repeated for multiple angles
   -dihed: change the dihedral (atom1, atom2, atom3, atom4) to the specified angle
          the arguments must be enclosed in quotes, and may be repeated for multiple angles
   -atomtype: set the type (element) of atom to type
          the arguments must be enclosed in quotes, and may be repeated for multiple types
   -structure: add a structure just as if using the structure tool in AMSinput
          atom is the selected atom, structure is the name of the structure file
          the arguments must be enclosed in quotes, and may be repeated for multiple changes
   -liststructures: list available structure files for use with -structure, and exit

   -runtype: run type (SinglePoint,GeometryOptimization,Frequencies)
   -gradientsonly: after calculating the gradients, stop
                   works also for excited state gradients if requested in your template
   -z: charge (real number)
   -s: spin (integer), if not zero this implies an unrestricted calculation
   -q: quality (Basic, Normal, Good, VeryGood or Excellent), default for Becke/ZlmFit
   -i: integration (integer)
   -i: Becke integration (Basic, Normal, Good, VeryGood or Excellent)
   -i: teVelde integration (integer)
   -zlmfit: ZlmFit quality (Basic, Normal, Good, VeryGood or Excellent)
   -kspace: KSpace quality (GammaOnly, Basic, Normal, Good, VeryGood or Excellent)
   -lattice: lattice vectors first three numbers for the first vector, next for the second etc
             The dimension follows from the number of vectors
   -b: basis type (SZ, DZ, DZP, TZ, TCP, TZ2P, QZ4P)
   -c: core type (None, Small, Medium, Large)
   -basiscacheid id: refer to t21 files from previous runs prefixed with this id
   -r: relativistic level (None, Scalar, Spin-Orbit), using ZORA
   -x: XC potential during SCF, one from the options available in AMSinput:
           LDA,
           GGA:BP, GGA:BLYP, GGA:PW91, GGA:mPW, GGA:PBE, GGA:RPBE, GGA:revPBE, GGA:mPBE,
           GGA:OLYP, GGA:OPBE,
           Model:SAOP, Model:LB94,
           Hartree-Fock,
           Hybrid:B3LYP, Hybrid:B3LYP*, Hybrid:B1LYP, Hybrid:KMLYP, Hybrid:O3LYP, Hybrid:X3LYP,
           Hybrid:BHandH, Hybrid:BHandHLYP, Hybrid:B1PW91, Hybrid:MPW1PW, Hybrid:MPW1K,
           Hybrid:PBE0, Hybrid:OPBE0
   -e: XC energy after SCF (Default, LDA+GGA_METAGGA, LDA+GGA+METAGGA+HYBRIDS)
   -pointcharges: file, file with point charges, one point charge per line (ADF only)
                  x y z charge, xyz in Angstrom, charge in elementary units (+1 for a proton)
   -efield: Ex Ey Ez the electric field vector (in Hartree/(e Bohr))
   -k: replace any key, the single argument will be broken into:
        the key, the replacement value, and END for a block key
        all separated by spaces. To insert a return, add a |
        When the key is not found, it is added just before the ATOMS key
        The -k key may be repeated, and is applied at the end, replacing even earlier changes

   -dftbmodel DFTB|SCC-DFTB|DFTB3: select the DFTB model
   -dftbparameters dir: select the directory with DFTB parameters
   -dftbdispersion [None|Default|D3-BJ|D2|ULG|UFF]: dispersion option to use, default is None

   -rxforcefield fname: the ReaxFF force field file
   -rxniter n: number of ReaxFF iterations
   -rxnrstep n: number of non-reactive iterations (out of the total number of iterations)
   -rxtstep T: the time step used in the MD simulation
   -rxmethod string: the simulation type: Velocity Verlet + Berendsen|NPT|NVE
   -rxmdtemp T: the thermostat temperature
   -rxmdpres p: the required pressure

   -region name at1 at2 ...: make a region with specified name and atoms, may be repeated
        The atom numbers at1 at2 refer to input order, after geometry modifications, start at 1
        Use at1-at2 to refer to all atoms between at1 and including at2
        If the region key is present all regions already present are deleted
   -fragments prefix: set up a fragment calculation, prefix fragment run/job scripts with prefix
                      if this key is present fragment run/job scripts will be saved (unless -onejob)
                      if a job script is requested, the fragment job names will be prefix.fragname.job
    -onejob: for fragment jobs, concatenate the fragment jobs and final job into one on stdout
   -g "key value": set any key to the specified value (note key value within quotes)
            key: internal name in AMSinput for some option, see bin/amsinput.tcl/tpl/Defaults.tpl
            value: set gin(key) to the specified value
    -nochain: unset chain option (used internally by chain jobs)

   OUTPUT
   -bondsonly: only the bonds as generated by the GUI will be exported (the GUIBONDS block)
   -logfile: force the specified logfile to be used in the run script
   -j: produce a fully runnable job (as the .job files from AMSjobs),
       using the specified jobname.
       The job script produces files like jobname.out, jobname.t21 etc. Several job scripts can simply
       be concatenated, the results will be stored in different files using the job name parameter
       the default is a simple run script (the .run file from AMSinput, files are left as they are)
   -a: save a .ams file that matches the run script, except for the -k arguments
       (they are listed in the user input field)
       amsfile is the name of the AMSinput, including the .ams extension (required)

   Example: calculate gradients for a molecule in file mymol.xyz
            amsprep -t GO -m mymol.xyz -k "stopafter ggrads"

   Example: calculate gradients for a molecule in file mymol.xyz, using good quality integration and fit:
            amsprep -t GO -q Good -m mymol.xyz -k "stopafter ggrads"

   Example: calculate DFTB frequencies for a molecule in file mymol.xyz
            amsprep -t DFTB-FREQ -m mymol.xyz


Additional Notes
================

CRSprep represents a scripting solution which is exclusively oriented
towards generating input files for the COSMO-RS program.
