Run Jobs from the Command Line
******************************

Command-line Terminal Shell script Run script Run file

This tutorial explains how to run AMS calculations from the command
line. This is sometimes convenient, but usually not necessary. You can
always set up calculations using the graphical user interface (GUI)
instead.

See also: AMS Driver documentation on input, execution and output


An example shell script
=======================

If you followed the Getting started: Geometry optimization of ethanol
or GUI tour: UV/Vis spectrum of ethene tutorial, you will have created
a file called "jobname.run", that contains something similar to this:

   #!/bin/sh

   "$AMSBIN/ams" << eor

   Task GeometryOptimization
   System
       Atoms
           C  0.01247  0.02254  1.08262
           C -0.00894 -0.01624 -0.43421
           H -0.49334  0.93505  1.44716
           H  1.05522  0.04512  1.44808
           H -0.64695 -1.12346  2.54219
           H  0.50112 -0.91640 -0.80440
           H  0.49999  0.86726 -0.84481
           H -1.04310 -0.02739 -0.80544
           O -0.66442 -1.15471  1.56909
       End
   End

   Engine ADF
       Basis
           Type SZ
       End
   EndEngine
   eor

This file is a **shell script**. With a shell script, you can run an
AMS calculation without the graphical user interface (GUI). Such a
shell script is also called a **run script** or a **run file**. You
will still be able to visualize the results with the GUI.


Run the job
===========

Note:

  This tutorial assumes that you have basic familiarity with a
  command-line, for example that you are familiar with the "cd" and
  "ls" commands.

   Create a new **empty** directory
   Save the above script with the filename "jobname.run" in the new directory

To run the job, you first need to open up a terminal or command-line.

* Windows: **Help → Command-line**, type "bash" and hit Enter.

* MacOS: **Help → Terminal**.

* Linux : Open a terminal and run: "source /path/to/ams/amsbashrc.sh"

   [image]

   In the terminal, go to the directory containing the "jobname.run" file (and no other file)
   Run the job with this command: "sh jobname.run > jobname.out"
   After the job has finished, list all files with "ls -R"

The following should appear:

* the original "jobname.run" file

* the "jobname.out" file containing the **standard output** from ams

* the "ams.results" directory, containing the **logfile** "ams.log",
  the **optimized geometry in xyz format** "output.xyz", the **binary
  output files** "ams.rkf" and "adf.rkf", as well as a few more files.


Visualize the results in the GUI
--------------------------------

GUI modules can also be started from the command line. For example, to
open the geometry optimization trajectory in AMSmovie, run

   $AMSBIN/amsmovie ams.results

   [image]


Meaning of the run command
==========================

The command "sh jobname.run > jobname.out" executes the "jobname.run"
file via the "sh" shell interpreter, and places the output in a file
called "jobname.out".


Customize the run command
-------------------------

Note:

  Before running the job again, you must remove the "ams.results"
  directory. "ams" will never overwrite results if they already exist.

* To view the output on the screen, as well as save it to a file,
  instead run "sh jobname.run | tee jobname.out"

* You can also make the jobname.run file executable, if you prefer:

   chmod +x jobname.run
   ./jobname.run > jobname.out


Meaning of the shell script contents
====================================


#!/bin/sh
---------

This line indicates how the file should be executed. In this case, it
means to use the "sh" shell interpreter. If you run the file using

* "sh jobname.run > jobname.out", this line is optional, but using

* "./jobname.run > jobname.out", it is required.


"$AMSBIN/ams" << eor
--------------------

This line executes the "ams" program. "AMSBIN" is an environment
variable, and points to the directory containing the "ams" file. When
you open a terminal following these instructions, the "AMSBIN"
variable will be set to the correct value.

   Check what "AMSBIN" contains with this command: "echo $AMSBIN"

"<< eor" means that all the following lines, until there is a line
exactly equal to "eor", will be used as input for "ams". The input to
"ams" thus becomes

   Task GeometryOptimization
   System
       Atoms
           C  0.01247  0.02254  1.08262
           C -0.00894 -0.01624 -0.43421
           H -0.49334  0.93505  1.44716
           H  1.05522  0.04512  1.44808
           H -0.64695 -1.12346  2.54219
           H  0.50112 -0.91640 -0.80440
           H  0.49999  0.86726 -0.84481
           H -1.04310 -0.02739 -0.80544
           O -0.66442 -1.15471  1.56909
       End
   End

   Engine ADF
       Basis
           Type SZ
       End
   EndEngine


Task and System block
---------------------

When "ams" reads the "Task GeometryOptimization" line, it knows to
perform a geometry optimization.

Similarly, the "System" block tells "ams" for which molecule to run
the calculation. Each line contains an atomic element and the atomic
coordinates in angstrom.

Technically, the "Task" and "System" block are input options to the
AMS Driver.  All allowed keywords are described in the AMS Driver
manual.


Engine ADF block
----------------

The lines between "Engine ADF" and "EndEngine" are passed on to the
ADF engine. In this case, the "Basis" block is used to specify a
single-ζ (SZ) basis set.

All keywords within the "Engine ADF" block are described in the ADF
manual.

See also: More information about the AMS Driver and Engines.


Customize the shell script
==========================


Set the job name
----------------

"ams" will place all its output files in a **results directory**. By
default, this directory is called "ams.results". You can change it by
replacing the ""$AMSBIN/ams" << eor" line with:

   AMS_JOBNAME=my_jobname "$AMSBIN/ams" << eor

This will create the directory "my_jobname.results" instead.


Overwrite old results
---------------------

If you want to overwrite the results if they already exist, add the "
--delete-old-results" flag:

   "$AMSBIN/ams" --delete-old-results << eor
       # ams input
   eor


Run in serial/parallel
----------------------

To set the number of processes used by "ams", specify the "-n" flag.
To run in serial (using only 1 core):

   "$AMSBIN/ams" -n 1 << eor
       # ams input
   eor

Alternatively, you can set the environment variable "NSCM":

   export NSCM=1
   "$AMSBIN/ams" << eor
       # ams input
   eor

Note:

  If you run "ams" on a batch system (compute cluster), it will
  automatically use the right number of cores.


Place the input to ams in its own file
--------------------------------------

Save the input to ams (all lines starting from "Task" to "EndEngine")
in its own file "jobname.in".

Then the run script "jobname.run" can be simplified to become:

   #!/bin/sh

   "$AMSBIN/ams" < jobname.in > jobname.out

Because this script is now really only 1 line, you could also run this
command directly in the terminal: ""$AMSBIN/ams" < jobname.in >
jobname.out"


Specify a .xyz file for the geometry
------------------------------------

When editing shell scripts manually, it is often more convenient to
read the atomic coordinates from an external file. You can read the
coordinates from ".xyz" files, for example, the "output.xyz" file from
a previous calculation.  You can also create or open the structure in
AMSinput GUI and choose File → Export coordinates → xyz.

Then, in your shell script change the System block to become:

   System
       GeometryFile my_xyz_file.xyz
   End


Tips for creating the input
===========================

AMSinput is a very convenient tool for creating .run files.

Whenever you use AMSinput, make a habit of checking the .run file
before running the job. You can also preview it, or even edit it,
before saving, by selecting **Details → Run Script**.

Warning:

  On the **Details → Run Script** panel, clicking inside the text area
  will disable the "auto-update". Any other changes you make in
  AMSinput will then **not be added to the run file**! Check that
  "Auto update" is enabled, unless you manually want to edit the run
  script.

The run script lets you see at a glance if all the input options that
you (think you) have specified are actually present in the input to
the job. Inspecting the run script can help you to prevent mistakes.
