sofa_vml.lis 2010 September 5
--------------------------
SOFA Vector/Matrix Library
--------------------------
PREFACE
The routines described here comprise the SOFA vector/matrix library.
Their general appearance and coding style conforms to conventions
agreed by the SOFA Review Board, and their functions, names and
algorithms have been ratified by the Board. Procedures for
soliciting and agreeing additions to the library are still evolving.
PROGRAMMING LANGUAGES
The SOFA routines are available in two programming languages at present:
Fortran 77 and ANSI C.
There is a one-to-one relationship between the two language versions.
The naming convention is such that a SOFA routine referred to
generically as "EXAMPL" exists as a Fortran subprogram iau_EXAMPL and a
C function iauExampl. The calls for the two versions are very similar,
with the same arguments in the same order. In a few cases, the C
equivalent of a Fortran SUBROUTINE subprogram uses a return value rather
than an argument.
GENERAL PRINCIPLES
The library consists mostly of routines which operate on ordinary
Cartesian vectors (x,y,z) and 3x3 rotation matrices. However, there is
also support for vectors which represent velocity as well as position
and vectors which represent rotation instead of position. The vectors
which represent both position and velocity may be considered still to
have dimensions (3), but to comprise elements each of which is two
numbers, representing the value itself and the time derivative. Thus:
* "Position" or "p" vectors (or just plain 3-vectors) have dimension
(3) in Fortran and [3] in C.
* "Position/velocity" or "pv" vectors have dimensions (3,2) in Fortran
and [2][3] in C.
* "Rotation" or "r" matrices have dimensions (3,3) in Fortran and [3][3]
in C. When used for rotation, they are "orthogonal"; the inverse of
such a matrix is equal to the transpose. Most of the routines in
this library do not assume that r-matrices are necessarily orthogonal
and in fact work on any 3x3 matrix.
* "Rotation" or "r" vectors have dimensions (3) in Fortran and [3] in C.
Such vectors are a combination of the Euler axis and angle and are
convertible to and from r-matrices. The direction is the axis of
rotation and the magnitude is the angle of rotation, in radians.
Because the amount of rotation can be scaled up and down simply by
multiplying the vector by a scalar, r-vectors are useful for
representing spins about an axis which is fixed.
* The above rules mean that in terms of memory address, the three
velocity components of a pv-vector follow the three position
components. Application code is permitted to exploit this and all
other knowledge of the internal layouts: that x, y and z appear in
that order and are in a right-handed Cartesian coordinate system etc.
For example, the cp function (copy a p-vector) can be used to copy
the velocity component of a pv-vector (indeed, this is how the
CPV routine is coded).
* The routines provided do not completely fill the range of operations
that link all the various vector and matrix options, but are confined
to functions that are required by other parts of the SOFA software or
which are likely to prove useful.
In addition to the vector/matrix routines, the library contains some
routines related to spherical angles, including conversions to and
from sexagesimal format.
Using the library requires knowledge of vector/matrix methods, spherical
trigonometry, and methods of attitude representation. These topics are
covered in many textbooks, including "Spacecraft Attitude Determination
and Control", James R. Wertz (ed.), Astrophysics and Space Science
Library, Vol. 73, D. Reidel Publishing Company, 1986.
OPERATIONS INVOLVING P-VECTORS AND R-MATRICES
Initialize
ZP zero p-vector
ZR initialize r-matrix to null
IR initialize r-matrix to identity
Copy/extend/extract
CP copy p-vector
CR copy r-matrix
Build rotations
RX rotate r-matrix about x
RY rotate r-matrix about y
RZ rotate r-matrix about z
Spherical/Cartesian conversions
S2C spherical to unit vector
C2S unit vector to spherical
S2P spherical to p-vector
P2S p-vector to spherical
Operations on vectors
PPP p-vector plus p-vector
PMP p-vector minus p-vector
PPSP p-vector plus scaled p-vector
PDP inner (=scalar=dot) product of two p-vectors
PXP outer (=vector=cross) product of two p-vectors
PM modulus of p-vector
PN normalize p-vector returning modulus
SXP multiply p-vector by scalar
Operations on matrices
RXR r-matrix multiply
TR transpose r-matrix
Matrix-vector products
RXP product of r-matrix and p-vector
TRXP product of transpose of r-matrix and p-vector
Separation and position-angle
SEPP angular separation from p-vectors
SEPS angular separation from spherical coordinates
PAP position-angle from p-vectors
PAS position-angle from spherical coordinates
Rotation vectors
RV2M r-vector to r-matrix
RM2V r-matrix to r-vector
OPERATIONS INVOLVING PV-VECTORS
Initialize
ZPV zero pv-vector
Copy/extend/extract
CPV copy pv-vector
P2PV append zero velocity to p-vector
PV2P discard velocity component of pv-vector
Spherical/Cartesian conversions
S2PV spherical to pv-vector
PV2S pv-vector to spherical
Operations on vectors
PVPPV pv-vector plus pv-vector
PVMPV pv-vector minus pv-vector
PVDPV inner (=scalar=dot) product of two pv-vectors
PVXPV outer (=vector=cross) product of two pv-vectors
PVM modulus of pv-vector
SXPV multiply pv-vector by scalar
S2XPV multiply pv-vector by two scalars
PVU update pv-vector
PVUP update pv-vector discarding velocity
Matrix-vector products
RXPV product of r-matrix and pv-vector
TRXPV product of transpose of r-matrix and pv-vector
OPERATIONS ON ANGLES
ANP normalize radians to range 0 to 2pi
ANPM normalize radians to range -pi to +pi
A2TF decompose radians into hours, minutes, seconds
A2AF decompose radians into degrees, arcminutes, arcseconds
AF2A degrees, arcminutes, arcseconds to radians
D2TF decompose days into hours, minutes, seconds
TF2A hours, minutes, seconds to radians
TF2D hours, minutes, seconds to days
CALLS: FORTRAN VERSION
CALL iau_A2AF ( NDP, ANGLE, SIGN, IDMSF )
CALL iau_A2TF ( NDP, ANGLE, SIGN, IHMSF )
CALL iau_AF2A ( S, IDEG, IAMIN, ASEC, RAD, J )
D = iau_ANP ( A )
D = iau_ANPM ( A )
CALL iau_C2S ( P, THETA, PHI )
CALL iau_CP ( P, C )
CALL iau_CPV ( PV, C )
CALL iau_CR ( R, C )
CALL iau_D2TF ( NDP, DAYS, SIGN, IHMSF )
CALL iau_IR ( R )
CALL iau_P2PV ( P, PV )
CALL iau_P2S ( P, THETA, PHI, R )
CALL iau_PAP ( A, B, THETA )
CALL iau_PAS ( AL, AP, BL, BP, THETA )
CALL iau_PDP ( A, B, ADB )
CALL iau_PM ( P, R )
CALL iau_PMP ( A, B, AMB )
CALL iau_PN ( P, R, U )
CALL iau_PPP ( A, B, APB )
CALL iau_PPSP ( A, S, B, APSB )
CALL iau_PV2P ( PV, P )
CALL iau_PV2S ( PV, THETA, PHI, R, TD, PD, RD )
CALL iau_PVDPV ( A, B, ADB )
CALL iau_PVM ( PV, R, S )
CALL iau_PVMPV ( A, B, AMB )
CALL iau_PVPPV ( A, B, APB )
CALL iau_PVU ( DT, PV, UPV )
CALL iau_PVUP ( DT, PV, P )
CALL iau_PVXPV ( A, B, AXB )
CALL iau_PXP ( A, B, AXB )
CALL iau_RM2V ( R, P )
CALL iau_RV2M ( P, R )
CALL iau_RX ( PHI, R )
CALL iau_RXP ( R, P, RP )
CALL iau_RXPV ( R, PV, RPV )
CALL iau_RXR ( A, B, ATB )
CALL iau_RY ( THETA, R )
CALL iau_RZ ( PSI, R )
CALL iau_S2C ( THETA, PHI, C )
CALL iau_S2P ( THETA, PHI, R, P )
CALL iau_S2PV ( THETA, PHI, R, TD, PD, RD, PV )
CALL iau_S2XPV ( S1, S2, PV )
CALL iau_SEPP ( A, B, S )
CALL iau_SEPS ( AL, AP, BL, BP, S )
CALL iau_SXP ( S, P, SP )
CALL iau_SXPV ( S, PV, SPV )
CALL iau_TF2A ( S, IHOUR, IMIN, SEC, RAD, J )
CALL iau_TF2D ( S, IHOUR, IMIN, SEC, DAYS, J )
CALL iau_TR ( R, RT )
CALL iau_TRXP ( R, P, TRP )
CALL iau_TRXPV ( R, PV, TRPV )
CALL iau_ZP ( P )
CALL iau_ZPV ( PV )
CALL iau_ZR ( R )
CALLS: C VERSION
iauA2af ( ndp, angle, &sign, idmsf );
iauA2tf ( ndp, angle, &sign, ihmsf );
i = iauAf2a ( s, ideg, iamin, asec, &rad );
d = iauAnp ( a );
d = iauAnpm ( a );
iauC2s ( p, &theta, &phi );
iauCp ( p, c );
iauCpv ( pv, c );
iauCr ( r, c );
iauD2tf ( ndp, days, &sign, ihmsf );
iauIr ( r );
iauP2pv ( p, pv );
iauP2s ( p, &theta, &phi, &r );
d = iauPap ( a, b );
d = iauPas ( al, ap, bl, bp );
d = iauPdp ( a, b );
d = iauPm ( p );
iauPmp ( a, b, amb );
iauPn ( p, &r, u );
iauPpp ( a, b, apb );
iauPpsp ( a, s, b, apsb );
iauPv2p ( pv, p );
iauPv2s ( pv, &theta, &phi, &r, &td, &pd, &rd );
iauPvdpv ( a, b, adb );
iauPvm ( pv, &r, &s );
iauPvmpv ( a, b, amb );
iauPvppv ( a, b, apb );
iauPvu ( dt, pv, upv );
iauPvup ( dt, pv, p );
iauPvxpv ( a, b, axb );
iauPxp ( a, b, axb );
iauRm2v ( r, p );
iauRv2m ( p, r );
iauRx ( phi, r );
iauRxp ( r, p, rp );
iauRxpv ( r, pv, rpv );
iauRxr ( a, b, atb );
iauRy ( theta, r );
iauRz ( psi, r );
iauS2c ( theta, phi, c );
iauS2p ( theta, phi, r, p );
iauS2pv ( theta, phi, r, td, pd, rd, pV );
iauS2xpv ( s1, s2, pv );
d = iauSepp ( a, b );
d = iauSeps ( al, ap, bl, bp );
iauSxp ( s, p, sp );
iauSxpv ( s, pv, spv );
i = iauTf2a ( s, ihour, imin, sec, &rad );
i = iauTf2d ( s, ihour, imin, sec, &days );
iauTr ( r, rt );
iauTrxp ( r, p, trp );
iauTrxpv ( r, pv, trpv );
iauZp ( p );
iauZpv ( pv );
iauZr ( r );