1 /* zzspkfzt.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__6 = 6;
11
12 /* $Procedure ZZSPKFZT ( SPK function, easy reader, target ) */
zzspkfzt_(S_fp trgsub,doublereal * et,char * ref,char * abcorr,integer * obs,doublereal * starg,doublereal * lt,ftnlen ref_len,ftnlen abcorr_len)13 /* Subroutine */ int zzspkfzt_(S_fp trgsub, doublereal *et, char *ref, char *
14 abcorr, integer *obs, doublereal *starg, doublereal *lt, ftnlen
15 ref_len, ftnlen abcorr_len)
16 {
17 /* Initialized data */
18
19 static logical first = TRUE_;
20 static char prvcor[5] = " ";
21
22 /* System generated locals */
23 doublereal d__1;
24
25 /* Builtin functions */
26 integer s_cmp(char *, char *, ftnlen, ftnlen);
27 /* Subroutine */ int s_copy(char *, char *, ftnlen, ftnlen);
28
29 /* Local variables */
30 static integer fj2000, type__;
31 static logical xmit;
32 extern /* Subroutine */ int mxvg_(doublereal *, doublereal *, integer *,
33 integer *, doublereal *), zzvalcor_(char *, logical *, ftnlen),
34 zzspkfat_(S_fp, doublereal *, char *, char *, integer *,
35 doublereal *, doublereal *, doublereal *, ftnlen, ftnlen),
36 zzcorsxf_(logical *, doublereal *, doublereal *, doublereal *),
37 vaddg_(doublereal *, doublereal *, integer *, doublereal *),
38 chkin_(char *, ftnlen), errch_(char *, char *, ftnlen, ftnlen);
39 static logical found;
40 static doublereal state[6], stemp[6], stobs[6], xform[36] /* was [6][6]
41 */;
42 extern doublereal vnorm_(doublereal *);
43 extern logical failed_(void);
44 extern /* Subroutine */ int frmchg_(integer *, integer *, doublereal *,
45 doublereal *);
46 extern doublereal clight_(void);
47 static integer center;
48 static logical attblk[15];
49 extern /* Subroutine */ int namfrm_(char *, integer *, ftnlen), frinfo_(
50 integer *, integer *, integer *, integer *, logical *);
51 static logical usegeo;
52 static doublereal ltcent;
53 extern /* Subroutine */ int spkgeo_(integer *, doublereal *, char *,
54 integer *, doublereal *, doublereal *, ftnlen);
55 static doublereal dltctr, corxfm[36] /* was [6][6] */;
56 static integer reqfrm, ltsign, typeid;
57 extern /* Subroutine */ int chkout_(char *, ftnlen), setmsg_(char *,
58 ftnlen), sigerr_(char *, ftnlen);
59 static integer trgctr;
60 extern /* Subroutine */ int spkssb_(integer *, doublereal *, char *,
61 doublereal *, ftnlen), spkltc_(integer *, doublereal *, char *,
62 char *, doublereal *, doublereal *, doublereal *, doublereal *,
63 ftnlen, ftnlen);
64 extern logical return_(void);
65 static doublereal sttctr[6], dlt;
66
67 /* $ Abstract */
68
69 /* SPICE Private routine intended solely for the support of SPICE */
70 /* routines. Users should not call this routine directly due */
71 /* to the volatile nature of this routine. */
72
73 /* Return the state (position and velocity) of a target body */
74 /* relative to an observing body, optionally corrected for light */
75 /* time (planetary aberration) and stellar aberration. An input */
76 /* subroutine provides the state of the target relative to its */
77 /* center of motion. */
78
79 /* $ Disclaimer */
80
81 /* THIS SOFTWARE AND ANY RELATED MATERIALS WERE CREATED BY THE */
82 /* CALIFORNIA INSTITUTE OF TECHNOLOGY (CALTECH) UNDER A U.S. */
83 /* GOVERNMENT CONTRACT WITH THE NATIONAL AERONAUTICS AND SPACE */
84 /* ADMINISTRATION (NASA). THE SOFTWARE IS TECHNOLOGY AND SOFTWARE */
85 /* PUBLICLY AVAILABLE UNDER U.S. EXPORT LAWS AND IS PROVIDED "AS-IS" */
86 /* TO THE RECIPIENT WITHOUT WARRANTY OF ANY KIND, INCLUDING ANY */
87 /* WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR A */
88 /* PARTICULAR USE OR PURPOSE (AS SET FORTH IN UNITED STATES UCC */
89 /* SECTIONS 2312-2313) OR FOR ANY PURPOSE WHATSOEVER, FOR THE */
90 /* SOFTWARE AND RELATED MATERIALS, HOWEVER USED. */
91
92 /* IN NO EVENT SHALL CALTECH, ITS JET PROPULSION LABORATORY, OR NASA */
93 /* BE LIABLE FOR ANY DAMAGES AND/OR COSTS, INCLUDING, BUT NOT */
94 /* LIMITED TO, INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANY KIND, */
95 /* INCLUDING ECONOMIC DAMAGE OR INJURY TO PROPERTY AND LOST PROFITS, */
96 /* REGARDLESS OF WHETHER CALTECH, JPL, OR NASA BE ADVISED, HAVE */
97 /* REASON TO KNOW, OR, IN FACT, SHALL KNOW OF THE POSSIBILITY. */
98
99 /* RECIPIENT BEARS ALL RISK RELATING TO QUALITY AND PERFORMANCE OF */
100 /* THE SOFTWARE AND ANY RELATED MATERIALS, AND AGREES TO INDEMNIFY */
101 /* CALTECH AND NASA FOR ALL THIRD-PARTY CLAIMS RESULTING FROM THE */
102 /* ACTIONS OF RECIPIENT IN THE USE OF THE SOFTWARE. */
103
104 /* $ Required_Reading */
105
106 /* SPK */
107 /* NAIF_IDS */
108 /* FRAMES */
109 /* TIME */
110
111 /* $ Keywords */
112
113 /* EPHEMERIS */
114
115 /* $ Declarations */
116 /* $ Abstract */
117
118 /* The parameters below form an enumerated list of the recognized */
119 /* frame types. They are: INERTL, PCK, CK, TK, DYN. The meanings */
120 /* are outlined below. */
121
122 /* $ Disclaimer */
123
124 /* THIS SOFTWARE AND ANY RELATED MATERIALS WERE CREATED BY THE */
125 /* CALIFORNIA INSTITUTE OF TECHNOLOGY (CALTECH) UNDER A U.S. */
126 /* GOVERNMENT CONTRACT WITH THE NATIONAL AERONAUTICS AND SPACE */
127 /* ADMINISTRATION (NASA). THE SOFTWARE IS TECHNOLOGY AND SOFTWARE */
128 /* PUBLICLY AVAILABLE UNDER U.S. EXPORT LAWS AND IS PROVIDED "AS-IS" */
129 /* TO THE RECIPIENT WITHOUT WARRANTY OF ANY KIND, INCLUDING ANY */
130 /* WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR A */
131 /* PARTICULAR USE OR PURPOSE (AS SET FORTH IN UNITED STATES UCC */
132 /* SECTIONS 2312-2313) OR FOR ANY PURPOSE WHATSOEVER, FOR THE */
133 /* SOFTWARE AND RELATED MATERIALS, HOWEVER USED. */
134
135 /* IN NO EVENT SHALL CALTECH, ITS JET PROPULSION LABORATORY, OR NASA */
136 /* BE LIABLE FOR ANY DAMAGES AND/OR COSTS, INCLUDING, BUT NOT */
137 /* LIMITED TO, INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANY KIND, */
138 /* INCLUDING ECONOMIC DAMAGE OR INJURY TO PROPERTY AND LOST PROFITS, */
139 /* REGARDLESS OF WHETHER CALTECH, JPL, OR NASA BE ADVISED, HAVE */
140 /* REASON TO KNOW, OR, IN FACT, SHALL KNOW OF THE POSSIBILITY. */
141
142 /* RECIPIENT BEARS ALL RISK RELATING TO QUALITY AND PERFORMANCE OF */
143 /* THE SOFTWARE AND ANY RELATED MATERIALS, AND AGREES TO INDEMNIFY */
144 /* CALTECH AND NASA FOR ALL THIRD-PARTY CLAIMS RESULTING FROM THE */
145 /* ACTIONS OF RECIPIENT IN THE USE OF THE SOFTWARE. */
146
147 /* $ Parameters */
148
149 /* INERTL an inertial frame that is listed in the routine */
150 /* CHGIRF and that requires no external file to */
151 /* compute the transformation from or to any other */
152 /* inertial frame. */
153
154 /* PCK is a frame that is specified relative to some */
155 /* INERTL frame and that has an IAU model that */
156 /* may be retrieved from the PCK system via a call */
157 /* to the routine TISBOD. */
158
159 /* CK is a frame defined by a C-kernel. */
160
161 /* TK is a "text kernel" frame. These frames are offset */
162 /* from their associated "relative" frames by a */
163 /* constant rotation. */
164
165 /* DYN is a "dynamic" frame. These currently are */
166 /* parameterized, built-in frames where the full frame */
167 /* definition depends on parameters supplied via a */
168 /* frame kernel. */
169
170 /* ALL indicates any of the above classes. This parameter */
171 /* is used in APIs that fetch information about frames */
172 /* of a specified class. */
173
174
175 /* $ Author_and_Institution */
176
177 /* N.J. Bachman (JPL) */
178 /* W.L. Taber (JPL) */
179
180 /* $ Literature_References */
181
182 /* None. */
183
184 /* $ Version */
185
186 /* - SPICELIB Version 4.0.0, 08-MAY-2012 (NJB) */
187
188 /* The parameter ALL was added to support frame fetch APIs. */
189
190 /* - SPICELIB Version 3.0.0, 28-MAY-2004 (NJB) */
191
192 /* The parameter DYN was added to support the dynamic frame class. */
193
194 /* - SPICELIB Version 2.0.0, 12-DEC-1996 (WLT) */
195
196 /* Various unused frames types were removed and the */
197 /* frame time TK was added. */
198
199 /* - SPICELIB Version 1.0.0, 10-DEC-1995 (WLT) */
200
201 /* -& */
202
203 /* End of INCLUDE file frmtyp.inc */
204
205 /* $ Abstract */
206
207 /* Include file zzabcorr.inc */
208
209 /* SPICE private file intended solely for the support of SPICE */
210 /* routines. Users should not include this file directly due */
211 /* to the volatile nature of this file */
212
213 /* The parameters below define the structure of an aberration */
214 /* correction attribute block. */
215
216 /* $ Disclaimer */
217
218 /* THIS SOFTWARE AND ANY RELATED MATERIALS WERE CREATED BY THE */
219 /* CALIFORNIA INSTITUTE OF TECHNOLOGY (CALTECH) UNDER A U.S. */
220 /* GOVERNMENT CONTRACT WITH THE NATIONAL AERONAUTICS AND SPACE */
221 /* ADMINISTRATION (NASA). THE SOFTWARE IS TECHNOLOGY AND SOFTWARE */
222 /* PUBLICLY AVAILABLE UNDER U.S. EXPORT LAWS AND IS PROVIDED "AS-IS" */
223 /* TO THE RECIPIENT WITHOUT WARRANTY OF ANY KIND, INCLUDING ANY */
224 /* WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR A */
225 /* PARTICULAR USE OR PURPOSE (AS SET FORTH IN UNITED STATES UCC */
226 /* SECTIONS 2312-2313) OR FOR ANY PURPOSE WHATSOEVER, FOR THE */
227 /* SOFTWARE AND RELATED MATERIALS, HOWEVER USED. */
228
229 /* IN NO EVENT SHALL CALTECH, ITS JET PROPULSION LABORATORY, OR NASA */
230 /* BE LIABLE FOR ANY DAMAGES AND/OR COSTS, INCLUDING, BUT NOT */
231 /* LIMITED TO, INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANY KIND, */
232 /* INCLUDING ECONOMIC DAMAGE OR INJURY TO PROPERTY AND LOST PROFITS, */
233 /* REGARDLESS OF WHETHER CALTECH, JPL, OR NASA BE ADVISED, HAVE */
234 /* REASON TO KNOW, OR, IN FACT, SHALL KNOW OF THE POSSIBILITY. */
235
236 /* RECIPIENT BEARS ALL RISK RELATING TO QUALITY AND PERFORMANCE OF */
237 /* THE SOFTWARE AND ANY RELATED MATERIALS, AND AGREES TO INDEMNIFY */
238 /* CALTECH AND NASA FOR ALL THIRD-PARTY CLAIMS RESULTING FROM THE */
239 /* ACTIONS OF RECIPIENT IN THE USE OF THE SOFTWARE. */
240
241 /* $ Parameters */
242
243 /* An aberration correction attribute block is an array of logical */
244 /* flags indicating the attributes of the aberration correction */
245 /* specified by an aberration correction string. The attributes */
246 /* are: */
247
248 /* - Is the correction "geometric"? */
249
250 /* - Is light time correction indicated? */
251
252 /* - Is stellar aberration correction indicated? */
253
254 /* - Is the light time correction of the "converged */
255 /* Newtonian" variety? */
256
257 /* - Is the correction for the transmission case? */
258
259 /* - Is the correction relativistic? */
260
261 /* The parameters defining the structure of the block are as */
262 /* follows: */
263
264 /* NABCOR Number of aberration correction choices. */
265
266 /* ABATSZ Number of elements in the aberration correction */
267 /* block. */
268
269 /* GEOIDX Index in block of geometric correction flag. */
270
271 /* LTIDX Index of light time flag. */
272
273 /* STLIDX Index of stellar aberration flag. */
274
275 /* CNVIDX Index of converged Newtonian flag. */
276
277 /* XMTIDX Index of transmission flag. */
278
279 /* RELIDX Index of relativistic flag. */
280
281 /* The following parameter is not required to define the block */
282 /* structure, but it is convenient to include it here: */
283
284 /* CORLEN The maximum string length required by any aberration */
285 /* correction string */
286
287 /* $ Author_and_Institution */
288
289 /* N.J. Bachman (JPL) */
290
291 /* $ Literature_References */
292
293 /* None. */
294
295 /* $ Version */
296
297 /* - SPICELIB Version 1.0.0, 18-DEC-2004 (NJB) */
298
299 /* -& */
300 /* Number of aberration correction choices: */
301
302
303 /* Aberration correction attribute block size */
304 /* (number of aberration correction attributes): */
305
306
307 /* Indices of attributes within an aberration correction */
308 /* attribute block: */
309
310
311 /* Maximum length of an aberration correction string: */
312
313
314 /* End of include file zzabcorr.inc */
315
316 /* $ Brief_I/O */
317
318 /* Variable I/O Description */
319 /* -------- --- -------------------------------------------------- */
320 /* TRGSUB I Target body state subroutine. */
321 /* ET I Observer epoch. */
322 /* REF I Reference frame of output state vector. */
323 /* ABCORR I Aberration correction flag. */
324 /* OBS I Observing body. */
325 /* STARG O State of target. */
326 /* LT O One way light time between observer and target. */
327
328 /* $ Detailed_Input */
329
330 /* TRGSUB is the name of an external subroutine that returns */
331 /* the geometric state of the target body relative to a */
332 /* center of motion, expressed in the inertial reference */
333 /* frame REF, at the epoch ET. */
334
335 /* The center of motion can be any ephemeris object; it */
336 /* need not be a gravity source. */
337
338 /* The calling sequence of TRGSUB is */
339
340 /* SUBROUTINE TRGSUB ( ET, REF, TRGCTR, STATE ) */
341
342 /* DOUBLE PRECISION ET */
343 /* CHARACTER*(*) REF */
344 /* INTEGER TRGCTR */
345 /* DOUBLE PRECISION STATE ( 6 ) */
346
347
348 /* The inputs of TRGSUB are ET and REF; the outputs */
349 /* are TRGCTR and STATE. STATE is the geometric state */
350 /* of the target relative to the returned center of */
351 /* motion at ET, expressed in the frame REF. */
352
353 /* The target and observer define a state vector whose */
354 /* position component points from the observer to the */
355 /* target. */
356
357 /* ET is the ephemeris time, expressed as seconds past J2000 */
358 /* TDB, at which the state of the target body relative to */
359 /* the observer is to be computed. ET refers to time at */
360 /* the observer's location. */
361
362 /* REF is the name of the reference frame relative to which */
363 /* the output state vector should be expressed. This may */
364 /* be any frame supported by the SPICE system, including */
365 /* built-in frames (documented in the Frames Required */
366 /* Reading) and frames defined by a loaded frame kernel */
367 /* (FK). */
368
369 /* When REF designates a non-inertial frame, the */
370 /* orientation of the frame is evaluated at an epoch */
371 /* dependent on the selected aberration correction. */
372 /* See the description of the output state vector STARG */
373 /* for details. */
374
375 /* ABCORR indicates the aberration corrections to be applied */
376 /* to the state of the target body to account for one-way */
377 /* light time and stellar aberration. See the discussion */
378 /* in the Particulars section for recommendations on */
379 /* how to choose aberration corrections. */
380
381 /* ABCORR may be any of the following: */
382
383 /* 'NONE' Apply no correction. Return the */
384 /* geometric state of the target body */
385 /* relative to the observer. */
386
387 /* The following values of ABCORR apply to the */
388 /* "reception" case in which photons depart from the */
389 /* target's location at the light-time corrected epoch */
390 /* ET-LT and *arrive* at the observer's location at ET: */
391
392 /* 'LT' Correct for one-way light time (also */
393 /* called "planetary aberration") using a */
394 /* Newtonian formulation. This correction */
395 /* yields the state of the target at the */
396 /* moment it emitted photons arriving at */
397 /* the observer at ET. */
398
399 /* The light time correction uses an */
400 /* iterative solution of the light time */
401 /* equation (see Particulars for details). */
402 /* The solution invoked by the 'LT' option */
403 /* uses one iteration. */
404
405 /* 'LT+S' Correct for one-way light time and */
406 /* stellar aberration using a Newtonian */
407 /* formulation. This option modifies the */
408 /* state obtained with the 'LT' option to */
409 /* account for the observer's velocity */
410 /* relative to the solar system */
411 /* barycenter. The result is the apparent */
412 /* state of the target---the position and */
413 /* velocity of the target as seen by the */
414 /* observer. */
415
416 /* 'CN' Converged Newtonian light time */
417 /* correction. In solving the light time */
418 /* equation, the 'CN' correction iterates */
419 /* until the solution converges (three */
420 /* iterations on all supported platforms). */
421 /* Whether the 'CN+S' solution is */
422 /* substantially more accurate than the */
423 /* 'LT' solution depends on the geometry */
424 /* of the participating objects and on the */
425 /* accuracy of the input data. In all */
426 /* cases this routine will execute more */
427 /* slowly when a converged solution is */
428 /* computed. See the Particulars section */
429 /* below for a discussion of precision of */
430 /* light time corrections. */
431
432 /* 'CN+S' Converged Newtonian light time */
433 /* correction and stellar aberration */
434 /* correction. */
435
436
437 /* The following values of ABCORR apply to the */
438 /* "transmission" case in which photons *depart* from */
439 /* the observer's location at ET and arrive at the */
440 /* target's location at the light-time corrected epoch */
441 /* ET+LT: */
442
443 /* 'XLT' "Transmission" case: correct for */
444 /* one-way light time using a Newtonian */
445 /* formulation. This correction yields the */
446 /* state of the target at the moment it */
447 /* receives photons emitted from the */
448 /* observer's location at ET. */
449
450 /* 'XLT+S' "Transmission" case: correct for */
451 /* one-way light time and stellar */
452 /* aberration using a Newtonian */
453 /* formulation This option modifies the */
454 /* state obtained with the 'XLT' option to */
455 /* account for the observer's velocity */
456 /* relative to the solar system */
457 /* barycenter. The position component of */
458 /* the computed target state indicates the */
459 /* direction that photons emitted from the */
460 /* observer's location must be "aimed" to */
461 /* hit the target. */
462
463 /* 'XCN' "Transmission" case: converged */
464 /* Newtonian light time correction. */
465
466 /* 'XCN+S' "Transmission" case: converged */
467 /* Newtonian light time correction and */
468 /* stellar aberration correction. */
469
470
471 /* Neither special nor general relativistic effects are */
472 /* accounted for in the aberration corrections applied */
473 /* by this routine. */
474
475 /* Case and blanks are not significant in the string */
476 /* ABCORR. */
477
478 /* OBS is the NAIF ID code for an observing body. */
479
480
481 /* $ Detailed_Output */
482
483 /* STARG is a Cartesian state vector representing the position */
484 /* and velocity of the target body relative to the */
485 /* specified observer. STARG is corrected for the */
486 /* specified aberrations, and is expressed with respect */
487 /* to the reference frame specified by REF. The first */
488 /* three components of STARG represent the x-, y- and */
489 /* z-components of the target's position; the last three */
490 /* components form the corresponding velocity vector. */
491
492 /* The position component of STARG points from the */
493 /* observer's location at ET to the aberration-corrected */
494 /* location of the target. Note that the sense of the */
495 /* position vector is independent of the direction of */
496 /* radiation travel implied by the aberration */
497 /* correction. */
498
499 /* The velocity component of STARG is the derivative */
500 /* with respect to time of the position component of */
501 /* STARG. */
502
503 /* Units are always km and km/sec. */
504
505 /* Non-inertial frames are treated as follows: letting */
506 /* LTCENT be the one-way light time between the observer */
507 /* and the central body associated with the frame, the */
508 /* orientation of the frame is evaluated at ET-LTCENT, */
509 /* ET+LTCENT, or ET depending on whether the requested */
510 /* aberration correction is, respectively, for received */
511 /* radiation, transmitted radiation, or is omitted. */
512 /* LTCENT is computed using the method indicated by */
513 /* ABCORR. */
514
515 /* LT is the one-way light time between the observer and */
516 /* target in seconds. If the target state is corrected */
517 /* for aberrations, then LT is the one-way light time */
518 /* between the observer and the light time corrected */
519 /* target location. */
520
521 /* $ Parameters */
522
523 /* None. */
524
525 /* $ Exceptions */
526
527 /* 1) If the reference frame REF is not a recognized reference */
528 /* frame the error 'SPICE(UNKNOWNFRAME)' is signaled. */
529
530 /* 2) If an invalid aberration correction is specified, the */
531 /* error will be diagnosed by a routine in the call tree */
532 /* of this routine. */
533
534 /* 3) If the loaded kernels provide insufficient data to */
535 /* compute the requested state vector, the deficiency will */
536 /* be diagnosed by a routine in the call tree of this routine. */
537
538 /* 4) If an error occurs while reading an SPK or other kernel file, */
539 /* the error will be diagnosed by a routine in the call tree */
540 /* of this routine. */
541
542 /* $ Files */
543
544 /* This routine computes states using SPK files that have been */
545 /* loaded into the SPICE system, normally via the kernel loading */
546 /* interface routine FURNSH. See the routine FURNSH and the SPK */
547 /* and KERNEL Required Reading for further information on loading */
548 /* (and unloading) kernels. */
549
550 /* If the output state STARG is to be expressed relative to a */
551 /* non-inertial frame, or if any of the ephemeris data used to */
552 /* compute STARG are expressed relative to a non-inertial frame in */
553 /* the SPK files providing those data, additional kernels may be */
554 /* needed to enable the reference frame transformations required to */
555 /* compute the state. Normally these additional kernels are PCK */
556 /* files or frame kernels. Any such kernels must already be loaded */
557 /* at the time this routine is called. */
558
559 /* $ Particulars */
560
561 /* This routine is part of the user interface to the SPICE ephemeris */
562 /* system. It allows you to retrieve state information for any */
563 /* ephemeris object relative to any other in a reference frame that */
564 /* is convenient for further computations. */
565
566
567 /* Aberration corrections */
568 /* ====================== */
569
570 /* In space science or engineering applications one frequently */
571 /* wishes to know where to point a remote sensing instrument, such */
572 /* as an optical camera or radio antenna, in order to observe or */
573 /* otherwise receive radiation from a target. This pointing problem */
574 /* is complicated by the finite speed of light: one needs to point */
575 /* to where the target appears to be as opposed to where it actually */
576 /* is at the epoch of observation. We use the adjectives */
577 /* "geometric," "uncorrected," or "true" to refer to an actual */
578 /* position or state of a target at a specified epoch. When a */
579 /* geometric position or state vector is modified to reflect how it */
580 /* appears to an observer, we describe that vector by any of the */
581 /* terms "apparent," "corrected," "aberration corrected," or "light */
582 /* time and stellar aberration corrected." The SPICE Toolkit can */
583 /* correct for two phenomena affecting the apparent location of an */
584 /* object: one-way light time (also called "planetary aberration") */
585 /* and stellar aberration. */
586
587 /* One-way light time */
588 /* ------------------ */
589
590 /* Correcting for one-way light time is done by computing, given an */
591 /* observer and observation epoch, where a target was when the */
592 /* observed photons departed the target's location. The vector from */
593 /* the observer to this computed target location is called a "light */
594 /* time corrected" vector. The light time correction depends on the */
595 /* motion of the target relative to the solar system barycenter, but */
596 /* it is independent of the velocity of the observer relative to the */
597 /* solar system barycenter. Relativistic effects such as light */
598 /* bending and gravitational delay are not accounted for in the */
599 /* light time correction performed by this routine. */
600
601 /* Stellar aberration */
602 /* ------------------ */
603
604 /* The velocity of the observer also affects the apparent location */
605 /* of a target: photons arriving at the observer are subject to a */
606 /* "raindrop effect" whereby their velocity relative to the observer */
607 /* is, using a Newtonian approximation, the photons' velocity */
608 /* relative to the solar system barycenter minus the velocity of the */
609 /* observer relative to the solar system barycenter. This effect is */
610 /* called "stellar aberration." Stellar aberration is independent */
611 /* of the velocity of the target. The stellar aberration formula */
612 /* used by this routine does not include (the much smaller) */
613 /* relativistic effects. */
614
615 /* Stellar aberration corrections are applied after light time */
616 /* corrections: the light time corrected target position vector is */
617 /* used as an input to the stellar aberration correction. */
618
619 /* When light time and stellar aberration corrections are both */
620 /* applied to a geometric position vector, the resulting position */
621 /* vector indicates where the target "appears to be" from the */
622 /* observer's location. */
623
624 /* As opposed to computing the apparent position of a target, one */
625 /* may wish to compute the pointing direction required for */
626 /* transmission of photons to the target. This also requires */
627 /* correction of the geometric target position for the effects of */
628 /* light time and stellar aberration, but in this case the */
629 /* corrections are computed for radiation traveling *from* the */
630 /* observer to the target. */
631
632 /* The "transmission" light time correction yields the target's */
633 /* location as it will be when photons emitted from the observer's */
634 /* location at ET arrive at the target. The transmission stellar */
635 /* aberration correction is the inverse of the traditional stellar */
636 /* aberration correction: it indicates the direction in which */
637 /* radiation should be emitted so that, using a Newtonian */
638 /* approximation, the sum of the velocity of the radiation relative */
639 /* to the observer and of the observer's velocity, relative to the */
640 /* solar system barycenter, yields a velocity vector that points in */
641 /* the direction of the light time corrected position of the target. */
642
643 /* One may object to using the term "observer" in the transmission */
644 /* case, in which radiation is emitted from the observer's location. */
645 /* The terminology was retained for consistency with earlier */
646 /* documentation. */
647
648 /* Below, we indicate the aberration corrections to use for some */
649 /* common applications: */
650
651 /* 1) Find the apparent direction of a target for a remote-sensing */
652 /* observation. */
653
654 /* Use 'LT+S' or 'CN+S: apply both light time and stellar */
655 /* aberration corrections. */
656
657 /* Note that using light time corrections alone ('LT' or 'CN') */
658 /* is generally not a good way to obtain an approximation to */
659 /* an apparent target vector: since light time and stellar */
660 /* aberration corrections often partially cancel each other, */
661 /* it may be more accurate to use no correction at all than to */
662 /* use light time alone. */
663
664
665 /* 2) Find the corrected pointing direction to radiate a signal */
666 /* to a target. This computation is often applicable for */
667 /* implementing communications sessions. */
668
669 /* Use 'XLT+S' or 'XCN+S: apply both light time and stellar */
670 /* aberration corrections for transmission. */
671
672
673 /* 3) Compute the apparent position of a target body relative */
674 /* to a star or other distant object. */
675
676 /* Use 'LT', 'CN', 'LT+S', or 'CN+S' as needed to match the */
677 /* correction applied to the position of the distant */
678 /* object. For example, if a star position is obtained from */
679 /* a catalog, the position vector may not be corrected for */
680 /* stellar aberration. In this case, to find the angular */
681 /* separation of the star and the limb of a planet, the */
682 /* vector from the observer to the planet should be */
683 /* corrected for light time but not stellar aberration. */
684
685
686 /* 4) Obtain an uncorrected state vector derived directly from */
687 /* data in an SPK file. */
688
689 /* Use 'NONE'. */
690
691
692 /* 5) Use a geometric state vector as a low-accuracy estimate */
693 /* of the apparent state for an application where execution */
694 /* speed is critical. */
695
696 /* Use 'NONE'. */
697
698
699 /* 6) While this routine cannot perform the relativistic */
700 /* aberration corrections required to compute states */
701 /* with the highest possible accuracy, it can supply the */
702 /* geometric states required as inputs to these computations. */
703
704 /* Use 'NONE', then apply relativistic aberration */
705 /* corrections (not available in the SPICE Toolkit). */
706
707
708 /* Below, we discuss in more detail how the aberration corrections */
709 /* applied by this routine are computed. */
710
711 /* Geometric case */
712 /* ============== */
713
714 /* ZZSPKFZT begins by computing the geometric position T(ET) of */
715 /* the target body relative to the solar system barycenter (SSB). */
716 /* Subtracting the geometric position of the observer O(ET) gives */
717 /* the geometric position of the target body relative to the */
718 /* observer. The one-way light time, LT, is given by */
719
720 /* | T(ET) - O(ET) | */
721 /* LT = ------------------- */
722 /* c */
723
724 /* The geometric relationship between the observer, target, and */
725 /* solar system barycenter is as shown: */
726
727
728 /* SSB ---> O(ET) */
729 /* | / */
730 /* | / */
731 /* | / */
732 /* | / T(ET) - O(ET) */
733 /* V V */
734 /* T(ET) */
735
736
737 /* The returned state consists of the position vector */
738
739 /* T(ET) - O(ET) */
740
741 /* and a velocity obtained by taking the difference of the */
742 /* corresponding velocities. In the geometric case, the */
743 /* returned velocity is actually the time derivative of the */
744 /* position. */
745
746
747 /* Reception case */
748 /* ============== */
749
750 /* When any of the options 'LT', 'CN', 'LT+S', 'CN+S' is selected */
751 /* for ABCORR, ZZSPKFZT computes the position of the target body */
752 /* at epoch ET-LT, where LT is the one-way light time. Let T(t) */
753 /* and O(t) represent the positions of the target and observer */
754 /* relative to the solar system barycenter at time t; then LT is */
755 /* the solution of the light-time equation */
756
757 /* | T(ET-LT) - O(ET) | */
758 /* LT = ------------------------ (1) */
759 /* c */
760
761 /* The ratio */
762
763 /* | T(ET) - O(ET) | */
764 /* --------------------- (2) */
765 /* c */
766
767 /* is used as a first approximation to LT; inserting (2) into the */
768 /* right hand side of the light-time equation (1) yields the */
769 /* "one-iteration" estimate of the one-way light time ("LT"). */
770 /* Repeating the process until the estimates of LT converge */
771 /* yields the "converged Newtonian" light time estimate ("CN"). */
772
773 /* Subtracting the geometric position of the observer O(ET) gives */
774 /* the position of the target body relative to the observer: */
775 /* T(ET-LT) - O(ET). */
776
777 /* SSB ---> O(ET) */
778 /* | \ | */
779 /* | \ | */
780 /* | \ | T(ET-LT) - O(ET) */
781 /* | \ | */
782 /* V V V */
783 /* T(ET) T(ET-LT) */
784
785 /* The position component of the light time corrected state */
786 /* is the vector */
787
788 /* T(ET-LT) - O(ET) */
789
790 /* The velocity component of the light time corrected state */
791 /* is the difference */
792
793 /* T_vel(ET-LT)*(1-dLT/dET) - O_vel(ET) */
794
795 /* where T_vel and O_vel are, respectively, the velocities of the */
796 /* target and observer relative to the solar system barycenter at */
797 /* the epochs ET-LT and ET. */
798
799 /* If correction for stellar aberration is requested, the target */
800 /* position is rotated toward the solar system barycenter- */
801 /* relative velocity vector of the observer. The rotation is */
802 /* computed as follows: */
803
804 /* Let r be the light time corrected vector from the observer */
805 /* to the object, and v be the velocity of the observer with */
806 /* respect to the solar system barycenter. Let w be the angle */
807 /* between them. The aberration angle phi is given by */
808
809 /* sin(phi) = v sin(w) / c */
810
811 /* Let h be the vector given by the cross product */
812
813 /* h = r X v */
814
815 /* Rotate r by phi radians about h to obtain the apparent */
816 /* position of the object. */
817
818 /* When stellar aberration corrections are used, the rate of */
819 /* change of the stellar aberration correction is accounted for */
820 /* in the computation of the output velocity. */
821
822
823 /* Transmission case */
824 /* ================== */
825
826 /* When any of the options 'XLT', 'XCN', 'XLT+S', 'XCN+S' is */
827 /* selected, ZZSPKFZT computes the position of the target body T */
828 /* at epoch ET+LT, where LT is the one-way light time. LT is the */
829 /* solution of the light-time equation */
830
831 /* | T(ET+LT) - O(ET) | */
832 /* LT = ------------------------ (3) */
833 /* c */
834
835 /* Subtracting the geometric position of the observer, O(ET), */
836 /* gives the position of the target body relative to the */
837 /* observer: T(ET-LT) - O(ET). */
838
839 /* SSB --> O(ET) */
840 /* / | * */
841 /* / | * T(ET+LT) - O(ET) */
842 /* / |* */
843 /* / *| */
844 /* V V V */
845 /* T(ET+LT) T(ET) */
846
847 /* The position component of the light-time corrected state */
848 /* is the vector */
849
850 /* T(ET+LT) - O(ET) */
851
852 /* The velocity component of the light-time corrected state */
853 /* consists of the difference */
854
855 /* T_vel(ET+LT)*(1+dLT/dET) - O_vel(ET) */
856
857 /* where T_vel and O_vel are, respectively, the velocities of the */
858 /* target and observer relative to the solar system barycenter at */
859 /* the epochs ET+LT and ET. */
860
861 /* If correction for stellar aberration is requested, the target */
862 /* position is rotated away from the solar system barycenter- */
863 /* relative velocity vector of the observer. The rotation is */
864 /* computed as in the reception case, but the sign of the */
865 /* rotation angle is negated. Velocities are adjusted to account */
866 /* for the rate of change of the stellar aberration correction. */
867
868
869 /* Precision of light time corrections */
870 /* =================================== */
871
872 /* Corrections using one iteration of the light time solution */
873 /* ---------------------------------------------------------- */
874
875 /* When the requested aberration correction is 'LT', 'LT+S', */
876 /* 'XLT', or 'XLT+S', only one iteration is performed in the */
877 /* algorithm used to compute LT. */
878
879 /* The relative error in this computation */
880
881 /* | LT_ACTUAL - LT_COMPUTED | / LT_ACTUAL */
882
883 /* is at most */
884
885 /* (V/C)**2 */
886 /* ---------- */
887 /* 1 - (V/C) */
888
889 /* which is well approximated by (V/C)**2, where V is the */
890 /* velocity of the target relative to an inertial frame and C is */
891 /* the speed of light. */
892
893 /* For nearly all objects in the solar system V is less than 60 */
894 /* km/sec. The value of C is ~300000 km/sec. Thus the */
895 /* one-iteration solution for LT has a potential relative error */
896 /* of not more than 4e-8. This is a potential light time error of */
897 /* approximately 2e-5 seconds per astronomical unit of distance */
898 /* separating the observer and target. Given the bound on V cited */
899 /* above: */
900
901 /* As long as the observer and target are separated by less */
902 /* than 50 astronomical units, the error in the light time */
903 /* returned using the one-iteration light time corrections is */
904 /* less than 1 millisecond. */
905
906 /* The magnitude of the corresponding position error, given */
907 /* the above assumptions, may be as large as (V/C)**2 * the */
908 /* distance between the observer and the uncorrected target */
909 /* position: 300 km or equivalently 6 km/AU. */
910
911 /* In practice, the difference between positions obtained using */
912 /* one-iteration and converged light time is usually much smaller */
913 /* than the value computed above and can be insignificant. For */
914 /* example, for the spacecraft Mars Reconnaissance Orbiter and */
915 /* Mars Express, the position error for the one-iteration light */
916 /* time correction, applied to the spacecraft-to-Mars center */
917 /* vector, is at the 1 cm level. */
918
919 /* Comparison of results obtained using the one-iteration and */
920 /* converged light time solutions is recommended when adequacy of */
921 /* the one-iteration solution is in doubt. */
922
923
924 /* Converged corrections */
925 /* --------------------- */
926
927 /* When the requested aberration correction is 'CN', 'CN+S', */
928 /* 'XCN', or 'XCN+S', as many iterations as are required for */
929 /* convergence are performed in the computation of LT. Usually */
930 /* the solution is found after three iterations. The relative */
931 /* error present in this case is at most */
932
933 /* (V/C)**4 */
934 /* ---------- */
935 /* 1 - (V/C) */
936
937 /* which is well approximated by (V/C)**4. */
938
939 /* The precision of this computation (ignoring round-off */
940 /* error) is better than 4e-11 seconds for any pair of objects */
941 /* less than 50 AU apart, and having speed relative to the */
942 /* solar system barycenter less than 60 km/s. */
943
944 /* The magnitude of the corresponding position error, given */
945 /* the above assumptions, may be as large as (V/C)**4 * the */
946 /* distance between the observer and the uncorrected target */
947 /* position: 1.2 cm at 50 AU or equivalently 0.24 mm/AU. */
948
949 /* However, to very accurately model the light time between */
950 /* target and observer one must take into account effects due to */
951 /* general relativity. These may be as high as a few hundredths */
952 /* of a millisecond for some objects. */
953
954 /* Relativistic Corrections */
955 /* ========================= */
956
957 /* This routine does not attempt to perform either general or */
958 /* special relativistic corrections in computing the various */
959 /* aberration corrections. For many applications relativistic */
960 /* corrections are not worth the expense of added computation */
961 /* cycles. If however, your application requires these additional */
962 /* corrections we suggest you consult the astronomical almanac (page */
963 /* B36) for a discussion of how to carry out these corrections. */
964
965
966 /* $ Examples */
967
968 /* None. */
969
970 /* $ Restrictions */
971
972 /* 1) This routine must not be called by routines of the SPICE */
973 /* frame or SPK subsystems. */
974
975 /* 2) The input subroutine TRGSUB must not call this routine */
976 /* or any of the supporting, private SPK routines */
977
978 /* ZZSPKFAO */
979 /* ZZSPKFAP */
980 /* ZZSPKFAT */
981 /* ZZSPKFLT */
982 /* C */
983 /* $ Literature_References */
984
985 /* None. */
986
987 /* $ Author_and_Institution */
988
989 /* C.H. Acton (JPL) */
990 /* W.L. Taber (JPL) */
991 /* N.J. Bachman (JPL) */
992 /* I.M. Underwood (JPL) */
993
994 /* $ Version */
995
996 /* - SPICELIB Version 1.0.0, 04-JUL-2014 (CHA) (NJB) (WLT) (IMU) */
997
998 /* Discussion of light time corrections was updated. Assertions */
999 /* that converged light time corrections are unlikely to be */
1000 /* useful were removed. */
1001
1002 /* Last update was 22-FEB-2012 (CHA) (NJB) (WLT) (IMU) */
1003
1004 /* -& */
1005 /* $ Index_Entries */
1006
1007 /* target function easy reader for spk file */
1008
1009 /* -& */
1010 /* $ Revisions */
1011
1012 /* None. */
1013
1014 /* -& */
1015
1016
1017 /* SPICELIB functions */
1018
1019
1020 /* Local parameters */
1021
1022
1023 /* Local variables */
1024
1025
1026 /* Saved variables */
1027
1028
1029 /* Initial values */
1030
1031
1032 /* Standard SPICE error handling. */
1033
1034 if (return_()) {
1035 return 0;
1036 } else {
1037 chkin_("ZZSPKFZT", (ftnlen)8);
1038 }
1039 if (first || s_cmp(abcorr, prvcor, abcorr_len, (ftnlen)5) != 0) {
1040
1041 /* The aberration correction flag differs from the value it */
1042 /* had on the previous call, if any. Analyze the new flag. */
1043
1044 zzvalcor_(abcorr, attblk, abcorr_len);
1045 if (failed_()) {
1046 chkout_("ZZSPKFZT", (ftnlen)8);
1047 return 0;
1048 }
1049
1050 /* The aberration correction flag is recognized; save it. */
1051
1052 s_copy(prvcor, abcorr, (ftnlen)5, abcorr_len);
1053
1054 /* Set logical flags indicating the attributes of the requested */
1055 /* correction: */
1056
1057 /* XMIT is .TRUE. when the correction is for transmitted */
1058 /* radiation. */
1059
1060 /* USEGEO indicates geometric state computation. */
1061
1062 /* The above definitions are consistent with those used by */
1063 /* ZZVALCOR. */
1064
1065 xmit = attblk[4];
1066 usegeo = attblk[0];
1067
1068 /* Get the frame ID for J2000 on the first call to this routine. */
1069
1070 if (first) {
1071 namfrm_("J2000", &fj2000, (ftnlen)5);
1072 first = FALSE_;
1073 }
1074 }
1075
1076 /* If we only want a geometric state, then use SPKGEO to compute */
1077 /* just that. */
1078
1079 /* Otherwise, if REF is inertial, compute the state of the target */
1080 /* relative to the observer via SPKACS. If REF is non-inertial, */
1081 /* compute the requested state in the J2000 frame, then transform it */
1082 /* to the frame designated by REF. */
1083
1084 if (usegeo) {
1085
1086 /* Get the state of the target relative to its center at ET. */
1087 /* Add the state of the target's center to obtain the state */
1088 /* of the target with respect to the observer. */
1089
1090 (*trgsub)(et, ref, &trgctr, sttctr, ref_len);
1091 spkgeo_(&trgctr, et, ref, obs, stemp, <cent, ref_len);
1092 if (failed_()) {
1093 chkout_("ZZSPKFZT", (ftnlen)8);
1094 return 0;
1095 }
1096 vaddg_(sttctr, stemp, &c__6, starg);
1097 *lt = vnorm_(starg) / clight_();
1098 } else {
1099
1100 /* Get the auxiliary information about the requested output */
1101 /* frame. */
1102
1103 namfrm_(ref, &reqfrm, ref_len);
1104 if (reqfrm == 0) {
1105 setmsg_("The requested output frame '#' is not recognized by the"
1106 " reference frame subsystem. Please check that the approp"
1107 "riate kernels have been loaded and that you have correct"
1108 "ly entered the name of the output frame. ", (ftnlen)208);
1109 errch_("#", ref, (ftnlen)1, ref_len);
1110 sigerr_("SPICE(UNKNOWNFRAME)", (ftnlen)19);
1111 chkout_("ZZSPKFZT", (ftnlen)8);
1112 return 0;
1113 }
1114 frinfo_(&reqfrm, ¢er, &type__, &typeid, &found);
1115
1116 /* If we are dealing with an inertial frame, we can simply */
1117 /* call ZZSPKFAT and return. */
1118
1119 if (type__ == 1) {
1120 zzspkfat_((S_fp)trgsub, et, ref, abcorr, obs, starg, lt, &dlt,
1121 ref_len, abcorr_len);
1122 chkout_("ZZSPKFZT", (ftnlen)8);
1123 return 0;
1124 }
1125
1126 /* Still here? */
1127
1128 /* We are dealing with a non-inertial frame. But we need to do */
1129 /* light time and stellar aberration corrections in an inertial */
1130 /* frame. Get the "apparent" state of TARG in the intermediary */
1131 /* inertial reference frame J2000. */
1132
1133 /* We also need the light time to the center of the frame. */
1134 /* We compute that first so that we can re-use the temporary */
1135 /* variable STATE when we compute the inertial apparent state */
1136 /* of the target relative to the observer. */
1137
1138 zzspkfat_((S_fp)trgsub, et, "J2000", abcorr, obs, state, lt, &dlt, (
1139 ftnlen)5, abcorr_len);
1140 if (failed_()) {
1141 chkout_("ZZSPKFZT", (ftnlen)8);
1142 return 0;
1143 }
1144
1145 /* If the frame is centered at the observer, the light time and */
1146 /* light time rate are both zero. If the frame is centered */
1147 /* elsewhere, we'll need to obtain the light time between the */
1148 /* observer and the frame center. Unlike SPKEZ, we have no case */
1149 /* here for the frame centered at the target, since the target */
1150 /* isn't an ephemeris object, as far as this routine can */
1151 /* determine. */
1152
1153 if (center == *obs) {
1154 ltcent = 0.;
1155 dltctr = 0.;
1156 } else {
1157 spkssb_(obs, et, "J2000", stobs, (ftnlen)5);
1158 spkltc_(¢er, et, "J2000", abcorr, stobs, stemp, <cent, &
1159 dltctr, (ftnlen)5, abcorr_len);
1160 }
1161
1162 /* If something went wrong (like we couldn't get the state of */
1163 /* the center relative to the observer) now it is time to quit. */
1164
1165 if (failed_()) {
1166 chkout_("ZZSPKFZT", (ftnlen)8);
1167 return 0;
1168 }
1169
1170 /* If the aberration corrections are for transmission, make the */
1171 /* sign of the light time positive, since we wish to compute the */
1172 /* orientation of the non-inertial frame at an epoch later than */
1173 /* ET by the one-way light time. */
1174
1175 if (xmit) {
1176 ltsign = 1;
1177 } else {
1178 ltsign = -1;
1179 }
1180
1181 /* Get the state transformation from J2000 to the requested frame */
1182 /* and convert the state. */
1183
1184 d__1 = *et + ltsign * ltcent;
1185 frmchg_(&fj2000, &reqfrm, &d__1, xform);
1186 if (failed_()) {
1187 chkout_("ZZSPKFZT", (ftnlen)8);
1188 return 0;
1189 }
1190
1191 /* There's a tricky bit here: since XFORM is evaluated */
1192 /* at time */
1193
1194 /* ET + LTSIGN*LTCENT */
1195
1196 /* XFORM is actually dependent on LTCENT. We need to account for */
1197 /* this dependency in our velocity transformation. */
1198
1199 zzcorsxf_(&xmit, &dltctr, xform, corxfm);
1200
1201 /* Now apply the frame transformation CORXFM to produce the */
1202 /* state expressed relative to the request frame REQFRM. */
1203
1204 mxvg_(corxfm, state, &c__6, &c__6, starg);
1205 }
1206 chkout_("ZZSPKFZT", (ftnlen)8);
1207 return 0;
1208 } /* zzspkfzt_ */
1209
1210