(M)DCM TEST SUITE

MIKE DEVEREUX, MARCH 2021

PURPOSE:
--------

THIS TEST SUITE IS AIMED AT DEVELOPERS OF THE MDCM ROUTINES IN CHARMM. THE EXAMPLES MAKE USE OF A
WIDE RANGE OF THE CODE'S FEATURES AND ARE MEANT TO CHECK THAT ANY CHANGES MADE TO THE CODE OR TO
CHARMM IN GENERAL IN A NEW RELEASE HAVE NOT BROKEN ANYTHING IN THE DCM ROUTINES.

AS SUCH, THE PARAMETERS USED IN PARTICULAR ARE NOT SUITABLE FOR PRODUCTION SIMULATIONS, THEY ARE
MOSTLY MADE UP VALUES AND OFTEN UNNECESSARILY COMPLICATED (MANY MORE CHARGES AND POLARIZABILITIES
THAN WOULD BE NEEDED) IN ORDER TO THOROUGHLY TEST THE CODE OR FOR BENCHMARKING.

THE EXAMPLES CAN BE INSTRUCTIVE, HOWEVER, AS A REFERENCE FOR SYNTAX AND STRUCTURE OF INPUT FILES FOR
(M)DCM SIMULATIONS.

USE:
----

STABILITY TESTS
THE EXAMPLES ARE OF MOST USE IF YOU SUPPLY TWO BINARIES IN THE RUN_TESTS.SH SCRIPT IN THIS FOLDER.
THAT WAY RESULTS FROM YOUR NEW RELEASE / DEVELOPMENT CODE ARE DIRECTLY COMPARED WITH RESULTS FROM A
STABLE BINARY OR EARLIER RELEASE. THE TESTS WILL STILL PROVIDE USEFUL COMPARISONS FOR SOME EXAMPLES
IF ONLY A SINGLE DEVELOPMENT BINARY IS PROVIDED AS BOTH DEVELOPMENT AND REFERENCE, THOUGH, WHERE DCM
ROUTINES ARE TESTED AGAINST STANDARD CHARMM ROUTINES BY APPROXIMATING A STANDARD CHARMM MODEL IN THE
DCM PARAMETER FILE.

TO RUN THE TESTS, FIRST EDIT THE USER-DEFINED PARAMETERS AT THE TOP OF THE RUN_TESTS.SH SCRIPT, THEN
RUN THE SCRIPT. ADJUSTABLE PARAMETERS INCLUDE THE NUMBER OF CPU CORES TO USE IN MPI, THE REFERENCE
AND DEVELOPMENT BINARIES TO USE AND WHICH TESTS SHOULD BE RUN.

BENCHMARKING TESTS
THESE TESTS CAN BE RUN FROM THE TEST ROOT FOLDER WITH THE RUN-BENCH.SH SCRIPT IN A SIMILAR MANNER TO
THE STABILITY TESTS, OR FOR MORE DETAILED BENCHMARKING ANALYSIS THE BENCHx FOLDERS ALSO CONTAIN
SCRIPTS TO BE USED WITH THE "GPROF" GNU PROFILING TOOL (REQUIRES COMPILATION OF CHARMM WITH FLAGS 
"-g -pg -fcheck=bounds,mem"). RUNNING WITHOUT GPROF ALLOWS A SIMPLE TIME COMPARISON OF TWO CODES
SUPPLIED IN RUN-BENCH.SH. RUNNING WITH GPROF.SH PROVIDES A BREAKDOWN OF TIME SPENT IN DIFFERENT
SUBROUTINES AND A LINE-BY-LINE BREAKDOWN OF THE MOST HEAVILY USED LINES OF CODE.

DYNAMICS TESTS
THESE TESTS ARE MEANT TO CHECK FOR STABILITY DURING SIMULATIONS, INCLUDING ENERGY CONSERVATION,
SAMPLING OF DIVERSE CONFORMATIONS, COMPATIBILITY WITH BAROSTATS AND FREE ENERGY ROUTINES. AGAIN,
PARAMETERS ARE NOT MEANT FOR PRODUCTION PURPOSES AND ARE USED HERE ONLY FOR THOROUGH TESTING. 
EXAMPLES SHOULD BE RUN INDIVIDUALLY FROM EACH FOLDER, IDEALLY VIA YOUR CLUSTER'S JOB SCHEDULER.
INSTRUCTIONS FOR INTERPRETING THE OUTPUT OF EACH EXAMPLE ARE INCLUDED IN README FILES IN THE
INDIVIDUAL SUBFOLDERS OF THE "DYNA" FOLDER (HOW TO CHECK FOR ENERGY CONSERVATION ETC.)

OUTPUT:
-------

THERE IS NO PASS / FAIL CRITERION OF THE TESTS AS FOR DEVELOPMENT PURPOSES IT IS OFTEN MORE
INSTRUCTIVE TO EXAMINE THE OUTPUT OF THE RUNS DIRECTLY. IN GENERAL THERE SHOULD BE EXACT OR VERY
CLOSE AGREEMENT BETWEEN ENERGIES FROM THE DEVELOPMENT AND REFERENCE CODE (IF 2 CODES ARE USED AND
COMPARED), AND THE FORCES AND VIRIAL NUMERICAL VS ANALYTICAL DERIVATIVE TESTS (TEST CRYS / TEST
CRYS HOMO TEST THE VIRIAL) SHOULD AGREE TO WITHIN CA. 0.1 KCAL/MOL/A. PAY PARTICULAR ATTENTION TO
AGREEMENT IN TOTAL ENERGY, MAKE SURE NO INDIVIDUAL FORCE COMPONENT ERRORS ARE LARGER THAN CA. 0.1
KCAL/MOL AND THE VIRIAL (CRYS / CRYS HOMO) ERROR ALSO DOES NOT EXCEED CA. 0.1 KCAL/MOL.