# $Id: aaareadme.txt,v 1.4 1999/03/12 17:46:01 asc Exp $ This is a library of FORTRAN routines that transforms position and velocity between various common coordinate systems used on the ACE sensor. These have been run successfully on a SUN; and without much modification should run on an HP or a DEC Alpha. Below in APPENDIX I, there is a description of the original library. YOU SHOULD READ IT before proceeding! It contains important info you'll need in order to use this library. The library can be placed into libcoordtrans.a by the Makefile. You will need to edit ic_open_time_coeff_file.f and ic_pos_vel_of_sun.F, because these files contain hard-coded paths to input data files (timcof.dat and m2000.dat). There are several test codes that are included with the library, these are: test_j2000_HS.f test_j2000_gse.f test_j2000_rtn.f test_rtn_to_gse.f which can be compiled as: f77 -o test_XXXX test_XXXX.f libcoordtrans.a and run as: test_XXXX producing an output: data.dat For test purposes, a second, less accurate library of routines results are compared to the first library. The second library routines are indicated by adding a _xx to their name. The following coordinated systems are covered in the library: Geocentric Equatorial Inertial GEI X= First Point of Aries (J2000 or ECI or GCI) Z= Geographic North Pole Geographic GEO X= Intersection of Greenwich (efi) Meridian and Geographic Equator Z= Geographic North Pole Geocentric Solar Ecliptic GSE X= Earth-Sun Line Z= Ecliptic North Pole Geocentric Solar Magnetospheric GSM X= Earth-Sun Line Z= Projection of dipole axis on GSE YZ plane Heliocentric Solar Ecliptic HSEb X= Sun-Earth Line (Earth-orientated) Z= Ecliptic North Pole Heliocentric Solar Ecliptic HSEa X= First Point Aries (Inertial) Z= Ecliptic North Pole Heliocentric Solar HS X= Intersection between solar equator and solar central meridian as seen from Earth Z= North Pole of solar rotation axis Radial-Tangential-Normal RTN R= Sun to spacecraft Line T= Lies in the Solar equatorial plane 90 degrees from R and points in the direction as the solar spin The routine test_j2000_HS.f shows the procedure to transform from j2000 (GEI {Geocentric Equatorial Inertial} or gci or eci - earth centered inertial) coordinates to GSE, HSEB, HSEA, and HS as well as GEO (efi - earth fixed inertial). The routine test_rtn_gse.f shows the procedure to transform attitude from RTN given the position of sensor in j2000 coordinates, to GEI (j2000 or eci or gci), GSE, and GSM. APPENDIX I Files in the SYS$PUBLIC:[OA_ROUTINES.UNIX] directory are source code and data files for coordinate transformation routines adapted from the CDHF originally developed on a VAX running VMS 5.4 to run on Sun and DEC workstations running SunOS, and ULTRIX respectively. These routines have been tested on the following platforms: SUN SPARC 2 workstation running SunOS 4.1.2 SUN SPARC 10 workstation running SunOS 4.1.3 DEC 5000/200 RISC workstation running ULTRIX 4.2 In order to convert the files from the VAX, all references to the message file ICSS_MESSAGES.MSG were removed from the files. Single digit return statuses replaced statuses from the message file. Any VAX specific routines and NAG library routines referenced in the code were replaced with functionally equivalent routines that will run on UNIX systems. There are two data files needed for these routines: m2000.dat, and timcof.dat. These were converted from the VAX to the correct formats for the Sun and DEC workstations.Since these files contain floating point data the files differ for the Sun and the DEC. The files for the Sun are named M2000.DAT, and TIMCOF.DAT. The files for the DEC are named M2000_DEC.dat and TIMCOF_DEC.DAT. When copying these files to the sun the filenames on the sun must be in lowercase in order for the files to be opened. When copying the files to the DEC the files must be renamed to m2000.dat and timcof.dat in lowercase in order for the files to be opened. Note: the data files can be copied using ftp with FTP/BINARY so that the file format will be unchanged. The following files are in this directory: SOURCE FILES: ICSS_CNVT_FROM_RP.FOR - Convert a vector in the spacecraft rotating coordinate frame to a fixed payload coordinate frame ICSS_PAYLOAD_TO_GSE.FOR - Perform coordinate transformation from non-spinning payload coordinates to gse coordinates ICSS_TRANSF_ATT.FOR - Spacecraft spin stabilized attitude vectors in GCI, GSE, or GSM coordinates are accepted and transformed into the user's choice of GCI, GSE, or GSM ICSS_TRANSF_ORB.FOR - Vectors in GCI, GSE, or GSM coordinates are accepted and transformed into the user's choice of GCI, GSE, GSM, or geographical (GEO) coordinates. ICSS_VELOCITY_TRANS.FOR - Vectors in GCI, GSE, or GSM coordinates are accepted and transformed into the user's choice of GCI, GSE, GSM, or geographical (GEO) coordinates for velocity. IC_ANGLES_TO_VECTOR.FOR - Convert the angles of right ascension and declination into unit vector form. IC_CONV_GEO_TO_GCI.FOR - Convert a vector in geographical coordinates into a vector in GCI coordinates. IC_CONV_MATRIX.FOR - Calculates, through appropriate analytic expressions, values for the precession and nutation angles and the matrix required to rotate from mean of julian 2000 to true of date. IC_CROSS_PRODUCT.FOR - Calculate the cross product of 2 position vectors. Each vector has 3 components. IC_FETCH_SLP_COEF.FOR - Calculate the record-pair needed from the SLP file for a given time and return the coefficients on that record-pair. IC_FETCH_TCC_REC.FOR - To obtain a given record from the timing coefficients file IC_GCI_TO_GEO.FOR - Calculate the transformation matrix from GCI coordinates to GEO coordinates at a given date and time IC_GCI_TO_GSE.FOR - Calculate the transformation matrix from GCI coordinates to GSE coordinates at a given date and time IC_GCI_TO_GSM.FOR - Calculate the transformation matrix from GCI coordinates to GSM coordinates at a given date and time IC_GET_NUT_ANGLES.FOR - This subroutine calculates, through appropriate analytic expressions, values for the nutation angles to rotate from mean of julian 2000 to true of date IC_GET_TIME_DIFF.FOR - To obtain the differences between the utc, ut1, and a.1 time systems IC_GRNWCH_SIDEREAL.FOR - Calculate the true of date greenwich sidereal time in radians. IC_GSE_TO_GEO.FOR - Calculate the transformation matrix from GSE coordinates to GEO coordinates at a given date and time IC_GSE_TO_GSM.FOR - Calculate the transformation matrix from GSE coordinates to GSM coordinates at a given date and time IC_GSM_TO_GEO.FOR - Calculate the transformation matrix from GSM coordinates to GEO coordinates at a given date and time IC_OPEN_TIME_COEFF_FILE.FOR - to open the timing coefficient file IC_POS_VEL_OF_SUN.F - Return the instantaneous position and velocity of the sun IC_VECTOR_TO_ANGLES.FOR - Convert a unit vector to angles of right ascension and declination. DXJUL.FOR - Computes a julian day number MATTRP.FOR - Routine transposes a matrix (real*8) in place. UTMXTRP8.F - Forms the transpose of an N x M matrix COMMON BLOCK FILES NUT_ANG.CMN - This common is used to store the values of variables from a previous call to ic_get_nut_angles ORSLPR.CMN - The common block is uset to hold the large amount of data that each pair of SLP file records contains for a 10-day span of time. DATA FILES: TIMCOF.DAT - This is the time coefficients file M2000.DAT - This is the Solar/Lunar/Planetary (SLP) Ephemeris file When calling ICSS_TRANSF_ATT, ICSS_TRANSF_ORB, or ICSS_VELOCITY_TRANS from a program, use integers to represent source and target systems according to the list below: GCI = 1 GSE = 2 GSM = 3 GEO = 4 This differs from the routines on the CDHF which use character strings for source and target systems Since the UNIX operating system is case sensitive and lowercase is the default, it is recommended that files are named in all lowercase letters on all UNIX workstations. There is one exception, IC_POS_VEL_OF_SUN, this must have an extension of an uppercase F on a Sun Workstation because it contains code that must be precompiled. e.g. ic_pos_vel_of_sun.F The .F extension tells the compiler to precompile the unit first. On the DEC workstation, in order to precompile the unit, the -cpp option must be used for compiling. The extension can be .for, .F or .f. e. g. On the Sun workstation f77 -c ic_pos_vel_of_sun.F This precompiles the unit first before compiling because of the .F extension on the file. The -c option produces an object file but does call the linker. On the DEC workstation f77 -c -cpp ic_pos_vel_of_sun.for OR f77 -c -cpp ic_pos_vel_of_sun.F OR f77 -c -cpp ic_pos_vel_of_sun.f The -cpp option precompiles the unit first before compiling, the extension does not have to be an uppercase letter. The -c option produces an object file but does call the linker, as it does for the Sun.