fpt Reference: INSERT RUN-TIME TRACE

fpt and WinFPT Reference Manual - Command-line Commands

| SimCon Home | Ref Manual Home |

INSERT RUN-TIME TRACE and Relative Debugging

Syntax:

[DO NOT] INSERT RUN-TIME TRACE [STATEMENTS]

Recommended Usage:

Write an fsp file for the program to be traced. Add a reference to the fsp file FPTMAIN:rt_trace.fsp at the end of the program fsp file. This fsp file contains the command %insert run-time trace and also adds the service routines which log and read the trace file. Please do not write this as the first file on the command line. The first file referenced is used to determine the names of some of the output files.

Under WinFPT, right-click the last item in the project tree, select "Add after" | "Existing FSP folder", navigate to the WinFPT installation (By default, C:\<Program files>\SimCon\WinFPT\ and select rt_trace.fsp.

Function:

Trace statements are inserted in the program to record entry to and exit from every sub-program and to capture every scalar value which is computed. For example, the code shown below is a simulation of a cannon ball:

PROGRAM BALL ! COMMON H, X, HDOT, XDOT, HDDOT, XDDOT, THETA0, THETA, & V0, V, DRAGCOEF, FRAMETIME, TIME ! ! U.S. units. PARAMETER (G=32.2) ! ! Initialise interactive handler CALL ADINIT ! ! Initial conditions setup by ADB CALL ADB ! HDOT=V0*SIND(THETA0) XDOT=V0*COSD(THETA0) ! DO WHILE (H .GE. 0.0) CALL ADB P_HDDOT=HDDOT P_XDDOT=XDDOT P_HDOT=HDOT P_XDOT=XDOT TIME=TIME+FRAMETIME THETA=ATAN2(HDOT,XDOT) V=SQRT(HDOT*HDOT+XDOT*XDOT) ! Square law drag XDDOT=-DRAGCOEF*V**2*COS(THETA) HDDOT=-G-DRAGCOEF*V**2*SIN(THETA) ! ! Integrate next frame positions - AB2 HDOT=HDOT+FRAMETIME*(3*HDDOT-P_HDDOT)*0.5 XDOT=XDOT+FRAMETIME*(3*XDDOT-P_XDDOT)*0.5 H=H+FRAMETIME*(3*HDOT-P_HDOT)*0.5 X=X+FRAMETIME*(3*XDOT-P_XDOT)*0.5 ENDDO : :

This code is instrumented to record a trace file:

!H!**************************************************************************** !H! File: m:\simcon_technical\web\htprp\example_codes\ball\fpt_output\ball.f !H! Output by fpt 3.7-q WinFPT On 05-NOV-12 At 11:35:29 Input files: !H! Main: m:\simcon_technical\web\htprp\example_codes\ball\fpt\ball.fpp !H! Current: m:\simcon_technical\web\htprp\example_codes\ball\source\ball.f !H! Licensee: SimCon: Development version. !H!**************************************************************************** PROGRAM BALL ! COMMON H,X,HDOT,XDOT,HDDOT,XDDOT,THETA0,THETA, & V0,V,DRAGCOEF,FRAMETIME,TIME ! ! U.S. units. PARAMETER (G=32.2) CALL TRACE_START_SUB_PROGRAM('BALL',1) ! ! Initialise interactive handler CALL ADINIT ! ! Initial conditions setup by ADB CALL ADB ! HDOT=V0*SIND(THETA0) CALL TRACE_R4_DATA('HDOT',HDOT,7) XDOT=V0*COSD(THETA0) CALL TRACE_R4_DATA('XDOT',XDOT,8) ! DO WHILE (H .GE. 0.0) CALL ADB P_HDDOT=HDDOT CALL TRACE_R4_DATA('P_HDDOT',P_HDDOT,9) P_XDDOT=XDDOT CALL TRACE_R4_DATA('P_XDDOT',P_XDDOT,10) P_HDOT=HDOT CALL TRACE_R4_DATA('P_HDOT',P_HDOT,11) P_XDOT=XDOT CALL TRACE_R4_DATA('P_XDOT',P_XDOT,12) TIME=TIME+FRAMETIME CALL TRACE_R4_DATA('TIME',TIME,13) THETA=ATAN2(HDOT,XDOT) CALL TRACE_R4_DATA('THETA',THETA,14) V=SQRT(HDOT*HDOT+XDOT*XDOT) CALL TRACE_R4_DATA('V',V,15) ! Square law drag XDDOT=-DRAGCOEF*V**2*COS(THETA) CALL TRACE_R4_DATA('XDDOT',XDDOT,16) HDDOT=-G-DRAGCOEF*V**2*SIN(THETA) CALL TRACE_R4_DATA('HDDOT',HDDOT,17) ! ! Integrate next frame positions - AB2 HDOT=HDOT+FRAMETIME*(3*HDDOT-P_HDDOT)*0.5 CALL TRACE_R4_DATA('HDOT',HDOT,18) XDOT=XDOT+FRAMETIME*(3*XDDOT-P_XDDOT)*0.5 CALL TRACE_R4_DATA('XDOT',XDOT,19) H=H+FRAMETIME*(3*HDOT-P_HDOT)*0.5 CALL TRACE_R4_DATA('H',H,20) X=X+FRAMETIME*(3*XDOT-P_XDOT)*0.5 CALL TRACE_R4_DATA('X',X,21) ENDDO ! : :

The fpt library routines which capture the computed data, for example, TRACE_R4_DATA, have three arguments:

a string, which describes the data computed. This is usually the variable name which may be subscripted;
the value computed;
a unique number which identifies the call-site.

A section of the trace file generated when the code is run is shown below. The first column contains a counter for trace calls and the second contains the trace call-site identifier.

1 1 2 3 3 22 V0 4 23 THETA0 5 24 HDDOT 6 25 XDDOT 7 26 DRAGCOEF 8 27 TIME 9 28 FRAMETIME 10 4 Return: ADINIT 11 5 12 6 Return: ADB 13 7 HDOT 14 8 XDOT 15 5 16 6 Return: ADB 17 9 P_HDDOT 18 10 P_XDDOT 19 11 P_HDOT 20 12 P_XDOT 21 13 TIME 22 14 THETA 23 15 V 24 16 XDDOT 25 17 HDDOT 26 18 HDOT 27 19 XDOT 28 20 H 29 21 X 30 5 31 6 Return: ADB 32 9 P_HDDOT 33 10 P_XDDOT 34 11 P_HDOT 35 12 P_XDOT 36 13 TIME 37 14 THETA 38 15 V 39 16 XDDOT 40 17 HDDOT 41 18 HDOT 42 19 XDOT 43 20 H 44 21 X : : Start sub-program: BALL Start sub-program: ADINIT = 0.400000000000000E+03 = 0.200000000000000E+02 = 0.000000000000000E+00 = 0.000000000000000E+00 = 0.199999994947575E-03 = 0.000000000000000E+00 = 0.100000004749745E-02 Start sub-program: ADB = 0.136808059692383E+03 = 0.375877044677734E+03 Start sub-program: ADB = 0.000000000000000E+00 = 0.000000000000000E+00 = 0.136808059692383E+03 = 0.375877044677734E+03 = 0.100000004749745E-02 = 0.349065870046616E+00 = 0.400000000000000E+03 = -0.300701637268066E+02 = -0.431446456909180E+02 = 0.136743347167969E+03 = 0.375831939697266E+03 = 0.136711001396179E+00 = 0.375809401273727E+00 Start sub-program: ADB = -0.431446456909180E+02 = -0.300701637268066E+02 = 0.136743347167969E+03 = 0.375831939697266E+03 = 0.200000009499490E-02 = 0.348952382802963E+00 = 0.399935485839844E+03 = -0.300617046356201E+02 = -0.431377029418945E+02 = 0.136700210571289E+03 = 0.375801879882812E+03 = 0.273389637470245E+00 = 0.751596271991730E+00

This file is readable, and may be used to trace unexpected program behaviour.

Relative Debugging

The same program may produce significantly different results when it is built with different compilers or even with different levels of optimisation under the same compiler. The differences may be due only to numerical drift. This occurs when different systems choose different orders of execution, or different variables to store in processor registers, with the result that there are small differences in rounding errors. These differences integrate and eventually affect the results. However, the differences may also be due to compiler bugs or to coding errors which behave differently in different environments.

The run-time trace facility may be used to analyse this situation and to separate the effects of numerical drift from those of coding errors and compiler bugs. The procedure is as follows:

The program is instrumented for run-time trace as described above
It is built in the first compilation environment.
The program is run and a trace file is generated. The trace file generated has the default name trace.txt.
The trace file is renamed trace_input.txt.
The program is built in the second compilation environment and is run.

The library routines which support the run-time trace facility detect the presence of the file trace_input.txt. The behaviour then changes. At every call each trace routine reads the next trace record from trace_input.txt. The call-site identification number is checked to confirm that the program has followed the same path as on the first run. If it has not, the run terminates with a report indicating where the two runs diverged. If the trace is of an assignment, the value computed is then checked against the value recorded in the trace file.

If the value is the same, no action is taken.
If the value is different and is integer or logical, the difference is reported.
If the value is different and is real or complex, the difference is compared with two criteria, a relative criterion difference and an absolute criterion difference. If it exceeds both criteria it is reported. Two criteria are used to prevent spurious reports of large relative differences when values are close to zero.
If the values are different, the value computed is overwritten by the value read from the trace file. This prevents the accumulation of small differences and therefore eliminates numerical drift.

The report, which is written to a new file named trace.txt, contains only a record of significant differences between the two runs.

Control of the Comparison

The trace runs, and in particular the comparison run, may be controlled by writing an optional configuration file named trace_controls.txt. The file is placed in the directory in which the program is run. The commands in this file are:

REAL RATIO = <value> - sets the value of the relative criterion difference for real numbers.

REAL DELTA = <value> - sets the value of the absolute criterion difference for real numbers.

[DO NOT] OVERWITE LOGICALS - controls overwriting of logical variables when a difference is detected.

[DO NOT] OVERWRITE INTEGERS - controls overwriting of integer variables when a difference is detected.

TRACE DIRECTORY = <name> - specifies the directory in which the trace file resides.

By default, the relative criterion difference is set to 0.01 (i.e. 1%), the absolute criterion difference is set to 0.0001 and all numeric values are overwritten. The commands (But not the trace directory name) must be written in upper case. Comments in the configuration file are introduced by exclamation marks in column 1.

Note that integer variables are sometimes used to store objects like database and file handles which are intended to vary from run to run, and overwriting these objects is likely to cause problems.

Default

No change is made by default.

Publications and Further Description

This command was used in the analyses described in: