1 /* zzgfudb.f -- translated by f2c (version 19980913).
2 You must link the resulting object file with the libraries:
3 -lf2c -lm (in that order)
4 */
5
6 #include "f2c.h"
7
8 /* Table of constant values */
9
10 static logical c_false = FALSE_;
11 static doublereal c_b10 = 1.;
12
13 /* $Procedure ZZGFUDB ( Private --- GF, general use boolean search ) */
zzgfudb_(U_fp udfuns,U_fp udfunb,doublereal * tol,U_fp udstep,U_fp udrefn,logical * rpt,S_fp udrepi,U_fp udrepu,S_fp udrepf,logical * bail,L_fp udbail,doublereal * cnfine,doublereal * result)14 /* Subroutine */ int zzgfudb_(U_fp udfuns, U_fp udfunb, doublereal *tol, U_fp
15 udstep, U_fp udrefn, logical *rpt, S_fp udrepi, U_fp udrepu, S_fp
16 udrepf, logical *bail, L_fp udbail, doublereal *cnfine, doublereal *
17 result)
18 {
19 /* System generated locals */
20 integer i__1;
21
22 /* Local variables */
23 integer i__;
24 extern /* Subroutine */ int chkin_(char *, ftnlen), errdp_(char *,
25 doublereal *, ftnlen);
26 integer count;
27 doublereal start;
28 extern logical failed_(void);
29 extern /* Subroutine */ int zzgfsolvx_(U_fp, U_fp, U_fp, U_fp, logical *,
30 L_fp, logical *, doublereal *, doublereal *, doublereal *,
31 doublereal *, logical *, U_fp, doublereal *);
32 extern integer wncard_(doublereal *);
33 doublereal finish;
34 extern /* Subroutine */ int sigerr_(char *, ftnlen), chkout_(char *,
35 ftnlen), setmsg_(char *, ftnlen), wnfetd_(doublereal *, integer *,
36 doublereal *, doublereal *);
37 extern logical return_(void);
38
39 /* $ Abstract */
40
41 /* SPICE Private routine intended solely for the support of SPICE */
42 /* routines. Users should not call this routine directly due */
43 /* to the volatile nature of this routine. */
44
45 /* Routine to determine time intervals when a user defined boolean */
46 /* function returns true. Report progress and handle interrupts */
47 /* if so commanded. */
48
49 /* $ Disclaimer */
50
51 /* THIS SOFTWARE AND ANY RELATED MATERIALS WERE CREATED BY THE */
52 /* CALIFORNIA INSTITUTE OF TECHNOLOGY (CALTECH) UNDER A U.S. */
53 /* GOVERNMENT CONTRACT WITH THE NATIONAL AERONAUTICS AND SPACE */
54 /* ADMINISTRATION (NASA). THE SOFTWARE IS TECHNOLOGY AND SOFTWARE */
55 /* PUBLICLY AVAILABLE UNDER U.S. EXPORT LAWS AND IS PROVIDED "AS-IS" */
56 /* TO THE RECIPIENT WITHOUT WARRANTY OF ANY KIND, INCLUDING ANY */
57 /* WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR A */
58 /* PARTICULAR USE OR PURPOSE (AS SET FORTH IN UNITED STATES UCC */
59 /* SECTIONS 2312-2313) OR FOR ANY PURPOSE WHATSOEVER, FOR THE */
60 /* SOFTWARE AND RELATED MATERIALS, HOWEVER USED. */
61
62 /* IN NO EVENT SHALL CALTECH, ITS JET PROPULSION LABORATORY, OR NASA */
63 /* BE LIABLE FOR ANY DAMAGES AND/OR COSTS, INCLUDING, BUT NOT */
64 /* LIMITED TO, INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANY KIND, */
65 /* INCLUDING ECONOMIC DAMAGE OR INJURY TO PROPERTY AND LOST PROFITS, */
66 /* REGARDLESS OF WHETHER CALTECH, JPL, OR NASA BE ADVISED, HAVE */
67 /* REASON TO KNOW, OR, IN FACT, SHALL KNOW OF THE POSSIBILITY. */
68
69 /* RECIPIENT BEARS ALL RISK RELATING TO QUALITY AND PERFORMANCE OF */
70 /* THE SOFTWARE AND ANY RELATED MATERIALS, AND AGREES TO INDEMNIFY */
71 /* CALTECH AND NASA FOR ALL THIRD-PARTY CLAIMS RESULTING FROM THE */
72 /* ACTIONS OF RECIPIENT IN THE USE OF THE SOFTWARE. */
73
74 /* $ Required_Reading */
75
76 /* None. */
77
78 /* $ Keywords */
79
80 /* GF */
81 /* TIME */
82 /* WINDOWS */
83
84 /* $ Declarations */
85 /* $ Abstract */
86
87 /* This file contains public, global parameter declarations */
88 /* for the SPICELIB Geometry Finder (GF) subsystem. */
89
90 /* $ Disclaimer */
91
92 /* THIS SOFTWARE AND ANY RELATED MATERIALS WERE CREATED BY THE */
93 /* CALIFORNIA INSTITUTE OF TECHNOLOGY (CALTECH) UNDER A U.S. */
94 /* GOVERNMENT CONTRACT WITH THE NATIONAL AERONAUTICS AND SPACE */
95 /* ADMINISTRATION (NASA). THE SOFTWARE IS TECHNOLOGY AND SOFTWARE */
96 /* PUBLICLY AVAILABLE UNDER U.S. EXPORT LAWS AND IS PROVIDED "AS-IS" */
97 /* TO THE RECIPIENT WITHOUT WARRANTY OF ANY KIND, INCLUDING ANY */
98 /* WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR A */
99 /* PARTICULAR USE OR PURPOSE (AS SET FORTH IN UNITED STATES UCC */
100 /* SECTIONS 2312-2313) OR FOR ANY PURPOSE WHATSOEVER, FOR THE */
101 /* SOFTWARE AND RELATED MATERIALS, HOWEVER USED. */
102
103 /* IN NO EVENT SHALL CALTECH, ITS JET PROPULSION LABORATORY, OR NASA */
104 /* BE LIABLE FOR ANY DAMAGES AND/OR COSTS, INCLUDING, BUT NOT */
105 /* LIMITED TO, INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANY KIND, */
106 /* INCLUDING ECONOMIC DAMAGE OR INJURY TO PROPERTY AND LOST PROFITS, */
107 /* REGARDLESS OF WHETHER CALTECH, JPL, OR NASA BE ADVISED, HAVE */
108 /* REASON TO KNOW, OR, IN FACT, SHALL KNOW OF THE POSSIBILITY. */
109
110 /* RECIPIENT BEARS ALL RISK RELATING TO QUALITY AND PERFORMANCE OF */
111 /* THE SOFTWARE AND ANY RELATED MATERIALS, AND AGREES TO INDEMNIFY */
112 /* CALTECH AND NASA FOR ALL THIRD-PARTY CLAIMS RESULTING FROM THE */
113 /* ACTIONS OF RECIPIENT IN THE USE OF THE SOFTWARE. */
114
115 /* $ Required_Reading */
116
117 /* GF */
118
119 /* $ Keywords */
120
121 /* GEOMETRY */
122 /* ROOT */
123
124 /* $ Restrictions */
125
126 /* None. */
127
128 /* $ Author_and_Institution */
129
130 /* N.J. Bachman (JPL) */
131 /* L.E. Elson (JPL) */
132 /* E.D. Wright (JPL) */
133
134 /* $ Literature_References */
135
136 /* None. */
137
138 /* $ Version */
139
140 /* - SPICELIB Version 2.0.0 29-NOV-2016 (NJB) */
141
142 /* Upgraded to support surfaces represented by DSKs. */
143
144 /* Bug fix: removed declaration of NVRMAX parameter. */
145
146 /* - SPICELIB Version 1.3.0, 01-OCT-2011 (NJB) */
147
148 /* Added NWILUM parameter. */
149
150 /* - SPICELIB Version 1.2.0, 14-SEP-2010 (EDW) */
151
152 /* Added NWPA parameter. */
153
154 /* - SPICELIB Version 1.1.0, 08-SEP-2009 (EDW) */
155
156 /* Added NWRR parameter. */
157 /* Added NWUDS parameter. */
158
159 /* - SPICELIB Version 1.0.0, 21-FEB-2009 (NJB) (LSE) (EDW) */
160
161 /* -& */
162
163 /* Root finding parameters: */
164
165 /* CNVTOL is the default convergence tolerance used by the */
166 /* high-level GF search API routines. This tolerance is */
167 /* used to terminate searches for binary state transitions: */
168 /* when the time at which a transition occurs is bracketed */
169 /* by two times that differ by no more than CNVTOL, the */
170 /* transition time is considered to have been found. */
171
172 /* Units are TDB seconds. */
173
174
175 /* NWMAX is the maximum number of windows allowed for user-defined */
176 /* workspace array. */
177
178 /* DOUBLE PRECISION WORK ( LBCELL : MW, NWMAX ) */
179
180 /* Currently no more than twelve windows are required; the three */
181 /* extra windows are spares. */
182
183 /* Callers of GFEVNT can include this file and use the parameter */
184 /* NWMAX to declare the second dimension of the workspace array */
185 /* if necessary. */
186
187
188 /* Callers of GFIDST should declare their workspace window */
189 /* count using NWDIST. */
190
191
192 /* Callers of GFSEP should declare their workspace window */
193 /* count using NWSEP. */
194
195
196 /* Callers of GFRR should declare their workspace window */
197 /* count using NWRR. */
198
199
200 /* Callers of GFUDS should declare their workspace window */
201 /* count using NWUDS. */
202
203
204 /* Callers of GFPA should declare their workspace window */
205 /* count using NWPA. */
206
207
208 /* Callers of GFILUM should declare their workspace window */
209 /* count using NWILUM. */
210
211
212 /* ADDWIN is a parameter used to expand each interval of the search */
213 /* (confinement) window by a small amount at both ends in order to */
214 /* accommodate searches using equality constraints. The loaded */
215 /* kernel files must accommodate these expanded time intervals. */
216
217
218 /* FRMNLN is a string length for frame names. */
219
220
221 /* FOVTLN -- maximum length for FOV string. */
222
223
224 /* Specify the character strings that are allowed in the */
225 /* specification of field of view shapes. */
226
227
228 /* Character strings that are allowed in the */
229 /* specification of occultation types: */
230
231
232 /* Occultation target shape specifications: */
233
234
235 /* Specify the number of supported occultation types and occultation */
236 /* type string length: */
237
238
239 /* Instrument field-of-view (FOV) parameters */
240
241 /* Maximum number of FOV boundary vectors: */
242
243
244 /* FOV shape parameters: */
245
246 /* circle */
247 /* ellipse */
248 /* polygon */
249 /* rectangle */
250
251
252 /* End of file gf.inc. */
253
254 /* $ Brief_I/O */
255
256 /* Variable I/O Description */
257 /* -------- --- -------------------------------------------------- */
258 /* UDFUNS I Name of the routine that computes a scalar */
259 /* quantity of interest. */
260 /* UDFUNB I Name of the routine that computes the boolean */
261 /* value of interest. */
262 /* TOL I Convergence tolerance in seconds. */
263 /* UDSTEP I Name of the routine that returns a time step. */
264 /* UDREFN I Name of the routine that computes a refined time. */
265 /* RPT I Progress report flag. */
266 /* UDREPI I Function that initializes progress reporting. */
267 /* UDREPU I Function that updates the progress report. */
268 /* UDREPF I Function that finalizes progress reporting. */
269 /* BAIL I Logical indicating program interrupt monitoring. */
270 /* UDBAIL I Name of a routine that signals a program interrupt. */
271 /* CNFINE I SPICE window to which the search is restricted. */
272 /* RESULT O SPICE window containing results. */
273
274 /* $ Detailed_Input */
275
276 /* UDFUNS the routine that returns the value of the scalar */
277 /* quantity of interest at time ET. The calling sequence */
278 /* for UDFUNC is: */
279
280 /* CALL UDFUNS ( ET, VALUE ) */
281
282 /* where: */
283
284 /* ET a double precision value representing */
285 /* ephemeris time, expressed as seconds past */
286 /* J2000 TDB at which to determine the scalar */
287 /* value. */
288
289 /* VALUE is the value of the scalar quantity */
290 /* at ET. */
291
292
293 /* UDFUNB the user defined routine returning a boolean value */
294 /* for an epoch ET. */
295
296 /* The calling sequence: */
297
298 /* CALL UDFUNB ( UDFUNS, ET, BOOL ) */
299
300 /* where: */
301
302 /* UDFUNS a scalar function as previously defined. */
303
304 /* ET a double precision value representing */
305 /* ephemeris time, expressed as seconds past */
306 /* J2000 TDB, at which to evaluate UDFUNB. */
307
308 /* BOOL the boolean value at ET. */
309
310
311 /* TOL is a tolerance value used to determine convergence of */
312 /* root-finding operations. TOL is measured in TDB seconds */
313 /* and must be greater than zero. */
314
315
316 /* UDSTEP is an externally specified routine that computes a */
317 /* time step used to find transitions of the state being */
318 /* considered. A state transition occurs where the state */
319 /* changes from being "in state" to being "not in */
320 /* state" or vice versa. */
321
322 /* This routine relies on UDSTEP returning step sizes */
323 /* small enough so that state transitions within the */
324 /* confinement window are not overlooked. */
325
326 /* The calling sequence for UDSTEP is: */
327
328 /* CALL UDSTEP ( ET, STEP ) */
329
330 /* where: */
331
332 /* ET is the input start time from which the */
333 /* algorithm is to search forward for a state */
334 /* transition. ET is expressed as seconds past */
335 /* J2000 TDB. ET is a DOUBLE PRECISION number. */
336
337 /* STEP is the output step size. STEP indicates */
338 /* how far to advance ET so that ET and */
339 /* ET+STEP may bracket a state transition and */
340 /* definitely do not bracket more than one */
341 /* state transition. STEP is a DOUBLE */
342 /* PRECISION number. Units are TDB seconds. */
343
344 /* If a constant step size is desired, the routine GFSTEP */
345 /* may be used. If GFSTEP is used, the step size must be */
346 /* set by calling GFSSTP prior to calling this routine. */
347
348
349 /* UDREFN is the name of the externally specified routine that */
350 /* refines the times that bracket a transition point. In */
351 /* other words, once a pair of times, T1 and T2, that */
352 /* bracket a state transition have been found, UDREFN */
353 /* computes an intermediate time T such that either */
354 /* [T1, T] or [T, T2] contains the time of the state */
355 /* transition. The calling sequence for UDREFN is: */
356
357 /* CALL UDREFN ( T1, T2, S1, S2, T ) */
358
359 /* where the inputs are: */
360
361 /* T1 is a time when the visibility state is S1. T1 */
362 /* is expressed as seconds past J2000 TDB. */
363
364 /* T2 is a time when the visibility state is S2. T2 */
365 /* is expressed as seconds past J2000 TDB. and */
366 /* is assumed to be larger than T1. */
367
368 /* S1 is the visibility state at time T1. S1 is a */
369 /* LOGICAL value. */
370
371 /* S2 is the visibility state at time T2. S2 is a */
372 /* LOGICAL value. */
373
374 /* The output is: */
375
376 /* T is the next time to check for a state */
377 /* transition. T is expressed as seconds past */
378 /* J2000 TDB and is between T1 and T2. */
379
380 /* If a simple bisection method is desired, the routine */
381 /* GFREFN may be used. */
382
383
384 /* RPT is a logical variable which controls whether */
385 /* progress reporting is enabled. When RPT is .TRUE., */
386 /* progress reporting is enabled and the routines */
387 /* UDREPI, UDREPU, and UDPREF (see descriptions below) */
388 /* are used to report progress. */
389
390
391 /* UDREPI is a user-defined subroutine that initializes a */
392 /* progress report. When progress reporting is */
393 /* enabled, UDREPI is called at the start */
394 /* of a search. The calling sequence of UDREPI is */
395
396 /* UDREPI ( CNFINE, SRCPRE, SRCSUF ) */
397
398 /* DOUBLE PRECISION CNFINE ( LBCELL : * ) */
399 /* CHARACTER*(*) SRCPRE */
400 /* CHARACTER*(*) SRCSUF */
401
402 /* where */
403
404 /* CNFINE */
405
406 /* is the confinement window and */
407
408 /* SRCPRE */
409 /* SRCSUF */
410
411 /* are prefix and suffix strings used in the progress */
412 /* report: these strings are intended to bracket a */
413 /* representation of the fraction of work done. For */
414 /* example, when the CSPICE progress reporting functions */
415 /* are used, if SRCPRE and SRCSUF are, respectively, */
416
417 /* "User defined boolean event search" */
418 /* "done." */
419
420 /* the progress report display at the end of the */
421 /* search will be: */
422
423 /* User defined boolean event search 100.00% done. */
424
425 /* The SPICELIB routine GFREPI may be used as the */
426 /* actual argument corresponding to UDREPI. If so, */
427 /* the SPICELIB routines GFREPU and GFREPF must be */
428 /* the actual arguments corresponding to UDREPU and */
429 /* UDREPF. */
430
431
432 /* UDREPU is a user-defined subroutine that updates the */
433 /* progress report for a search. The calling sequence */
434 /* of UDREPU is */
435
436 /* UDREPU ( IVBEG, IVEND, ET ) */
437
438 /* DOUBLE PRECISION IVBEG */
439 /* DOUBLE PRECISION IVEND */
440 /* DOUBLE PRECISION ET */
441
442 /* Here IVBEG, IVEND are the bounds of an interval that */
443 /* is contained in some interval belonging to the */
444 /* confinement window. The confinement window is */
445 /* associated with some root finding activity. It is used */
446 /* to determine how much total time is being searched in */
447 /* order to find the events of interest. */
448
449 /* ET is an epoch belonging to the interval */
450 /* [IVBEG, IVEND]. */
451
452 /* In order for a meaningful progress report to be */
453 /* displayed, IVBEG and IVEND must satisfy the following */
454 /* constraints: */
455
456 /* - IVBEG must be less than or equal to IVEND. */
457
458 /* - The interval [ IVBEG, IVEND ] must be contained in */
459 /* some interval of the confinement window. It can be */
460 /* a proper subset of the containing interval; that */
461 /* is, it can be smaller than the interval of the */
462 /* confinement window that contains it. */
463
464 /* - Over a search, the sum of the differences */
465
466 /* IVEND - IVBEG */
467
468 /* for all calls to this routine made during the search */
469 /* must equal the measure of the confinement window. */
470
471 /* The SPICELIB routine GFREPU may be used as the */
472 /* actual argument corresponding to UDREPU. If so, */
473 /* the SPICELIB routines GFREPI and GFREPF must be */
474 /* the actual arguments corresponding to UDREPI and */
475 /* UDREPF. */
476
477
478 /* UDREPF is a user-defined subroutine that finalizes a */
479 /* progress report. UDREPF has no arguments. */
480
481 /* The SPICELIB routine GFREPF may be used as the */
482 /* actual argument corresponding to UDREPF. If so, */
483 /* the SPICELIB routines GFREPI and GFREPU must be */
484 /* the actual arguments corresponding to UDREPI and */
485 /* UDREPU. */
486
487
488 /* BAIL is a logical variable indicating whether or not */
489 /* interrupt handling is enabled. When BAIL is */
490 /* set to .TRUE., the input function UDBAIL (see */
491 /* description below) is used to determine whether */
492 /* an interrupt has been issued. */
493
494
495 /* UDBAIL is the name of a user defined logical function that */
496 /* indicates whether an interrupt signal has been */
497 /* issued (for example, from the keyboard). UDBAIL */
498 /* has no arguments and returns a LOGICAL value. */
499 /* The return value is .TRUE. if an interrupt has */
500 /* been issued; otherwise the value is .FALSE. */
501
502 /* GFUDB uses UDBAIL only when BAIL (see above) is set */
503 /* to .TRUE., indicating that interrupt handling is */
504 /* enabled. When interrupt handling is enabled, GFUDB */
505 /* and routines in its call tree will call UDBAIL to */
506 /* determine whether to terminate processing and return */
507 /* immediately. */
508
509 /* If interrupt handing is not enabled, a logical */
510 /* function must still be passed to GFUDB as */
511 /* an input argument. The SPICE function */
512
513 /* GFBAIL */
514
515 /* may be used for this purpose. */
516
517
518 /* CNFINE is a SPICE window that confines the time period over */
519 /* which the specified search is conducted. CNFINE may */
520 /* consist of a single interval or a collection of */
521 /* intervals. */
522
523 /* The endpoints of the time intervals comprising CNFINE */
524 /* are interpreted as seconds past J2000 TDB. */
525
526 /* See the Examples section below for a code example */
527 /* that shows how to create a confinement window. */
528
529 /* CNFINE must be initialized by the caller via the */
530 /* SPICELIB routine SSIZED. */
531
532
533 /* $ Detailed_Output */
534
535 /* RESULT is a SPICE window representing the set of time */
536 /* intervals, within the confinement period, when the */
537 /* specified boolean function has a value true. */
538
539 /* The endpoints of the time intervals comprising RESULT */
540 /* are interpreted as seconds past J2000 TDB. */
541
542 /* If RESULT is non-empty on input, its contents */
543 /* will be discarded before GFUDB conducts its */
544 /* search. */
545
546 /* $ Parameters */
547
548 /* LBCELL is the SPICELIB cell lower bound. */
549
550 /* $ Exceptions */
551
552 /* 1) SPICE(INVALIDTOLERANCE) will signal if the convergence */
553 /* tolerance value is non-positive. */
554
555 /* $ Files */
556
557 /* Appropriate kernels must be loaded by the calling program before */
558 /* this routine is called. */
559
560 /* If the boolean function requires access to ephemeris data: */
561
562 /* - SPK data: ephemeris data for any body over the */
563 /* time period defined by the confinement window must be */
564 /* loaded. If aberration corrections are used, the states of */
565 /* target and observer relative to the solar system barycenter */
566 /* must be calculable from the available ephemeris data. */
567 /* Typically ephemeris data are made available by loading one */
568 /* or more SPK files via FURNSH. */
569
570 /* - If non-inertial reference frames are used, then PCK */
571 /* files, frame kernels, C-kernels, and SCLK kernels may be */
572 /* needed. */
573
574 /* In all cases, kernel data are normally loaded once per program */
575 /* run, NOT every time this routine is called. */
576
577 /* $ Particulars */
578
579 /* This routine provides the SPICE GF system's most flexible */
580 /* interface for searching for boolean events based on a user */
581 /* defined boolean function. */
582
583 /* Applications that do not require support for progress */
584 /* reporting, interrupt handling, non-default step refinement */
585 /* functions, or non-default convergence tolerance normally should */
586 /* call GFUDB rather than this routine. */
587
588 /* This routine determines a set of one or more time intervals */
589 /* within the confinement window when the boolean function */
590 /* satisfies a caller-specified constraint. The resulting set of */
591 /* intervals is returned as a SPICE window. */
592
593 /* Below we discuss in greater detail aspects of this routine's */
594 /* solution process that are relevant to correct and efficient */
595 /* use of this routine in user applications. */
596
597 /* The Search Process */
598 /* ================== */
599
600 /* The search for boolean events is treated as a search for state */
601 /* transitions: times are sought when the boolean function value */
602 /* changes from true to false or vice versa. */
603
604 /* Step Size */
605 /* ========= */
606
607 /* Each interval of the confinement window is searched as follows: */
608 /* first, the input step size is used to determine the time */
609 /* separation at which the boolean function will be sampled. */
610 /* Starting at the left endpoint of the interval, samples of the */
611 /* boolean function will be taken at each step. If a state change */
612 /* is detected, a root has been bracketed; at that point, the */
613 /* "root"--the time at which the state change occurs---is found by a */
614 /* refinement process, for example, via binary search. */
615
616 /* Note that the optimal choice of step size depends on the lengths */
617 /* of the intervals over which the boolean function is constant: */
618 /* the step size should be shorter than the shortest such interval */
619 /* and the shortest separation between the intervals, within */
620 /* the confinement window. */
621
622 /* Having some knowledge of the relative geometry of the targets and */
623 /* observer can be a valuable aid in picking a reasonable step size. */
624 /* In general, the user can compensate for lack of such knowledge by */
625 /* picking a very short step size; the cost is increased computation */
626 /* time. */
627
628 /* Note that the step size is not related to the precision with which */
629 /* the endpoints of the intervals of the result window are computed. */
630 /* That precision level is controlled by the convergence tolerance. */
631
632
633 /* Convergence Tolerance */
634 /* ===================== */
635
636 /* Once a root has been bracketed, a refinement process is used to */
637 /* narrow down the time interval within which the root must lie. */
638 /* This refinement process terminates when the location of the root */
639 /* has been determined to within an error margin called the */
640 /* "convergence tolerance." The default convergence tolerance */
641 /* used by this routine is set by the parameter CNVTOL (defined */
642 /* in gf.inc). */
643
644 /* The value of CNVTOL is set to a "tight" value so that the */
645 /* tolerance doesn't become the limiting factor in the accuracy of */
646 /* solutions found by this routine. In general the accuracy of input */
647 /* data will be the limiting factor. */
648
649 /* The user may change the convergence tolerance from the default */
650 /* CNVTOL value by calling the routine GFSTOL, e.g. */
651
652 /* CALL GFSTOL( tolerance value ) */
653
654 /* Call GFSTOL prior to calling this routine. All subsequent */
655 /* searches will use the updated tolerance value. */
656
657 /* Setting the tolerance tighter than CNVTOL is unlikely to be */
658 /* useful, since the results are unlikely to be more accurate. */
659 /* Making the tolerance looser will speed up searches somewhat, */
660 /* since a few convergence steps will be omitted. However, in most */
661 /* cases, the step size is likely to have a much greater effect */
662 /* on processing time than would the convergence tolerance. */
663
664
665 /* The Confinement Window */
666 /* ====================== */
667
668 /* The simplest use of the confinement window is to specify a time */
669 /* interval within which a solution is sought. */
670
671 /* The confinement window also can be used to restrict a search to */
672 /* a time window over which required data are known to be */
673 /* available. */
674
675 /* In some cases, the confinement window be used to make searches */
676 /* more efficient. Sometimes it's possible to do an efficient search */
677 /* to reduce the size of the time period over which a relatively */
678 /* slow search of interest must be performed. See the "CASCADE" */
679 /* example program in gf.req for a demonstration. */
680
681 /* $ Examples */
682
683 /* Refer to GFUDB. */
684
685 /* $ Restrictions */
686
687 /* 1) Any kernel files required by this routine must be loaded */
688 /* (normally via the SPICELIB routine FURNSH) before this routine */
689 /* is called. */
690
691 /* $ Literature_References */
692
693 /* None. */
694
695 /* $ Author_and_Institution */
696
697 /* N.J. Bachman (JPL) */
698 /* E.D. Wright (JPL) */
699
700 /* $ Version */
701
702 /* - SPICELIB Version 1.0.0 17-OCT-2013 (EDW) */
703
704 /* Logic and implementation based on GFOCCE by Nat Bachman. */
705
706 /* -& */
707 /* $ Index_Entries */
708
709 /* GF user defined boolean function search */
710
711 /* -& */
712
713 /* SPICELIB functions */
714
715
716 /* Local parameters */
717
718
719 /* STEP is a step size initializer for the unused, dummy step size */
720 /* argument to ZZGFSOLVX. The routine UDSTEP, which is passed to */
721 /* ZZGFSOLVX, will be used by that routine to obtain the step size. */
722
723
724 /* CSTEP indicates whether a constant step size, provided */
725 /* via the input argument STEP, is to be used by ZZGFSOLVX. */
726
727
728 /* Local variables */
729
730
731 /* Standard SPICE error handling. */
732
733 if (return_()) {
734 return 0;
735 }
736 chkin_("ZZGFUDB", (ftnlen)7);
737
738 /* Check the convergence tolerance. */
739
740 if (*tol <= 0.) {
741 setmsg_("Tolerance must be positive but was #.", (ftnlen)37);
742 errdp_("#", tol, (ftnlen)1);
743 sigerr_("SPICE(INVALIDTOLERANCE)", (ftnlen)23);
744 chkout_("ZZGFUDB", (ftnlen)7);
745 return 0;
746 }
747
748 /* Prepare the progress reporter if appropriate. */
749
750 if (*rpt) {
751 (*udrepi)(cnfine, "User defined boolean event search ", "done.", (
752 ftnlen)34, (ftnlen)5);
753 }
754
755 /* Cycle over the intervals in the confining window. */
756
757 count = wncard_(cnfine);
758 i__1 = count;
759 for (i__ = 1; i__ <= i__1; ++i__) {
760
761 /* Retrieve the bounds for the Ith interval of the confinement */
762 /* window. Search this interval for boolean events. Union the */
763 /* result with the contents of the RESULT window. */
764
765 wnfetd_(cnfine, &i__, &start, &finish);
766
767 /* Call ZZGFSOLVX to do the event detection work. The boolean */
768 /* function passes as UDFUNB, the scalar as UDFUNS. */
769
770 zzgfsolvx_((U_fp)udfuns, (U_fp)udfunb, (U_fp)udstep, (U_fp)udrefn,
771 bail, (L_fp)udbail, &c_false, &c_b10, &start, &finish, tol,
772 rpt, (U_fp)udrepu, result);
773 if (failed_()) {
774 chkout_("ZZGFUDB", (ftnlen)7);
775 return 0;
776 }
777 if (*bail) {
778
779 /* Interrupt handling is enabled. */
780
781 if ((*udbail)()) {
782
783 /* An interrupt has been issued. Return now regardless of */
784 /* whether the search completed. */
785
786 chkout_("ZZGFUDB", (ftnlen)7);
787 return 0;
788 }
789 }
790 }
791
792 /* End the progress report. */
793
794 if (*rpt) {
795 (*udrepf)();
796 }
797 chkout_("ZZGFUDB", (ftnlen)7);
798 return 0;
799 } /* zzgfudb_ */
800
801