10 Ways to Get the Energy and Other Properties
**********************************************

AMSjobs AMSlogfile AMSoutput KFbrowser PLAMS Scripting Spreadsheet

Most AMS calculations produce several output files:

* the **standard output** ("jobname.out" file)

* the **logfile** ("jobname.logfile", or "ams.log")

* the **binary ams.rkf file** inside the "jobname.results" directory

* the **binary "engine.rkf" file** inside the "jobname.results"
  directory. The name of the file depends on the calculation, and can
  be "adf.rkf", "band.rkf", "dftb.rkf", "reaxff.rkf", etc.

One important result from an AMS geometry optimization or single-point
calculation is the **final potential energy**. AMS will print this
number in **hartree** to the standard output, logfile, and engine.rkf
file.

This tutorial shows you how to get this number with the

* Graphical User Interface (Output, Logfile, KFbrowser, Spreadsheet
  (Excel), AMSjobs)

* Command-line (amsreport, dmpkf and akf, grep)

* Python (AMSJob, KFReader)

Most of these tools can also be used to extract **many other
properties**, such as atom coordinates, bond lengths, orbital
energies, excitation energies, density of states, etc.

Note:

  ADF and BAND give the energy with respect to fragments. The
  fragments are spherically symmetric nonspinpolarized atoms, by
  default. See also the FAQ.

This tutorial uses results from Getting started: Geometry optimization
of ethanol.


Graphical User Interface
========================


1. Standard output
------------------

* Select the job in AMSjobs (SCM → Jobs)

   [image]

* SCM → Output

* Scroll down towards the end, or search for "CALCULATION RESULTS"
  with the search box at the bottom of the window.

   [image]

* Under "CALCULATION RESULTS" is a line with the energy.


2. Logfile
----------

* Select the job in AMSjobs (SCM → Jobs)

* SCM → Logfile

* Scroll down towards the end. Depending on the engine and task, the
  energy is sometimes printed as "Bond Energy", "ENERGY OF FORMATION",
  "current energy", etc.

   [image]


3. KF browser
-------------

KF browser is a program for viewing the binary ams.rkf and engine.rkf
files.

* Select the job in AMSjobs (SCM → Jobs)

* SCM → KF browser. This will show you the contents on the **ams.rkf**
  file.

* **File → Related files -> engine.rkf** (here: **adf.rkf**)

   [image]

* Click on the arrow next to Energies

   [image]

To start kfbrowser from the command line, run "$AMSBIN/kfbrowser
engine.rkf".

See also: The difference between ams.rkf and engine.rkf.

Tip:

  If you select File → Expert Mode, you will see the raw structure of
  the binary file.


4. Spreadsheet (Excel) summary
------------------------------

* Select the job in AMSJobs (SCM → Jobs)

* **Tools → Build spreadsheet...**

   [image]

* Choose your preferred units

   [image]

* Click "Do It"

This places a spreadsheet .xlsx file in the job.results folder and
opens it in your default spreadsheet viewer. The energy is given under
"Main results".

   [image]

See also: Documentation for spreadsheet export.


5. AMSjobs
----------

* Open AMSjobs (SCM → Jobs)

* **View → Comments**

* Select the job

* **Job → Edit Comments**

* In the Results dropdown menu choose **Energy**

* Click **Set as Default**

* Click **Save**

[image]


Command-line (bash, terminal)
=============================

Start a terminal window as follows:

* 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 examples, replace "/path/to/engine.rkf" with the actual path to
the file (the path can be absolute or relative).


6. Command-line: amsreport
--------------------------

   $AMSBIN/amsreport /path/to/engine.rkf energy

Some engines calculate the energy by summing up contributions. See the
contributions with

   $AMSBIN/amsreport /path/to/engine.rkf energies

You can also read key-value pairs from engine.rkf directly.  To find
out which entry to read, first inspect the file with kfbrowser in
**Expert Mode** (File → Expert Mode).

   $AMSBIN/amsreport /path/to/engine.rkf "AMSResults%Energy" -r

"amsreport" can also extract many other properties. See the amsreport
documentation.


7. Command-line: dmpkf or akf
-----------------------------

   $AMSBIN/dmpkf /path/to/engine.rkf "AMSResults%Energy"

For more human-friendly output, you can also use "$AMSBIN/akf":

   $AMSBIN/akf /path/to/engine.rkf -pv "AMSResults%Energy"

For more information, run "$AMSBIN/akf -h", or see the akf
documentation.


8. Command-line: grep (not recommended)
---------------------------------------

We do not recommend to "grep" the output file, as the output file
format may change in future versions.

   grep "^Energy (hartree)" jobname.out


Python
======

"amspython" is the python interpreter included with the Amsterdam
Modeling Suite. It gives you access to the PLAMS python library.


9. Python: Load an AMSJob
-------------------------

To get the final energy:

* Save the below code snippet into a file "filename.py"

* Run it from the command-line with: "$AMSBIN/amspython filename.py".

   from scm.plams import AMSJob
   job = AMSJob.load_external('/path/to/jobname.results')
   energy = job.results.get_energy()
   print(energy)

To get all the energies from for example a geometry optimization:

   from scm.plams import AMSJob
   job = AMSJob.load_external('/path/to/jobname.results')
   energies_list = job.results.get_history_property('Energy')
   print(energies_list)

PLAMS has many different functions for extracting results. See the
AMSResults API.


10. Python: Direct access to .rkf file
--------------------------------------

To find out which entry to read from a binary file, first inspect the
file with kfbrowser in **Expert Mode** (File → Expert Mode).

You can read it using PLAMS, scm.akfreader, scm.base.KFFile. or
scm.akfreader.

* Save the one of the below code snippets into a file "filename.py"

* Run it from the command-line with: "$AMSBIN/amspython filename.py".


PLAMS KFReader.read
~~~~~~~~~~~~~~~~~~~

To get the final energy with KFReader:

   from scm.plams import KFReader
   kf = KFReader('/path/to/jobname.results/engine.rkf')
   energy = kf.read('AMSResults', 'Energy')
   print(energy)


PLAMS AMSResults.readrkf
~~~~~~~~~~~~~~~~~~~~~~~~

Alternatively, load an AMSJob and call the "readrkf" method on its
results:

   from scm.plams import AMSJob
   job = AMSJob.load_external('/path/to/jobname.results')
   energy = job.results.readrkf('AMSResults', 'Energy', file='engine')
   print(energy)


scm.akfreader AKF
~~~~~~~~~~~~~~~~~

   from scm.akfreader import AKFReader
   akf = AKFReader('/path/to/jobname.results/engine.rkf')
   energy = akf.read("AMSResults%Energy")
   print(energy)

See also the scm.akfreader documentation.


scm.base KFFile
~~~~~~~~~~~~~~~

Warning:

  With scm.base.KFFile there are methods that change the contents of
  the .rkf file. To not accidentally modify the contents, only use the
  "read_" methods, like "read_real" below.

   from scm.base import KFFile

   with KFFile("/path/to/jobname.results/engine.rkf") as kf:
      # read_real reads a floating point number
      energy = kf.read_real("AMSResults", "Energy")
      print(energy)

See also the scm.base KFFile documentation.
