308 lines
10 KiB
Plaintext
308 lines
10 KiB
Plaintext
sofa_vml.lis 2013 October 8
|
|
|
|
--------------------------
|
|
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 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 );
|