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