Index Page
gfevnt_c
A  B  C  D  E  F  G  H  I  J  K  L  M  N  O  P  Q  R  S  T  U  V  W  X 

Procedure
Abstract
Required_Reading
Keywords
Brief_I/O
Detailed_Input
Detailed_Output
Parameters
Exceptions
Files
Particulars
Examples
Restrictions
Literature_References
Author_and_Institution
Version
Index_Entries

Procedure

   void gfevnt_c ( void             ( * udstep ) ( SpiceDouble       et,
                                                   SpiceDouble     * step ),

                   void             ( * udrefn ) ( SpiceDouble       t1,
                                                   SpiceDouble       t2,
                                                   SpiceBoolean      s1,
                                                   SpiceBoolean      s2,
                                                   SpiceDouble     * t    ),
                   ConstSpiceChar     * gquant,
                   SpiceInt             qnpars,
                   SpiceInt             lenvals,
                   const void         * qpnams,
                   const void         * qcpars, 
                   ConstSpiceDouble   * qdpars, 
                   ConstSpiceInt      * qipars, 
                   ConstSpiceBoolean  * qlpars,
                   ConstSpiceChar     * op,
                   SpiceDouble          refval,
                   SpiceDouble          tol,
                   SpiceDouble          adjust,
                   SpiceBoolean         rpt,  

                   void             ( * udrepi ) ( SpiceCell       * cnfine,
                                                   ConstSpiceChar  * srcpre,
                                                   ConstSpiceChar  * srcsuf ),

                   void             ( * udrepu ) ( SpiceDouble       ivbeg,
                                                   SpiceDouble       ivend,
                                                   SpiceDouble       et      ),

                   void             ( * udrepf ) ( void ),
                   SpiceInt             nintvls,
                   SpiceBoolean         bail,      
                   SpiceBoolean     ( * udbail ) ( void ),
                   SpiceCell          * cnfine,
                   SpiceCell          * result )

Abstract

 
     Determine time intervals when a specified geometric quantity
     satisfies a specified mathematical condition.
 

Required_Reading

 
   GF 
   WINDOWS   
 

Keywords

 
   EVENT 
   GEOMETRY
   SEARCH 
   WINDOW 
 

Brief_I/O

 
   VARIABLE  I/O  DESCRIPTION
   --------  ---  --------------------------------------------------
   udstep     I   Name of the routine that computes and returns a 
                  time step.
   udrefn     I   Name of the routine that computes a refined time.
   gquant     I   Type of geometric quantity.
   qnpars     I   Number of quantity definition parameters.
   lenvals    I   Length of strings in 'qpnams' and 'qcpars'.
   qpnams     I   Names of quantity definition parameters.
   qcpars     I   Array of character quantity definition parameters.
   qdpars     I   Array of double precision quantity definition 
                  parameters.
   qipars     I   Array of integer quantity definition parameters.
   qlpars     I   Array of logical quantity definition parameters.
   op         I   Operator that either looks for an extreme value
                  (max, min, local, absolute) or compares the
                  geometric quantity value and a number.
   refval     I   Reference value.
   tol        I   Convergence tolerance in seconds
   adjust     I   Absolute extremum adjustment value.
   rpt        I   Progress reporter on (.TRUE.) or off (.FALSE.)
   udrepi     I   Function that initializes progress reporting.
   udrepu     I   Function that updates the progress report.
   udrepf     I   Function that finalizes progress reporting.
   nintvls    I   Workspace window interval count
   bail       I   Logical indicating program interrupt monitoring.
   udbail     I   Name of a routine that signals a program interrupt.
   cnfine    I-O  SPICE window to which the search is restricted.
   result     O   SPICE window containing results.
 

