Ideas on user interface

[schneiderfelipe]

The user experience is essential for the widespread of the project. As such, considerable time should be devoted to its planning, and proper documentation should match an excellent interface. Currently, I envision three separate processes for using overreact in a project:

1. Create a model
2. Validate
3. Analyze

All steps take place after calculations have been effectuated. In reality, those steps can happen in a nonlinear fashion, e.g., you might calculate structures, then attempt a model and validate it, only to realize that the model needs adjustments, in which case you go back to your calculations. The analysis is the last step, where conclusions are taken, and quantitative results are gathered.

Creating a model

Model creation consists of specifying reactions and species, together with data sources from computational chemistry logfiles. A dictionary object encodes all information necessary for a model. This object can be stored in the JSON format for convenience (extension .jk). Additionally, we offer an input format for compiling JSON-encoded models files (extension .k).

Below are the usual ways of constructing a model file:

1. Using orxn -c to compile a .jk file from a .k file (might read logfiles).
2. Specifying reactions and species in Python and writing the resulting object to a .jk file (might read logfiles).

Below are the usual ways of constructing dictionary model objects:

1. Reading a .jk file to build the resulting object.
2. Reading a .k file directly (might read logfiles) to build the resulting object.
3. Specifying reactions and species in Python to build the resulting object (might read logfiles).

The most efficient way is to compile a .jk file from a .k file, which ensures logfiles are only read once. You can always come back and improve your .k file and recompile.

Validating

This is a broad concept but consists of checking how good is the model in predicting something you're interested in. As such, it consists of property calculation and comparison with experimental evidence. Some commonly compared properties are:

• Non-simulated properties:
  • Rate constants
  • Equilibrium constants
  • Arrhenius plots
  • Apparent activation energy
  • Boltzmann-averaged temperature-resolved spectroscopic properties
  • Kinetic isotope effects
• End-of-simulation properties:
  • Reaction yields
  • Product selectivity
• Simulated properties:
  • Boltzmann-averaged time-resolved spectroscopic properties
  • Reaction progress kinetic analysis (see below)

Reaction progress kinetic analysis (Blackmond (2005)) consists of a framework to investigate reaction mechanisms, in which graphs are used to understand chemical reactions:

• Reaction concentration profiles
  • Substrate concentration versus time ("integral method")
• Reaction rate profiles
  • Reaction rate versus time ("differential method")
• "Graphical rate equations" (see here as well)
  • Zeroth order
  • First-order
  • Second-order
• Turnover frequency
  • Turnover frequency versus substrate concentration
• Michaelis-Menten plots
  • Rate versus substrate concentration
  • Rate over one substrate concentration versus another substrate concentration
• Lineweaver-Burk plots
  • Reciprocal rate versus reciprocal substrate

The only things overreact needs to expose in order to allow reaction progress kinetic analysis are some properties over time (concentrations, rates, and turnover numbers and frequencies). The graphing part can be very easily done in matplotlib.

Analyzing models

In my view, the analysis consists of explaining the phenomena. This means determining the most important effects and measuring them. Determining the most important reaction steps is part of this:

• Rate-determining state analysis (Kozuch (2011))
• Degree of rate control (Campbell (2017))

The functionality of overreact ends here. After the most important steps are known, specific analysis with particular transition states can be employed somewhere else, such as the reaction force analysis (Yepes (2013)), resonance NBOs (Glendening (2019)) and the activation strain model (Vermeeren (2020)).

[schneiderfelipe]

Projects and issues related to the degree of rate control were moved to milestone 1.2.

[schneiderfelipe]

Discussions about kinetic isotope effects were moved to milestone 1.1.

[schneiderfelipe]

I'm removing this from 1.0 as this is simply a set of ideas with no particular schedule.

[schneiderfelipe]

This has served its purpose and all that is left are automated analysis and useful plotting primitives, which are going to be postponed for now.