# 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.

## 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



## 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

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.

## 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 at a glance see 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.