Detailed_Input

 
   udstep     is an externally specified routine that computes a 
              time step in an attempt to find a transition of the 
              state being considered. In the context of this 
              routine's algorithm, a "state transition" occurs where 
              the geometric state changes from being in the desired
              geometric condition event to not, or vice versa. 
          
              This routine relies on `udstep' returning step sizes 
              small enough so that state transitions within the 
              confinement window are not overlooked.  There must 
              never be two roots A and B separated by less than 
              `step', where `step' is the minimum step size returned by 
              `udstep' for any value of `et; in the interval [A, B]. 
  
              The prototype for `udstep' is
 
                 void   ( * udstep ) ( SpiceDouble       et,
                                       SpiceDouble     * step )

              where: 
 
                 et      is the input start time from which the 
                         algorithm is to search forward for a state 
                         transition. `et' is expressed as seconds past 
                         J2000 TDB.  
 
                 step    is the output step size.  `step' indicates 
                         how far to advance `et' so that `et' and 
                         et+step may bracket a state transition and 
                         definitely do not bracket more than one 
                         state transition. Units are TDB seconds. 
 
              If a constant step size is desired, the CSPICE routine 

                 gfstep_c 
 
              may be used as the step size function. If gfstep_c is
              used, the step size must be set by calling 
              
                 gfsstp_c 
              
              prior to calling this routine.
 
 
   udrefn     is the name of the externally specified routine that 
              computes a refinement in the times that bracket a 
              transition point. In other words, once a pair of 
              times have been detected such that the system is in 
              different states at each of the two times, `udrefn' 
              selects an intermediate time which should be closer to 
              the transition state than one of the two known times. 
              The prototype for `udrefn' is: 
 
                 void   ( * udrefn ) ( SpiceDouble       t1,
                                       SpiceDouble       t2,
                                       SpiceBoolean      s1,
                                       SpiceBoolean      s2,
                                       SpiceDouble     * t   )
 
              where the inputs are: 
 
                 t1    is a time when the system is in state `s1'. `t1'
                       is expressed as seconds past J2000 TDB.
 
                 t2    is a time when the system is in state `s2'. `t2'
                       is expressed as seconds past J2000 TDB. `t2' is
                       assumed to be larger than `t1'.
 
                 s1    is the state of the system at time t1.

                 s2    is the state of the system at time t2.

                udrefn may use or ignore the S1 and S2 values.
  
              The output is: 
 
                 t     is next time to check for a state transition.
                       `t' has value between `t1' and `t2'. `t' is
                       expressed as seconds past J2000 TDB.
 
              If a simple bisection method is desired, the CSPICE routine 
              gfrefn_c may be used as the refinement function.


   gquant     is a string containing the name of a geometric 
              quantity.  The times when this quantity satisfies
              a condition specified by the arguments OP
              and ADJUST (described below) are to be found.

              Each quantity is specified by the quantity name
              given in argument 'gquant', and by a set of parameters
              specified by the arguments 
               
                 qnpars
                 qpnams
                 qcpars
                 qdpars
                 qipars
                 qlpars

              For each quantity listed here, we also show how to
              set up these input arguments to define the quantity.
              See the detailed discussion of these arguments
              below for further information.
              
              'gquant' may be any of the strings: 

                 "COORDINATE"
                 "DISTANCE"
                 "ANGULAR SEPARATION"

              'gquant' strings are case insensitive.  Values,
              meanings, and associated parameters are discussed 
              below.                

              COORDINATE  is a coordinate of a specified vector in 
                          a specified reference frame and coordinate
                          system.  For example, a coordinate can
                          be the Z component of the earth-sun vector
                          in the J2000 reference frame, or the
                          latitude of the nearest point on Mars to
                          an orbiting spacecraft, expressed relative
                          to the IAU_MARS reference frame.

                          The method by which the vector is defined
                          is indicated by the
 
                             "VECTOR DEFINITION" 

                          parameter.  Allowed values and meanings of
                          this parameter are:

                             "POSITION"

                                 The vector is defined by the 
                                 position of a target relative to 
                                 an observer.

                             "SUB-OBSERVER POINT"

                                 The vector is the sub-observer point
                                 on a specified target body.

                             "SURFACE INTERCEPT POINT"

                                 The vector is defined as the 
                                 intercept point of a vector from the
                                 observer to the target body.

                          Some vector definitions, such as the
                          sub-observer point may be specified by a
                          variety of methods, so a parameter is
                          provided to select the computation method.
                          The computation method parameter name is

                             "METHOD"

                          If the vector definition is 
                          
                             "POSITION"
                          
                          the METHOD parameter should be set to
                          blank:

                             " " 

                          If the vector definition is 

                             "SUB-OBSERVER POINT"

                          the METHOD parameter should be set to 
                          either:

                             "Near point: ellipsoid"
                             "Intercept: ellipsoid"
                             
                          If the vector definition is
                           
                             "SURFACE INTERCEPT POINT"

                          the METHOD parameter should be set to:

                             "Ellipsoid"
                             
                                The intercept computation uses
                                a triaxial ellipsoid to model
                                the surface of the target body.
                                The ellipsoid's radii must be
                                available in the kernel pool.

             The supported coordinate systems and coordinate names:

             Coordinate System       Coordinates        Range

             "RECTANGULAR"           "X"
                                     "Y"
                                     "Z"

             "LATITUDINAL"           "RADIUS"
                                     "LONGITUDE"        (-Pi,Pi]
                                     "LATITUDE"         [-Pi/2,Pi/2]

             "RA/DEC"                "RANGE"
                                     "RIGHT ASCENSION"  [0,2Pi)
                                     "DECLINATION"      [-Pi/2,Pi/2]

             "SPHERICAL"             "RADIUS"
                                     "COLATITUDE"       [0,Pi]
                                     "LONGITUDE"        (-Pi,Pi]

             "CYLINDRICAL"           "RADIUS"
                                     "LONGITUDE"        [0,2Pi)
                                     "Z"

             "GEODETIC"              "LONGITUDE"        (-Pi,Pi]
                                     "LATITUDE"         [-Pi/2,Pi/2]
                                     "ALTITUDE" 

             "PLANETOGRAPHIC"        "LONGITUDE"        [0,2Pi)
                                     "LATITUDE"         [-Pi/2,Pi/2]
                                     "ALTITUDE"


                          When geodetic coordinates are selected,
                          the radii used are those of the central
                          body associated with the reference frame.
                          For example, if IAU_MARS is the reference
                          frame, then geodetic coordinates defined
                          using the radii of Mars.  One cannot ask
                          for geodetic coordinates for a frame which
                          doesn't have an extended body as its 
                          center.
                          
                          Reference frame names must be recognized
                          by the SPICE frame subsystem.

                          Quantity Parameters:

                             qnpars = 10

                             SpiceChar qpnams[SPICE_GFEVNT_MAXPAR][LNSIZE] = 
                                                    { "TARGET",
                                                      "OBSERVER",
                                                      "ABCORR",
                                                      "COORDINATE SYSTEM",
                                                      "COORDINATE",
                                                      "REFERENCE FRAME",
                                                      "VECTOR DEFINITION",
                                                      "METHOD",
                                                      "DREF",
                                                      "DVEC" };

                          Only "SUB-OBSERVER POINT" searches make 
                          use of the "DREF" and "DVEC" parameters.

                          Only "SUB-OBSERVER POINT" searches make 
                          use of the "DREF" and "DVEC" parameters.

                             SpiceChar qcpars[SPICE_GFEVNT_MAXPAR][LNSIZE] = 
                                               { <name of first target>,
                                                 <name of observer>,
                                                 <aberration correction> ,
                                                 <coordinate system name>,
                                                 <coordinate name>,
                                                 <reference frame name>,
                                                 <vector definition>,
                                                 <computation method>,
                                                 <reference frame of DVEC> };
                             
                             qdpars[0] = <pointing vector x from observer>
                             qdpars[1] = <pointing vector y from observer>
                             qdpars[2] = <pointing vector x from observer>


              DISTANCE    is the apparent distance between a target
                          body and an observing body. Distances are 
                          always measured between centers of mass.

                          Quantity Parameters:

                             QNPARS    = 3

                             SpiceChar qpnams[SPICE_GFEVNT_MAXPAR][LNSIZE] = 
                                                     { "TARGET",
                                                       "OBSERVER",
                                                       "ABCORR" };

                             SpiceChar qcpars[MAXPAR][LNSIZE] = 
                                               { <name of target>,
                                                 <name of observer>,
                                                 <aberration correction> };


              ANGULAR SEPARATION  is the apparent angular separation of 
                                  two target bodies as seen from an observing
                                  body.

                          Quantity Parameters:

                             qnpars    = 8

                             SpiceChar qpnams[SPICE_GFEVNT_MAXPAR][LNSIZE] = 
                                                    { "TARGET1",
                                                      "FRAME1",
                                                      "SHAPE1",
                                                      "TARGET2",
                                                      "FRAME2",
                                                      "SHAPE2",
                                                      "OBSERVER",
                                                      "ABCORR" };

                             SpiceChar qcpars[SPICE_GFEVNT_MAXPAR][LNSIZE] = 
                                               { <name of first target>,
                                                 <name of body-fixed frame 
                                                          of first target>,
                                                 <shape of first target>,
                                                 <name of second target>,
                                                 <name of body-fixed frame 
                                                        of second target>,
                                                 <shape of second target>,
                                                 <name of observer>,
                                                 <aberration correction> }; 

                          The target shape model specifiers may be
                          set to either of the values

                             "POINT"
                             "SPHERE"

                          The shape models for the two bodies need
                          not match.

                          Spherical models have radii equal to the
                          longest equatorial radius of the
                          PCK-based, tri-axial ellipsoids used to
                          model the respective bodies. When both
                          target bodies are modeled as spheres, the
                          angular separation between the bodies is
                          the angle between the closest points on
                          the limbs of the spheres, as viewed from
                          the vantage point of the observer. If the
                          limbs overlap, the angular separation is 
                          negative.

                          (In this case, the angular separation is
                          the angle between the centers of the 
                          spheres minus the sum of the apparent
                          angular radii of the spheres.)
 
              A note on aberration correction parameters:  the 
              aberration correction parameter indicates the
              aberration corrections to be applied to the state of
              the target body to account for one-way light time and
              stellar aberration. If relevant, it applies to the
              rotation of the target body as well.

              Supported aberration correction options for
              observation (case where radiation is received by
              observer at ET) are:

                "NONE"          No correction.
                "LT"            Light time only.
                "LT+S"          Light time and stellar aberration.
                "CN"            Converged Newtonian (CN) light time.
                "CN+S"          CN light time and stellar aberration.

              Supported aberration correction options for
              transmission (case where radiation is emitted from
              observer at ET) are:

                "XLT"           Light time only.
                "XLT+S"         Light time and stellar aberration.
                "XCN"           Converged Newtonian (CN) light time.
                "XCN+S"         CN light time and stellar aberration.

              For detailed information, see the geometry finder
              required reading, gf.req. 

              Case, leading and trailing blanks are not significant
              in aberration correction parameter strings.


   qnpars     is the count of quantity parameter definition 
              parameters.  These parameters supply the quantity-
              specific information needed to fully define the 
              quantity used in the search performed by this routine.


   lenvals    the length of the string in arrays 'qpnames' and 'qcpars', 
              including the null terminators. 
   
   
   qpnams     is an array of names of quantity definition parameters.
              The names occupy elements 0:QNPARS-1 of this array.
              The value associated with the Ith element of QPNAMS
              is located in element I of the parameter value argument
              having data type appropriate for the parameter:  

                 Data Type                      Argument
                 ---------                      --------
                 Character strings              qcpars
                 Double precision numbers       qdpars
                 Integers                       qipars
                 Logicals                       qlpars

              The order in which the parameter names are listed
              is unimportant, as long as the corresponding 
              parameter values are listed in the same order.

              The names in 'qpnams' are case-insensitive. 

              See the description of the input argument 'gquant' 
              for a discussion of the parameter names and values
              associated with a given quantity.


   qcpars,
   qdpars,
   qipars,
   qlpars     are, respectively, parameter arrays of types
              
                   const void         * qcpars, 
                   ConstSpiceDouble   * qdpars, 
                   ConstSpiceInt      * qipars, 
                   ConstSpiceBoolean  * qlpars,

              The value associated with the Ith name in the array
              'qpnams'' resides in the Ith element of whichever of 
              these arrays has the appropriate data type.

              All of these arrays should be declared with dimension
              at least 'qnpars'. 'qcpars' should have the same dimension 
              and shape as 'qpnams'

              The names in the array 'qcpars' are case-insensitive. 

              Note that there is no required order for 'qpnams'/'q*pars'
              pairs.

              See the description of the input argument 'gquant'
              for a discussion of the parameter names and values
              associated with a given quantity.
              

   op         is a scalar string comparison operator indicating the numeric
              constraint of interest. Values are:

                 '>'   value of geometric quantity greater than some
                       reference (REFVAL).

                 '='   value of geometric quantity equal to some
                       reference (REFVAL).

                 '<'   value of geometric quantity less than some
                       reference (REFVAL).

                 'ABSMAX'  The geometric quantity is at an absolute
                           maximum.

                 'ABSMIN'  The geometric quantity is at an absolute
                           minimum.

                 'LOCMAX'  The geometric quantity is at a local 
                           maximum.

                 'LOCMIN'  The geometric quantity is at a local 
                           minimum.

              The caller may indicate that the region of interest
              is the set of time intervals where the quantity is
              within a specified distance of an absolute extremum.
              The argument 'adjust' (described below) is used to
              specified this distance.

              Local extrema are considered to exist only in the
              interiors of the intervals comprising the confinement
              window:  a local extremum cannot exist at a boundary
              point of the confinement window.

              Case is not significant in the string 'op'.


  refval      is the reference value used to define an equality or
              inequality to be satisfied by the geometric quantity.
              The units of 'refval' are radians, radians/sec, km, or 
              km/sec as appropriate.


   tol        is a tolerance value used to determine convergence of
              root-finding operations. 'tol' is measured in ephemeris
              seconds and must be greater than zero.


   adjust     the amount by which the quantity is allowed to vary
              from an absolute extremum.
              
              If the search is for an absolute minimum is performed, 
              the resulting window contains time intervals when the 
              geometric quantity 'gquant' has values between 
              ABSMIN and ABSMIN + 'adjust'.

              If the search is for an absolute maximum, the
              corresponding range is  between ABSMAX - 'adjust' and
              ABSMAX.

              'adjust' is not used for searches for local extrema,
              equality or inequality conditions and must have value
              zero for such searches. 'adjust' must not be
              negative.


   rpt        is a logical variable which controls whether 
              progress reporting is enabled. When `rpt' is SPICETRUE, 
              progress reporting is enabled and the routines 
              udrepi, udrepu, and udpref (see descriptions below) 
              are used to report progress.  
  
 
   udrepi     is a user-defined subroutine that initializes a 
              progress report.  When progress reporting is  
              enabled, `udrepi' is called at the start 
              of a search. The prototype for `udrepi' is

                 void   ( * udrepi ) ( SpiceCell       * cnfine,
                                       ConstSpiceChar  * srcpre,
                                       ConstSpiceChar  * srcsuf )
 
              where 
 
                 cnfine  
 
              is a confinement window specifying the time period
              over which a search is conducted, and
  
                 srcpre 
                 srcsuf 
 
              are prefix and suffix strings used in the progress 
              report: these strings are intended to bracket a  
              representation of the fraction of work done. For
              example, when the CSPICE progress reporting functions
              are used, if srcpre and srcsuf are, respectively,

                 "Occultation/transit search"
                 "done."
 
              the progress report display at the end of
              the search will be:

                 Occultation/transit search 100.00% done.

              If the user doesn't wish to provide a custom set of
              progress reporting functions, the CSPICE routine

                 gfrepi_c

              may be used.  
 
             
   udrepu     is a user-defined subroutine that updates the  
              progress report for a search.  The prototype
              of `udrepu' is 
  
                 void   ( * udrepu ) ( SpiceDouble       ivbeg,
                                       SpiceDouble       ivend,
                                       SpiceDouble       et      )
 
              where `et' is an epoch belonging to the confinement 
              window, `ivbeg' and `ivend' are the start and stop times, 
              respectively of the current confinement window 
              interval.  The ratio of the measure of the portion 
              of `cnfine' that precedes `et' to the measure of `cnfine' 
              would be a logical candidate for the searches 
              completion percentage; however the method of 
              measurement is up to the user. 
 
              If the user doesn't wish to provide a custom set of
              progress reporting functions, the CSPICE routine

                 gfrepu_c

              may be used.           
 
 
   udrepf     is a user-defined subroutine that finalizes a 
              progress report. `udrepf' has no arguments. 
 
              If the user doesn't wish to provide a custom set of
              progress reporting functions, the CSPICE routine

                 gfrepf_c

              may be used.   


   nintvls    an integer value specifying the number of intervals in the 
              the internal workspace array used by this routine. 'nintvls'
              should be at least as large as the number of intervals
              within the search region on which the specified geometric
              event function is monotone increasing or decreasing. 
              It does no harm to pick a value of 'nintvls' larger than the
              minimum required to execute the specified search, but if chosen 
              too small, the search will fail.


   bail       is a logical variable indicating whether or not 
              interrupt handling is enabled. When `bail' is 
              set to SPICETRUE, the input function `udbail' (see 
              description below) is used to determine whether 
              an interrupt has been issued. 
 

   udbail     is the name of a user defined logical function that 
              indicates whether an interrupt signal has been  
              issued (for example, from the keyboard). udbail
              has the prototype

                 SpiceBoolean   ( * udbail ) ( void )

              The return value is SPICETRUE if an interrupt has 
              been issued; otherwise the value is SPICEFALSE.

              gfevnt_c uses `udbail' only when `bail' (see above) is set 
              to SPICETRUE, indicating that interrupt handling is 
              enabled. When interrupt handling is enabled, gfevnt_c 
              and routines in its call tree will call `udbail' to 
              determine whether to terminate processing and return 
              immediately.                

              If the user doesn't wish to provide a custom interrupt
              handling function, the CSPICE routine

                 gfbail_c

              may be used.   

              The function `udbail' will be usually be tested
              multiple times by the GF system between the time
              an interrupt is issued and the time when 
              control is returned to the calling program, so
              `udbail' must continue to return SPICETRUE
              until explicitly reset by the calling application.
              So `udbail' must provide a "reset" mechanism."
              In the case of gfbail_c, the reset function is
              
                 gfclrh_c              

              If interrupt handing is not enabled, a logical 
              function must still be passed as an input argument.
              The CSPICE function  
 
                 gfbail_c 
       
              may be used for this purpose. 
 
              See the Examples header section below for a complete code
              example demonstrating use of the CSPICE interrupt
              handling capability.


   cnfine     is a SPICE window that confines the time period over 
              which the specified search is conducted. `cnfine' may 
              consist of a single interval or a collection of  
              intervals.  
 
              In some cases the confinement window can be used to 
              greatly reduce the time period that must be searched 
              for the desired solution. See the Particulars section 
              below for further discussion. 
               
              See the Examples section below for a code example  
              that shows how to create a confinement window. 

Detailed_Output

 
   cnfine     is the input confinement window, updated if necessary
              so the control area of its data array indicates the
              window's size and cardinality. The window data are
              unchanged.


   result     is a SPICE window representing the set of time 
              intervals, within the confinement period, when the 
              specified geometric event occurs. 
 
              If `result' is non-empty on input, its contents 
              will be discarded before gfevnt_c conducts its 
              search. 
 

