8.1.2. AMS, VASP, Quantum ESPRESSO, and Gaussian reference data
***************************************************************

ResultsImporters can extract reference data from AMS, VASP, Quantum
ESPRESSO, and Gaussian calculations.

When using a results importer with VASP, Quantum ESPRESSO or Gaussian
reference data, the outputs will automatically be converted to AMS
format (files named "ams.rkf" and "vasp.rkf", "qe.rkf" or
"gaussian.rkf") if such RKF files do not already exist.

Note:

  If you ran

  * a VASP calculation with the VASP via AMS GUI, or

  * a Quantum ESPRESSO calculation using the engine interface in
    AMS2024 or later,

  **this counts as an AMS job** since the "ams.rkf" file should
  already exist.

Important:

  For VASP, Quantum ESPRESSO, and Gaussian, the engine added to the
  engine collection cannot be used to calculate new reference data. It
  only stores some settings from the original calculations.


Supported ResultsImporters
^^^^^^^^^^^^^^^^^^^^^^^^^^

+----------------------+----------------------+----------------------+----------------------+----------------------+
| ResultsImporter      | AMS                  | VASP                 | Quantum ESPRESSO     | Gaussian             |
|======================|======================|======================|======================|======================|
| "add_neb_singlepoin  | ✔                    | ❌                   | ❌                   | ❌                   |
| ts()"                |                      |                      |                      |                      |
+----------------------+----------------------+----------------------+----------------------+----------------------+
| "add_pesexploration  | ✔                    | ❌                   | ❌                   | ❌                   |
| _singlepoints()"     |                      |                      |                      |                      |
+----------------------+----------------------+----------------------+----------------------+----------------------+
| "add_pesscan_single  | ✔                    | ❌                   | ❌                   | ❌                   |
| points()"            |                      |                      |                      |                      |
+----------------------+----------------------+----------------------+----------------------+----------------------+
| "add_reaction_energ  | ✔                    | ✔                    | ✔                    | ✔                    |
| y()"                 |                      |                      |                      |                      |
+----------------------+----------------------+----------------------+----------------------+----------------------+
| "add_singlejob()"    | ✔                    | ✔                    | ✔                    | ✔                    |
+----------------------+----------------------+----------------------+----------------------+----------------------+
| "add_trajectory_sin  | ✔                    | ✔                    | ✔                    | ✔                    |
| glepoints()"         |                      |                      |                      |                      |
+----------------------+----------------------+----------------------+----------------------+----------------------+


Supported properties
^^^^^^^^^^^^^^^^^^^^

+----------------------+----------------------+----------------------+----------------------+----------------------+
| Property             | AMS                  | VASP                 | Quantum ESPRESSO     | Gaussian             |
|======================|======================|======================|======================|======================|
| angle                | ✔                    | ✔                    | ✔                    | ✔                    |
+----------------------+----------------------+----------------------+----------------------+----------------------+
| charges              | ✔                    | ❌                   | ❌                   | ❌                   |
+----------------------+----------------------+----------------------+----------------------+----------------------+
| energy               | ✔                    | ✔                    | ✔                    | ✔                    |
+----------------------+----------------------+----------------------+----------------------+----------------------+
| dihedral             | ✔                    | ✔                    | ✔                    | ✔                    |
+----------------------+----------------------+----------------------+----------------------+----------------------+
| distance             | ✔                    | ✔                    | ✔                    | ✔                    |
+----------------------+----------------------+----------------------+----------------------+----------------------+
| forces               | ✔                    | ✔                    | ✔                    | ✔                    |
+----------------------+----------------------+----------------------+----------------------+----------------------+
| hessian              | ✔                    | ❌                   | ❌                   | ❌                   |
+----------------------+----------------------+----------------------+----------------------+----------------------+
| relative_energies    | ✔                    | ✔                    | ✔                    | ✔                    |
+----------------------+----------------------+----------------------+----------------------+----------------------+
| stress tensor        | ✔                    | ✔                    | ✔                    | ❌                   |
+----------------------+----------------------+----------------------+----------------------+----------------------+


8.1.2.1. AMS
============

The main results file from an AMS calculation is called ams.rkf. Set
the path to a directory containing ams.rkf, *or* to the ams.rkf file:

   ri = ResultsImporter()
   ri.add_singlejob('/path/to/directory_containing_ams_rkf', properties='forces')
   # or
   ri.add_singlejob('/path/to/ams.rkf', properties='energy')

**Engine in the engine collection**: The reference calculation's
engine settings will be copied to the shortcut's engine collection.


8.1.2.2. VASP
=============

Note:

  If you ran a VASP calculation with the VASP via AMS GUI, this counts
  as an AMS job since the "ams.rkf" file should already exist.

Set the path to a directory containing OUTCAR from a VASP job.
Example:

   ri = ResultsImporter()
   ri.add_singlejob('/path/to/directory_containing_OUTCAR', properties='forces')
   # or
   ri.add_singlejob('/path/to/OUTCAR', properties='energy')

Important:

  The VASP output file must be called exactly "OUTCAR" without any
  file extension.

**Conversion to ams.rkf and engine.rkf**: A subdirectory **AMSJob** is
created in the directory containing OUTCAR, and the "ams.rkf" and
"vasp.rkf" files are placed in that directory.

**Engine in the engine collection**: If the file INCAR exists in the
same directory as OUTCAR, the contents of INCAR are copied to the
engine collection. The default name for the engine is a condensed
version of the INCAR contents. Note that this engine **CANNOT** be
used to calculate new reference data.


8.1.2.3. Quantum ESPRESSO and Gaussian
======================================

Note:

  This section applies if you ran Quantum ESPRESSO as

  * a standalone program (directly launching pw.x)

  * with the AMS GUI in AMS versions up to and including 2023

  This section does not apply if you ran Quantum ESPRESSO using the
  interface in AMS2024 or later. It then counts as an AMS job.

Set the path to the standard output file (**must** have the file
extension ".out") from a Quantum ESPRESSO or Gaussian job. Example:

   ri = ResultsImporter()
   ri.add_singlejob('/path/to/job.out', properties='forces')

**Conversion to ams.rkf and engine.rkf**: If the name of the output
file is "jobname.out", then *if* the directory "jobname.results"
exists the **AMSJob** directory will be created inside
"jobname.results" and "ams.rkf" and "qe.rkf"/"gaussian.rkf" files will
be placed in that directory. Otherwise, the directory will be called
"jobname.AMSJob".

**Engine in the engine collection**: No input settings are extracted
from the Quantum ESPRESSO or Gaussian job. The reference engine will
contain "Unknown Quantum ESPRESSO (Gaussian) input". Note that this
engine **CANNOT** be used to calculate new reference data.

Note:

  Importing results from VASP, Quantum ESPRESSO, or Gaussian may not
  be 100% reliable, as the codes are not developed by SCM. ParAMS uses
  ASE to parse the corresponding output files.
