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