SOFTWARE USER'S MANUAL FOR THE CRRES Project Orbital Data Processing Task Attitude Determination Subtask (AGMOD) Initial Release December 10, 1990 Prepared for: RMS Technologies, Inc 70 Westview Street Lexington, MA 02173 Prepared by: Space Applications Corporation Satellite Systems and Software Division 1310 Orleans Drive Sunnyvale, CA 94089 Revised by: Radex, Inc. Three Preston Court Bedford, MA 01730 1. Introduction to User's Manual ------------ -- ------ ------ 1.1 Purpose ------- This Software User's Manual provides information that should be helpful in the use of the AGMOD subroutines which are called by a user's program to evaluate the CRRES Attitude Model. 1.2 Scope ----- The source program language of the Agency Module is ANSI x3.9- 1978 Standard Fortran 77 (No extensions). The program was developed at Space Applications Corporation via network data link to the AFGL. The software is currently maintained by Radex, Inc. 2. AGMOD Overview ----- -------- 2.1 AGMOD Purpose ----- ------- The Agency Module function shall perform the conversion from time span/fit coefficient sets to instrument line of sight at a particular time of interest. 2.2 AGMOD Functional Flow ----- ---------- ---- The lower level computer software component (LLCSC) that controls the execution of subordinate functions is called AGMOD. It is called by the user's program (Appendix A provides a sample main program). 2.2.1 AGMOD ----- Subroutine AGMOD is the driver for the Line of Sight (LOS) function. AGMOD calls LLCSCs RAAF, CHECK, EPOLY and CLOS within the function to perform the line of sight calculations assigned to this function. Upon completion of AGMOD, control is returned to the user's main program. 2.2.2 RAAF ---- Subroutine RAAF reads in the contents of the Agency Attitude file into an internal common, LOSCOM. A sample attitude file is in Section 6. 2.2.3 CHECK ----- Subroutine CHECK verifies the requested times, year, day and instrument ID with the valid segment times, year and day in LOSCOM, and the ID parameters in IDCOM respectively. An error flag is set if the instrument ID is invalid or the requested times, year or day are out of range. 2.2.4 EPOLY ----- Subroutine EPOLY evaluates the Chebyshev polynomials using the appropriate coefficients in LOSCOM. EPOLY calls CNPS (a sub- routine from the IBM scientific subroutine library that is included in the AGMOD source code). 2.2.5 CLOS ---- Subroutine CLOS calculates the line(s) of sight of the user's instrument in Earth Centered Inertial (ECI) coordinates. 3. AGMOD Operation ----- --------- This section describes the AGMOD operation in terms of inputs and outputs from the agency's main program and processing as it occurs in AGMOD. 3.1 Inputs ------ Input parameters from the agency program are described as follows: +-------------+-----------------+-------+-------+---------+---------+ | Identifier | Description | Data | Type | Units | Limit/ | | | | Rep'n | | | Range | +-------------+-----------------+-------+-------+---------+---------+ | ATAFLU | Agency Tape | Const | Intg | None | 1-99 | | | Attitude File | | | | | | | Logical Unit | | | | | +-------------+-----------------+-------+-------+---------+---------+ | ID | Instrument | Const | Intg | None | 1-40 | | | identication | | | | | +-------------+-----------------+-------+-------+---------+---------+ | YEAR | Year | Const | Intg | year | NA | | | | | | | | +-------------+-----------------+-------+-------+---------+---------+ | DAY | Day | Const | Intg | day | 1-366 | | | | | | | | +-------------+-----------------+-------+-------+---------+---------+ | NTIMES | Number of | Const | Intg | None | NA | | | requested times | | | | | +-------------+-----------------+-------+-------+---------+---------+ | TIMEIN | Time(s) of | Array | Real | fp secs | NA | | (NTIMES) | interest | | | | | +-------------+-----------------+-------+-------+---------+---------+ NOTE: Times must be entered as floating point seconds past midnight. Times also must be entered from the lowest to the highest values. Should requested times cross midnight continue to increase times accordingly. The sequence, 86398, 86399, 86400, 86401, 86402 is correct, whereas, 86398, 86399, 86400, 0, 1 is incorrect. ) NTIMES declares the upper bound for the output array, LOS(3,NTIMES) in AGMOD. LOS in the user's driver program must dimension LOS(3*NTIMES). 3.2 Processing ---------- After control is given to AGMOD by the user's program the following processing is executed: 1) Read ATAF data 2) Verify instrument ID, Year, Day and validity of requested times. 3) Perform required calculations to get lines of sight. 3.3 Outputs ------- This section describes each output produced by AGMOD and, if it is an ERROR, then the conditions under which it was produced is provided. +-------------+-----------------+-------+-------+---------+---------+ | Identifier | Description | Data | Type | Units | Limit/ | | | | Rep'n | | | Range | +-------------+-----------------+-------+-------+---------+---------+ | LOS(3, | Output array | Array | Real | None | 0-1.0 | | NTIMES) | storing the | | | | | | | instrument's | | | | | | | line of sight | | | | | | | at the re- | | | | | | | quested times | | | | | +-------------+-----------------+-------+-------+---------+---------+ | ERROR | Error return | Const | Intg | None | (-8) - | | | value | | | | 1023 | +-------------+-----------------+-------+-------+---------+---------+ NOTE: The components of LOS are: ( LOS(1,I) => x-component at time I ) ( LOS(2,I) => y-component at time I ) ( LOS(3,I) => z-component at time I ) The possible ERROR return values are: (+) - Mission event code number signifying that a mission event took place in segment containing the requested times. See Section 5 for mission event code numbers. (0) - No errors (-1) - File read error (-2) - Incorrect vehicle ID (-3) - End of file reached prematurely (-4) - NUMSEG exceeds MAXSEG (It will be necessary to change all MAXSEGs in all PARAMETER declarations in the source code) (-5) - IORDER exceeds MAXORD (It will be necessary to change all MAXORDs in all PARAMETER declarations in the source code) (-6) - Error in ID (-7) - Error in YEAR or DAY (-8) - Error in TIMEIN (Input time is not in time span) 4. Instrument Line of Sight (LOS) Definition ---------- ---- -- ----- ----- ---------- The AGMOD routine produces the instantaneous modeled pointing direction of an arbitrary spacecraft frame vector in the Earth Centered Inertial (ECI) coordinates. In order to find the ECI pointing direction of a chosen instrument or other spacecraft frame vector, one must first define the vector in the AGMOD software. 4.1. Defining a LOS -------- - --- An arbitrary reference vector is defined in the AGMOD system by choosing a reference number to assign to the vector then inserting the spacecraft frame azimuth and elevation angles (in degrees) into the common block /IDCOM/ in the block data subroutine LOSBLK. The azimuth angle, in spacecraft coordinates, is defined as the angle between the spacecraft positive x-axis and the projection of the chosen vector into the spacecraft x/y-plane, measured counter- clockwise looking down the spacecraft z-axis. The elevation is the angle between the vector and the spacecraft x/y-plane. For example, the spacecraft x-axis has azimuth 0 and elevation 0 degrees. The spacecraft negative y-axis has azimuth 270 and elevation 0 degrees. The spacecraft z-axis has elevation 90 and undefined azimuth (the value chosen doesn't matter). If you know the vector components X,Y and Z of the instrument or vector in spacecraft coordinates, you can calculate the azimuth (A) and elevation (E) from: E = ASIN(Z/SQRT(X**2+Y**2+Z**2)) A = ATAN2(Y,X) ASIN above is the Fortran arc sin function and ATAN2 is the arc tangent function that returns the angle in the proper quadrant. Azimuth lies between 0 and 360 degrees and elevation between -90 and 90 degrees. 4.2. Accessing a Particular LOS --------- - ---------- --- Once a LOS has been defined in the common block IDCOM, it is used by calling AGMOD with the parameter ID set to the chosen instrument ID (see Section 3.1). The ID is the array element number of the arrays AZIMUTH and ELVATN. 4.3. Default LOS Definitions ------- --- ----------- In the original version of AGMOD released (Revision 00) there are eight pre-defined `instrument'. These are: Instrument ID Azimuth Elevation Description 1 0 0 x-axis 2 90 0 y-axis 3 180 0 neg. x-axis 4 270 0 neg. y-axis 5 0 90 z-axis 6 90 -90 neg. z-axis 7 180 45 45 d. above neg. x 8 270 -45 45 d. below neg. y These can be replaced with definitions of relevant instruments or (of course) retained if they are of some interest. There is space in IDCOM for a total of 40 instruments. Originally, it was the intention to provide an updated version of AGMOD with a relatively complete set of instrument pointing directions. However, it has proved too difficult (and in some cases dangerous) to compile the necessary data in this context. As of this writing, there are no plans to provide an updated AGMOD. Although we are happy to assist you in obtaining any information you might need, it is ultimately the responsibility of the user to obtain and verify instrument alignment data and to verify the correctness of the implementation in the AGMOD code. 5. Mission Event Code Definitions ------------------------------ One of the parameters returned by AGMOD is an integer representing the type of attitude segment from which the result was obtained. These are defined below. 512 => Unspecified Event 256 => Timing Discontinuity 128 => End of eclipse 64 => Start of eclipse 32 => Orbit adjust 16 => Boom deployment 8 => Attitude adjust 4 => Canister eject 2 => Spin down 1 => Spin up 0 => Normal Segment Aside from normal and eclipse segments the most frequently used is the attitude adjust. In general (for GTO periods) an attitude adjust period will be labeled as such for at least two to three hours after the maneuver. However, it should be cautioned that one should not rely on segment times or labels for precise information on mission events. A non-zero but positive flag returned by AGMOD (see Section 3.3) may indicate less precise attitude than is normally obtained. However, mission events listed above may be missed entirely during modeling if they do not perceptibly change the attitude. "Unspecified Event" is used rarely to label at attitude irregularity that does not fit another category. "Timing Discontinuity" indicates a clock jump which results in a timing error. These times are only approximate, however. 6. Sample Fit Coefficient File ------ --- ----------- ---- CAF01750 Fit Coefficient File Name CRRES P86-1 CRRES Vehicle I.D. C01750 Orbit (period) No. 1990 Year 278 Day of Year 62400000 Start UT (ms) 98100000 End UT (ms) 6 Number of Segments 1 Segment Number 1 0.0000 Segment Start (sec relative to UT0) 685.0000 Segment End 2.9197080291971E-03 Timespan Compression Factor 1 -1.0000000000000E+00 Timespan Offset Factor 1 0 Type of Segment (normal) 1 Order of Right Ascension 1.9969108080898E+02 Coefficient 1 of Right Ascension 1 Order of Declination -5.5631665156934E+00 Coefficient 1 of Declination 2 Order of Spin Rate 2.0657926626723E+00 Coefficient 1 of Spin Rate -9.7127955116047E-05 Coefficient 2 of Spin Rate -1.3667652963821E+01 Phase at Start of Segment 2 Segment Number 2 685.0000 etc. 3374.0000 7.4377091855708E-04 -1.5094830792116E+00 64 1 1.9969108080898E+02 1 -5.5631665156934E+00 2 2.0670822358915E+00 8.5700353546380E-04 1.9633975542319E+02 3 3374.0000 3974.0000 3.3333333333333E-03 -1.2246666666667E+01 128 1 1.9969108080898E+02 1 -5.5631665156934E+00 2 2.0688867975101E+00 -4.8004718666700E-04 -2.7952979711974E+02 4 3974.0000 7394.0000 5.8479532163742E-04 -3.3239766081871E+00 0 1 1.9969108080898E+02 1 -5.5631665156934E+00 2 2.0662600751017E+00 -1.4150497392698E-04 -3.3265743969771E+01 5 7394.0000 26100.0000 1.0691756655618E-04 -1.7905484871164E+00 0 1 1.9969108080898E+02 1 -5.5631665156934E+00 2 2.0659774859267E+00 -2.5529493625514E-06 -1.1605943777734E+02 6 26100.0000 35700.0000 2.0833333333333E-04 -6.4375000000000E+00 0 1 1.9969108080898E+02 1 -5.5631665156934E+00 2 2.0659792189096E+00 -3.8351257647903E-05 -7.9490857866551E+01 ---------------------------------------------------------------------------- 7. Acronyms, Abbreviations and Terms --------- ------------- --- ----- AFGL Air Force Geophysics Laboratory AGMOD Agency Module (subroutine to perform LOS function) ANSI American National Standards Institute ATAF Agency Tape Attitude File ATAFLU ATAF logical unit CADP CRRES Attitude Determination Program (CRESAD and AGMOD) CHECK Subroutine that checks the input parameters into AGMOD CLOS Subroutine that calculates the instrument line(s) of sight CNPS Subroutine from the IBM scientific library that computes the Chebyshev polynomial CRESAD CRRES Attitude Determination Program (AFGL Cyber portion) CRRES Combined Release and Radiation Effects Satellite ECI Earth Centered Inertial coordinate system EPOLY Subroutine that Evaluates the Chebyshev Polynomial FCD Fit Coefficients Data file (CRESAD working interface) LOSCOM Line of Sight Common containing the information from the ATAF LLCSC Lower Level Computer Software Component LU Logical Unit (FORTRAN file identifier) RAAF Subroutine that Reads the Agency Attitude File TLCSC Top Level Computer Software Component UT Universal Time ************************************************************************** Appendix A Sample User's Program to use AGMOD ---------------------------------------------------------------------------- The following is a simple program that will drive the AGMOD subroutine package. After it, are sample outputs for the fit coefficient file given above, CAF01750. *************************************************************************** PROGRAM DRIVEAG C DIMENSION XYZ(3) C CHARACTER*80 FCDFILE C PRINT*,'ENTER FIT COEFFICIENT FILE:' READ100,FCDFILE 100 FORMAT(A80) C OPEN(9,FILE=FCDFILE,FORM='FORMATTED',STATUS='OLD') IUNIT=9 C PRINT*,'ENTER TIME1,TIME2,DT (IN SECONDS)' READ*,T1,T2,DT TIME=T1-DT PRINT*,'ENTER INSTRUMENT ID:' READ*,ID PRINT*,'ENTER YEAR:' READ*,IYEAR PRINT*,'ENTER DAY:' READ*,IDAY NTIMES=1 IERR=0 C PRINT400,'YEAR','DAY','UT(S)','IER','X(ECI)','Y(ECI)','Z(ECI)' 400 FORMAT(2X,A6,A4,A12,A5,3A8) 10 TIME=TIME+DT CALL AGMOD(IUNIT,ID,IYEAR,IDAY,NTIMES,TIME,IERR,XYZ) PRINT500,IYEAR,IDAY,TIME,IERR,XYZ 500 FORMAT(5X,I6,I4,F12.1,I5,3F8.4) IF(TIME.LE.T2)GOTO10 C END ********************************************************************* ENTER FIT COEFFICIENT FILE:caf01750 ENTER TIME1,TIME2,DT (IN SECONDS)80000,80025,1 ENTER INSTRUMENT ID:1 ENTER YEAR:1990 ENTER DAY:278 YEAR DAY UT(S) IER X(ECI) Y(ECI) Z(ECI) 1990 278 80000.0 0 .2184 -.7798 .5868 1990 278 80001.0 0 .1548 -.6481 .7457 1990 278 80002.0 0 .0840 -.4862 .8698 1990 278 80003.0 0 .0093 -.3017 .9534 1990 278 80004.0 0 -.0658 -.1031 .9925 1990 278 80005.0 0 -.1379 .1004 .9854 1990 278 80006.0 0 -.2035 .2991 .9323 1990 278 80007.0 0 -.2596 .4839 .8357 1990 278 80008.0 0 -.3037 .6461 .7002 1990 278 80009.0 0 -.3336 .7783 .5320 1990 278 80010.0 0 -.3479 .8741 .3391 1990 278 80011.0 0 -.3460 .9291 .1303 1990 278 80012.0 0 -.3280 .9409 -.0846 1990 278 80013.0 0 -.2947 .9088 -.2955 1990 278 80014.0 0 -.2476 .8343 -.4926 1990 278 80015.0 0 -.1890 .7209 -.6668 1990 278 80016.0 0 -.1216 .5739 -.8098 1990 278 80017.0 0 -.0485 .4001 -.9152 1990 278 80018.0 0 .0268 .2077 -.9778 1990 278 80019.0 0 .1009 .0056 -.9949 1990 278 80020.0 0 .1703 -.1967 -.9656 1990 278 80021.0 0 .2317 -.3899 -.8912 1990 278 80022.0 0 .2824 -.5649 -.7753 1990 278 80023.0 0 .3199 -.7136 -.6233 1990 278 80024.0 0 .3424 -.8290 -.4422 1990 278 80025.0 0 .3490 -.9057 -.2404 1990 278 80026.0 0 .3393 -.9403 -.0275 ENTER FIT COEFFICIENT FILE:caf01750 ENTER TIME1,TIME2,DT (IN SECONDS)90000,90025,1 ENTER INSTRUMENT ID:5 ENTER YEAR:1990 ENTER DAY:278 YEAR DAY UT(S) IER X(ECI) Y(ECI) Z(ECI) 1990 278 90000.0 0 -.9371 -.3354 -.0969 1990 278 90001.0 0 -.9371 -.3354 -.0969 1990 278 90002.0 0 -.9371 -.3354 -.0969 1990 278 90003.0 0 -.9371 -.3354 -.0969 1990 278 90004.0 0 -.9371 -.3354 -.0969 1990 278 90005.0 0 -.9371 -.3354 -.0969 1990 278 90006.0 0 -.9371 -.3354 -.0969 1990 278 90007.0 0 -.9371 -.3354 -.0969 1990 278 90008.0 0 -.9371 -.3354 -.0969 1990 278 90009.0 0 -.9371 -.3354 -.0969 1990 278 90010.0 0 -.9371 -.3354 -.0969 1990 278 90011.0 0 -.9371 -.3354 -.0969 1990 278 90012.0 0 -.9371 -.3354 -.0969 1990 278 90013.0 0 -.9371 -.3354 -.0969 1990 278 90014.0 0 -.9371 -.3354 -.0969 1990 278 90015.0 0 -.9371 -.3354 -.0969 1990 278 90016.0 0 -.9371 -.3354 -.0969 1990 278 90017.0 0 -.9371 -.3354 -.0969 1990 278 90018.0 0 -.9371 -.3354 -.0969 1990 278 90019.0 0 -.9371 -.3354 -.0969 1990 278 90020.0 0 -.9371 -.3354 -.0969 1990 278 90021.0 0 -.9371 -.3354 -.0969 1990 278 90022.0 0 -.9371 -.3354 -.0969 1990 278 90023.0 0 -.9371 -.3354 -.0969 1990 278 90024.0 0 -.9371 -.3354 -.0969 1990 278 90025.0 0 -.9371 -.3354 -.0969 1990 278 90026.0 0 -.9371 -.3354 -.0969