Parameters

 
   None.
 

Exceptions

 
 
   1)  There are varying requirements on how distinct the three
       objects, QCPARS, must be. If the requirements are not met,
       the error, SPICE(BODIESNOTDISTINCT) will signal from 
       this routine.

       When 'gquant' has value "ANGULAR SEPARATION" then all three must 
       be distinct.

       When 'gquant' has value "DISTANCE" or "COORDINATE" then

          The 'qcpas[0]' and 'qcpas[1]' objects must be distinct.

   2)  If any of the bodies involved do not have NAIF ID codes, the
       error SPICE(IDCODENOTFOUND) will signal from this routine.

   3)  If the value of 'gquant' is not recognized as a valid value,
       the error SPICE(NOTRECOGNIZED) will signal from this routine.

   4)  If the number of quantity definition parameters, QNPARS is
       greater than the maximum allowed value, MAXPAR, the error
       SPICE(INVALIDCOUNT) will signal from this routine.

   5)  If the proper required parameters, 'qpars', are not supplied,
       the error SPICE(MISSINGVALUE) will signal from this routine.

   6)  If the comparison operator, 'op', is not recognized, the error
       SPICE(NOTRECOGNIZED) will signal from this routine.

   7)  If the sizes of the workspace windows are too small, 
       the error SPICE(ARRAYTOOSMALL) will signal from routines
       called by this routine. 

   8)  If 'tol' is not greater than zero, the error
       SPICE(VALUEOUTOFRANGE) will signal from routines called by
       this routine.

   9)  If 'adjust' is negative, the error SPICE(VALUEOUTOFRANGE) will
       signal from routines called by this routine. A non-zero 
       value for 'adjust' when 'op' has any value other than 
       "ABSMIN" or "ABSMAX" causes routines called by this
       routine to signal the error SPICE(INVALIDVALUE).

  10)  The user must take care when searching for an extremum
       ("ABSMAX", "ABSMIN", "LOCMAX", "LOCMIN") of an angular quantity.
       Problems are most common when using the "COORDINATE" value of
       'gquant' with "LONGITUDE" or "RIGHT ASCENSION" values for the
       coordinate name. Since these quantities are cyclical, rather
       than monotonically increasing or decreasing, an extremum may
       be hard to interpret. In particular, if an extremum is found
       near the cycle boundary (-PI for longitude, 2 PI for
       "RIGHT ASCENSION") it may not be numerically reasonable. For
       example, the search for times when a longitude coordinate is
       at its absolute maximum may result in a time when the
       longitude value is -PI, due to roundoff error.

   11) If the required amount of workspace memory cannot be
       allocated, the error SPICE(MALLOCFAILURE) will signal
       from this routine.

   12) If any attempt to change the handler for the interrupt 
       signal SIGINT fails, the error SPICE(SIGNALFAILURE) is
       signaled.

   13) If operation of this routine is interrupted, the output result
       window will be invalid.

