1 /* gfilum.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 integer c__5 = 5;
11 static integer c__3 = 3;
12 static integer c_n1 = -1;
13 static integer c__0 = 0;
14 static integer c__8 = 8;
15 static logical c_false = FALSE_;
16
17 /* $Procedure GFILUM ( GF, illumination angle search ) */
gfilum_(char * method,char * angtyp,char * target,char * illmn,char * fixref,char * abcorr,char * obsrvr,doublereal * spoint,char * relate,doublereal * refval,doublereal * adjust,doublereal * step,doublereal * cnfine,integer * mw,integer * nw,doublereal * work,doublereal * result,ftnlen method_len,ftnlen angtyp_len,ftnlen target_len,ftnlen illmn_len,ftnlen fixref_len,ftnlen abcorr_len,ftnlen obsrvr_len,ftnlen relate_len)18 /* Subroutine */ int gfilum_(char *method, char *angtyp, char *target, char *
19 illmn, char *fixref, char *abcorr, char *obsrvr, doublereal *spoint,
20 char *relate, doublereal *refval, doublereal *adjust, doublereal *
21 step, doublereal *cnfine, integer *mw, integer *nw, doublereal *work,
22 doublereal *result, ftnlen method_len, ftnlen angtyp_len, ftnlen
23 target_len, ftnlen illmn_len, ftnlen fixref_len, ftnlen abcorr_len,
24 ftnlen obsrvr_len, ftnlen relate_len)
25 {
26 /* System generated locals */
27 integer work_dim1, work_offset, i__1;
28
29 /* Builtin functions */
30 /* Subroutine */ int s_copy(char *, char *, ftnlen, ftnlen);
31
32 /* Local variables */
33 extern /* Subroutine */ int chkin_(char *, ftnlen), moved_(doublereal *,
34 integer *, doublereal *), errdp_(char *, doublereal *, ftnlen);
35 extern integer sized_(doublereal *);
36 extern logical gfbail_();
37 logical ok;
38 extern /* Subroutine */ int scardd_(integer *, doublereal *);
39 extern /* Subroutine */ int gfrefn_(), gfrepi_();
40 extern logical return_(void);
41 extern /* Subroutine */ int gfrepu_(), gfrepf_(), gfstep_();
42 char qcpars[80*8], qpnams[80*8];
43 doublereal qdpars[8];
44 integer qipars[8];
45 logical qlpars[8];
46 extern /* Subroutine */ int setmsg_(char *, ftnlen), errint_(char *,
47 integer *, ftnlen), sigerr_(char *, ftnlen), chkout_(char *,
48 ftnlen), gfsstp_(doublereal *), gfevnt_(U_fp, U_fp, char *,
49 integer *, char *, char *, doublereal *, integer *, logical *,
50 char *, doublereal *, doublereal *, doublereal *, doublereal *,
51 logical *, U_fp, U_fp, U_fp, integer *, integer *, doublereal *,
52 logical *, L_fp, doublereal *, ftnlen, ftnlen, ftnlen, ftnlen);
53 doublereal tol;
54 extern /* Subroutine */ int zzholdd_(integer *, integer *, logical *,
55 doublereal *);
56
57 /* $ Abstract */
58
59 /* Determine time intervals over which a specified constraint on */
60 /* the observed phase, solar incidence, or emission angle at */
61 /* a specified target body surface point is met. */
62
63 /* $ Disclaimer */
64
65 /* THIS SOFTWARE AND ANY RELATED MATERIALS WERE CREATED BY THE */
66 /* CALIFORNIA INSTITUTE OF TECHNOLOGY (CALTECH) UNDER A U.S. */
67 /* GOVERNMENT CONTRACT WITH THE NATIONAL AERONAUTICS AND SPACE */
68 /* ADMINISTRATION (NASA). THE SOFTWARE IS TECHNOLOGY AND SOFTWARE */
69 /* PUBLICLY AVAILABLE UNDER U.S. EXPORT LAWS AND IS PROVIDED "AS-IS" */
70 /* TO THE RECIPIENT WITHOUT WARRANTY OF ANY KIND, INCLUDING ANY */
71 /* WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR A */
72 /* PARTICULAR USE OR PURPOSE (AS SET FORTH IN UNITED STATES UCC */
73 /* SECTIONS 2312-2313) OR FOR ANY PURPOSE WHATSOEVER, FOR THE */
74 /* SOFTWARE AND RELATED MATERIALS, HOWEVER USED. */
75
76 /* IN NO EVENT SHALL CALTECH, ITS JET PROPULSION LABORATORY, OR NASA */
77 /* BE LIABLE FOR ANY DAMAGES AND/OR COSTS, INCLUDING, BUT NOT */
78 /* LIMITED TO, INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANY KIND, */
79 /* INCLUDING ECONOMIC DAMAGE OR INJURY TO PROPERTY AND LOST PROFITS, */
80 /* REGARDLESS OF WHETHER CALTECH, JPL, OR NASA BE ADVISED, HAVE */
81 /* REASON TO KNOW, OR, IN FACT, SHALL KNOW OF THE POSSIBILITY. */
82
83 /* RECIPIENT BEARS ALL RISK RELATING TO QUALITY AND PERFORMANCE OF */
84 /* THE SOFTWARE AND ANY RELATED MATERIALS, AND AGREES TO INDEMNIFY */
85 /* CALTECH AND NASA FOR ALL THIRD-PARTY CLAIMS RESULTING FROM THE */
86 /* ACTIONS OF RECIPIENT IN THE USE OF THE SOFTWARE. */
87
88 /* $ Required_Reading */
89
90 /* GF */
91 /* FRAMES */
92 /* NAIF_IDS */
93 /* PCK */
94 /* SPK */
95 /* TIME */
96
97 /* $ Keywords */
98
99 /* ANGLE */
100 /* EPHEMERIS */
101 /* ILLUMINATION */
102 /* LIGHTING */
103 /* SEARCH */
104
105 /* $ Declarations */
106 /* $ Abstract */
107
108 /* This file contains public, global parameter declarations */
109 /* for the SPICELIB Geometry Finder (GF) subsystem. */
110
111 /* $ Disclaimer */
112
113 /* THIS SOFTWARE AND ANY RELATED MATERIALS WERE CREATED BY THE */
114 /* CALIFORNIA INSTITUTE OF TECHNOLOGY (CALTECH) UNDER A U.S. */
115 /* GOVERNMENT CONTRACT WITH THE NATIONAL AERONAUTICS AND SPACE */
116 /* ADMINISTRATION (NASA). THE SOFTWARE IS TECHNOLOGY AND SOFTWARE */
117 /* PUBLICLY AVAILABLE UNDER U.S. EXPORT LAWS AND IS PROVIDED "AS-IS" */
118 /* TO THE RECIPIENT WITHOUT WARRANTY OF ANY KIND, INCLUDING ANY */
119 /* WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR A */
120 /* PARTICULAR USE OR PURPOSE (AS SET FORTH IN UNITED STATES UCC */
121 /* SECTIONS 2312-2313) OR FOR ANY PURPOSE WHATSOEVER, FOR THE */
122 /* SOFTWARE AND RELATED MATERIALS, HOWEVER USED. */
123
124 /* IN NO EVENT SHALL CALTECH, ITS JET PROPULSION LABORATORY, OR NASA */
125 /* BE LIABLE FOR ANY DAMAGES AND/OR COSTS, INCLUDING, BUT NOT */
126 /* LIMITED TO, INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANY KIND, */
127 /* INCLUDING ECONOMIC DAMAGE OR INJURY TO PROPERTY AND LOST PROFITS, */
128 /* REGARDLESS OF WHETHER CALTECH, JPL, OR NASA BE ADVISED, HAVE */
129 /* REASON TO KNOW, OR, IN FACT, SHALL KNOW OF THE POSSIBILITY. */
130
131 /* RECIPIENT BEARS ALL RISK RELATING TO QUALITY AND PERFORMANCE OF */
132 /* THE SOFTWARE AND ANY RELATED MATERIALS, AND AGREES TO INDEMNIFY */
133 /* CALTECH AND NASA FOR ALL THIRD-PARTY CLAIMS RESULTING FROM THE */
134 /* ACTIONS OF RECIPIENT IN THE USE OF THE SOFTWARE. */
135
136 /* $ Required_Reading */
137
138 /* GF */
139
140 /* $ Keywords */
141
142 /* GEOMETRY */
143 /* ROOT */
144
145 /* $ Restrictions */
146
147 /* None. */
148
149 /* $ Author_and_Institution */
150
151 /* N.J. Bachman (JPL) */
152 /* L.E. Elson (JPL) */
153 /* E.D. Wright (JPL) */
154
155 /* $ Literature_References */
156
157 /* None. */
158
159 /* $ Version */
160
161 /* - SPICELIB Version 2.0.0 29-NOV-2016 (NJB) */
162
163 /* Upgraded to support surfaces represented by DSKs. */
164
165 /* Bug fix: removed declaration of NVRMAX parameter. */
166
167 /* - SPICELIB Version 1.3.0, 01-OCT-2011 (NJB) */
168
169 /* Added NWILUM parameter. */
170
171 /* - SPICELIB Version 1.2.0, 14-SEP-2010 (EDW) */
172
173 /* Added NWPA parameter. */
174
175 /* - SPICELIB Version 1.1.0, 08-SEP-2009 (EDW) */
176
177 /* Added NWRR parameter. */
178 /* Added NWUDS parameter. */
179
180 /* - SPICELIB Version 1.0.0, 21-FEB-2009 (NJB) (LSE) (EDW) */
181
182 /* -& */
183
184 /* Root finding parameters: */
185
186 /* CNVTOL is the default convergence tolerance used by the */
187 /* high-level GF search API routines. This tolerance is */
188 /* used to terminate searches for binary state transitions: */
189 /* when the time at which a transition occurs is bracketed */
190 /* by two times that differ by no more than CNVTOL, the */
191 /* transition time is considered to have been found. */
192
193 /* Units are TDB seconds. */
194
195
196 /* NWMAX is the maximum number of windows allowed for user-defined */
197 /* workspace array. */
198
199 /* DOUBLE PRECISION WORK ( LBCELL : MW, NWMAX ) */
200
201 /* Currently no more than twelve windows are required; the three */
202 /* extra windows are spares. */
203
204 /* Callers of GFEVNT can include this file and use the parameter */
205 /* NWMAX to declare the second dimension of the workspace array */
206 /* if necessary. */
207
208
209 /* Callers of GFIDST should declare their workspace window */
210 /* count using NWDIST. */
211
212
213 /* Callers of GFSEP should declare their workspace window */
214 /* count using NWSEP. */
215
216
217 /* Callers of GFRR should declare their workspace window */
218 /* count using NWRR. */
219
220
221 /* Callers of GFUDS should declare their workspace window */
222 /* count using NWUDS. */
223
224
225 /* Callers of GFPA should declare their workspace window */
226 /* count using NWPA. */
227
228
229 /* Callers of GFILUM should declare their workspace window */
230 /* count using NWILUM. */
231
232
233 /* ADDWIN is a parameter used to expand each interval of the search */
234 /* (confinement) window by a small amount at both ends in order to */
235 /* accommodate searches using equality constraints. The loaded */
236 /* kernel files must accommodate these expanded time intervals. */
237
238
239 /* FRMNLN is a string length for frame names. */
240
241
242 /* FOVTLN -- maximum length for FOV string. */
243
244
245 /* Specify the character strings that are allowed in the */
246 /* specification of field of view shapes. */
247
248
249 /* Character strings that are allowed in the */
250 /* specification of occultation types: */
251
252
253 /* Occultation target shape specifications: */
254
255
256 /* Specify the number of supported occultation types and occultation */
257 /* type string length: */
258
259
260 /* Instrument field-of-view (FOV) parameters */
261
262 /* Maximum number of FOV boundary vectors: */
263
264
265 /* FOV shape parameters: */
266
267 /* circle */
268 /* ellipse */
269 /* polygon */
270 /* rectangle */
271
272
273 /* End of file gf.inc. */
274
275 /* $ Abstract */
276
277 /* Include file zzabcorr.inc */
278
279 /* SPICE private file intended solely for the support of SPICE */
280 /* routines. Users should not include this file directly due */
281 /* to the volatile nature of this file */
282
283 /* The parameters below define the structure of an aberration */
284 /* correction attribute block. */
285
286 /* $ Disclaimer */
287
288 /* THIS SOFTWARE AND ANY RELATED MATERIALS WERE CREATED BY THE */
289 /* CALIFORNIA INSTITUTE OF TECHNOLOGY (CALTECH) UNDER A U.S. */
290 /* GOVERNMENT CONTRACT WITH THE NATIONAL AERONAUTICS AND SPACE */
291 /* ADMINISTRATION (NASA). THE SOFTWARE IS TECHNOLOGY AND SOFTWARE */
292 /* PUBLICLY AVAILABLE UNDER U.S. EXPORT LAWS AND IS PROVIDED "AS-IS" */
293 /* TO THE RECIPIENT WITHOUT WARRANTY OF ANY KIND, INCLUDING ANY */
294 /* WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR A */
295 /* PARTICULAR USE OR PURPOSE (AS SET FORTH IN UNITED STATES UCC */
296 /* SECTIONS 2312-2313) OR FOR ANY PURPOSE WHATSOEVER, FOR THE */
297 /* SOFTWARE AND RELATED MATERIALS, HOWEVER USED. */
298
299 /* IN NO EVENT SHALL CALTECH, ITS JET PROPULSION LABORATORY, OR NASA */
300 /* BE LIABLE FOR ANY DAMAGES AND/OR COSTS, INCLUDING, BUT NOT */
301 /* LIMITED TO, INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANY KIND, */
302 /* INCLUDING ECONOMIC DAMAGE OR INJURY TO PROPERTY AND LOST PROFITS, */
303 /* REGARDLESS OF WHETHER CALTECH, JPL, OR NASA BE ADVISED, HAVE */
304 /* REASON TO KNOW, OR, IN FACT, SHALL KNOW OF THE POSSIBILITY. */
305
306 /* RECIPIENT BEARS ALL RISK RELATING TO QUALITY AND PERFORMANCE OF */
307 /* THE SOFTWARE AND ANY RELATED MATERIALS, AND AGREES TO INDEMNIFY */
308 /* CALTECH AND NASA FOR ALL THIRD-PARTY CLAIMS RESULTING FROM THE */
309 /* ACTIONS OF RECIPIENT IN THE USE OF THE SOFTWARE. */
310
311 /* $ Parameters */
312
313 /* An aberration correction attribute block is an array of logical */
314 /* flags indicating the attributes of the aberration correction */
315 /* specified by an aberration correction string. The attributes */
316 /* are: */
317
318 /* - Is the correction "geometric"? */
319
320 /* - Is light time correction indicated? */
321
322 /* - Is stellar aberration correction indicated? */
323
324 /* - Is the light time correction of the "converged */
325 /* Newtonian" variety? */
326
327 /* - Is the correction for the transmission case? */
328
329 /* - Is the correction relativistic? */
330
331 /* The parameters defining the structure of the block are as */
332 /* follows: */
333
334 /* NABCOR Number of aberration correction choices. */
335
336 /* ABATSZ Number of elements in the aberration correction */
337 /* block. */
338
339 /* GEOIDX Index in block of geometric correction flag. */
340
341 /* LTIDX Index of light time flag. */
342
343 /* STLIDX Index of stellar aberration flag. */
344
345 /* CNVIDX Index of converged Newtonian flag. */
346
347 /* XMTIDX Index of transmission flag. */
348
349 /* RELIDX Index of relativistic flag. */
350
351 /* The following parameter is not required to define the block */
352 /* structure, but it is convenient to include it here: */
353
354 /* CORLEN The maximum string length required by any aberration */
355 /* correction string */
356
357 /* $ Author_and_Institution */
358
359 /* N.J. Bachman (JPL) */
360
361 /* $ Literature_References */
362
363 /* None. */
364
365 /* $ Version */
366
367 /* - SPICELIB Version 1.0.0, 18-DEC-2004 (NJB) */
368
369 /* -& */
370 /* Number of aberration correction choices: */
371
372
373 /* Aberration correction attribute block size */
374 /* (number of aberration correction attributes): */
375
376
377 /* Indices of attributes within an aberration correction */
378 /* attribute block: */
379
380
381 /* Maximum length of an aberration correction string: */
382
383
384 /* End of include file zzabcorr.inc */
385
386 /* $ Abstract */
387
388 /* SPICE private routine intended solely for the support of SPICE */
389 /* routines. Users should not call this routine directly due to the */
390 /* volatile nature of this routine. */
391
392 /* This file contains parameter declarations for the ZZHOLDD */
393 /* routine. */
394
395 /* $ Disclaimer */
396
397 /* THIS SOFTWARE AND ANY RELATED MATERIALS WERE CREATED BY THE */
398 /* CALIFORNIA INSTITUTE OF TECHNOLOGY (CALTECH) UNDER A U.S. */
399 /* GOVERNMENT CONTRACT WITH THE NATIONAL AERONAUTICS AND SPACE */
400 /* ADMINISTRATION (NASA). THE SOFTWARE IS TECHNOLOGY AND SOFTWARE */
401 /* PUBLICLY AVAILABLE UNDER U.S. EXPORT LAWS AND IS PROVIDED "AS-IS" */
402 /* TO THE RECIPIENT WITHOUT WARRANTY OF ANY KIND, INCLUDING ANY */
403 /* WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR A */
404 /* PARTICULAR USE OR PURPOSE (AS SET FORTH IN UNITED STATES UCC */
405 /* SECTIONS 2312-2313) OR FOR ANY PURPOSE WHATSOEVER, FOR THE */
406 /* SOFTWARE AND RELATED MATERIALS, HOWEVER USED. */
407
408 /* IN NO EVENT SHALL CALTECH, ITS JET PROPULSION LABORATORY, OR NASA */
409 /* BE LIABLE FOR ANY DAMAGES AND/OR COSTS, INCLUDING, BUT NOT */
410 /* LIMITED TO, INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANY KIND, */
411 /* INCLUDING ECONOMIC DAMAGE OR INJURY TO PROPERTY AND LOST PROFITS, */
412 /* REGARDLESS OF WHETHER CALTECH, JPL, OR NASA BE ADVISED, HAVE */
413 /* REASON TO KNOW, OR, IN FACT, SHALL KNOW OF THE POSSIBILITY. */
414
415 /* RECIPIENT BEARS ALL RISK RELATING TO QUALITY AND PERFORMANCE OF */
416 /* THE SOFTWARE AND ANY RELATED MATERIALS, AND AGREES TO INDEMNIFY */
417 /* CALTECH AND NASA FOR ALL THIRD-PARTY CLAIMS RESULTING FROM THE */
418 /* ACTIONS OF RECIPIENT IN THE USE OF THE SOFTWARE. */
419
420 /* $ Required_Reading */
421
422 /* None. */
423
424 /* $ Keywords */
425
426 /* None. */
427
428 /* $ Declarations */
429
430 /* None. */
431
432 /* $ Brief_I/O */
433
434 /* None. */
435
436 /* $ Detailed_Input */
437
438 /* None. */
439
440 /* $ Detailed_Output */
441
442 /* None. */
443
444 /* $ Parameters */
445
446 /* GEN general value, primarily for testing. */
447
448 /* GF_REF user defined GF reference value. */
449
450 /* GF_TOL user defined GF convergence tolerance. */
451
452 /* GF_DT user defined GF step for numeric differentiation. */
453
454 /* $ Exceptions */
455
456 /* None. */
457
458 /* $ Files */
459
460 /* None. */
461
462 /* $ Particulars */
463
464 /* None. */
465
466 /* $ Examples */
467
468 /* None. */
469
470 /* $ Restrictions */
471
472 /* None. */
473
474 /* $ Literature_References */
475
476 /* None. */
477
478 /* $ Author_and_Institution */
479
480 /* E.D. Wright (JPL) */
481
482 /* $ Version */
483
484 /* - SPICELIB Version 1.0.0 03-DEC-2013 (EDW) */
485
486 /* -& */
487
488 /* OP codes. The values exist in the integer domain */
489 /* [ -ZZNOP, -1], */
490
491
492 /* Current number of OP codes. */
493
494
495 /* ID codes. The values exist in the integer domain */
496 /* [ 1, NID], */
497
498
499 /* General use, primarily testing. */
500
501
502 /* The user defined GF reference value. */
503
504
505 /* The user defined GF convergence tolerance. */
506
507
508 /* The user defined GF step for numeric differentiation. */
509
510
511 /* Current number of ID codes, dimension of array */
512 /* in ZZHOLDD. Bad things can happen if this parameter */
513 /* does not have the proper value. */
514
515
516 /* End of file zzholdd.inc. */
517
518 /* $ Brief_I/O */
519
520 /* Variable I/O Description */
521 /* -------- --- -------------------------------------------------- */
522 /* LBCELL P SPICE Cell lower bound. */
523 /* CNVTOL P Convergence tolerance. */
524 /* NWILUM P Number of workspace windows for angle search. */
525 /* METHOD I Computation method. */
526 /* ANGTYP I Type of illumination angle. */
527 /* TARGET I Name of the target body. */
528 /* ILLMN I Name of the illumination source. */
529 /* FIXREF I Body-fixed, body-centered target body frame. */
530 /* ABCORR I Aberration correction flag. */
531 /* OBSRVR I Name of the observing body. */
532 /* SPOINT I Body-fixed coordinates of a target surface point. */
533 /* RELATE I Relational operator. */
534 /* REFVAL I Reference value. */
535 /* ADJUST I Adjustment value for absolute extrema searches. */
536 /* STEP I Step size used for locating extrema and roots. */
537 /* CNFINE I SPICE window to which the search is confined. */
538 /* MW I Workspace window size. */
539 /* NW I Workspace window count. */
540 /* WORK I-O Array of workspace windows. */
541 /* RESULT I-O SPICE window containing results. */
542
543 /* $ Detailed_Input */
544
545 /* METHOD is a short string providing parameters defining */
546 /* the computation method to be used. Parameters */
547 /* include, but are not limited to, the shape model */
548 /* used to represent the surface of the target body. */
549
550 /* The only choice currently supported is */
551
552 /* 'Ellipsoid' The illumination angle */
553 /* computation uses a triaxial */
554 /* ellipsoid to model the surface */
555 /* of the target body. The */
556 /* ellipsoid's radii must be */
557 /* available in the kernel pool. */
558
559 /* Neither case nor blanks are significant in METHOD. */
560 /* For example, the string ' eLLipsoid ' is valid. */
561
562
563 /* ANGTYP is a string specifying the type of illumination */
564 /* angle for which a search is to be performed. The */
565 /* possible values of ANGTYP are */
566
567 /* 'PHASE' */
568 /* 'INCIDENCE' */
569 /* 'EMISSION' */
570
571 /* When the illumination source is the sun, the */
572 /* incidence angle is commonly called the "solar */
573 /* incidence angle." */
574
575 /* See the Particulars section below for a detailed */
576 /* description of these angles. */
577
578 /* Neither case nor white space are significant in */
579 /* ANGTYP. For example, the string ' Incidence ' is */
580 /* valid. */
581
582
583 /* TARGET is the name of a target body. The point at which the */
584 /* illumination angles are defined is located on the */
585 /* surface of this body. */
586
587 /* Optionally, you may supply the integer ID code for */
588 /* the object as an integer string. For example both */
589 /* 'MOON' and '301' are legitimate strings that indicate */
590 /* the moon is the target body. */
591
592 /* Neither case nor leading and trailing blanks are */
593 /* significant in TARGET. For example, the string */
594 /* ' Incidence ' is valid. Sequences of embedded blanks */
595 /* are treated as a single blank. */
596
597
598 /* ILLMN is the name of the illumination source. This source */
599 /* may be any ephemeris object. Case, blanks, and */
600 /* numeric values are treated in the same way as for the */
601 /* input TARGET. */
602
603
604 /* FIXREF is the name of the body-fixed, body-centered */
605 /* reference frame associated with the target body. The */
606 /* input surface point SPOINT is expressed relative to */
607 /* this reference frame, and this frame is used to */
608 /* define the orientation of the target body as a */
609 /* function of time. */
610
611 /* The string FIXREF is case-insensitive, and leading */
612 /* and trailing blanks in FIXREF are not significant. */
613
614
615 /* ABCORR indicates the aberration corrections to be applied to */
616 /* the observer-surface point vector, the surface point- */
617 /* illumination source vector, and the target body */
618 /* orientation to account for one-way light time and */
619 /* stellar aberration. */
620
621 /* Any "reception" correction accepted by SPKEZR can be */
622 /* used here. See the header of SPKEZR for a detailed */
623 /* description of the aberration correction options. For */
624 /* convenience, the options are listed below: */
625
626 /* 'NONE' Apply no correction. */
627
628 /* 'LT' "Reception" case: correct for */
629 /* one-way light time using a Newtonian */
630 /* formulation. */
631
632 /* 'LT+S' "Reception" case: correct for */
633 /* one-way light time and stellar */
634 /* aberration using a Newtonian */
635 /* formulation. */
636
637 /* 'CN' "Reception" case: converged */
638 /* Newtonian light time correction. */
639
640 /* 'CN+S' "Reception" case: converged */
641 /* Newtonian light time and stellar */
642 /* aberration corrections. */
643
644 /* Case and blanks are not significant in the string */
645 /* ABCORR. */
646
647
648 /* OBSRVR is the name of an observing body. Case, blanks, and */
649 /* numeric values are treated in the same way as for the */
650 /* input TARGET. */
651
652
653 /* SPOINT is a surface point on the target body, expressed in */
654 /* Cartesian coordinates, relative to the body-fixed */
655 /* target frame designated by FIXREF. */
656
657 /* SPOINT need not be visible from the observer's */
658 /* location in order for the constraint specified by */
659 /* RELATE and REFVAL (see descriptions below) to be */
660 /* satisfied. */
661
662 /* The components of SPOINT have units of km. */
663
664
665 /* RELATE is a relational operator used to define a constraint */
666 /* on a specified illumination angle. The result window */
667 /* found by this routine indicates the time intervals */
668 /* where the constraint is satisfied. Supported values */
669 /* of RELATE and corresponding meanings are shown below: */
670
671 /* '>' The angle is greater than the reference */
672 /* value REFVAL. */
673
674 /* '=' The angle is equal to the reference */
675 /* value REFVAL. */
676
677 /* '<' The angle is less than the reference */
678 /* value REFVAL. */
679
680
681 /* 'ABSMAX' The angle is at an absolute maximum. */
682
683 /* 'ABSMIN' The angle is at an absolute minimum. */
684
685 /* 'LOCMAX' The angle is at a local maximum. */
686
687 /* 'LOCMIN' The angle is at a local minimum. */
688
689 /* The caller may indicate that the window of interest is */
690 /* the set of time intervals where the angle is within a */
691 /* specified separation from an absolute extremum. The */
692 /* argument ADJUST (described below) is used to specify */
693 /* this separation. */
694
695 /* Local extrema are considered to exist only in the */
696 /* interiors of the intervals comprising the confinement */
697 /* window: a local extremum cannot exist at a boundary */
698 /* point of the confinement window. */
699
700 /* Case is not significant in the string RELATE. */
701
702
703 /* REFVAL is the reference value used together with the argument */
704 /* RELATE to define an equality or inequality to be */
705 /* satisfied by the specified illumination angle. See the */
706 /* discussion of RELATE above for further information. */
707
708 /* The units of REFVAL are radians. */
709
710
711 /* ADJUST is a parameter used to modify searches for absolute */
712 /* extrema: when RELATE is set to ABSMAX or ABSMIN and */
713 /* ADJUST is set to a positive value, GFILUM will find */
714 /* times when the specified illumination angle is within */
715 /* ADJUST radians of the specified extreme value. */
716
717 /* If ADJUST is non-zero and a search for an absolute */
718 /* minimum is performed, the result window contains */
719 /* time intervals when the specified illumination angle */
720 /* has values between the absolute minimum MIN */
721 /* MIN + ADJUST radians. */
722
723 /* If ADJUST is non-zero and the search is for an */
724 /* absolute maximum, the corresponding angle is between */
725 /* the absolute maximum MAX and MAX - ADJUST radians. */
726
727 /* ADJUST is not used for searches for local extrema, */
728 /* equality or inequality conditions. */
729
730
731 /* STEP is the step size to be used in the search. STEP must */
732 /* be short enough for a search using this step size to */
733 /* locate the time intervals where the specified */
734 /* illumination angle is monotone increasing or */
735 /* decreasing. However, STEP must not be *too* short, or */
736 /* the search will take an unreasonable amount of time. */
737
738 /* The choice of STEP affects the completeness but not */
739 /* the precision of solutions found by this routine; the */
740 /* precision is controlled by the convergence tolerance. */
741 /* See the discussion of the parameter CNVTOL for */
742 /* details. */
743
744 /* STEP has units of seconds. */
745
746
747 /* CNFINE is a SPICE window that confines the time period over */
748 /* which the specified search is conducted. CNFINE may */
749 /* consist of a single interval or a collection of */
750 /* intervals. */
751
752 /* In some cases the confinement window can be used to */
753 /* greatly reduce the time window that must be searched */
754 /* for the desired solution. See the Particulars section */
755 /* below for further discussion. */
756
757 /* See the Examples section below for a code example */
758 /* that shows how to create a confinement window. */
759
760 /* CNFINE must be initialized by the caller via the */
761 /* SPICELIB routine SSIZED. */
762
763
764 /* MW is a parameter specifying the length of the workspace */
765 /* array WORK (see description below) used by this */
766 /* routine. MW should be at least as large as TWICE the */
767 /* number of intervals within the search window on which */
768 /* the specified illumination angle is monotone increasing */
769 /* or decreasing. It does no harm to pick a value of */
770 /* MW larger than the minimum required to execute the */
771 /* specified search, but if MW is too small, the */
772 /* search will fail. */
773
774
775 /* WORK is an array used to store workspace windows. This */
776 /* array should be declared by the caller as shown: */
777
778 /* INCLUDE 'gf.inc' */
779 /* ... */
780
781 /* DOUBLE PRECISION WORK ( LBCELL : MW, NWILUM ) */
782
783 /* where MW is a constant declared by the caller and */
784 /* NWILUM is a constant defined in the SPICELIB INCLUDE */
785 /* file gf.inc. */
786
787 /* WORK need not be initialized by the caller. */
788
789
790 /* RESULT is the result window. RESULT must be initialized via a */
791 /* call to SSIZED. RESULT must be declared and initialized */
792 /* with sufficient size to capture the full set of time */
793 /* intervals within the search window on which the */
794 /* specified constraint is satisfied. */
795
796
797 /* $ Detailed_Output */
798
799 /* WORK is the input workspace array, modified by this */
800 /* routine. The caller should re-initialize this array */
801 /* before attempting to use it for any other purpose. */
802
803 /* RESULT is the window of intervals, contained within the */
804 /* confinement window CNFINE, on which the specified */
805 /* constraint is satisfied. */
806
807 /* The endpoints of the time intervals comprising RESULT */
808 /* are interpreted as seconds past J2000 TDB. */
809
810 /* If RESULT is non-empty on input, its contents will be */
811 /* discarded before gfilum_c conducts its search. */
812
813 /* If the search is for local extrema, or for absolute */
814 /* extrema with ADJUST set to zero, then normally each */
815 /* interval of RESULT will be a singleton: the left and */
816 /* right endpoints of each interval will be identical. */
817
818 /* If no times within the confinement window satisfy the */
819 /* constraint, RESULT will be returned with a */
820 /* cardinality of zero. */
821
822 /* $ Parameters */
823
824 /* LBCELL is the lower bound for SPICE Cell arrays. */
825
826 /* CNVTOL is the default convergence tolerance used for finding */
827 /* endpoints of the intervals comprising the result */
828 /* window. CNVTOL is also used for finding intermediate */
829 /* results; in particular, CNVTOL is used for finding the */
830 /* windows on which the specified illumination angle is */
831 /* increasing or decreasing. CNVTOL is used to determine */
832 /* when binary searches for roots should terminate: when */
833 /* a root is bracketed within an interval of length */
834 /* CNVTOL, the root is considered to have been found. */
835
836 /* The accuracy, as opposed to precision, of roots found */
837 /* by this routine depends on the accuracy of the input */
838 /* data. In most cases, the accuracy of solutions will be */
839 /* inferior to their precision. */
840
841 /* The calling program can reset the convergence */
842 /* tolerance; see the Particulars section below for */
843 /* further information. */
844
845
846 /* NWILUM is the number of workspace windows required by */
847 /* this routine. */
848
849 /* See INCLUDE file gf.inc for declarations and descriptions of */
850 /* parameters used throughout the GF subsystem. */
851
852 /* $ Exceptions */
853
854 /* 1) In order for this routine to produce correct results, */
855 /* the step size must be appropriate for the problem at hand. */
856 /* Step sizes that are too large may cause this routine to miss */
857 /* roots; step sizes that are too small may cause this routine */
858 /* to run unacceptably slowly and in some cases, find spurious */
859 /* roots. */
860
861 /* This routine does not diagnose invalid step sizes, except */
862 /* that if the step size is non-positive, the error */
863 /* SPICE(INVALIDSTEP) is signaled. */
864
865 /* 2) Due to numerical errors, in particular, */
866
867 /* - Truncation error in time values */
868 /* - Finite tolerance value */
869 /* - Errors in computed geometric quantities */
870
871 /* it is *normal* for the condition of interest to not always be */
872 /* satisfied near the endpoints of the intervals comprising the */
873 /* result window. */
874
875 /* The result window may need to be contracted slightly by the */
876 /* caller to achieve desired results. The SPICE window routine */
877 /* WNCOND can be used to contract the result window. */
878
879 /* 3) If the window size MW is less than 2, the error */
880 /* SPICE(INVALIDDIMENSION) will be signaled. */
881
882 /* 4) If the window count NW is less than NWILUM, the error */
883 /* SPICE(INVALIDDIMENSION) will be signaled. */
884
885 /* 5) If an error (typically cell overflow) occurs while performing */
886 /* window arithmetic, the error will be diagnosed by a routine */
887 /* in the call tree of this routine. */
888
889 /* 6) If the output SPICE window RESULT has insufficient capacity */
890 /* to hold the set of intervals on which the specified */
891 /* illumination angle condition is met, the error will be */
892 /* diagnosed by a routine in the call tree of this routine. If */
893 /* the result window has size less than 2, the error */
894 /* SPICE(INVALIDDIMENSION) will be signaled by this routine. */
895
896 /* 7) If the input target body-fixed frame FIXREF is not */
897 /* recognized, an error is signaled by a routine in the call */
898 /* tree of this routine. A frame name may fail to be recognized */
899 /* because a required frame specification kernel has not been */
900 /* loaded; another cause is a misspelling of the frame name. */
901
902 /* 8) If the input frame FIXREF is not centered at the target body, */
903 /* an error is signaled by a routine in the call tree of this */
904 /* routine. */
905
906 /* 9) If the input argument METHOD is not recognized, the error */
907 /* SPICE(INVALIDMETHOD) is signaled. */
908
909 /* 10) If the illumination angle type ANGTYP is not recognized, */
910 /* an error is signaled by a routine in the call tree */
911 /* of this routine. */
912
913 /* 11) If the relational operator RELATE is not recognized, an */
914 /* error is signaled by a routine in the call tree of this */
915 /* routine. */
916
917 /* 12) If the aberration correction specifier contains an */
918 /* unrecognized value, an error is signaled by a routine in the */
919 /* call tree of this routine. */
920
921 /* 13) If ADJUST is negative, an error is signaled by a routine in */
922 /* the call tree of this routine. */
923
924 /* 14) If any of the input body names do not map to NAIF ID */
925 /* codes, an error is signaled by a routine in the call tree of */
926 /* this routine. */
927
928 /* 15) If the target coincides with the observer or the illumination */
929 /* source, an error is signaled by a routine in the call tree */
930 /* of this routine. */
931
932 /* 16) If required ephemerides or other kernel data are not */
933 /* available, an error is signaled by a routine in the call tree */
934 /* of this routine. */
935
936 /* $ Files */
937
938 /* Appropriate kernels must be loaded by the calling program before */
939 /* this routine is called. */
940
941 /* The following data are required: */
942
943 /* - SPK data: ephemeris data for target, observer, and the */
944 /* illumination source must be loaded. If aberration */
945 /* corrections are used, the states of target, observer, and */
946 /* the illumination source relative to the solar system */
947 /* barycenter must be calculable from the available ephemeris */
948 /* data. Typically ephemeris data are made available by loading */
949 /* one or more SPK files via FURNSH. */
950
951 /* - PCK data: if the target body shape is modeled as an */
952 /* ellipsoid (currently no other shapes are supported), */
953 /* triaxial radii for the target body must be loaded */
954 /* into the kernel pool. Typically this is done by loading a */
955 /* text PCK file via FURNSH. */
956
957 /* - Further PCK data: rotation data for the target body must be */
958 /* loaded. These may be provided in a text or binary PCK file. */
959
960 /* - Frame data: if a frame definition not built into SPICE */
961 /* is required to convert the observer and target states to the */
962 /* body-fixed frame of the target, that definition must be */
963 /* available in the kernel pool. Typically the definition is */
964 /* supplied by loading a frame kernel via FURNSH. */
965
966 /* In all cases, kernel data are normally loaded once per program */
967 /* run, NOT every time this routine is called. */
968
969
970 /* $ Particulars */
971
972 /* This routine determines a set of one or more time intervals */
973 /* within the confinement window when the specified illumination */
974 /* angle satisfies a caller-specified constraint. The resulting set */
975 /* of intervals is returned as a SPICE window. */
976
977 /* The term "illumination angles" refers to the following set of */
978 /* angles: */
979
980
981 /* phase angle Angle between the vectors from the */
982 /* surface point to the observer and */
983 /* from the surface point to the */
984 /* illumination source. */
985
986 /* incidence angle Angle between the surface normal at */
987 /* the specified surface point and the */
988 /* vector from the surface point to the */
989 /* illumination source. When the sun is */
990 /* the illumination source, this angle is */
991 /* commonly called the "solar incidence */
992 /* angle." */
993
994 /* emission angle Angle between the surface normal at */
995 /* the specified surface point and the */
996 /* vector from the surface point to the */
997 /* observer. */
998
999 /* The diagram below illustrates the geometric relationships */
1000 /* defining these angles. The labels for the incidence, emission, */
1001 /* and phase angles are "inc.", "e.", and "phase". */
1002
1003
1004 /* * */
1005 /* illumination source */
1006
1007 /* surface normal vector */
1008 /* ._ _. */
1009 /* |\ /| illumination */
1010 /* \ phase / source vector */
1011 /* \ . . / */
1012 /* . . */
1013 /* \ ___ / */
1014 /* . \/ \/ */
1015 /* _\ inc./ */
1016 /* . / \ / */
1017 /* . | e. \ / */
1018 /* * <--------------- * surface point on */
1019 /* viewing vector target body */
1020 /* location to viewing */
1021 /* (observer) location */
1022
1023
1024 /* Note that if the target-observer vector, the target normal vector */
1025 /* at the surface point, and the target-illumination source vector */
1026 /* are coplanar, then phase is the sum of the incidence and emission */
1027 /* angles. This rarely occurs; usually */
1028
1029 /* phase angle < incidence angle + emission angle */
1030
1031 /* All of the above angles can be computed using light time */
1032 /* corrections, light time and stellar aberration corrections, or no */
1033 /* aberration corrections. In order to describe apparent geometry as */
1034 /* observed by a remote sensing instrument, both light time and */
1035 /* stellar aberration corrections should be used. */
1036
1037 /* The way aberration corrections are applied by this routine */
1038 /* is described below. */
1039
1040 /* Light time corrections */
1041 /* ====================== */
1042
1043 /* Observer-target surface point vector */
1044 /* ------------------------------------ */
1045
1046 /* Let ET be the epoch at which an observation or remote */
1047 /* sensing measurement is made, and let ET - LT ("LT" stands */
1048 /* for "light time") be the epoch at which the photons */
1049 /* received at ET were emitted from the surface point SPOINT. */
1050 /* Note that the light time between the surface point and */
1051 /* observer will generally differ from the light time between */
1052 /* the target body's center and the observer. */
1053
1054
1055 /* Target body's orientation */
1056 /* ------------------------- */
1057
1058 /* Using the definitions of ET and LT above, the target body's */
1059 /* orientation at ET - LT is used. The surface normal is */
1060 /* dependent on the target body's orientation, so the body's */
1061 /* orientation model must be evaluated for the correct epoch. */
1062
1063
1064 /* Target body -- illumination source vector */
1065 /* ----------------------------------------- */
1066
1067 /* The surface features on the target body near SPOINT will */
1068 /* appear in a measurement made at ET as they were at ET-LT. */
1069 /* In particular, lighting on the target body is dependent on */
1070 /* the apparent location of the illumination source as seen */
1071 /* from the target body at ET-LT. So, a second light time */
1072 /* correction is used to compute the position of the */
1073 /* illumination source relative to the surface point. */
1074
1075
1076 /* Stellar aberration corrections */
1077 /* ============================== */
1078
1079 /* Stellar aberration corrections are applied only if */
1080 /* light time corrections are applied as well. */
1081
1082 /* Observer-target surface point body vector */
1083 /* ----------------------------------------- */
1084
1085 /* When stellar aberration correction is performed, the */
1086 /* observer-to-surface point direction vector, which we'll */
1087 /* call SRFVEC, is adjusted so as to point to the apparent */
1088 /* position of SPOINT: considering SPOINT to be an ephemeris */
1089 /* object, SRFVEC points from the observer's position at ET to */
1090 /* the light time and stellar aberration */
1091 /* corrected position of SPOINT. */
1092
1093 /* Target body-illumination source vector */
1094 /* -------------------------------------- */
1095
1096 /* The target body-illumination source vector is the apparent */
1097 /* position of the illumination source, corrected for light */
1098 /* time and stellar aberration, as seen from the surface point */
1099 /* SPOINT at time ET-LT. */
1100
1101
1102 /* Below we discuss in greater detail aspects of this routine's */
1103 /* solution process that are relevant to correct and efficient */
1104 /* use of this routine in user applications. */
1105
1106
1107 /* The Search Process */
1108 /* ================== */
1109
1110 /* Regardless of the type of constraint selected by the caller, this */
1111 /* routine starts the search for solutions by determining the time */
1112 /* periods, within the confinement window, over which the specified */
1113 /* illumination angle is monotone increasing and monotone decreasing. */
1114 /* Each of these time periods is represented by a SPICE window. */
1115 /* Having found these windows, all of the illumination angle's local */
1116 /* extrema within the confinement window are known. Absolute extrema */
1117 /* then can be found very easily. */
1118
1119 /* Within any interval of these "monotone" windows, there will be at */
1120 /* most one solution of any equality constraint. Since the boundary */
1121 /* of the solution set for any inequality constraint is contained in */
1122 /* the union of */
1123
1124 /* - the set of points where an equality constraint is met */
1125 /* - the boundary points of the confinement window */
1126
1127 /* the solutions of both equality and inequality constraints can be */
1128 /* found easily once the monotone windows have been found. */
1129
1130
1131 /* Step Size */
1132 /* ========= */
1133
1134 /* The monotone windows (described above) are found via a two-step */
1135 /* search process. Each interval of the confinement window is */
1136 /* searched as follows: first, the input step size is used to */
1137 /* determine the time separation at which the sign of the rate of */
1138 /* change of the illumination angle will be sampled. Starting at the */
1139 /* left endpoint of an interval, samples will be taken at each step. */
1140 /* If a change of sign is found, a root has been bracketed; at that */
1141 /* point, the time at which the rate of change of the selected */
1142 /* illumination angle is zero can be found by a refinement process, */
1143 /* for example, via binary search. */
1144
1145 /* Note that the optimal choice of step size depends on the lengths */
1146 /* of the intervals over which the illumination angle is monotone: */
1147 /* the step size should be shorter than the shortest of these */
1148 /* intervals (within the confinement window). */
1149
1150 /* The optimal step size is *not* necessarily related to the lengths */
1151 /* of the intervals comprising the result window. For example, if */
1152 /* the shortest monotone interval has length 10 days, and if the */
1153 /* shortest result window interval has length 5 minutes, a step size */
1154 /* of 9.9 days is still adequate to find all of the intervals in the */
1155 /* result window. In situations like this, the technique of using */
1156 /* monotone windows yields a dramatic efficiency improvement over a */
1157 /* state-based search that simply tests at each step whether the */
1158 /* specified constraint is satisfied. The latter type of search can */
1159 /* miss solution intervals if the step size is longer than the */
1160 /* shortest solution interval. */
1161
1162 /* Having some knowledge of the relative geometry of the target, */
1163 /* observer, and illumination source can be a valuable aid in */
1164 /* picking a reasonable step size. In general, the user can */
1165 /* compensate for lack of such knowledge by picking a very short */
1166 /* step size; the cost is increased computation time. */
1167 /* Note that the step size is not related to the precision with which */
1168 /* the endpoints of the intervals of the result window are computed. */
1169 /* That precision level is controlled by the convergence tolerance. */
1170
1171
1172 /* Convergence Tolerance */
1173 /* ===================== */
1174
1175 /* As described above, the root-finding process used by this routine */
1176 /* involves first bracketing roots and then using a search process */
1177 /* to locate them. "Roots" are both times when local extrema are */
1178 /* attained and times when the illumination angle is equal to a */
1179 /* reference value. All endpoints of the intervals comprising the */
1180 /* result window are either endpoints of intervals of the */
1181 /* confinement window or roots. */
1182
1183 /* Once a root has been bracketed, a refinement process is used to */
1184 /* narrow down the time interval within which the root must lie. */
1185 /* This refinement process terminates when the location of the root */
1186 /* has been determined to within an error margin called the */
1187 /* "convergence tolerance." The convergence tolerance used by this */
1188 /* routine is set via the parameter CNVTOL. */
1189
1190 /* The value of CNVTOL is set to a "tight" value so that the */
1191 /* tolerance doesn't become the limiting factor in the accuracy of */
1192 /* solutions found by this routine. In general the accuracy of input */
1193 /* data will be the limiting factor. */
1194
1195 /* The user may change the convergence tolerance from the default */
1196 /* CNVTOL value by calling the routine GFSTOL, e.g. */
1197
1198 /* CALL GFSTOL( tolerance value in seconds ) */
1199
1200 /* Call GFSTOL prior to calling this routine. All subsequent */
1201 /* searches will use the updated tolerance value. */
1202
1203 /* Searches over time windows of long duration may require use of */
1204 /* larger tolerance values than the default: the tolerance must be */
1205 /* large enough so that it, when added to or subtracted from the */
1206 /* confinement window's lower and upper bounds, yields distinct time */
1207 /* values. */
1208
1209 /* Setting the tolerance tighter than CNVTOL is unlikely to be */
1210 /* useful, since the results are unlikely to be more accurate. */
1211 /* Making the tolerance looser will speed up searches somewhat, */
1212 /* since a few convergence steps will be omitted. */
1213
1214
1215 /* The Confinement Window */
1216 /* ====================== */
1217
1218 /* The simplest use of the confinement window is to specify a time */
1219 /* interval within which a solution is sought. However, the */
1220 /* confinement window can, in some cases, be used to make searches */
1221 /* more efficient. Sometimes it's possible to do an efficient search */
1222 /* to reduce the size of the time period over which a relatively */
1223 /* slow search of interest must be performed. */
1224
1225 /* $ Examples */
1226
1227
1228 /* The numerical results shown for these examples may differ across */
1229 /* platforms. The results depend on the SPICE kernels used as */
1230 /* input, the compiler and supporting libraries, and the machine */
1231 /* specific arithmetic implementation. */
1232
1233
1234 /* 1) Determine time intervals over which the MER-1 ("Opportunity") */
1235 /* rover's location satisfies certain constraints on its */
1236 /* illumination and visibility as seen from the Mars */
1237 /* Reconaissance Orbiter (MRO) spacecraft. */
1238
1239 /* In this case we require the emission angle to be less than */
1240 /* 20 degrees and the solar incidence angle to be less than */
1241 /* 60 degrees. */
1242
1243 /* The reader can verify that the observation start times of the */
1244 /* MRO HIRISE images */
1245
1246 /* Product ID Image start time */
1247 /* ---------- ---------------- */
1248 /* TRA_000873_1780_RED 2006-10-03T12:44:13.425 */
1249 /* PSP_001414_1780_RED 2006-11-14T15:39:55.373 */
1250 /* PSP_001612_1780_RED 2006-11-30T01:38:34.390 */
1251
1252 /* are contained within the result window found by the */
1253 /* example program shown below. */
1254
1255 /* Use the meta-kernel shown below to load the required SPICE */
1256 /* kernels. */
1257
1258
1259 /* KPL/MK */
1260
1261 /* File: mer1_ex.tm */
1262
1263 /* This meta-kernel is intended to support operation of SPICE */
1264 /* example programs. The kernels shown here should not be */
1265 /* assumed to contain adequate or correct versions of data */
1266 /* required by SPICE-based user applications. */
1267
1268 /* In order for an application to use this meta-kernel, the */
1269 /* kernels referenced here must be present in the user's */
1270 /* current working directory. */
1271
1272 /* The names and contents of the kernels referenced */
1273 /* by this meta-kernel are as follows: */
1274
1275 /* File name Contents */
1276 /* --------- -------- */
1277 /* de421.bsp Planetary ephemeris */
1278 /* pck00010.tpc Planet orientation */
1279 /* and radii */
1280 /* naif0010.tls Leapseconds */
1281 /* mro_psp1.bsp MRO ephemeris */
1282 /* mer1_surf_rover_ext10_v1.bsp MER-1 ephemeris */
1283 /* mer1_surf_rover_ext11_v1.bsp MER-1 ephemeris */
1284 /* mer1_ls_040128_iau2000_v1.bsp MER-1 landing site */
1285 /* ephemeris */
1286 /* mer1_v10.tf MER-1 frame kernel */
1287
1288
1289 /* \begindata */
1290
1291 /* KERNELS_TO_LOAD = ( 'de421.bsp', */
1292 /* 'pck00010.tpc', */
1293 /* 'naif0010.tls', */
1294 /* 'mro_psp1.bsp', */
1295 /* 'mer1_surf_rover_ext10_v1.bsp', */
1296 /* 'mer1_surf_rover_ext11_v1.bsp', */
1297 /* 'mer1_ls_040128_iau2000_v1.bsp', */
1298 /* 'mro_psp1.bsp', */
1299 /* 'mer1_v10.tf' ) */
1300 /* \begintext */
1301
1302
1303
1304 /* Example code begins here. */
1305
1306
1307 /* PROGRAM MER1_EX */
1308 /* IMPLICIT NONE */
1309 /* C */
1310 /* C Global parameters */
1311 /* C */
1312 /* INCLUDE 'gf.inc' */
1313 /* INCLUDE 'zzabcorr.inc' */
1314
1315 /* C */
1316 /* C SPICE cell lower bound: */
1317 /* C */
1318 /* INTEGER LBCELL */
1319 /* PARAMETER ( LBCELL = -5 ) */
1320
1321 /* C */
1322 /* C SPICELIB functions */
1323 /* C */
1324 /* DOUBLE PRECISION DPR */
1325 /* DOUBLE PRECISION RPD */
1326
1327 /* INTEGER WNCARD */
1328
1329 /* C */
1330 /* C Local parameters */
1331 /* C */
1332 /* C */
1333 /* C Output time format: */
1334 /* C */
1335 /* CHARACTER*(*) FMT */
1336 /* PARAMETER ( FMT = */
1337 /* . 'YYYY MON DD HR:MN:SC.###### UTC' ) */
1338
1339 /* C */
1340 /* C Meta-kernel name: */
1341 /* C */
1342 /* CHARACTER*(*) META */
1343 /* PARAMETER ( META = 'mer1_ex.tm' ) */
1344
1345 /* C */
1346 /* C Maximum number of intervals in the windows */
1347 /* C used in this program: */
1348 /* C */
1349 /* INTEGER MAXIVL */
1350 /* PARAMETER ( MAXIVL = 1000 ) */
1351
1352 /* INTEGER MAXWIN */
1353 /* PARAMETER ( MAXWIN = 2 * MAXIVL ) */
1354
1355 /* C */
1356 /* C Maximum length of reference frame name: */
1357 /* C */
1358 /* INTEGER FRNMLN */
1359 /* PARAMETER ( FRNMLN = 32 ) */
1360
1361 /* C */
1362 /* C Maximum length of body name: */
1363 /* C */
1364 /* INTEGER BDNMLN */
1365 /* PARAMETER ( BDNMLN = 36 ) */
1366
1367 /* C */
1368 /* C Maximum length of time string: */
1369 /* C */
1370 /* INTEGER TIMLEN */
1371 /* PARAMETER ( TIMLEN = 40 ) */
1372
1373 /* C */
1374 /* C Length of computation method string: */
1375 /* C */
1376 /* INTEGER METLEN */
1377 /* PARAMETER ( METLEN = 80 ) */
1378
1379 /* C */
1380 /* C Local variables */
1381 /* C */
1382 /* CHARACTER*(CORLEN) ABCORR */
1383 /* CHARACTER*(FRNMLN) FIXREF */
1384 /* CHARACTER*(BDNMLN) ILLMN */
1385 /* CHARACTER*(METLEN) METHOD */
1386 /* CHARACTER*(BDNMLN) OBSRVR */
1387 /* CHARACTER*(BDNMLN) TARGET */
1388 /* CHARACTER*(TIMLEN) TIMSTR */
1389 /* CHARACTER*(TIMLEN) UTCBEG */
1390 /* CHARACTER*(TIMLEN) UTCEND */
1391
1392 /* DOUBLE PRECISION ADJUST */
1393 /* DOUBLE PRECISION CNFINE ( LBCELL : MAXWIN ) */
1394 /* DOUBLE PRECISION EMISSN */
1395 /* DOUBLE PRECISION ET0 */
1396 /* DOUBLE PRECISION ET1 */
1397 /* DOUBLE PRECISION FINISH */
1398 /* DOUBLE PRECISION PHASE */
1399 /* DOUBLE PRECISION REFVAL */
1400 /* DOUBLE PRECISION RESULT ( LBCELL : MAXWIN ) */
1401 /* DOUBLE PRECISION ROVLT */
1402 /* DOUBLE PRECISION ROVPOS ( 3 ) */
1403 /* DOUBLE PRECISION SOLAR */
1404 /* DOUBLE PRECISION SRFVEC ( 3 ) */
1405 /* DOUBLE PRECISION START */
1406 /* DOUBLE PRECISION STEP */
1407 /* DOUBLE PRECISION TRGEPC */
1408 /* DOUBLE PRECISION WORK ( LBCELL : MAXWIN, NWILUM ) */
1409 /* DOUBLE PRECISION WNSOLR ( LBCELL : MAXWIN ) */
1410
1411 /* INTEGER I */
1412
1413 /* C */
1414 /* C Load kernels: */
1415 /* C */
1416 /* CALL FURNSH ( META ) */
1417
1418 /* C */
1419 /* C Set window sizes: */
1420 /* C */
1421 /* CALL SSIZED ( 2, CNFINE ) */
1422 /* CALL SSIZED ( MAXWIN, RESULT ) */
1423 /* CALL SSIZED ( MAXWIN, WNSOLR ) */
1424
1425 /* C */
1426 /* C Set the search interval: */
1427 /* C */
1428 /* UTCBEG = '2006 OCT 02 00:00:00 UTC' */
1429 /* CALL STR2ET ( UTCBEG, ET0 ) */
1430
1431 /* UTCEND = '2006 NOV 30 12:00:00 UTC' */
1432 /* CALL STR2ET ( UTCEND, ET1 ) */
1433
1434 /* CALL WNINSD ( ET0, ET1, CNFINE ) */
1435
1436 /* C */
1437 /* C Set observer, target, aberration correction, and the */
1438 /* C Mars body-fixed, body-centered reference frame. The */
1439 /* C lighting source is the sun. */
1440 /* C */
1441 /* C Aberration corrections are set for remote observations. */
1442 /* C */
1443 /* ILLMN = 'SUN' */
1444 /* OBSRVR = 'MRO' */
1445 /* TARGET = 'MARS' */
1446 /* ABCORR = 'CN+S' */
1447 /* FIXREF = 'IAU_MARS' */
1448
1449 /* C */
1450 /* C Use the rover position at the start of */
1451 /* C the search interval as the surface point. */
1452 /* C */
1453 /* CALL SPKPOS ( 'MER-1', ET0, FIXREF, */
1454 /* . 'NONE', TARGET, ROVPOS, ROVLT ) */
1455
1456 /* C */
1457 /* C Initialize the adjustment value for absolute */
1458 /* C extremum searches. We're not performing */
1459 /* C such searches in this example, but this input */
1460 /* C to GFILUM must still be set. */
1461 /* C */
1462 /* ADJUST = 0.D0 */
1463
1464 /* C */
1465 /* C The computation uses an ellipsoidal model for the */
1466 /* C target body shape. */
1467 /* C */
1468 /* METHOD = 'Ellipsoid' */
1469
1470 /* C */
1471 /* C Set the reference value to use for the solar */
1472 /* C incidence angle search. */
1473 /* C */
1474 /* REFVAL = 60.D0 * RPD() */
1475
1476 /* C */
1477 /* C Since the period of the solar incidence angle */
1478 /* C is about one Martian day, we can safely use 6 hours */
1479 /* C as the search step. */
1480 /* C */
1481 /* STEP = 21600.D0 */
1482
1483 /* C */
1484 /* C Search over the confinement window for times */
1485 /* C when the solar incidence angle is less than */
1486 /* C the reference value. */
1487 /* C */
1488 /* CALL GFILUM ( METHOD, 'INCIDENCE', TARGET, ILLMN, */
1489 /* . FIXREF, ABCORR, OBSRVR, ROVPOS, */
1490 /* . '<', REFVAL, ADJUST, STEP, CNFINE, */
1491 /* . MAXWIN, NWILUM, WORK, WNSOLR ) */
1492
1493 /* C */
1494 /* C With the search on the incidence angle complete, perform */
1495 /* C a search on the emission angle. */
1496 /* C */
1497 /* C Set the reference value for the emission angle search. */
1498 /* C */
1499 /* REFVAL = 20D0 * RPD() */
1500
1501 /* C */
1502 /* C We'll use 15 minutes as the search step. This step */
1503 /* C is small enough to be suitable for Mars orbiters. */
1504 /* C Units are seconds. */
1505 /* C */
1506 /* STEP = 900.D0 */
1507
1508 /* C */
1509 /* C Search over the previous result window for times when the */
1510 /* C emission angle is less than the reference value. */
1511 /* C */
1512 /* CALL GFILUM ( METHOD, 'EMISSION', TARGET, ILLMN, */
1513 /* . FIXREF, ABCORR, OBSRVR, ROVPOS, */
1514 /* . '<', REFVAL, ADJUST, STEP, */
1515 /* . WNSOLR, MAXWIN, NWILUM, WORK, RESULT ) */
1516
1517 /* C */
1518 /* C Display the result window. Show the solar incidence */
1519 /* C and emission angles at the window's interval */
1520 /* C boundaries. */
1521 /* C */
1522 /* WRITE (*,*) ' ' */
1523
1524 /* IF ( WNCARD( RESULT ) .EQ. 0 ) THEN */
1525
1526 /* WRITE (*,*) ' Window is empty: condition ' */
1527 /* . // 'is not met.' */
1528
1529 /* ELSE */
1530
1531 /* WRITE (*,*) ' ' */
1532 /* . // ' Solar Incidence Emission' */
1533 /* WRITE (*,*) ' ' */
1534 /* . // ' (deg) (deg)' */
1535 /* WRITE (*,*) ' ' */
1536
1537 /* DO I = 1, WNCARD( RESULT ) */
1538
1539 /* CALL WNFETD ( RESULT, I, START, FINISH ) */
1540
1541 /* CALL TIMOUT ( START, FMT, TIMSTR ) */
1542 /* C */
1543 /* C Compute the angles of interest at the boundary */
1544 /* C epochs. */
1545 /* C */
1546 /* CALL ILUMIN ( METHOD, TARGET, START, FIXREF, */
1547 /* . ABCORR, OBSRVR, ROVPOS, TRGEPC, */
1548 /* . SRFVEC, PHASE, SOLAR, EMISSN ) */
1549
1550 /* WRITE (*, '(A11, A31, 2F15.9)' ) */
1551 /* . 'Start: ', TIMSTR, SOLAR*DPR(), EMISSN*DPR() */
1552
1553
1554 /* CALL TIMOUT ( FINISH, FMT, TIMSTR ) */
1555
1556 /* CALL ILUMIN ( METHOD, TARGET, FINISH, FIXREF, */
1557 /* . ABCORR, OBSRVR, ROVPOS, TRGEPC, */
1558 /* . SRFVEC, PHASE, SOLAR, EMISSN ) */
1559
1560 /* WRITE (*, '(A11, A31, 2F15.9)' ) */
1561 /* . 'Stop: ', TIMSTR, SOLAR*DPR(), EMISSN*DPR() */
1562
1563 /* WRITE (*,*) ' ' */
1564
1565 /* END DO */
1566
1567 /* END IF */
1568
1569 /* END */
1570
1571
1572 /* When this program was executed on a PC/Linux/gfortran */
1573 /* platform, the output was: */
1574
1575
1576 /* Solar Incidence Emission */
1577 /* (deg) (deg) */
1578
1579 /* Start: 2006 OCT 03 12:43:46.949483 UTC 56.104150191 20.000000187 */
1580 /* Stop: 2006 OCT 03 12:44:42.288747 UTC 56.299961806 20.000000155 */
1581
1582 /* Start: 2006 OCT 08 16:03:33.956839 UTC 56.489554846 20.000000207 */
1583 /* Stop: 2006 OCT 08 16:04:29.495919 UTC 56.687545101 19.999999969 */
1584
1585 /* Start: 2006 OCT 13 19:23:24.634854 UTC 56.887410591 19.999999879 */
1586 /* Stop: 2006 OCT 13 19:24:12.492952 UTC 57.059318573 20.000000174 */
1587
1588 /* Start: 2006 OCT 18 22:43:21.631086 UTC 57.309244667 20.000000118 */
1589 /* Stop: 2006 OCT 18 22:43:47.966990 UTC 57.404572725 20.000000043 */
1590
1591 /* Start: 2006 NOV 14 15:39:44.153177 UTC 54.328758385 19.999999935 */
1592 /* Stop: 2006 NOV 14 15:40:10.446479 UTC 54.426680766 19.999999896 */
1593
1594 /* Start: 2006 NOV 19 18:59:10.190551 UTC 54.630961112 20.000000067 */
1595 /* Stop: 2006 NOV 19 18:59:54.776369 UTC 54.798407529 19.999999848 */
1596
1597 /* Start: 2006 NOV 24 22:18:38.342454 UTC 54.949599996 19.999999822 */
1598 /* Stop: 2006 NOV 24 22:19:30.964843 UTC 55.148838833 20.000000029 */
1599
1600 /* Start: 2006 NOV 30 01:38:07.309245 UTC 55.280547838 19.999999832 */
1601 /* Stop: 2006 NOV 30 01:39:03.296253 UTC 55.494189248 19.999999989 */
1602
1603
1604
1605 /* $ Restrictions */
1606
1607 /* 1) The kernel files to be used by this routine must be loaded */
1608 /* (normally using the SPICELIB routine FURNSH) before this */
1609 /* routine is called. */
1610
1611 /* 2) This routine has the side effect of re-initializing the */
1612 /* illumination angle utility package. Callers may */
1613 /* need to re-initialize the package after calling this routine. */
1614
1615 /* $ Literature_References */
1616
1617 /* None. */
1618
1619 /* $ Author_and_Institution */
1620
1621 /* N.J. Bachman (JPL) */
1622 /* B.V. Semenov (JPL) */
1623 /* E.D. Wright (JPL) */
1624
1625 /* $ Version */
1626
1627 /* - SPICELIB Version 1.0.0, 20-NOV-2012 (NJB) (BVS) (EDW) */
1628
1629 /* -& */
1630 /* $ Index_Entries */
1631
1632 /* solve for illumination_angle constraints */
1633 /* solve for phase_angle constraints */
1634 /* solve for solar_incidence_angle constraints */
1635 /* solve for incidence_angle constraints */
1636 /* solve for emission_angle constraints */
1637 /* search using illumination_angle constraints */
1638 /* search using lighting_angle constraints */
1639
1640 /* -& */
1641
1642 /* SPICELIB functions */
1643
1644
1645 /* External functions */
1646
1647
1648 /* Interrupt indicator function: */
1649
1650
1651 /* Routines to set step size, refine transition times */
1652 /* and report work. */
1653
1654
1655 /* Local parameters */
1656
1657
1658 /* Local variables */
1659
1660
1661 /* Quantity definition parameter arrays: */
1662
1663
1664 /* Other local variables */
1665
1666
1667 /* Standard SPICE error handling. */
1668
1669 /* Parameter adjustments */
1670 work_dim1 = *mw + 6;
1671 work_offset = work_dim1 - 5;
1672
1673 /* Function Body */
1674 if (return_()) {
1675 return 0;
1676 }
1677 chkin_("GFILUM", (ftnlen)6);
1678
1679 /* Check the result window's size. */
1680
1681 if (sized_(result) < 2) {
1682 setmsg_("Result window size must be at least 2 but was #.", (ftnlen)
1683 48);
1684 i__1 = sized_(result);
1685 errint_("#", &i__1, (ftnlen)1);
1686 sigerr_("SPICE(INVALIDDIMENSION)", (ftnlen)23);
1687 chkout_("GFILUM", (ftnlen)6);
1688 return 0;
1689 }
1690
1691 /* Check the workspace window dimensions. */
1692
1693 if (*mw < 2) {
1694 setmsg_("Workspace window size was #; size must be at least 2.", (
1695 ftnlen)53);
1696 errint_("#", mw, (ftnlen)1);
1697 sigerr_("SPICE(INVALIDDIMENSION)", (ftnlen)23);
1698 chkout_("GFILUM", (ftnlen)6);
1699 return 0;
1700 }
1701 if (*nw < 5) {
1702 setmsg_("Workspace window count was #; count must be at least #.", (
1703 ftnlen)55);
1704 errint_("#", nw, (ftnlen)1);
1705 errint_("#", &c__5, (ftnlen)1);
1706 sigerr_("SPICE(INVALIDDIMENSION)", (ftnlen)23);
1707 chkout_("GFILUM", (ftnlen)6);
1708 return 0;
1709 }
1710
1711 /* Set up a call to GFEVNT, which will handle the search. */
1712
1713 s_copy(qpnams, "TARGET", (ftnlen)80, (ftnlen)6);
1714 s_copy(qcpars, target, (ftnlen)80, target_len);
1715 s_copy(qpnams + 80, "ILLUM", (ftnlen)80, (ftnlen)5);
1716 s_copy(qcpars + 80, illmn, (ftnlen)80, illmn_len);
1717 s_copy(qpnams + 160, "OBSERVER", (ftnlen)80, (ftnlen)8);
1718 s_copy(qcpars + 160, obsrvr, (ftnlen)80, obsrvr_len);
1719 s_copy(qpnams + 240, "ABCORR", (ftnlen)80, (ftnlen)6);
1720 s_copy(qcpars + 240, abcorr, (ftnlen)80, abcorr_len);
1721 s_copy(qpnams + 320, "REFERENCE FRAME", (ftnlen)80, (ftnlen)15);
1722 s_copy(qcpars + 320, fixref, (ftnlen)80, fixref_len);
1723 s_copy(qpnams + 400, "ANGTYP", (ftnlen)80, (ftnlen)6);
1724 s_copy(qcpars + 400, angtyp, (ftnlen)80, angtyp_len);
1725 s_copy(qpnams + 480, "METHOD", (ftnlen)80, (ftnlen)6);
1726 s_copy(qcpars + 480, method, (ftnlen)80, method_len);
1727
1728 /* Copy SPOINT to elements 1-3 of the QDPARS array. */
1729
1730 s_copy(qpnams + 560, "SPOINT", (ftnlen)80, (ftnlen)6);
1731 moved_(spoint, &c__3, qdpars);
1732
1733 /* Set the step size. */
1734
1735 if (*step <= 0.) {
1736 setmsg_("Step size was #; step size must be positive.", (ftnlen)44);
1737 errdp_("#", step, (ftnlen)1);
1738 sigerr_("SPICE(INVALIDSTEP)", (ftnlen)18);
1739 chkout_("GFILUM", (ftnlen)6);
1740 return 0;
1741 }
1742 gfsstp_(step);
1743
1744 /* Retrieve the convergence tolerance, if set. */
1745
1746 zzholdd_(&c_n1, &c__3, &ok, &tol);
1747
1748 /* Use the default value CNVTOL if there's no stored tolerance */
1749 /* value. */
1750
1751 if (! ok) {
1752 tol = 1e-6;
1753 }
1754
1755 /* Initialize the RESULT window. */
1756
1757 scardd_(&c__0, result);
1758
1759 /* Look for solutions. */
1760
1761 /* Progress report and bail-out options are set to .FALSE. */
1762
1763 gfevnt_((U_fp)gfstep_, (U_fp)gfrefn_, "ILLUMINATION ANGLE", &c__8, qpnams,
1764 qcpars, qdpars, qipars, qlpars, relate, refval, &tol, adjust,
1765 cnfine, &c_false, (U_fp)gfrepi_, (U_fp)gfrepu_, (U_fp)gfrepf_, mw,
1766 &c__5, work, &c_false, (L_fp)gfbail_, result, (ftnlen)18, (
1767 ftnlen)80, (ftnlen)80, relate_len);
1768 chkout_("GFILUM", (ftnlen)6);
1769 return 0;
1770 } /* gfilum_ */
1771
1772