Product Ranking
***************

Ranking the molecules based on the net flux over the molecular
dynamics simulations is only as reliable as the simulations
themselves. All reactive simulations use some kind of scheme to induce
reactivity, and this means that reaction conditions like temperature
and pressure will most likely be higher than the conditions in the
target system. Letting a reaction under our extreme simulation
conditions continue too long will most likely result in the
degradation of viable products, combined with the formation of final
products that would never be formed at the milder experimental
conditions. To correct for the extreme conditions of the molecular
dynamics simulations we assign stabilities to the molecules based on
the reaction network.

Both a value for kinetic stability (cost) and thermodynamic stability
are assigned, and ultimately the molecules are ordered based in the
first place on cost, and in the second place on (thermodynamic)
stability. The ranked stable products are saved in the files
"products.sdf" and "products.rkf".


Reaction Energies
=================

As the first step in this procedure, we assign reaction energies to
all reaction nodes in the network, based on the energies of the
optimized molecules. These reaction energy values have the advantage
that they are independent of the simulation conditions.


Product Cost
============

We perform a network search to assign a relative cost value to each
molecule in the network. The cost c of the reactants is set to one.
The cost c_p of any product/intermediate molecule p is then assigned
in a breadth first search through the network.

c_p = \sum_r c_r + \left( 1 + e^{E_R/k_bT} \right)

Here R is the reaction that has molecule p as product, and results in
the lowest possible cost c_p. The molecules r are the reactants
involved in reaction R. The value E_R is the reaction energy of
reaction R. T is the ranking temperature, which is set to 300K by
default. Selecting a higher temperature brings the contributions of
different reactions closer together, resulting in relatively lower
costs for molecules that are formed via reactions with high reaction
energies.


Product Stability
=================

In a similar manner, a thermodynamic relative product stability is
assigned, with the stability of the initial reactants set to zero.

s_p = \sum_r s_r + E_R

Again, R is the reaction that has p as product and results in the
lowest value of the cost c_p.


Reaction Balance
================

Separate from the reaction network procedures, a set of stable
products is extracted based on two different metrics. First, molecules
with connectivities deviating vastly from the valences of the
corresponding elements are discarded. Secondly, the molecular charges
determined in the NetworkExtraction run are compared to the 'formal'
molecular charges based on bond orders, and if the two values differ,
the molecule is considered a radical, and discarded as a stable
product.

For all stable products, an estimated balanced overall formation
reaction is then determined by balancing the reaction of the initial
reactants to this product. If it is not possible to balance the
reaction, one of the other stable products is included as a co-
product.


Example: ProductRanking from finished NetworkExtraction
=======================================================

Input:

   MolecularDynamics Enabled=No
   NetworkExtraction Enabled=No
   ProductRanking Enabled=Yes ReactionNetwork=/some/path

"ProductRanking%ReactionNetwork" **must** be a previous Reactions
Discovery result directory that has at least finished the network
extraction.

   ProductRanking
      BalanceFromNetwork Yes/No
      DiscardIons Yes/No
      Enabled Yes/No
      MaxBalancedReactions integer
      ReactionNetwork string
      Temperature float
      WritePaths Yes/No
   End

"ProductRanking"
   Type:
      Block

   Description:
      Options for ranking of the intermediates by stability

   "BalanceFromNetwork"
      Type:
         Bool

      Default value:
         No

      Description:
         Use the network to determine the balanced reaction from the
         initial reactants to each stable product. This is not the
         default. By default, a balanced equation is determined
         directly by using the other stable products as possible side
         products.

   "DiscardIons"
      Type:
         Bool

      Default value:
         Yes

      Description:
         Remove all ions from the final product list

   "Enabled"
      Type:
         Bool

      Default value:
         Yes

      GUI name:
         ProductRanking

      Description:
         Whether to perform ranking of the reaction network.

   "MaxBalancedReactions"
      Type:
         Integer

      Default value:
         1000

      Description:
         The maximum number of stable products used to find a balanced
         reaction equation for each one.

   "ReactionNetwork"
      Type:
         String

      Description:
         Directory containing a previous Reactions Discovery
         calculation with 'NetworkExtraction%Enabled Yes'

   "Temperature"
      Type:
         Float

      Default value:
         298.0

      Description:
         Temperature used to compute reaction rates from reaction
         energies of reactions in the reaction network.

   "WritePaths"
      Type:
         Bool

      Default value:
         Yes

      Description:
         Write full paths to the reaction network for each molecule.
