8.1.1. ResultsImporter overview
*******************************


8.1.1.1. ResultsImporter summary
================================

The "ResultsImporter" class is convenient for setting up the Job
Collection, Data Set, and Engine Collection from finished reference
calculations. A *results importer* typically affects all three of
those classes with a single method (see Import Training Data with
ResultsImporter)

Most ResultsImporters work on **finished reference jobs**, coming from
one of these computational chemistry programs:

+----------------------------------------------------+----------------------------------------------------+
| Program                                            | Required results files                             |
|====================================================|====================================================|
| AMS (ADF, BAND, DFTB, ReaxFF, ...)                 | "ams.rkf" (and sometimes "engine.rkf")             |
+----------------------------------------------------+----------------------------------------------------+
| VASP                                               | "OUTCAR" (and optionally "INCAR")                  |
+----------------------------------------------------+----------------------------------------------------+
| Quantum ESPRESSO                                   | Standard output file (ending in ".out").           |
+----------------------------------------------------+----------------------------------------------------+
| Gaussian                                           | Standard output file (ending in ".out").           |
+----------------------------------------------------+----------------------------------------------------+

The ResultsImporter:

* **reads the input and output** from the reference job,

* **creates a reference engine** in the Engine Collection if it does
  not already exist,

* **adds one or more jobs** to the Job Collection using one or more
  systems from the reference job, if they do not already exist.

* **adds one or more entries** to the Data Set

Import Training Data with ResultsImporter gives an example on how to
use ResultsImporters.

All ResultsImporters are summarized in the below table, where SP
stands for SinglePoint, GO for GeometryOptimization, MD for
MolecularDynamics, and QE for Quantum ESPRESSO.

+----------------+----------------+----------------+----------------+----------------+----------------+----------------+
| ResultsImport  | add_singlejob  | add_trajector  | add_reaction_  | add_pesscan_s  | add_neb_singl  | add_pesexplor  |
| er name        |                | y_singlepoints | energy         | inglepoints    | epoints        | ation_singlep  |
|                |                |                |                |                |                | oints          |
|================|================|================|================|================|================|================|
| Reference job  | any            | GO or MD       | SP, GO, or     | PESScan        | NEB            | PESExploration |
| type           |                |                | None [1]       |                |                |                |
+----------------+----------------+----------------+----------------+----------------+----------------+----------------+
| Reference      | AMS/VASP/QE    | AMS/VASP/QE    | AMS/VASP/QE    | AMS            | AMS            | AMS            |
| program        |                |                |                |                |                |                |
+----------------+----------------+----------------+----------------+----------------+----------------+----------------+
| # jobs added   | 1              | any            | 1 per species  | any            | any            | any            |
+----------------+----------------+----------------+----------------+----------------+----------------+----------------+
| Default task   | SP             | SP             | SP             | SP             | SP             | SP             |
+----------------+----------------+----------------+----------------+----------------+----------------+----------------+
| Allowed tasks  | any            | SP             | SP or GO       | SP             | SP             | SP             |
+----------------+----------------+----------------+----------------+----------------+----------------+----------------+
| Systems        | final frame    | any            | final frames   | converged      | converged      | minima and     |
|                | [2]            |                |                | points         | points         | transition     |
|                |                |                |                |                |                | states         |
+----------------+----------------+----------------+----------------+----------------+----------------+----------------+
| # data_set     | any            | any            | 1              | any            | any            |                |
| entries        |                |                |                |                |                |                |
+----------------+----------------+----------------+----------------+----------------+----------------+----------------+
| Properties     | all extractors | traj. prop.    | None           | energy/relati  | energy/relati  | energy/relati  |
|                |                | [3]            |                | ve_energies/s  | ve_energies    | ve_energies    |
|                |                |                |                | tresstensor*   |                |                |
+----------------+----------------+----------------+----------------+----------------+----------------+----------------+
| API docs       | "add_singlejo  | "add_trajecto  | "add_reaction  | "add_pesscan_  | "add_neb_sing  | "add_pesexplo  |
|                | b()"           | ry_singlepoin  | _energy()"     | singlepoints(  | lepoints()"    | ration_single  |
|                |                | ts()"          |                | )"             |                | points()"      |
+----------------+----------------+----------------+----------------+----------------+----------------+----------------+

[1] add_reaction_energy can also be used without reference jobs, only
    the atomic coordinates are needed.

[2] add_singlejob takes the "main molecule", unless the reference job
    is a PESScan (then the input molecule is used).

[3] Trajectory properties: energy, relative_energies, forces,
    stresstensor


8.1.1.2. ResultsImporter settings
=================================

When initializing a "ResultsImporter", you can pass a "settings"
argument, that is either a string pointing to a
"results_importer_settings.yaml" file, or which is a PLAMS Settings
instance.

Example:

   results_importer_settings = Settings()
   results_importer_settings.trim_settings = True
   results_importer_settings.default_go_settings.MaxIterations = 30
   results_importer_settings.units.energy = 'kcal/mol'

   ri = ResultsImporter(settings=results_importer_settings)

For a detailed description of the available settings, see
"__init__()".


8.1.1.3. Training set, validation set, etc.
===========================================

See the tutorial section Training set, validation set, and other data
sets.


8.1.1.4. Save and load from disk
================================

The job collection, engine collection, data_set(s), and shortcut
settings can be stored for later retrieval with the "store()" method.

To load them from files, pass the paths to the files as arguments to
"__init__()".

For an example, see the tutorial section Save to disk.


8.1.1.5. add_singlejob
======================

"add_singlejob()" adds one job to the job collection, together with an
arbitrary number of entries in the data_set.

For how to use it, see Import Training Data with ResultsImporter, in
particular

* Add a singlepoint calculation on the optimized geometry

* Add a geometry optimization job extracting the bond length and bond
  angle

See also the API docs: "add_singlejob()"

Each entry in the data_set must be an extractor acting on the job.

Adding for example "'distance(0,1)'" to the "properties" argument will
add a data_set entry with the expression "distance('jobname',0,1)".

Example:

   ri = ResultsImporter()
   ri.add_singlejob('/path/to/ams.rkf',
                    properties=['energy', 'distance(0,1)'],
                    task='GeometryOptimization')


8.1.1.6. add_trajectory_singlepoints
====================================

"add_trajectory_singlepoints()" extracts given number of frames from a
trajectory file. The "properties" must be one or more of the
following: "energy", "relative_energies", "forces", or "stresstensor".

For how to use it, see Import Training Data with ResultsImporter, in
particular

* Add a trajectory

See also the API docs: "add_trajectory_singlepoints()"

Example:

   ri = ResultsImporter()

   # extract every 10 frames
   ri.add_trajectory_singlepoints('/path/to/ams.rkf',
                     properties=['forces', 'relative_energies'],
                     start=0,
                     step=10)

   # extract 20 frames
   ri.add_trajectory_singlepoints('/path/to/ams.rkf',
                     properties=['forces', 'relative_energies'],
                     N=20)


8.1.1.7. add_reaction_energy
============================

"add_reaction_energy()" calculates and adds a reaction energy to the
data_set.  The reaction is automatically balanced: only the reactants
and products need to be specified, not the stoichiometric
coefficients. The coefficients are normalized according to the
"normalization" and "normalization_value" arguments.

Setting "normalization='r0'" will set the coefficient for the first
reactant to "normalization_value". "normalization='r1'" would
correspond to the second reactant, etc. "normalization='p0'" would
correspond to the first product, etc.

add_reaction_energy can also be used with PLAMS molecules instead of
reference jobs. In that case one should specify the reference value
with the "reference" keyword.

For how to use it, see Import Training Data with ResultsImporter, in
particular

* Add a reaction energy

See also the API docs: "add_reaction_energy()"

Simple example:

   ri = ResultsImporter()

   # from reference jobs
   ri.add_reaction_energy(reactants=['/reactant1/ams.rkf', '/reactant2/ams.rkf'],
                          products=['/product1/ams.rkf', '/product2/ams.rkf'],
                          normalization='r0',
                          normalization_value=1.0)

   # from Molecule instances. mol_1 etc. need to be PLAMS Molecules
   ri.add_reaction_energy(reactants=[mol_1, mol_2],
                          products=[mol_3, mol_4],
                          normalization='p1',
                          normalization_value=2.0,
                          reference=12.34,
                          unit='kcal/mol')


8.1.1.8. add_pesscan_singlepoints
=================================

"add_pesscan_singlepoints()" extracts a given number of (converged)
frames from an AMS PESScan reference job, and adds them as single
point calculations to the job collection.

Important:

  If you want to add a job with "Task PESScan" to the job collection,
  do not use this shortcut but instead add_singlejob.

Tip:

  Adding singlepoint calculations from a PESScan with
  "add_pesscan_singlepoints(job, properties='relative_energies')" will
  give a much faster parametrization than using "add_singlejob(job,
  properties='pes', task='PESScan')". However, we in general recommend
  to use "add_singlejob" instead, since it will give a more accurate
  parametrization of the potential energy surface.

