Run Jobs from the Command Line¶
Important
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.
In this tutorial we will cover:
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.
jobname.run
in the new directoryTo 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
jobname.run
file (and no other file)sh jobname.run > jobname.out
ls -R
The following should appear:
the original
jobname.run
filethe
jobname.out
file containing the standard output from amsthe
ams.results
directory, containing the logfileams.log
, the optimized geometry in xyz formatoutput.xyz
, the binary output filesams.rkf
andadf.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
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.
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.