1 /* 2 * - - - - - - - - - - - 3 * g a l _ s t a r p v 4 * - - - - - - - - - - - 5 * 6 * This routine is part of the General Astrodynamics Library 7 * 8 * Description: 9 * 10 * Convert star catalog coordinates to position+velocity vector. 11 * 12 * This routine is an independent translation of a FORTRAN routine 13 * that is part of IAU's SOFA software collection. 14 * 15 * Status: 16 * 17 * support routine. 18 * 19 * Given (Note 1): 20 * ra d right ascension (radians) 21 * dec d declination (radians) 22 * pmr d RA proper motion (radians/year) 23 * pmd d Dec proper motion (radians/year) 24 * px d parallax (arcseconds) 25 * rv d radial velocity (km/s, positive = receding) 26 * 27 * Returned (Note 2): 28 * pv d[2][3] pv-vector (AU, AU/day) 29 * gal_starpv i status: 30 * 0 = no warnings 31 * 1 = distance overridden (Note 6) 32 * 2 = excessive velocity (Note 7) 33 * 4 = solution didn't converge (Note 8) 34 * else = binary logical OR of the above 35 * 36 * Notes: 37 * 38 * 1) The star data accepted by this routine are "observables" for an 39 * imaginary observer at the solar-system barycenter. Proper motion 40 * and radial velocity are, strictly, in terms of barycentric 41 * coordinate time, TCB. For most practical applications, it is 42 * permissible to neglect the distinction between TCB and ordinary 43 * "proper" time on Earth (TT/TAI). The result will, as a rule, be 44 * limited by the intrinsic accuracy of the proper-motion and radial- 45 * velocity data; moreover, the pv-vector is likely to be merely an 46 * intermediate result, so that a change of time unit would cancel 47 * out overall. 48 * 49 * In accordance with normal star-catalog conventions, the object's 50 * right ascension and declination are freed from the effects of 51 * secular aberration. The frame, which is aligned to the catalog 52 * equator and equinox, is Lorentzian and centered on the SSB. 53 * 54 * 2) The resulting position and velocity pv-vector is with respect to 55 * the same frame and, like the catalog coordinates, is freed from 56 * the effects of secular aberration. Should the "coordinate 57 * direction", where the object was located at the catalog epoch, be 58 * required, it may be obtained by calculating the magnitude of the 59 * position vector pv[0][0-2] dividing by the speed of light in AU/day 60 * to give the light-time, and then multiplying the space velocity 61 * pv[1][0-2] by this light-time and adding the result to pv[0][0-2]. 62 * 63 * Summarizing, the pv-vector returned is for most stars almost 64 * identical to the result of applying the standard geometrical 65 * "space motion" transformation. The differences, which are the 66 * subject of the Stumpff paper referenced below, are: 67 * 68 * (i) In stars with significant radial velocity and proper motion, 69 * the constantly changing light-time distorts the apparent proper 70 * motion. Note that this is a classical, not a relativistic, 71 * effect. 72 * 73 * (ii) The transformation complies with special relativity. 74 * 75 * 3) Care is needed with units. The star coordinates are in radians 76 * and the proper motions in radians per Julian year, but the 77 * parallax is in arcseconds; the radial velocity is in km/s, but 78 * the pv-vector result is in AU and AU/day. 79 * 80 * 4) The ra proper motion is in terms of coordinate angle, not true 81 * angle. If the catalog uses arcseconds for both ra and dec proper 82 * motions, the ra proper motion will need to be divided by cos(dec) 83 * before use. 84 * 85 * 5) Straight-line motion at constant speed, in the inertial frame, 86 * is assumed. 87 * 88 * 6) An extremely small (or zero or negative) parallax is interpreted 89 * to mean that the object is on the "celestial sphere", the radius 90 * of which is an arbitrary (large) value (see the constant PXMIN). 91 * When the distance is overridden in this way, the status, initially 92 * zero, has 1 added to it. 93 * 94 * 7) If the space velocity is a significant fraction of c (see the 95 * constant VMAX), it is arbitrarily set to zero. When this action 96 * occurs, 2 is added to the status. 97 * 98 * 8) The relativistic adjustment involves an iterative calculation. 99 * If the process fails to converge within a set number (IMAX) of 100 * iterations, 4 is added to the status. 101 * 102 * 9) The inverse transformation is performed by the routine gal_PVSTAR. 103 * 104 * Called: 105 * 106 * gal_s2pv spherical coordinates to pv-vector 107 * gal_pm modulus of p-vector 108 * gal_zp zero p-vector 109 * gal_pn decompose p-vector into modulus and direction 110 * gal_pdp scalar product of two p-vectors 111 * gal_sxp multiply p-vector by scalar 112 * gal_pmp p-vector minus p-vector 113 * gal_ppp p-vector plus p-vector 114 * 115 * References: 116 * 117 * Stumpff, P., Astron.Astrophys. 144, 232-240 (1985). 118 * 119 * This revision: 120 * 121 * 2006 November 13 ( c version 2008 June 8 ) 122 * 123 * 124 * Copyright (C) 2008 Paul C. L. Willmott. See notes at end. 125 * 126 *----------------------------------------------------------------------- 127 */ 128 129 #ifndef _GAL_STARPV_H_ 130 #define _GAL_STARPV_H_ 1 131 132 #undef __BEGIN_DECLS 133 #undef __END_DECLS 134 #ifdef __cplusplus 135 #define __BEGIN_DECLS extern "C" { 136 #define __END_DECLS } 137 #else 138 #define __BEGIN_DECLS /* empty */ 139 #define __END_DECLS /* empty */ 140 #endif 141 142 __BEGIN_DECLS 143 144 int 145 gal_starpv 146 ( 147 double ra, 148 double dec, 149 double pmr, 150 double pmd, 151 double px, 152 double rv, 153 double pv[2][3] ) ; 154 155 __END_DECLS 156 157 #endif /* !_GAL_STARPV_H_ */ 158 159 /* 160 * gal - General Astrodynamics Library 161 * Copyright (C) 2008 Paul C. L. Willmott 162 * 163 * This program is free software; you can redistribute it and/or modify 164 * it under the terms of the GNU General Public License as published by 165 * the Free Software Foundation; either version 2 of the License, or 166 * (at your option) any later version. 167 * 168 * This program is distributed in the hope that it will be useful, 169 * but WITHOUT ANY WARRANTY; without even the implied warranty of 170 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 171 * GNU General Public License for more details. 172 * 173 * You should have received a copy of the GNU General Public License along 174 * with this program; if not, write to the Free Software Foundation, Inc., 175 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. 176 * 177 * Contact: 178 * 179 * Paul Willmott 180 * vp9mu@amsat.org 181 */ 182