Output
******


Reactants, products, unstable
=============================

The results directory contains a file "reactions_discovery.rkf". This
file contains all the reaction network information. It can be read by
the reactions_discovery workflow, which can use it to perform/redo the
ranking process. Additionally, AMSmovie can be used to view the
molecules in the reaction network.

All molecules in the reaction network are categorized either as
"product", "unstable", or "reactant".

* **Reactants** are the molecules that exist at the beginning of the
  MD runs.

* **Products** are the suggested stable side products in the reaction
  network.

* **Unstable** are the molecules that are not considered stable.

There are three reasons a molecule is considered unstable.

1. The number of bonds to the atoms deviates from the atom valence by
   more than a maximum amount. This maximum is hardcoded per element.

2. The assigned molecular charge deviates from the formal molecular
   charge of the molecule. This is a strong indication that the
   molecule is a radical.

3. By default all ions are considered unstable, but this can be
   changed in the input.

The suggested side products can be found in the file "products.sdf" in
the results directory. This file contains all network intermediates
that are considered stable.

The text output contains a list of ranked products, with an estimate
of cost of formation (labeled 'Barrier') and reaction energy. This
list of products is followed by a list containing for each stable
product the shortest path from the initial reactants. The cost of
formation is a soft maximum of all reaction energies in the shortest
path to the product.


KF output files
===============

Note:

  This section documents the sections and variables in the
  "reactions_discovery.rkf" file.

KF Section: General
   **Content:** General information about the amsbatch calculation.

   "General%account"
      Type:
         string

      Description:
         Name of the account from the license

   "General%ElapsedTime"
      Type:
         float

      Description:
         Elapsed time of the AMS workflow.

      Unit:
         second

   "General%engine messages"
      Type:
         string

      Description:
         Message from the engine. In case the engine fails to solves,
         this may contains extra information on why.

   "General%file-ident"
      Type:
         string

      Description:
         The file type identifier, e.g. RKF, RUNKF, TAPE21...

   "General%jobid"
      Type:
         int

      Description:
         Unique identifier for the job.

   "General%ProcessTime"
      Type:
         float

      Description:
         Time the AMS workflow spent in Python.

      Unit:
         second

   "General%program"
      Type:
         string

      Description:
         The name of the program/engine that generated this kf file.

   "General%release"
      Type:
         string

      Description:
         The version of the program that generated this kf file
         (including svn revision number and date).

   "General%termination status"
      Type:
         string

      Description:
         The termination status. Possible values: 'NORMAL
         TERMINATION', 'NORMAL TERMINATION with warnings',  'NORMAL
         TERMINATION with errors', 'ERROR', 'IN PROGRESS'.

   "General%title"
      Type:
         string

      Description:
         Title of the calculation.

   "General%uid"
      Type:
         string

      Description:
         SCM User ID

   "General%user input"
      Type:
         string

      Description:
         The text input of the AMS workflow.

   "General%version"
      Type:
         int

      Description:
         Version number?

KF Section: MolecularDynamicsResults
   **Content:** Generic results.

   "MolecularDynamicsResults%NumSimulations"
      Type:
         int

      Description:
         Number of molecular dynamics simulations that were performed.

