sofa_vml.lis 2007 April 18
--------------------------
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.
At present the routines are all written in Fortran 77, complying with
the ANSI standard (X3.9-1978) except in two respects:
(1) All routine names are prefixed with the string "iau_". If
necessary, the string can be removed globally; the result
is correctly functioning code.
(2) All routines include an IMPLICIT NONE statement. This can
be removed without affecting the behaviour of the code.
If the "iau_" string and/or the IMPLICIT NONE statements are removed
globally, the resulting code is fully ANSI-compliant and is functionally
unaffected.
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 hms
A2AF decompose radians into d ' "
D2TF decompose days into hms
CALLS
SUBROUTINE iau_A2AF ( NDP, ANGLE, SIGN, IDMSF )
SUBROUTINE iau_A2TF ( NDP, ANGLE, SIGN, IHMSF )
DOUBLE PRECISION FUNCTION
iau_ANP ( A )
DOUBLE PRECISION FUNCTION
iau_ANPM ( A )
SUBROUTINE iau_C2S ( P, THETA, PHI )
SUBROUTINE iau_CP ( P, C )
SUBROUTINE iau_CPV ( PV, C )
SUBROUTINE iau_CR ( R, C )
SUBROUTINE iau_D2TF ( NDP, DAYS, SIGN, IHMSF )
SUBROUTINE iau_IR ( R )
SUBROUTINE iau_P2PV ( P, PV )
SUBROUTINE iau_P2S ( P, THETA, PHI, R )
SUBROUTINE iau_PAP ( A, B, THETA )
SUBROUTINE iau_PAS ( AL, AP, BL, BP, THETA )
SUBROUTINE iau_PDP ( A, B, ADB )
SUBROUTINE iau_PM ( P, R )
SUBROUTINE iau_PMP ( A, B, AMB )
SUBROUTINE iau_PN ( P, R, U )
SUBROUTINE iau_PPP ( A, B, APB )
SUBROUTINE iau_PPSP ( A, S, B, APSB )
SUBROUTINE iau_PV2P ( PV, P )
SUBROUTINE iau_PV2S ( PV, THETA, PHI, R, TD, PD, RD )
SUBROUTINE iau_PVDPV ( A, B, ADB )
SUBROUTINE iau_PVM ( PV, R, S )
SUBROUTINE iau_PVMPV ( A, B, AMB )
SUBROUTINE iau_PVPPV ( A, B, APB )
SUBROUTINE iau_PVU ( DT, PV, UPV )
SUBROUTINE iau_PVUP ( DT, PV, P )
SUBROUTINE iau_PVXPV ( A, B, AXB )
SUBROUTINE iau_PXP ( A, B, AXB )
SUBROUTINE iau_RM2V ( R, P )
SUBROUTINE iau_RV2M ( P, R )
SUBROUTINE iau_RX ( PHI, R )
SUBROUTINE iau_RXP ( R, P, RP )
SUBROUTINE iau_RXPV ( R, PV, RPV )
SUBROUTINE iau_RXR ( A, B, ATB )
SUBROUTINE iau_RY ( THETA, R )
SUBROUTINE iau_RZ ( PSI, R )
SUBROUTINE iau_S2C ( THETA, PHI, C )
SUBROUTINE iau_S2P ( THETA, PHI, R, P )
SUBROUTINE iau_S2PV ( THETA, PHI, R, TD, PD, RD, PV )
SUBROUTINE iau_S2XPV ( S1, S2, PV )
SUBROUTINE iau_SEPP ( A, B, S )
SUBROUTINE iau_SEPS ( AL, AP, BL, BP, S )
SUBROUTINE iau_SXP ( S, P, SP )
SUBROUTINE iau_SXPV ( S, PV, SPV )
SUBROUTINE iau_TR ( R, RT )
SUBROUTINE iau_TRXP ( R, P, TRP )
SUBROUTINE iau_TRXPV ( R, PV, TRPV )
SUBROUTINE iau_ZP ( P )
SUBROUTINE iau_ZPV ( PV )
SUBROUTINE iau_ZR ( R )