model.debug_function() -- test code self-consistency

edat = <energy_data>		objective function parameters
debug_function_cutoff = <float:3>	0.01 0.001 0.1	cutoffs for reporting differences between numerical and analytical derivatives: absolute, relative errors, factor_for_indiv_rstrs
detailed_debugging = <bool:1>	False	whether to evaluate energy and derivatives wrt each restraint

Description:

This command checks the self-consistency of the code for the objective function and its derivatives by calculating and comparing numeric and analytical derivatives. All the parameters influencing the evaluation of the molecular pdf are also relevant (see model.energy()). The derivative is reported if both the absolute difference and the fractional difference between the two kinds of evaluations are larger than debug_function_cutoff[1] and debug_function_cutoff[2], respectively.

When detailed_debugging is True, the analytic and numeric derivatives of each restraint with respect to atomic positions are also compared for the atoms `violated' by the whole molecular pdf. The absolute cutoff for writing out the discrepancies is scaled by debug_function_cutoff[3]; the relative cutoff remains the same as before.

When MODELLER is compiled in double precision, this test reports a smaller number of discrepancies.

Example: examples/commands/debug_function.py

# Example for: model.debug_function()

# This will use the MODELLER automodel class to construct homology
# restraints for 1fas. It will then use model.debug_function() to test
# the source code for the function and derivatives calculation
# by comparing analytical and numerical first derivatives (note that
# automodel is a derived class of model, so all 'model' methods will work
# on 'automodel'). Some discrepancies may be reported but ignore them here.

from modeller.automodel import *    # Load the automodel class

log.verbose()
env = environ()

a = automodel(env, alnfile = 'debug_function.ali',
              knowns  = ('2ctx', '1nbt'), sequence = '1fas')
a.spline_on_site = False
a.make(exit_stage=1)

# To assign 0 weights to restraints whose numerical derivatives
# code does not work (i.e., splines for angles and dihedrals):
a.schedule.read(file='debug_function.sched')
a.energy(output='SHORT')
a.debug_function(debug_function_cutoff=(15.00, 0.10, 0.1),
                 detailed_debugging=True)