gfevnt_c |

Table of contents## Proceduregfevnt_c (GF, geometric event finder ) 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 ) ## AbstractDetermine time intervals when a specified geometric quantity satisfies a specified mathematical condition. ## Required_ReadingGF WINDOWS ## KeywordsEVENT GEOMETRY SEARCH WINDOW ## Brief_I/OVARIABLE I/O DESCRIPTION -------- --- -------------------------------------------------- SPICE_GFEVNT_MAXPAR P Maximum number of parameters required to define any quantity. SPICE_GF_CNVTOL P Default convergence tolerance. 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 (SPICETRUE) or off (SPICEFALSE). 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_Inputudstep 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. This is the default option. If gfstep_c is used, the step size must be set by calling gfsstp_c ( step ); 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. This is the default option. 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: "ANGULAR SEPARATION" "COORDINATE" "DISTANCE" "ILLUMINATION ANGLE" "PHASE ANGLE" "RANGE RATE" `gquant' strings are case insensitive. Values, meanings, and associated parameters are discussed below. 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. ANGULAR SEPARATION is the apparent angular separation of two target bodies as seen from an observing body. Quantity Parameters: qnpars = 8; SpiceChar qpnams[qnpars][LNSIZE] = { "TARGET1", "FRAME1", "SHAPE1", "TARGET2", "FRAME2", "SHAPE2", "OBSERVER", "ABCORR" }; SpiceChar qcpars[qnpars][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.) 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 must be set to blank: " " If the vector definition is "SUB-OBSERVER POINT" the "METHOD" parameter must be set to either: "Near point: ellipsoid" "Intercept: ellipsoid" If the vector definition is "SURFACE INTERCEPT POINT" the "METHOD" parameter must 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 are calculated using the radii of Mars taken from a SPICE planetary constants kernel. 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[qnpars][LNSIZE] = { "TARGET", "OBSERVER", "ABCORR", "COORDINATE SYSTEM", "COORDINATE", "REFERENCE FRAME", "VECTOR DEFINITION", "METHOD", "DREF", "DVEC" }; Only "SURFACE INTERCEPT POINT" searches make use of the "DREF" and "DVEC" parameters. SpiceChar qcpars[qnpars][LNSIZE] = { <name of first target>, <name of observer>, <aberration correction>, <coordinate system name>, <coordinate name>, <target reference frame name>, <vector definition>, <computation method>, <reference frame of DVEC pointing vector, defined in qdpars> }; qdpars[0] = <DVEC pointing vector x component from observer> qdpars[1] = <DVEC pointing vector y component from observer> qdpars[2] = <DVEC pointing vector z component 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[qnpars][LNSIZE] = { "TARGET", "OBSERVER", "ABCORR" }; SpiceChar qcpars[qnpars][LNSIZE] = { <name of target>, <name of observer>, <aberration correction> }; ILLUMINATION ANGLE is any of the illumination angles emission phase solar incidence defined at a surface point on a target body. These angles are defined as in the CSPICE routine ilumin_c. Quantity Parameters: qnpars = 8; SpiceChar qpnams[qnpars][LNSIZE] = { "TARGET", "ILLUM", "OBSERVER", "ABCORR", "FRAME", "ANGTYP", "METHOD", "SPOINT" }; SpiceChar qcpars[qnpars][LNSIZE] = { <name of target>, <name of illumination source>, <name of observer>, <aberration correction>, <target body-fixed frame>, <type of illumination angle>, <computation method> }; The surface point is specified using rectangular coordinates in the specified body-fixed frame. qdpars[0] = <X coordinate of surface point> qdpars[1] = <Y coordinate of surface point> qdpars[2] = <Z coordinate of surface point> PHASE ANGLE is the apparent phase angle between a target body center and an illuminating body center as seen from an observer. Quantity Parameters: qnpars = 4; SpiceChar qpnams[qnpars][LNSIZE] = { "TARGET", "OBSERVER", "ABCORR", "ILLUM" }; SpiceChar qcpars[qnpars][LNSIZE] = { <name of target>, <name of observer>, <aberration correction>, <name of illuminating body> }; RANGE RATE is the apparent range rate between a target body and an observing body. Quantity Parameters: qnpars = 3; SpiceChar qpnams[qnpars][LNSIZE] = { "TARGET", "OBSERVER", "ABCORR" }; SpiceChar qcpars[qnpars][LNSIZE] = { <name of target>, <name of observer>, <aberration correction> }; 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 is 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 value 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 is 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 the progress reporter is enabled. When `rpt' is SPICETRUE, progress reporting is enabled and the routines `udrepi', `udrepu', and `udrepf' (see descriptions below) are used to report progress. udrepi is the name of the user specified routine 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 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 the name of the user specified routine 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 the name of the user specified routine 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 is an integer parameter specifying the number of intervals that can be accommodated by each of the dynamically allocated workspace windows used internally by this routine. In many cases, it's not necessary to compute an accurate estimate of how many intervals are needed; rather, the user can pick a size considerably larger than what's really required. However, since excessively large arrays can prevent applications from compiling, linking, or running properly, sometimes `nintvls' must be set according to the actual workspace requirement. A rule of thumb for the number of intervals needed is nintvls = 2*n + ( m / step ) where n is the number of intervals in the confinement window. m is the measure of the confinement window, in units of seconds. step is the search step size in seconds. bail is a logical flag indicating whether or not interrupt signaling 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 the user specified routine that indicates whether an interrupt signal has been issued (for example, from the keyboard). The prototype of `udbail' is SpiceBoolean ( * udbail ) ( void ) The return value is SPICETRUE if an interrupt has been issued; otherwise the value is SPICEFALSE. ## Detailed_Outputcnfine 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. `result' must be declared and initialized with sufficient size to capture the full set of time intervals within the search region on which the specified condition is satisfied. If `result' is non-empty on input, its contents will be discarded before ## ParametersAll parameters described here are declared in the header file SpiceGF.h. See that file for parameter values. SPICE_GFEVNT_MAXPAR is the maximum number of parameters required to define any quantity. SPICE_GFEVNT_MAXPAR may grow if new quantities require more parameters. SPICE_GF_CNVTOL is the default convergence tolerance used by the high-level GF search API routines. This tolerance is used to terminate searches for binary state transitions: when the time at which a transition occurs is bracketed by two times that differ by no more than SPICE_GF_CNVTOL, the transition time is considered to have been found. ## Exceptions1) There are varying requirements on how distinct the three objects, `qcpars', must be. If the requirements are not met, an, an error is signaled by a routine in the call tree of this routine. When `gquant' has value "ANGULAR SEPARATION" then all three must be distinct. When `gquant' has value of either "DISTANCE" "COORDINATE" "RANGE RATE" the qcpars[0] and qcpars[1] objects must be distinct. 2) If any of the bodies involved do not have NAIF ID codes, an error is signaled by a routine in the call tree of this routine. 3) If the value of `gquant' is not recognized as a valid value, the error SPICE(NOTRECOGNIZED) is signaled by a routine in the call tree of this routine. 4) If the number of quantity definition parameters, `qnpars' is greater than the maximum allowed value, SPICE_GFEVNT_MAXPAR, the error SPICE(INVALIDCOUNT) is signaled. 5) If the proper required parameters are not supplied in `qnpars', the error SPICE(MISSINGVALUE) is signaled by a routine in the call tree of this routine. 6) If the comparison operator, `op', is not recognized, the error SPICE(NOTRECOGNIZED) is signaled by a routine in the call tree of this routine. 7) If the number of intervals `nintvls' is less than 1, the error SPICE(VALUEOUTOFRANGE) is signaled. 8) If `tol' is not greater than zero, an error is signaled by a routine in the call tree of this routine. 9) If `adjust' is negative, an error is signaled by a routine in the call tree of this routine. 10) If `adjust' has a non-zero value when `op' has any value other than "ABSMIN" or "ABSMAX", an error is signaled by a routine in the call tree of this routine. 11) 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. 12) If operation of this routine is interrupted, the output result window will be invalid. 13) If any of the `qpnams', `qcpars', `gquant' or `op' input string pointers is null, the error SPICE(NULLPOINTER) is signaled. 14) If any of the `qpnams', `qcpars', `gquant' or `op' input strings has zero length, the error SPICE(EMPTYSTRING) is signaled. 15) If any the `cnfine' or `result' cell arguments has a type other than SpiceDouble, the error SPICE(TYPEMISMATCH) is signaled. 16) If memory cannot be allocated to create the temporary variable required for the execution of the underlying Fortran routine, the error SPICE(MALLOCFAILED) is signaled. 17) If any attempt to change the handler for the interrupt signal SIGINT fails, the error SPICE(SIGNALFAILED) is signaled. ## FilesAppropriate SPK and PCK kernels must be loaded by the calling program before this routine is called. The following data are required: - SPK data: ephemeris data for target, source and observer that describes the ephemeris of these objects for the period defined by the confinement window, `udbail' must be loaded. 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 are assumed to be spherical and must have a radius loaded from the kernel pool. Typically this is done by loading a text PCK file via furnsh_c. If the bodies are triaxial, the largest radius is chosen as that of the equivalent spherical body. - In some cases the observer's state may be computed at times outside of `udbail' by as much as 2 seconds; data required to compute this state must be provided by loaded kernels. See -Particulars for details. In all cases, kernel data are normally loaded once per program run, NOT every time this routine is called. ## ParticularsThis routine provides the SPICE GF subsystem's general interface to determines 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 `cnfine'. 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 a high level geometry quantity routine 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 contained in the union of - the set of points where an equality constraint is met - the boundary points of the confinement window 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 longer 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. Certain types of searches require the state of the observer, relative to the solar system barycenter, to be computed at times slightly outside the confinement window `udbail'. The time window that is actually used is the result of "expanding" `udbail' by a specified amount "T": each time interval of `udbail' is expanded by shifting the interval's left endpoint to the left and the right endpoint to the right by T seconds. Any overlapping intervals are merged. (The input argument `udbail' is not modified.) The window expansions listed below are additive: if both conditions apply, the window expansion amount is the sum of the individual amounts. - If a search uses an equality constraint, the time window over which the state of the observer is computed is expanded by 1 second at both ends of all of the time intervals comprising the window over which the search is conducted. - If a search uses stellar aberration corrections, the time window over which the state of the observer is computed is expanded as described above. When light time corrections are used, expansion of the search window also affects the set of times at which the light time- corrected state of the target is computed. In addition to the possible 2 second expansion of the search window that occurs when both an equality constraint and stellar aberration corrections are used, round-off error should be taken into account when the need for data availability is analyzed. ## ExamplesThe numerical results shown for this example 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) 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: gfevnt_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 --------- -------- de414.bsp Planetary ephemeris pck00008.tpc Planet orientation and radii naif0009.tls Leapseconds \begindata KERNELS_TO_LOAD = ( 'de414.bsp', 'pck00008.tpc', 'naif0009.tls' ) \begintext End of meta-kernel Example code begins here. /. Program gfevnt_ex1 ./ #include "SpiceUsr.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 /. 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 is 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 ( "gfevnt_ex1.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 step size 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. ./ ## Restrictions1) The kernel files to be used by ## Literature_ReferencesNone. ## Author_and_InstitutionN.J. Bachman (JPL) J. Diaz del Rio (ODC Space) E.D. Wright (JPL) ## Version-CSPICE Version 1.1.0, 01-NOV-2021 (JDR) (EDW) (NJB) Added check for error condition "nintvls" less than one. Added check for `qnpars' out of range. Bug fix: moved creation of Fortran-style arrays for parameter names and string parameter values to right before the call to gfevnt_. This prevents a memory leak that could occur due to the prior placement of this code before checking macros that can execute return statements. Bug fix: changed input void array checks from using CHKFSTR to CHKOSTR. The previous checks did not inspect the input `lenvals'. Added use of ALLOC_CHECK_INTRA to check net null effect on alloc count. Updated header to describe use of expanded confinement window. Edited the header to comply with NAIF standard. Updated the description of "nintvls", "cnfine" and "result" arguments. Updates in -Exceptions section: Added entries #13 to #15, fixed short error message in entries #16 and #17, replaced entry #9 by new entries #9 and #10. Parameter MAXPAR has been replaced with parameter SPICE_GFEVNT_MAXPAR. Added descriptions of SPICE_GFEVNT_MAXPAR and SPICE_GF_CNVTOL to the -Brief_I/O and -Parameters sections. -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) (NJB) ## Index_Entriesdetermine when a geometric quantity satisfies a condition |

Fri Dec 31 18:41:07 2021