fpt and WinFPT Reference Manual - Command-line Commands
| SimCon Home | Ref Manual Home |
INSERT RUN-TIME TRACE and Relative Debugging
[DO NOT] INSERT RUN-TIME TRACE [STATEMENTS]
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.
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:
1 1 Start sub-program: BALL 2 3 Start sub-program: ADINIT 3 22 V0 = 0.400000000000000E+03 4 23 THETA0 = 0.200000000000000E+02 5 24 HDDOT = 0.000000000000000E+00 6 25 XDDOT = 0.000000000000000E+00 7 26 DRAGCOEF = 0.199999994947575E-03 8 27 TIME = 0.000000000000000E+00 9 28 FRAMETIME = 0.100000004749745E-02 10 4 Return: ADINIT 11 5 Start sub-program: ADB 12 6 Return: ADB 13 7 HDOT = 0.136808059692383E+03 14 8 XDOT = 0.375877044677734E+03 15 5 Start sub-program: ADB 16 6 Return: ADB 17 9 P_HDDOT = 0.000000000000000E+00 18 10 P_XDDOT = 0.000000000000000E+00 19 11 P_HDOT = 0.136808059692383E+03 20 12 P_XDOT = 0.375877044677734E+03 21 13 TIME = 0.100000004749745E-02 22 14 THETA = 0.349065870046616E+00 23 15 V = 0.400000000000000E+03 24 16 XDDOT = -0.300701637268066E+02 25 17 HDDOT = -0.431446456909180E+02 26 18 HDOT = 0.136743347167969E+03 27 19 XDOT = 0.375831939697266E+03 28 20 H = 0.136711001396179E+00 29 21 X = 0.375809401273727E+00 30 5 Start sub-program: ADB 31 6 Return: ADB 32 9 P_HDDOT = -0.431446456909180E+02 33 10 P_XDDOT = -0.300701637268066E+02 34 11 P_HDOT = 0.136743347167969E+03 35 12 P_XDOT = 0.375831939697266E+03 36 13 TIME = 0.200000009499490E-02 37 14 THETA = 0.348952382802963E+00 38 15 V = 0.399935485839844E+03 39 16 XDDOT = -0.300617046356201E+02 40 17 HDDOT = -0.431377029418945E+02 41 18 HDOT = 0.136700210571289E+03 42 19 XDOT = 0.375801879882812E+03 43 20 H = 0.273389637470245E+00 44 21 X = 0.751596271991730E+00 : :
This file is readable, and may be used to trace unexpected program behaviour.
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 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.
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.
No change is made by default.
Publications and Further Description
This command was used in the analyses described in:
Copyright ©1995 to 2022 Software Validation Ltd. All rights reserved.