KF Section: ChemicalSystem(#)
   **Content:** Molecules

   "ChemicalSystem(#)%nAtoms"
      Type:
         int

      Description:
         The number of atoms in the system

   "ChemicalSystem(#)%nAtomsTypes"
      Type:
         int

      Description:
         The number different of atoms types

   "ChemicalSystem(#)%AtomicNumbers"
      Type:
         int_array

      Description:
         Atomic number 'Z' of the atoms in the system

      Shape:
         [nAtoms]

   "ChemicalSystem(#)%AtomMasses"
      Type:
         float_array

      Description:
         Masses of the atoms

      Unit:
         a.u.

      Values range:
         [0, '\infinity']

      Shape:
         [nAtoms]

   "ChemicalSystem(#)%AtomSymbols"
      Type:
         string

      Description:
         The atom's symbols (e.g. 'C' for carbon)

      Shape:
         [nAtoms]

   "ChemicalSystem(#)%EngineAtomicInfo"
      Type:
         string_fixed_length

      Description:
         Atom-wise info possibly used by the engine.

   "ChemicalSystem(#)%Coords"
      Type:
         float_array

      Description:
         Coordinates of the nuclei (x,y,z)

      Unit:
         bohr

      Shape:
         [3, nAtoms]

   "ChemicalSystem(#)%bondOrders"
      Type:
         float_array

      Description:
         The bond orders for the bonds in the system. The indices of
         the two atoms participating in the bond are defined in the
         arrays 'fromAtoms' and 'toAtoms'. e.g. bondOrders[1]=2,
         fromAtoms[1]=4 and toAtoms[1]=7 means that there is a double
         bond between atom number 4 and atom number 7

   "ChemicalSystem(#)%toAtoms"
      Type:
         int_array

      Description:
         Index of the second atom in a bond. See the bondOrders array

   "ChemicalSystem(#)%fromAtoms"
      Type:
         int_array

      Description:
         Index of the first atom in a bond. See the bondOrders array

KF Section: Categories
   **Content:** Different categories of molecules.

   "Categories%NumProducts"
      Type:
         int

      Description:
         Number of products.

   "Categories%NumReactants"
      Type:
         int

      Description:
         Number of reactants.

   "Categories%NumUnstable"
      Type:
         int

      Description:
         Number of unstable systems.

   "Categories%Products"
      Type:
         int_array

      Description:
         Indices of (RD)History entries that are products.

      Shape:
         [NumProducts]

   "Categories%Reactants"
      Type:
         int_array

      Description:
         Indices of (RD)History entries that are reactants.

      Shape:
         [NumReactants]

   "Categories%Unstable"
      Type:
         int_array

      Description:
         Indices of (RD)History entries that are unstable.

      Shape:
         [NumUnstable]

KF Section: Reaction(#)
   **Content:** A reaction.

   "Reaction(#)%Composition"
      Type:
         string

      Description:
         The description of the reaction (for example, A => B + C)
         where the molecules are described by their empirical formula.

   "Reaction(#)%Count"
      Type:
         int

      Description:
         Total number of this this reaction was observed.

   "Reaction(#)%Hash"
      Type:
         string

      Description:
         Unique identifier for this reaction.

   "Reaction(#)%ProductHashes"
      Type:
         lchar_string_array

      Description:
         Hashes (i.e. the unique identifiers) of the product
         molecules.

   "Reaction(#)%ProductIndices"
      Type:
         int_array

      Description:
         Indices of the product molecules in the RDHistory section.

   "Reaction(#)%ReactantHashes"
      Type:
         lchar_string_array

      Description:
         Hashes (i.e. the unique identifiers) of the reactant
         molecules.

   "Reaction(#)%ReactantIndices"
      Type:
         int_array

      Description:
         Indices of the reactant molecules in the RDHistory section.

   "Reaction(#)%ReactionEnergy"
      Type:
         float

      Description:
         The reaction energy for this reaction.

      Unit:
         hartree

   "Reaction(#)%SMILESDescription"
      Type:
         string

      Description:
         The description of the reaction (for example, A => B + C)
         where the molecules are described by their SMILES strings.

KF Section: History
   **Content:** History of the system during the AMS calculation. What
   is stored here depends on the task of the AMS calculation. For
   example, for a GeometryOptimization this will contain the
   intermediate steps of the GO, while for a MoleculeDynamics
   calculation it will contain the MD frames.

   "History%Bonds"
      Type:
         subsection

      Description:
         ?

   "History%Coords(#)"
      Type:
         float_array

      Description:
         Coordinates of the systems of a given entry.

      Shape:
         [3, :]

   "History%Energy(#)"
      Type:
         float

      Description:
         Energy of the system of a given entry.

      Unit:
         hartree

   "History%LatticeVectors(#)"
      Type:
         float_array

      Description:
         The lattice vectors of a given entry.

      Unit:
         bohr

      Shape:
         [3, :]

   "History%nEntries"
      Type:
         int

      Description:
         Number of history entries.

   "History%nLatticeVectors(#)"
      Type:
         int

      Description:
         The number of lattice vectors (i.e. the number of periodic
         boundary conditions) of a given entry.

   "History%Step(#)"
      Type:
         int

      Description:
         The step number in a Molecular Dynamics calculation.

   "History%SystemVersion(#)"
      Type:
         int

      Description:
         Index of the versioned-chemical system of a given frame.

KF Section: RDHistory
   **Content:** History of a Molecular dynamics simulation.

   "RDHistory%Balance(#)"
      Type:
         string

      Description:
         The overall balanced reaction for this product

   "RDHistory%BalancedReaction(#)"
      Type:
         int_array

      Description:
         Index of the estimated most efficient balanced reaction
         resulting in this molecule (estimated from the pool of all
         reactants and all stable products).

   "RDHistory%blockSize"
      Type:
         int

      Description:
         Explain the block-system... ?

   "RDHistory%Cost(#)"
      Type:
         float_array

      Description:
         The sum of the exponentials (exp(E/RT)+1) of the reaction
         energy of each reaction involved in formation of this
         product. Taking the logarithm of this effectively results in
         the highest 'barrier' along the path.

   "RDHistory%CreatedBy(#)"
      Type:
         string

      Description:
         This command was used to obtain the coordinates for stability
         analysis for this molecule

   "RDHistory%currentEntryOpen"
      Type:
         bool

      Description:
         ?

   "RDHistory%Depth(#)"
      Type:
         int_array

      Description:
         The depth of the molecule in the network (number of
         elementary reactions separating it from the reactants)

   "RDHistory%FinalCount(#)"
      Type:
         int_array

      Description:
         Number of molecules of this kind at the end of the
         simulation.

   "RDHistory%GuessedCharge(#)"
      Type:
         float_array

      Description:
         The formal charge of the molecule as estimated by PLAMS

   "RDHistory%Hash(#)"
      Type:
         string

      Description:
         Unique identifier of the molecule.

   "RDHistory%Id(#)"
      Type:
         string

      Description:
         The indexed formula of this molecule.

   "RDHistory%InitialCount(#)"
      Type:
         int_array

      Description:
         Number of molecules of this kind at the beginning of the
         simulation.

   "RDHistory%ItemName(#)"
      Type:
         string

      Description:
         ?

   "RDHistory%MolecularFormula(#)"
      Type:
         string

      Description:
         Molecular formula.

   "RDHistory%Name(#)"
      Type:
         string

      Description:
         SMILES string

   "RDHistory%nBlocks"
      Type:
         int

      Description:
         Explain the block-system... ?

   "RDHistory%nEntries"
      Type:
         int

      Description:
         Number of MD history entries.

   "RDHistory%ParentReaction(#)"
      Type:
         int_array

      Description:
         The index of the parent reaction in the shortest path from
         reactants to this compound

   "RDHistory%PathEnergy(#)"
      Type:
         float_array

      Description:
         The overall energy balance of the full path to this product

   "RDHistory%PathTree(#)"
      Type:
         string

      Description:
         The full path through the network to this product, as a
         string.

   "RDHistory%PotentialEnergy(#)"
      Type:
         float_array

      Description:
         The potential energy, i.e. the energy as computed by the
         engine. This is a 'blocked' property. See the 'blockSize' and
         'nBlocks' variables for more details.

      Unit:
         hartree

   "RDHistory%Radical(#)"
      Type:
         bool_array

      Description:
         Is this molecule a radical or not.

   "RDHistory%ReactionsAsProduct(#)"
      Type:
         int_array

      Description:
         Indices of the reactions in which this molecule was part of
         the products.

   "RDHistory%ReactionsAsReactant(#)"
      Type:
         int_array

      Description:
         Indices of the reactions in which this molecule was part of
         the reactants.

   "RDHistory%Representative(#)"
      Type:
         bool_array

      Description:
         Signifies if the coordinates are representative of the
         molecule (as defined by the connectivity)

   "RDHistory%SMILES(#)"
      Type:
         string

      Description:
         SMILES string
