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

"$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

: 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

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.

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.

Run Jobs from the Command Line¶

An example shell script¶

Run the job¶

Visualize the results in the GUI¶

Meaning of the run command¶

Customize the run command¶

Meaning of the shell script contents¶

#!/bin/sh¶

“$AMSBIN/ams” << eor¶

Task and System block¶

Engine ADF block¶

Customize the shell script¶

Set the job name¶

Overwrite old results¶

Run in serial/parallel¶

Place the input to ams in its own file¶

Specify a .xyz file for the geometry¶

Tips for creating the input¶

An example shell script ¶

Run the job ¶

Meaning of the run command ¶

Meaning of the shell script contents ¶

Customize the shell script ¶

Tips for creating the input ¶