Files

   Appropriate kernels must be loaded by the
   calling program before this routine is called.

   The following data are required: 

      - SPK data: the calling application must load ephemeris data
        for the target, source and observer that cover the time
        period specified by the window `cnfine'. If aberration
        corrections are used, the states of target and observer
        relative to the solar system barycenter must be calculable
        from the available ephemeris data. Typically ephemeris data
        are made available by loading one or more SPK files via
        furnsh_c.

      - PCK data: bodies modeled as triaxial ellipsoids must have
        semi-axis lengths provided by variables in the kernel pool.
        Typically these data are made available by loading a text
        PCK file via furnsh_c.

   In all cases, kernel data are normally loaded once per program
   run, NOT every time this routine is called.

Particulars

   This routine provides the SPICE GF subsystem's general interface
   to determine time intervals when the value of some geometric 
   quantity related to one or more objects and an observer
   satisfies a user specified constraint. It puts these times in a
   result window called 'result'. It does this by first finding
   windows when the quantity of interest is either monotonically
   increasing or decreasing. These windows are then manipulated to 
   give the final result.

   Applications that require do not require support for progress 
   reporting, interrupt handling, non-default step or refinement 
   functions, or non-default convergence tolerance normally should 
   call gfsep_c, gfdist_c, gfposc_c, gfsubc_c, or gfsntc_c rather than 
   this routine.


   The Search Process
   ==================

   Regardless of the type of constraint selected by the caller, this
   routine starts the search for solutions by determining the time
   periods, within the confinement window, over which the specified
   geometric quantity function is monotone increasing and monotone
   decreasing. Each of these time periods is represented by a SPICE
   window. Having found these windows, all of the quantity
   function's local extrema within the confinement window are known.
   Absolute extrema then can be found very easily. 

   Within any interval of these "monotone" windows, there will be at
   most one solution of any equality constraint. Since the boundary
   of the solution set for any inequality constraint is the set 
   of points where an equality constraint is met, the solutions of
   both equality and inequality constraints can be found easily
   once the monotone windows have been found.
   

   Step Size
   =========

   The monotone windows (described above) are found using a two-step
   search process. Each interval of the confinement window is
   searched as follows: first, the input step size is used to
   determine the time separation at which the sign of the rate of
   change of quantity function will be sampled. Starting at
   the left endpoint of an interval, samples will be taken at each
   step. If a change of sign is found, a root has been bracketed; at
   that point, the time at which the time derivative of the quantity 
   function is zero can be found by a refinement process, for example,
   using a binary search.

   Note that the optimal choice of step size depends on the lengths
   of the intervals over which the quantity function is monotone:
   the step size should be shorter than the shortest of these
   intervals (within the confinement window).

   The optimal step size is *not* necessarily related to the lengths
   of the intervals comprising the result window. For example, if
   the shortest monotone interval has length 10 days, and if the
   shortest result window interval has length 5 minutes, a step size
   of 9.9 days is still adequate to find all of the intervals in the
   result window. In situations like this, the technique of using
   monotone windows yields a dramatic efficiency improvement over a
   state-based search that simply tests at each step whether the
   specified constraint is satisfied. The latter type of search can
   miss solution intervals if the step size is shorter than the
   shortest solution interval.
 
   Having some knowledge of the relative geometry of the targets and 
   observer can be a valuable aid in picking a reasonable step size. 
   In general, the user can compensate for lack of such knowledge by 
   picking a very short step size; the cost is increased computation 
   time. 
 
   Note that the step size is not related to the precision with which 
   the endpoints of the intervals of the result window are computed. 
   That precision level is controlled by the convergence tolerance. 


   Convergence Tolerance
   =====================
 
   Once a root has been bracketed, a refinement process is used to 
   narrow down the time interval within which the root must lie. 
   This refinement process terminates when the location of the root 
   has been determined to within an error margin called the 
   "convergence tolerance," passed to this routine as 'tol'. 
  
   The GF subsystem defines a parameter, SPICE_GF_CNVTOL (from SpiceGF.h), 
   as a default tolerance. This represents a "tight" tolerance value 
   so that the tolerance doesn't become the limiting factor in the 
   accuracy of solutions found by this routine. In general the accuracy 
   of input data will be the limiting factor. 
 
   Making the tolerance tighter than SPICE_GF_CNVTOL is unlikely to 
   be useful, since the results are unlikely to be more accurate. 
   Making the tolerance looser will speed up searches somewhat, 
   since a few convergence steps will be omitted. However, in most 
   cases, the step size is likely to have a much greater affect 
   on processing time than would the convergence tolerance.


   The Confinement Window 
   ====================== 
 
   The simplest use of the confinement window is to specify a time 
   interval within which a solution is sought. However, the 
   confinement window can, in some cases, be used to make searches 
   more efficient. Sometimes it's possible to do an efficient search 
   to reduce the size of the time period over which a relatively 
   slow search of interest must be performed. 

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. 

   Conduct a DISTANCE 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 local maximums of the distance from earth to
   Moon with light time and stellar aberration corrections to model 
   the apparent positions of the Moon.

   Use the meta-kernel shown below to load the required SPICE
   kernels.

      KPL/MK

      File name: standard.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.


      \begindata

         KERNELS_TO_LOAD = ( 'de414.bsp',
                             'pck00008.tpc',
                             'naif0009.tls'  )

      \begintext

   Code:

      #include "SpiceUsr.h"
      #include "SpiceGF.h"
      #include <stdio.h>
      #include <signal.h>

      int main()
         {

         /.
         Constants
         ./
         #define  TIMFMT  "YYYY-MON-DD HR:MN:SC.###### (TDB) ::TDB ::RND"
         #define  MAXVAL  10000
         #define  STRSIZ  41
         #define  LNSIZE  81
         #define  MAXPAR  10

         /.
         Local variables 
         ./
         SpiceBoolean            bail;
         SpiceBoolean            rpt;

         /.
         Confining window beginning and ending time strings.
         ./
         SpiceChar               begstr [LNSIZE] = "2001 jan 01 00:00:00.000";
         SpiceChar               endstr [LNSIZE] = "2001 dec 31 00:00:00.000";
         SpiceChar               event  []       = "DISTANCE";
         SpiceChar               relate []       = "LOCMAX";

         
         /.
         Declare qpnams and qcpars with the same dimensions.
         SPICE_GFEVNT_MAXPAR defined in SpiceGF.h.
         ./
         SpiceChar  qpnams[SPICE_GFEVNT_MAXPAR][LNSIZE] = { "TARGET",
                                                            "OBSERVER",
                                                            "ABCORR" };

         SpiceChar  qcpars[SPICE_GFEVNT_MAXPAR][LNSIZE] = { "MOON", 
                                                            "EARTH", 
                                                            "LT+S"  };

         SpiceDouble             qdpars[SPICE_GFEVNT_MAXPAR];
         SpiceInt                qipars[SPICE_GFEVNT_MAXPAR];
         SpiceBoolean            qlpars[SPICE_GFEVNT_MAXPAR];
 

         SPICEDOUBLE_CELL      ( cnfine, MAXVAL );
         SPICEDOUBLE_CELL      ( result, MAXVAL );

         SpiceDouble             begtim;
         SpiceDouble             endtim;
         SpiceDouble             step;
         SpiceDouble             refval;
         SpiceDouble             adjust;
         SpiceDouble             tol;
         SpiceDouble             beg;
         SpiceDouble             end;


         SpiceInt                lenvals;
         SpiceInt                nintvls;
         SpiceInt                count;
         SpiceInt                qnpars;
         SpiceInt                i;


         /.
         Load leapsecond and spk kernels. The name of the 
         meta kernel file shown here is fictitious; you 
         must supply the name of a file available 
         on your own computer system.
         ./
         furnsh_c ( "standard.tm" );

         /.
         Set a beginning and end time for confining window.
         ./

         str2et_c ( begstr, &begtim );
         str2et_c ( endstr, &endtim );


         /.
         Add 2 points to the confinement interval window.
         ./
         wninsd_c ( begtim, endtim, &cnfine );


         /.
         Check the number of intervals in confining window.
         ./
         count = wncard_c( &cnfine );
         printf( "Found %d intervals in cnfine\n", (int)count );

      
         /.
         Set the step size to 1/1000 day and convert to seconds.
         One day would be a reasonable stepsize for this
         search, but the run would not last long enough to issue
         an interrupt.
         ./
         step = 0.001 * spd_c();
         gfsstp_c ( step );


         /.
         Set interrupt handling and progress reporting.
         ./
         bail = SPICETRUE;
         rpt  = SPICETRUE;
            
         lenvals= LNSIZE;
         qnpars = 3;
         tol    = SPICE_GF_CNVTOL;
         refval = 0.;
         adjust = 0.;
         nintvls= MAXVAL;

         /.
         Perform the search.
         ./
         gfevnt_c ( gfstep_c,
                    gfrefn_c,
                    event,
                    qnpars,
                    lenvals,
                    qpnams,
                    qcpars,
                    qdpars,
                    qipars,
                    qlpars,
                    relate,
                    refval,
                    tol,
                    adjust,
                    rpt,
                    &gfrepi_c,
                    gfrepu_c,
                    gfrepf_c,
                    nintvls,
                    bail,
                    gfbail_c,
                    &cnfine,
                    &result );

         if ( gfbail_c() ) 
            {
            /.
            Clear the CSPICE interrupt indication. This is
            an essential step for programs that continue
            running after an interrupt; gfbail_c will
            continue to return SPICETRUE until this step
            has been performed.
            ./
            gfclrh_c();


            /.
            We've trapped an interrupt signal. In a realistic
            application, the program would continue operation
            from this point. In this simple example, we simply
            display a message and quit.
            ./
            printf ( "\nSearch was interrupted.\n\nThis message "
                     "was written after an interrupt signal\n"
                     "was trapped. By default, the program "
                     "would have terminated \nbefore this message "
                     "could be written.\n\n"                       );
            }
         else
            {
            count = wncard_c( &result);
            printf( "Found %d intervals in result\n", (int)count );

            /.
            List the beginning and ending points in each interval.
            ./
            for( i=0; i<count; i++ )
               {
               wnfetd_c( &result, i, &beg, &end );
        
               timout_c ( beg, TIMFMT, LNSIZE, begstr );
               timout_c ( end, TIMFMT, LNSIZE, endstr );

               printf( "Interval %d\n", (int)i );
               printf( "Beginning TDB %s\n", begstr );
               printf( "Ending TDB    %s\n", endstr );
               }

            }

         return ( 0 );
         }

   The program compiled on OS X with gcc: 

      The run output; the progress report had the format shown below:

         Distance pass 1 of 3  49.60% done.  

         Interval 0
         Beginning TDB 2001-JAN-24 19:22:01.436672 (TDB)
         Ending TDB    2001-JAN-24 19:22:01.436672 (TDB)
         
         Interval 1
         Beginning TDB 2001-FEB-20 21:52:07.914964 (TDB)
         Ending TDB    2001-FEB-20 21:52:07.914964 (TDB)

                           ...

         Interval 11
         Beginning TDB 2001-NOV-23 15:45:23.027511 (TDB)
         Ending TDB    2001-NOV-23 15:45:23.027511 (TDB)
         
         Interval 12
         Beginning TDB 2001-DEC-21 13:04:47.124241 (TDB)
         Ending TDB    2001-DEC-21 13:04:47.124241 (TDB)


      When the program was interrupted at an arbitrary time, 
      the output was:

         Distance pass 1 of 3  26.74% done.      
         Search was interrupted.

         This message was written after an interrupt signal
         was trapped. By default, the program would have terminated 
         before this message could be written.

Restrictions

   1) The kernel files to be used by gfevnt_c must be loaded (normally
      via the CSPICE routine furnsh_c) before calling gfevnt_c.

   2) If using the default, constant step size routine, gfstep_c, the
      the caller must set the step size by calling the entry point 
      gfsstp_c before calling gfevnt_c. The call syntax for gfsstp_c:

         gfsstp_c ( step );

Literature_References

   None.

Author_and_Institution

   N.J. Bachman   (JPL)
   L.S. Elson     (JPL)
   W.L. Taber     (JPL)
   I.M. Underwood (JPL)
   E.D. Wright    (JPL)
 

Version

   -CSPICE Version 1.0.2, 12-JUL-2016 (EDW)

      Edit to example program to use "%d" with explicit casts
      to int for printing SpiceInts with printf.

   -CSPICE Version 1.0.1, 24-APR-2010 (EDW)

      Minor edit to code comments eliminating typo.

   -CSPICE Version 1.0.0, 11-MAR-2009 (EDW) 

Index_Entries

 
   determine when a geometric quantity satisfies a condition
Wed Apr  5 17:54:35 2017