Editing NEEMP:Modes (section)

=Parametrization mode=

This mode serves for calculation of EEM parameters. Three main components make up the input for this mode: 

:* a training set of molecules (argument of <code>--sdf-file</code> option)

:* a set of QM charges for each molecule in the sdf file (argument of <code>--chg-file</code> option)

:* the specification of the parametrization approach (by <code>-p</code> or <code>--params-method</code>) and its specific options.

===Linear Regression (LR)===

'''''<u>BASIC USAGE:</u>''''' ''./neemp -m params -p lr-full --sdf-file examples/set01.sdf --chg-file examples/set01.chg --par-out-file new_parameters.par''

'''LR''' (<code>--params-method</code> <code>lr-full</code> or <code>-p</code> <code>lr-full</code>) is the default parametrization approach in '''NEEMP''', since its application in the parametrization process is well documented and described in literature. The main extension in respect to previous version is the ability for the user to define by which metrics the best performing parameter set will be selected ('''''see figure'''''): 

:<code>-s</code> <code>R2</code> or <code>--sort-by</code> <code>R2</code> to select the parameter set with the highest squared Pearson coefficient (R<sup>2</sup>)

:<code>-s</code> <code>RMSD</code> or <code>--sort-by</code> <code>RMSD</code> to select the parameter set with the lowest atomic type root mean square difference (avg(RMSDa))

{| class="wikitable" border="1" style="margin-left: auto; margin-right: auto;" width="650px"
 |-
 | [[File:LR_full_R2.png| 600px]]
 | [[File:LR_full_RMSD.png| 600px]]
 |- 
 |colspan=2 |'''''Figure 2:''''' Detailed view of the '''LR''' parametrization settings for two distinct '''NEEMP''' executions differing in the best-performance selection metrics (''R<sup>2</sup>'' in left side image and ''RMSD'' in the right side image).
 |}

Additionally, the quality of the parameter set may benefit from the usage of a discarding procedure (<code>-d</code> <code>simple</code> or <code>--discard</code> <code>simple</code>). In fact it has been proved that using a subset of the original training set often leads to EEM charges that better agree with the reference QM charges. For useful examples on the '''LR''' parametrization approach and the discarding procedure see respectively examples [[NEEMP:Examples#Example 3 - Parametrization mode | 3]]/[[NEEMP:Examples#Example 4 - Parametrization mode k search |4]] and [[NEEMP:Examples#Example 5 - Parametrization mode simple discard|5]]. In particular the latter introduces the <code>--limit-iters</code> and <code>--limit-time</code> options, which modulate the behaviour of the discarding procedure, setting respectively an upper bound in the number of iterations and/or in the execution time.

===Differential Evolution + Minimization (DE-MIN)===

'''''<u>BASIC USAGE:</u>''''' ''./neemp -m params -p de --sdf-file examples/set01.sdf --chg-file examples/charges.chg --par-out-file new_parameter.par''

In parallel we developed an advanced EEM parametrization approach specifically tailored to cope with heterogeneous data, which in the past presented quite a challenge in the EEM parametrization framework. It consists in the combination of ''differential evolution'' method with a local minimization technique (''NEWUOA''), hence the acronym '''DE-MIN'''. To call this approach in '''NEEMP''' use the option <code>--params-method</code> <code>de</code> or <code>-p</code> <code>de</code>.
<br style="clear:both" />

[[File:gm1.png | thumb | 700px | center | '''''Figure 3:''''' Abridged '''DE-MIN''' approach output for structural file ''examples/set01.sdf'' and charge file ''examples/set01.chg''. In the upper block are displayed the specifics for the '''de-min''' parametrization procedure. Note as the bottom block presents the same structure as for other parametrization approaches and options (compare [[NEEMP:Examples#Example 5 - Parametrization mode simple discard | here]]).]]

The behaviour of the '''DE-MIN''' approach can be modulated by several options, but to make life easier we provide the user with reasonable default values that have been tuned to output optimal parameter set (for a complete view of the options refer to the [[NEEMP:Options | option list]] and the [[NEEMP:Examples#Example 6 - Parametrization mode DE-MIN | examples]] section).

'''NB''': the default quality evaluating metrics for '''DE-MIN''' approach is ''(avg(RMSDa))''.