DEBUG_FUNCTION -- test code self-consistency

DEBUG_FUNCTION_CUTOFF = <real: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 = <logical:1>	off	whether to evaluate energy and derivatives wrt each restraint
all the ENERGY options

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 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 on, 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:

# Example for: DEBUG_FUNCTION

# This will use default MODELLER scripts to construct homology
# restraints for 1fas. It will then use DEBUG_FUNCTION to test
# the source code for the function and derivatives calculation
# by comparing analytical and numerical first derivatives.
# Some discrepancies will be reported but ignore them here.

INCLUDE

SET OUTPUT_CONTROL = 1 1 1 1 1

SET ALNFILE = 'debug_function.ali'
SET SEQUENCE = '1fas'
SET KNOWNS = '2ctx' '1nbt'
SET SPLINE_ON_SITE = off
CALL ROUTINE = 'model', EXIT_STAGE = 1

# To assign 0 weights to restraints whose numerical derivatives
# code does not work (i.e., splines for angles and dihedrals):
READ_SCHEDULE FILE = 'debug_function.sched'
ENERGY
DEBUG_FUNCTION DEBUG_FUNCTION_CUTOFF = 15.00 0.10 0.1, DETAILED_DEBUGGING = on