The "properties" must be one or more of the following: "energy",
"relative_energies", "stresstensor*" ("stresstensor",
"stresstensor_2d", etc., see Available Extractors).

Note:

  Extracting the stress tensor from an energy-volume scan will only
  work if CalcPropertiesAtPESPoints was set when running the job, i.e.
  if the files "PESPoint(1).rkf" etc. exist in the same directory as
  "ams.rkf".

See the API docs for details: "add_pesscan_singlepoints()"

Example:

   ri = ResultsImporter()

   ri.add_pesscan_singlepoints('/path/to/ams.rkf',  # ams.rkf from a PESScan job
                  properties=['relative_energies'])


8.1.1.9. add_neb_singlepoints
=============================

"add_neb_singlepoints()" extracts the converged frames from an AMS NEB
reference job, and adds them as single point calculations to the job
collection.

Important:

  If you want to add a job with "Task NEB" to the job collection, do
  not use this shortcut but instead add_singlejob.

The "properties" must be one or more of the following: "energy",
"relative_energies".

See the API docs for details: "add_neb_singlepoints()"

Example:

   ri = ResultsImporter()

   ri.add_neb_singlepoints('/path/to/ams.rkf',  # ams.rkf from a NEB job
              properties=['relative_energies'])


8.1.1.10. add_pesexploration_singlepoints
=========================================

"add_pesexploration_singlepoints()" extracts a given list of states an
AMS PESExploration reference job, and adds them as single point
calculations to the job collection.

Important:

  If you want to add a job with "Task PESExploration" to the job
  collection (although you probably do not because of how
  computationally demanding such jobs are), do not use this shortcut
  but instead add_singlejob.

The "properties" must be one or more of the following: "energy",
"relative_energies".

See the API docs for details: "add_pesexploration_singlepoints()"

Example:

   ri = ResultsImporter()

   ri.add_pesexploration_singlepoints('/path/to/ams.rkf',  # ams.rkf from a PESExploration job
                         properties=['relative_energies'],
                         indices=[1,2,5,6]) # state numbers (start with 1)
