1 /* 2 3 -Procedure oscltx_c ( Extended osculating elements from state ) 4 5 -Abstract 6 7 Determine the set of osculating conic orbital elements that 8 corresponds to the state (position, velocity) of a body at some 9 epoch. In additional to the classical elements, return the true 10 anomaly, semi-major axis, and period, if applicable. 11 12 -Disclaimer 13 14 THIS SOFTWARE AND ANY RELATED MATERIALS WERE CREATED BY THE 15 CALIFORNIA INSTITUTE OF TECHNOLOGY (CALTECH) UNDER A U.S. 16 GOVERNMENT CONTRACT WITH THE NATIONAL AERONAUTICS AND SPACE 17 ADMINISTRATION (NASA). THE SOFTWARE IS TECHNOLOGY AND SOFTWARE 18 PUBLICLY AVAILABLE UNDER U.S. EXPORT LAWS AND IS PROVIDED "AS-IS" 19 TO THE RECIPIENT WITHOUT WARRANTY OF ANY KIND, INCLUDING ANY 20 WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR A 21 PARTICULAR USE OR PURPOSE (AS SET FORTH IN UNITED STATES UCC 22 SECTIONS 2312-2313) OR FOR ANY PURPOSE WHATSOEVER, FOR THE 23 SOFTWARE AND RELATED MATERIALS, HOWEVER USED. 24 25 IN NO EVENT SHALL CALTECH, ITS JET PROPULSION LABORATORY, OR NASA 26 BE LIABLE FOR ANY DAMAGES AND/OR COSTS, INCLUDING, BUT NOT 27 LIMITED TO, INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANY KIND, 28 INCLUDING ECONOMIC DAMAGE OR INJURY TO PROPERTY AND LOST PROFITS, 29 REGARDLESS OF WHETHER CALTECH, JPL, OR NASA BE ADVISED, HAVE 30 REASON TO KNOW, OR, IN FACT, SHALL KNOW OF THE POSSIBILITY. 31 32 RECIPIENT BEARS ALL RISK RELATING TO QUALITY AND PERFORMANCE OF 33 THE SOFTWARE AND ANY RELATED MATERIALS, AND AGREES TO INDEMNIFY 34 CALTECH AND NASA FOR ALL THIRD-PARTY CLAIMS RESULTING FROM THE 35 ACTIONS OF RECIPIENT IN THE USE OF THE SOFTWARE. 36 37 -Required_Reading 38 39 None. 40 41 -Keywords 42 43 CONIC 44 ELEMENTS 45 EPHEMERIS 46 47 */ 48 49 #include "SpiceUsr.h" 50 #include "SpiceZfc.h" 51 #undef oscltx_c 52 oscltx_c(ConstSpiceDouble state[6],SpiceDouble et,SpiceDouble mu,SpiceDouble elts[SPICE_OSCLTX_NELTS])53 void oscltx_c ( ConstSpiceDouble state [6], 54 SpiceDouble et, 55 SpiceDouble mu, 56 SpiceDouble elts [SPICE_OSCLTX_NELTS] ) 57 58 /* 59 60 -Brief_I/O 61 62 VARIABLE I/O DESCRIPTION 63 -------- --- -------------------------------------------------- 64 state I State of body at epoch of elements. 65 et I Epoch of elements. 66 mu I Gravitational parameter (GM) of primary body. 67 elts O Extended set of classical conic elements. 68 69 -Detailed_Input 70 71 state is the state (position and velocity) of the body 72 at some epoch. Components are x, y, z, dx/dt, dy/dt, 73 dz/dt. `state' must be expressed relative to an 74 inertial reference frame. Units are km and km/sec. 75 76 77 et is the epoch of the input state, in ephemeris seconds 78 past J2000. 79 80 3 2 81 mu is the gravitational parameter (GM, km /sec ) of 82 the primary body. 83 84 -Detailed_Output 85 86 elts are equivalent conic elements describing the orbit 87 of the body around its primary. The elements are, 88 in order: 89 90 RP Perifocal distance. 91 ECC Eccentricity. 92 INC Inclination. 93 LNODE Longitude of the ascending node. 94 ARGP Argument of periapsis. 95 M0 Mean anomaly at epoch. 96 T0 Epoch. 97 MU Gravitational parameter. 98 NU True anomaly at epoch. 99 A Semi-major axis. A is set to zero if 100 it is not computable. 101 TAU Orbital period. Applicable only for 102 elliptical orbits. Set to zero otherwise. 103 104 The epoch of the elements is the epoch of the input 105 state. Units are km, rad, rad/sec. The same elements 106 are used to describe all three types (elliptic, 107 hyperbolic, and parabolic) of conic orbits. 108 109 See the Parameters section for information on the 110 declaration of `elts'. 111 112 113 -Parameters 114 115 SPICE_OSCLTX_NELTS 116 117 is the length of the output array `elts'. 118 119 `elts' is intended to contain unused space to hold 120 additional elements that may be added in a later version 121 of this routine. In order to maintain forward 122 compatibility, user applications should declare `elts' 123 as follows: 124 125 SpiceDouble elts[SPICE_OSCLTX_NELTS]; 126 127 128 -Exceptions 129 130 1) If MU is not positive, the error SPICE(NONPOSITIVEMASS) 131 is signaled. 132 133 2) If the specific angular momentum vector derived from `state' 134 is the zero vector, the error SPICE(DEGENERATECASE) 135 is signaled. 136 137 3) If the position or velocity vectors derived from `state' 138 is the zero vector, the error SPICE(DEGENERATECASE) 139 is signaled. 140 141 4) If the inclination is determined to be zero or 180 degrees, 142 the longitude of the ascending node is set to zero. 143 144 5) If the eccentricity is determined to be zero, the argument of 145 periapse is set to zero. 146 147 6) If the eccentricity of the orbit is very close to but not 148 equal to zero, the argument of periapse may not be accurately 149 determined. 150 151 7) For inclinations near but not equal to 0 or 180 degrees, 152 the longitude of the ascending node may not be determined 153 accurately. The argument of periapse and mean anomaly may 154 also be inaccurate. 155 156 8) For eccentricities very close to but not equal to 1, the 157 results of this routine are unreliable. 158 159 9) If the specific angular momentum vector is non-zero but 160 "close" to zero, the results of this routine are unreliable. 161 162 10) If `state' is expressed relative to a non-inertial reference 163 frame, the resulting elements are invalid. No error checking 164 is done to detect this problem. 165 166 11) The semi-major axis and period may not be computable for 167 orbits having eccentricity too close to 1. If the semi-major 168 axis is not computable, both it and the period are set to zero. 169 If the period is not computable, it is set to zero. 170 171 -Files 172 173 None. 174 175 -Particulars 176 177 This routine returns in the first 8 elements of the array `elts' 178 the outputs computed by oscelt_c, and in addition returns in 179 elements 9-11 the quantities: 180 181 elts[8] true anomaly at `et', in radians. 182 183 elts[9] orbital semi-major axis at `et', in km. Valid 184 if and only if this value is non-zero. 185 186 The semi-major axis won't be computable if the 187 eccentricity of the orbit is too close to 1. 188 In this case A is set to zero. 189 190 elts[10] orbital period. If the period is not computable, 191 TAU is set to zero. 192 193 The CSPICE routine conics_c is an approximate inverse of this 194 routine: conics_c maps a set of osculating elements and a time to a 195 state vector. 196 197 -Examples 198 199 Let vinit contain the initial state of a spacecraft relative to 200 the center of a planet at epoch `et', and let GM be the gravitation 201 parameter of the planet. The call 202 203 oscltx_c ( vinit, et, gm, elts ); 204 205 produces a set of osculating elements describing the nominal 206 orbit that the spacecraft would follow in the absence of all 207 other bodies in the solar system. 208 209 Now let state contain the state of the same spacecraft at some 210 other epoch, later. The difference between this state and the 211 state predicted by the nominal orbit at the same epoch can be 212 computed as follows. 213 214 conics_c ( elts, later, nominal ); 215 vsubg_c ( nominal, state, 6, diff ); 216 217 printf( "Perturbation in x, dx/dt = %e %e\n", diff[0], diff[3] ); 218 printf( " y, dy/dt = %e %e\n", diff[1], diff[4] ); 219 printf( " z, dz/dt = %e %e\n", diff[2], diff[5] ); 220 221 -Restrictions 222 223 1) The input state vector must be expressed relative to an 224 inertial reference frame. 225 226 2) Osculating elements are generally not useful for 227 high-accuracy work. 228 229 3) Accurate osculating elements may be difficult to derive for 230 near-circular or near-equatorial orbits. Osculating elements 231 for such orbits should be used with caution. 232 233 4) Extracting osculating elements from a state vector is a 234 mathematically simple but numerically challenging task. The 235 mapping from a state vector to equivalent elements is 236 undefined for certain state vectors, and the mapping is 237 difficult to implement with finite precision arithmetic for 238 states near the subsets of R6 where singularities occur. 239 240 In general, the elements found by this routine can have 241 two kinds of problems: 242 243 - The elements are not accurate but still represent 244 the input state accurately. The can happen in 245 cases where the inclination is near zero or 180 246 degrees, or for near-circular orbits. 247 248 - The elements are garbage. This can occur when 249 the eccentricity of the orbit is close to but 250 not equal to 1. In general, any inputs that cause 251 great loss of precision in the computation of the 252 specific angular momentum vector or the eccentricity 253 vector will result in invalid outputs. 254 255 For further details, see the Exceptions section. 256 257 Users of this routine should carefully consider whether 258 it is suitable for their applications. One recommended 259 "sanity check" on the outputs is to supply them to the 260 CSPICE routine conics_c and compare the resulting state 261 vector with the one supplied to this routine. 262 263 -Literature_References 264 265 [1] Roger Bate, Fundamentals of Astrodynamics, Dover, 1971. 266 267 -Author_and_Institution 268 269 N.J. Bachman (JPL) 270 K.R. Gehringer (JPL) 271 I.M. Underwood (JPL) 272 E.D. Wright (JPL) 273 274 -Version 275 276 -CSPICE Version 1.0.0, 25-JAN-2017 (NJB) (KRG) (IMU) (EDW) 277 278 Original version 11-NOV-2014 (NJB) (KRG) (IMU) (EDW) 279 280 -Index_Entries 281 282 extended conic elements from state 283 extended osculating elements from state 284 convert state to extended osculating elements 285 286 -& 287 */ 288 289 { /* Begin oscltx_c */ 290 291 292 /* 293 Participate in error tracing. 294 */ 295 chkin_c ( "oscltx_c" ); 296 297 298 /* 299 Let the f2c'd routine do the work. 300 */ 301 oscltx_ ( (doublereal *) state, 302 (doublereal *) &et, 303 (doublereal *) &mu, 304 (doublereal *) elts ); 305 306 307 chkout_c ( "oscltx_c" ); 308 309 } /* End oscltx_c */ 310