| gfrprt |
|
Table of contents
Procedure
GFRPRT ( GF, progress reporting package )
SUBROUTINE GFRPRT ( WINDOW, BEGMSS, ENDMSS, IVBEG, IVEND, TIME )
Abstract
The entry points contained under this routine provide users
information regarding the status of a GF search in progress.
Required_Reading
GF
Keywords
SEARCH
UTILITY
Declarations
IMPLICIT NONE
INCLUDE 'zzgf.inc'
INTEGER LBCELL
PARAMETER ( LBCELL = -5 )
DOUBLE PRECISION WINDOW ( LBCELL : * )
CHARACTER*(*) BEGMSS
CHARACTER*(*) ENDMSS
DOUBLE PRECISION IVBEG
DOUBLE PRECISION IVEND
DOUBLE PRECISION TIME
Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
LBCELL P The SPICE cell lower bound.
MXBEGM P Maximum progress report message prefix length.
MXENDM P Maximum progress report message suffix length.
WINDOW I A window over which a job is to be performed.
BEGMSS I Beginning of the text portion of the output message
ENDMSS I End of the text portion of the output message
IVBEG I Current confinement window interval start time.
IVEND I Current confinement window interval stop time.
TIME I Input to the reporting routine.
Detailed_Input
See the individual entry points.
Detailed_Output
See the individual entry points.
Parameters
LBCELL is the SPICE cell lower bound.
MXBEGM,
MXENDM are, respectively, the maximum lengths of the progress
report message prefix and suffix.
Exceptions
1) See the individual entry points.
Files
None.
Particulars
This umbrella routine contains default progress reporting entry
points that display a report via console I/O. These routines may
be used by SPICE-based applications as inputs to mid-level GF
search routines. These routines may be useful even when progress
reporting is not desired, since the mid-level search routines
provide some capabilities that aren't supported by the top-level
GF routines.
Developers wishing to use their own GF progress reporting
routines must design them with the same interfaces and should
assign them the same progress reporting roles as the entry points
of these routines.
The entry points contained in this routine are written to
make reporting of work (such as searching for a geometric event)
over a particular window easy. This is an important feature for
interactive programs that may "go away" from the user's control
for a considerable length of time. It allows the user to see that
something is still going on (although maybe not too quickly).
The three entry points contained under this module are:
GFREPI used to set up the reporting mechanism. It lets GFRPRT
know that some task is about to begin that involves
interaction with some window of times. It is used
only to set up and store the constants associated with
the reporting of the job in progress.
GFREPU is used to notify the reporter that work has
progressed to a given point with respect to the start
of the confinement window.
GFREPF is used to "finish" the reporting of work (set the
completion value to 100%.
The progress reporting utilities are called by GF search routines
as follows:
1) Given a window over which some work is to be performed,
CALL GFREPI with the appropriate inputs, to let the routine
know the intervals over which some work is to be done.
2) Each time some "good" amount of work has been done, call
GFREPU so that the total amount of work done can be updated
and can be reported.
3) When work is complete call GFREPF to "clean up" the end of
the progress report.
Examples
The numerical results shown for these examples may differ across
platforms. The results depend on the SPICE kernels used as
input, the compiler and supporting libraries, and the machine
specific arithmetic implementation.
1) This example shows how to call a mid-level GF search API that
requires as input progress reporting routines.
If custom progress reporting routines are available, they
can replace GFREPI, GFREPU, and GFREPF in any GF API calls.
The code example below is the first example in the header of
GFOCCE.
Conduct a search using the default GF progress reporting
capability.
The program will use console I/O to display a simple
ASCII-based progress report.
The program will find occultations of the Sun by the Moon as
seen from the center of the Earth over the month December,
2001.
We use light time corrections to model apparent positions of
Sun and Moon. Stellar aberration corrections are not specified
because they don't affect occultation computations.
Use the meta-kernel shown below to load the required SPICE
kernels.
KPL/MK
File name: gfrprt_ex1.tm
This meta-kernel is intended to support operation of SPICE
example programs. The kernels shown here should not be
assumed to contain adequate or correct versions of data
required by SPICE-based user applications.
In order for an application to use this meta-kernel, the
kernels referenced here must be present in the user's
current working directory.
The names and contents of the kernels referenced
by this meta-kernel are as follows:
File name Contents
--------- --------
de421.bsp Planetary ephemeris
pck00008.tpc Planet orientation and
radii
naif0009.tls Leapseconds
\begindata
KERNELS_TO_LOAD = ( 'de421.bsp',
'pck00008.tpc',
'naif0009.tls' )
\begintext
End of meta-kernel
Example code begins here.
PROGRAM GFRPRT_EX1
IMPLICIT NONE
C
C SPICELIB functions
C
INTEGER WNCARD
C
C SPICELIB default functions for
C
C - Interrupt handling (no-op function): GFBAIL
C - Search refinement: GFREFN
C - Progress report termination: GFREPF
C - Progress report initialization: GFREPI
C - Progress report update: GFREPU
C - Search step size "get" function: GFSTEP
C
LOGICAL GFBAIL
EXTERNAL GFBAIL
EXTERNAL GFREFN
EXTERNAL GFREPI
EXTERNAL GFREPU
EXTERNAL GFREPF
EXTERNAL GFSTEP
C
C Local parameters
C
CHARACTER*(*) TIMFMT
PARAMETER ( TIMFMT =
. 'YYYY MON DD HR:MN:SC.###### ::TDB (TDB)' )
DOUBLE PRECISION CNVTOL
PARAMETER ( CNVTOL = 1.D-6 )
INTEGER MAXWIN
PARAMETER ( MAXWIN = 2 * 100 )
INTEGER TIMLEN
PARAMETER ( TIMLEN = 40 )
INTEGER LBCELL
PARAMETER ( LBCELL = -5 )
C
C Local variables
C
CHARACTER*(TIMLEN) WIN0
CHARACTER*(TIMLEN) WIN1
CHARACTER*(TIMLEN) BEGSTR
CHARACTER*(TIMLEN) ENDSTR
DOUBLE PRECISION CNFINE ( LBCELL : 2 )
DOUBLE PRECISION ET0
DOUBLE PRECISION ET1
DOUBLE PRECISION LEFT
DOUBLE PRECISION RESULT ( LBCELL : MAXWIN )
DOUBLE PRECISION RIGHT
INTEGER I
LOGICAL BAIL
LOGICAL RPT
C
C Saved variables
C
C The confinement and result windows CNFINE and RESULT are
C saved because this practice helps to prevent stack
C overflow.
C
SAVE CNFINE
SAVE RESULT
C
C Load kernels.
C
CALL FURNSH ( 'gfrprt_ex1.tm' )
C
C Initialize the confinement and result windows.
C
CALL SSIZED ( 2, CNFINE )
CALL SSIZED ( MAXWIN, RESULT )
C
C Obtain the TDB time bounds of the confinement
C window, which is a single interval in this case.
C
WIN0 = '2001 DEC 01 00:00:00 TDB'
WIN1 = '2002 JAN 01 00:00:00 TDB'
CALL STR2ET ( WIN0, ET0 )
CALL STR2ET ( WIN1, ET1 )
C
C Insert the time bounds into the confinement
C window.
C
CALL WNINSD ( ET0, ET1, CNFINE )
C
C Select a 20 second step. We'll ignore any occultations
C lasting less than 20 seconds.
C
CALL GFSSTP ( 20.D0 )
C
C Turn on progress reporting; turn off interrupt
C handling.
C
RPT = .TRUE.
BAIL = .FALSE.
C
C Perform the search.
C
CALL GFOCCE ( 'ANY',
. 'MOON', 'ellipsoid', 'IAU_MOON',
. 'SUN', 'ellipsoid', 'IAU_SUN',
. 'LT', 'EARTH', CNVTOL,
. GFSTEP, GFREFN, RPT,
. GFREPI, GFREPU, GFREPF,
. BAIL, GFBAIL, CNFINE, RESULT )
IF ( WNCARD(RESULT) .EQ. 0 ) THEN
WRITE (*,*) 'No occultation was found.'
ELSE
DO I = 1, WNCARD(RESULT)
C
C Fetch and display each occultation interval.
C
CALL WNFETD ( RESULT, I, LEFT, RIGHT )
CALL TIMOUT ( LEFT, TIMFMT, BEGSTR )
CALL TIMOUT ( RIGHT, TIMFMT, ENDSTR )
WRITE (*,*) 'Interval ', I
WRITE (*,*) ' Start time: '//BEGSTR
WRITE (*,*) ' Stop time: '//ENDSTR
END DO
END IF
END
When this program was executed on a Mac/Intel/gfortran/64-bit
platform, the output was:
Occultation/transit search 100.00% done.
Interval 1
Start time: 2001 DEC 14 20:10:14.195952 (TDB)
Stop time: 2001 DEC 14 21:35:50.317994 (TDB)
Note that the progress report has the format shown below:
Occultation/transit search 6.02% done.
The completion percentage was updated approximately once per
second.
2) The following piece of code provides a more concrete example
of how these routines might be used. It is part of code that
performs a search for the time of an occultation of one body
by another. It is intended only for illustration and is not
recommended for use in code that has to do real work.
C
C Prepare the progress reporter if appropriate.
C
IF ( RPT ) THEN
CALL UDREPI ( CNFINE, 'Occultation/transit search ',
. 'done.' )
END IF
C
C Cycle over the intervals in the confining window.
C
COUNT = WNCARD(CNFINE)
DO I = 1, COUNT
C
C Retrieve the bounds for the Ith interval of the
C confinement window. Search this interval for
C occultation events. Union the result with the
C contents of the RESULT window.
C
CALL WNFETD ( CNFINE, I, START, FINISH )
CALL ZZGFSOLV ( ZZGFOCST, UDSTEP, UDREFN, BAIL,
. UDBAIL, CSTEP, STEP, START,
. FINISH, TOL, RPT, UDREPU,
. RESULT )
IF ( FAILED() ) THEN
CALL CHKOUT ( 'GFOCCE' )
RETURN
END IF
IF ( BAIL ) THEN
C
C Interrupt handling is enabled.
C
IF ( UDBAIL () ) THEN
C
C An interrupt has been issued. Return now
C regardless of whether the search has been
C completed.
C
CALL CHKOUT ( 'GFOCCE' )
RETURN
END IF
END IF
END DO
C
C End the progress report.
C
IF ( RPT ) THEN
CALL UDREPF
END IF
3) For more concrete examples of how these routines are used in
SPICELIB, please refer to the actual code of any of the GF API
calls.
Restrictions
None.
Literature_References
None.
Author_and_Institution
N.J. Bachman (JPL)
J. Diaz del Rio (ODC Space)
L.S. Elson (JPL)
B.V. Semenov (JPL)
W.L. Taber (JPL)
I.M. Underwood (JPL)
Version
SPICELIB Version 1.0.2, 27-AUG-2021 (JDR)
Edited the header of all entry points and GFRPRT to comply with
NAIF standard.
Added complete example code to GFRPRT.
SPICELIB Version 1.0.1, 10-FEB-2014 (BVS)
Added declarations of IVBEG and IVEND to the $Declarations
section of the GFREPU header.
Corrected declaration of WINDOW in the $Declarations
section and added descriptions of LBCELL to the GFREPI
header.
SPICELIB Version 1.0.0, 06-MAR-2009 (NJB) (LSE) (WLT) (IMU)
|
Fri Dec 31 18:36:25 2021