1sofa_vml.lis 2020 September 9 2 3 -------------------------- 4 SOFA Vector/Matrix Library 5 -------------------------- 6 7PREFACE 8 9The routines described here comprise the SOFA vector/matrix library. 10Their general appearance and coding style conforms to conventions 11agreed by the SOFA Board, and their functions, names and algorithms have 12been ratified by the Board. Procedures for soliciting and agreeing 13additions to the library are still evolving. 14 15 16PROGRAMMING LANGUAGES 17 18The SOFA routines are available in two programming languages at present: 19Fortran 77 and ANSI C. 20 21There is a one-to-one relationship between the two language versions. 22The naming convention is such that a SOFA routine referred to 23generically as "EXAMPL" exists as a Fortran subprogram iau_EXAMPL and a 24C function iauExampl. The calls for the two versions are very similar, 25with the same arguments in the same order. In a few cases, the C 26equivalent of a Fortran SUBROUTINE subprogram uses a return value rather 27than an argument. 28 29 30GENERAL PRINCIPLES 31 32The library consists mostly of routines which operate on ordinary 33Cartesian vectors (x,y,z) and 3x3 rotation matrices. However, there is 34also support for vectors which represent velocity as well as position 35and vectors which represent rotation instead of position. The vectors 36which represent both position and velocity may be considered still to 37have dimensions (3), but to comprise elements each of which is two 38numbers, representing the value itself and the time derivative. Thus: 39 40* "Position" or "p" vectors (or just plain 3-vectors) have dimension 41 (3) in Fortran and [3] in C. 42 43* "Position/velocity" or "pv" vectors have dimensions (3,2) in Fortran 44 and [2][3] in C. 45 46* "Rotation" or "r" matrices have dimensions (3,3) in Fortran and [3][3] 47 in C. When used for rotation, they are "orthogonal"; the inverse of 48 such a matrix is equal to the transpose. Most of the routines in 49 this library do not assume that r-matrices are necessarily orthogonal 50 and in fact work on any 3x3 matrix. 51 52* "Rotation" or "r" vectors have dimensions (3) in Fortran and [3] in C. 53 Such vectors are a combination of the Euler axis and angle and are 54 convertible to and from r-matrices. The direction is the axis of 55 rotation and the magnitude is the angle of rotation, in radians. 56 Because the amount of rotation can be scaled up and down simply by 57 multiplying the vector by a scalar, r-vectors are useful for 58 representing spins about an axis which is fixed. 59 60* The above rules mean that in terms of memory address, the three 61 velocity components of a pv-vector follow the three position 62 components. Application code is permitted to exploit this and all 63 other knowledge of the internal layouts: that x, y and z appear in 64 that order and are in a right-handed Cartesian coordinate system etc. 65 For example, the cp function (copy a p-vector) can be used to copy 66 the velocity component of a pv-vector (indeed, this is how the 67 CPV routine is coded). 68 69* The routines provided do not completely fill the range of operations 70 that link all the various vector and matrix options, but are confined 71 to functions that are required by other parts of the SOFA software or 72 which are likely to prove useful. 73 74In addition to the vector/matrix routines, the library contains some 75routines related to spherical angles, including conversions to and 76from sexagesimal format. 77 78Using the library requires knowledge of vector/matrix methods, spherical 79trigonometry, and methods of attitude representation. These topics are 80covered in many textbooks, including "Spacecraft Attitude Determination 81and Control", James R. Wertz (ed.), Astrophysics and Space Science 82Library, Vol. 73, D. Reidel Publishing Company, 1986. 83 84 85OPERATIONS INVOLVING P-VECTORS AND R-MATRICES 86 87 Initialize 88 89 ZP zero p-vector 90 ZR initialize r-matrix to null 91 IR initialize r-matrix to identity 92 93 Copy 94 95 CP copy p-vector 96 CR copy r-matrix 97 98 Build rotations 99 100 RX rotate r-matrix about x 101 RY rotate r-matrix about y 102 RZ rotate r-matrix about z 103 104 Spherical/Cartesian conversions 105 106 S2C spherical to unit vector 107 C2S unit vector to spherical 108 S2P spherical to p-vector 109 P2S p-vector to spherical 110 111 Operations on vectors 112 113 PPP p-vector plus p-vector 114 PMP p-vector minus p-vector 115 PPSP p-vector plus scaled p-vector 116 PDP inner (=scalar=dot) product of two p-vectors 117 PXP outer (=vector=cross) product of two p-vectors 118 PM modulus of p-vector 119 PN normalize p-vector returning modulus 120 SXP multiply p-vector by scalar 121 122 Operations on matrices 123 124 RXR r-matrix multiply 125 TR transpose r-matrix 126 127 Matrix-vector products 128 129 RXP product of r-matrix and p-vector 130 TRXP product of transpose of r-matrix and p-vector 131 132 Separation and position-angle 133 134 SEPP angular separation from p-vectors 135 SEPS angular separation from spherical coordinates 136 PAP position-angle from p-vectors 137 PAS position-angle from spherical coordinates 138 139 Rotation vectors 140 141 RV2M r-vector to r-matrix 142 RM2V r-matrix to r-vector 143 144 145OPERATIONS INVOLVING PV-VECTORS 146 147 Initialize 148 149 ZPV zero pv-vector 150 151 Copy/extend/extract 152 153 CPV copy pv-vector 154 P2PV append zero velocity to p-vector 155 PV2P discard velocity component of pv-vector 156 157 Spherical/Cartesian conversions 158 159 S2PV spherical to pv-vector 160 PV2S pv-vector to spherical 161 162 Operations on pv-vectors 163 164 PVPPV pv-vector plus pv-vector 165 PVMPV pv-vector minus pv-vector 166 PVDPV inner (=scalar=dot) product of two pv-vectors 167 PVXPV outer (=vector=cross) product of two pv-vectors 168 PVM modulus of pv-vector 169 SXPV multiply pv-vector by scalar 170 S2XPV multiply pv-vector by two scalars 171 PVU update pv-vector 172 PVUP update pv-vector discarding velocity 173 174 Matrix-vector products 175 176 RXPV product of r-matrix and pv-vector 177 TRXPV product of transpose of r-matrix and pv-vector 178 179 180OPERATIONS ON ANGLES 181 182 Wrap 183 184 ANP normalize radians to range 0 to 2pi 185 ANPM normalize radians to range -pi to +pi 186 187 To sexagesimal 188 189 A2TF decompose radians into hours, minutes, seconds 190 A2AF decompose radians into degrees, arcminutes, arcseconds 191 D2TF decompose days into hours, minutes, seconds 192 193 From sexagesimal 194 195 AF2A degrees, arcminutes, arcseconds to radians 196 TF2A hours, minutes, seconds to radians 197 TF2D hours, minutes, seconds to days 198 199 200CALLS: FORTRAN VERSION 201 202 CALL iau_A2AF ( NDP, ANGLE, SIGN, IDMSF ) 203 CALL iau_A2TF ( NDP, ANGLE, SIGN, IHMSF ) 204 CALL iau_AF2A ( S, IDEG, IAMIN, ASEC, RAD, J ) 205 D = iau_ANP ( A ) 206 D = iau_ANPM ( A ) 207 CALL iau_C2S ( P, THETA, PHI ) 208 CALL iau_CP ( P, C ) 209 CALL iau_CPV ( PV, C ) 210 CALL iau_CR ( R, C ) 211 CALL iau_D2TF ( NDP, DAYS, SIGN, IHMSF ) 212 CALL iau_IR ( R ) 213 CALL iau_P2PV ( P, PV ) 214 CALL iau_P2S ( P, THETA, PHI, R ) 215 CALL iau_PAP ( A, B, THETA ) 216 CALL iau_PAS ( AL, AP, BL, BP, THETA ) 217 CALL iau_PDP ( A, B, ADB ) 218 CALL iau_PM ( P, R ) 219 CALL iau_PMP ( A, B, AMB ) 220 CALL iau_PN ( P, R, U ) 221 CALL iau_PPP ( A, B, APB ) 222 CALL iau_PPSP ( A, S, B, APSB ) 223 CALL iau_PV2P ( PV, P ) 224 CALL iau_PV2S ( PV, THETA, PHI, R, TD, PD, RD ) 225 CALL iau_PVDPV ( A, B, ADB ) 226 CALL iau_PVM ( PV, R, S ) 227 CALL iau_PVMPV ( A, B, AMB ) 228 CALL iau_PVPPV ( A, B, APB ) 229 CALL iau_PVU ( DT, PV, UPV ) 230 CALL iau_PVUP ( DT, PV, P ) 231 CALL iau_PVXPV ( A, B, AXB ) 232 CALL iau_PXP ( A, B, AXB ) 233 CALL iau_RM2V ( R, P ) 234 CALL iau_RV2M ( P, R ) 235 CALL iau_RX ( PHI, R ) 236 CALL iau_RXP ( R, P, RP ) 237 CALL iau_RXPV ( R, PV, RPV ) 238 CALL iau_RXR ( A, B, ATB ) 239 CALL iau_RY ( THETA, R ) 240 CALL iau_RZ ( PSI, R ) 241 CALL iau_S2C ( THETA, PHI, C ) 242 CALL iau_S2P ( THETA, PHI, R, P ) 243 CALL iau_S2PV ( THETA, PHI, R, TD, PD, RD, PV ) 244 CALL iau_S2XPV ( S1, S2, PV ) 245 CALL iau_SEPP ( A, B, S ) 246 CALL iau_SEPS ( AL, AP, BL, BP, S ) 247 CALL iau_SXP ( S, P, SP ) 248 CALL iau_SXPV ( S, PV, SPV ) 249 CALL iau_TF2A ( S, IHOUR, IMIN, SEC, RAD, J ) 250 CALL iau_TF2D ( S, IHOUR, IMIN, SEC, DAYS, J ) 251 CALL iau_TR ( R, RT ) 252 CALL iau_TRXP ( R, P, TRP ) 253 CALL iau_TRXPV ( R, PV, TRPV ) 254 CALL iau_ZP ( P ) 255 CALL iau_ZPV ( PV ) 256 CALL iau_ZR ( R ) 257 258 259CALLS: C VERSION 260 261 iauA2af ( ndp, angle, &sign, idmsf ); 262 iauA2tf ( ndp, angle, &sign, ihmsf ); 263 i = iauAf2a ( s, ideg, iamin, asec, &rad ); 264 d = iauAnp ( a ); 265 d = iauAnpm ( a ); 266 iauC2s ( p, &theta, &phi ); 267 iauCp ( p, c ); 268 iauCpv ( pv, c ); 269 iauCr ( r, c ); 270 iauD2tf ( ndp, days, &sign, ihmsf ); 271 iauIr ( r ); 272 iauP2pv ( p, pv ); 273 iauP2s ( p, &theta, &phi, &r ); 274 d = iauPap ( a, b ); 275 d = iauPas ( al, ap, bl, bp ); 276 d = iauPdp ( a, b ); 277 d = iauPm ( p ); 278 iauPmp ( a, b, amb ); 279 iauPn ( p, &r, u ); 280 iauPpp ( a, b, apb ); 281 iauPpsp ( a, s, b, apsb ); 282 iauPv2p ( pv, p ); 283 iauPv2s ( pv, &theta, &phi, &r, &td, &pd, &rd ); 284 iauPvdpv ( a, b, adb ); 285 iauPvm ( pv, &r, &s ); 286 iauPvmpv ( a, b, amb ); 287 iauPvppv ( a, b, apb ); 288 iauPvu ( dt, pv, upv ); 289 iauPvup ( dt, pv, p ); 290 iauPvxpv ( a, b, axb ); 291 iauPxp ( a, b, axb ); 292 iauRm2v ( r, p ); 293 iauRv2m ( p, r ); 294 iauRx ( phi, r ); 295 iauRxp ( r, p, rp ); 296 iauRxpv ( r, pv, rpv ); 297 iauRxr ( a, b, atb ); 298 iauRy ( theta, r ); 299 iauRz ( psi, r ); 300 iauS2c ( theta, phi, c ); 301 iauS2p ( theta, phi, r, p ); 302 iauS2pv ( theta, phi, r, td, pd, rd, pv ); 303 iauS2xpv ( s1, s2, pv ); 304 d = iauSepp ( a, b ); 305 d = iauSeps ( al, ap, bl, bp ); 306 iauSxp ( s, p, sp ); 307 iauSxpv ( s, pv, spv ); 308 i = iauTf2a ( s, ihour, imin, sec, &rad ); 309 i = iauTf2d ( s, ihour, imin, sec, &days ); 310 iauTr ( r, rt ); 311 iauTrxp ( r, p, trp ); 312 iauTrxpv ( r, pv, trpv ); 313 iauZp ( p ); 314 iauZpv ( pv ); 315 iauZr ( r ); 316