Network Extraction
******************

In this second step of the workflow a reaction network is extracted,
and the individual molecules are optimized.


Initial Network from ChemTrayzer2
=================================

To extract the reaction network, ChemTraYzer2 is used. By default,
only the trajectories from simulations that terminated normally are
used for network extraction. The reaction network is fully stored in
the "ams.rkf" file, as well is in the file "reaction_network.gml",
which can be directly read into the networkx python module. Reaction
network information is also printed to output, and the details of the
latter can be set in the input block "NetworkExtraction%Print". In the
output, the molecules are listed in order of their net flux; The
difference between the number of instances at the end of the
simulation and the number of instances at the start of the
simulations. At this first approximation, products with the highest
positive net flux are considered to be the most stable.


Geometry Optimization
=====================

For all unique molecules, an attempt is made to find the optimized
geometry for that molecule. For each molecule the coordinates are
extracted either from the molecular dynamics runs (reported with
source file, frame and atom ids) or constructed from the SMILES string
using "from_smiles". Finally, a geometry optimization is performed and
each molecule is assigned the total energy corresponding to the
optimized geometry. If the geometry optimization fails, or if our bond
guessing algorithm predicts a different connectivity after
optimization, the energy of the unoptimized coordinates is used
instead. If desired, the geometry optimizations can be performed with
a different engine, e.g. using an implicit solvent, if this better
approximates the target experimental reaction conditions. To do this,
first perform a run with molecular dynamics only and then perform a
restart with molecular dynamics disabled and the engine of choice
defined in the input.


Molecular Charge Assignment
===========================

In order to correctly perform geometry optimizations, the charge of
each molecule needs to be determined beforehand. The charges are
obtained by collecting the atomic charges from the output of the
molecular dynamics simulations, averaging the resulting molecular
charges over the relevant frames, and rounding to integer values.
Every molecule will be connected to at most 2 reactions; The reaction
that creates it, and the reaction that destroys it. A check is
performed, to see if all the reaction charges are balanced. If this is
not the case, then the corresponding molecular charges are adjusted to
ensure charge balance through-out. The charge adjustments are
restricted in that the change \Delta q per molecule may not exceed
1.0e. If unbalanced reactions still remain after the charge
adjustments, then an ionization reaction is added, connecting two
versions of the molecule, each with a different charge.


Manual specification of MD trajectories
=======================================

You can run the network extraction on any MD trajectories, even if
they were not calculated by the Reactions Discovery tool.

If

* "MolecularDynamics%Enabled" is True, then those MD trajectories will
  be used for the network extraction,

* "MolecularDynamics%Enabled" is False, then you can specify a
  directory with ams.rkf files to analyze with
  "NetworkExtraction%MDTrajectories"

Example:

   MolecularDynamics Enabled=No
   NetworkExtraction Enabled=Yes MDTrajectories=/some/path

Unfinished simulations are only used if
"NetworkExtraction%ExtractFromFailedMDJobs" is enabled.

   NetworkExtraction
      Enabled Yes/No
      ExtractFromFailedMDJobs Yes/No
      MDTrajectories string
      Print
         FilterFluctuations Yes/No
         MaxReactionOrder integer
         MinReactionsThreshold integer
         SkipRareReactions Yes/No
      End
      UseCharges Yes/No
   End

"NetworkExtraction"
   Type:
      Block

   Description:
      Options for extracting the reactive network from MD trajectories

   "Enabled"
      Type:
         Bool

      Default value:
         Yes

      GUI name:
         NetworkExtraction

      Description:
         Whether to perform network extraction.

   "ExtractFromFailedMDJobs"
      Type:
         Bool

      Default value:
         No

      GUI name:
         Extract from failed MD jobs

      Description:
         Whether to extract from failed/crashed MD jobs (by default,
         only successful jobs are used)

   "MDTrajectories"
      Type:
         String

      GUI name:
         MD Trajectories

      Description:
         If MolecularDynamics%Enabled is False, this directory will be
         recursively scanned for ams.rkf files containing MD
         trajectories. All found trajectories will be used for the
         analysis. It should typically be a Reactions Discovery
         results directory containing finished MD simulations.

   "Print"
      Type:
         Block

      Description:
         Printing details

      "FilterFluctuations"
         Type:
            Bool

         Default value:
            Yes

         Description:
            If true, do not print molecules that are only part of
            recrossing reactions.

      "MaxReactionOrder"
         Type:
            Integer

         Default value:
            4

         Description:
            If the reaction order is larger than this value, the
            reaction will not be printed.

      "MinReactionsThreshold"
         Type:
            Integer

         Default value:
            3

         Description:
            If a molecule is involved in fewer reaction than this
            value, skip printing the results corresponding to it. To
            print all molecules, set this value to 0.

      "SkipRareReactions"
         Type:
            Bool

         Default value:
            Yes

         Description:
            If true,reduce the output by filtering out rare reactions.
            If false, always print all reactions.

   "UseCharges"
      Type:
         Bool

      Default value:
         Yes

      Description:
         Use engine-calculated charges if they exist on the MD
         trajectory files for the NetworkExtraction
