Spacecraft Attitude

Overview of Availble Attitude Models

GMAT supports many attitude models including the following: CoordinateSystemFixed, SpiceAttitude, NadirPointing, CCSDS-AEM, PrecessingSpinner, and Spinner (we recommend using thew new PrecessingSpinner model instead of Spinner). Different attitude models require different information to fully configure the model. For example, when you select the CoordinateSystemFixed model, the attitude and body rates are entirely determined by the CoordinateSystem model and defining Euler angles or angular velocity components are not required and have no effect. The reference tables above, and the detailed examples for each model type below, describe which fields are used for each model.

Overview of State Representations

aSpacecraft.Q1 = 0.5
aSpacecraft.Q2 = 0.5
aSpacecraft.Q3 = 0.5
aSpacecraft.Q4 = 0.5                

aSpacecraft.Quaternion = [0.5 0.5 0.5 0.5]         

aSpacecraft.DCM11 = 1
aSpacecraft.DCM12 = 0
aSpacecraft.DCM13 = 0
aSpacecraft.DCM21 = 0
aSpacecraft.DCM22 = 1
aSpacecraft.DCM23 = 0
aSpacecraft.DCM31 = 0
aSpacecraft.DCM32 = 0
aSpacecraft.DCM33 = 1        

aSpacecraft.EulerAngleSequence = '321'
aSpacecraft.EulerAngle1 = 45
aSpacecraft.EulerAngle2 = 45
aSpacecraft.EulerAngle3 = 90      

            aSpacecraft.MRP1 = 0.2928932188134525
aSpacecraft.MRP2 = 0.2928932188134524
aSpacecraft.MRP3 = 1.149673585146546e-017
          

            aSpacecraft.EulerAngleSequence = '321'
aSpacecraft.EulerAngleRate1 = -5
aSpacecraft.EulerAngleRate2 = 20
aSpacecraft.EulerAngleRate3 = 30      
          

            aSpacecraft.AngularVelocityX = 5;
aSpacecraft.AngularVelocityY = 10;
aSpacecraft.AngularVelocityZ = 5;
          

Coordinate System Fixed Attitude Model

The CoordinateSystemFixed model allows you to use any existing CoordinateSystem to define the attitude of a Spacecraft. The attitude uses the axes defined on the CoordinateSystem to compute the body fixed to inertial matrix and attitude rate parameters such as the angular velocity. To configure this attitude mode, select CoordinateSystemFixed, for Attitude. You can define the EulerAngleSequence used when outputting EulerAngles and EulerAngle rates.

The script example below shows how to configure a Spacecraft to use a spacecraft VNB attitude system.

          Create Spacecraft aSat
aSat.Attitude                 = CoordinateSystemFixed
aSat.ModelRotationZ           = -90
aSat.AttitudeCoordinateSystem = 'attCoordSys'

Create ForceModel Propagator1_ForceModel
Create Propagator Propagator1
Propagator1.FM        = Propagator1_ForceModel
Propagator1.MaxStep   = 10

Create CoordinateSystem attCoordSys
attCoordSys.Origin    = Earth
attCoordSys.Axes      = ObjectReferenced
attCoordSys.XAxis     = V
attCoordSys.YAxis     = N
attCoordSys.Primary   = Earth
attCoordSys.Secondary = aSat

Create OrbitView OrbitView1;
OrbitView1.Add                = {aSat, Earth}
OrbitView1.ViewPointReference = Earth
OrbitView1.ViewPointVector    = [ 30000 0 0 ]

BeginMissionSequence

Propagate Propagator1(aSat) {aSat.ElapsedSecs = 12000.0}
        

Spinner Attitude Model

The Spinner attitude model propagates the attitude assuming the spin axis direction is fixed in inertial space. We recommend using the newer PrecessingSpinner model instead of Spinner, and this model is maintained primarily for backwards compatibility. You define the attitude by providing initial body orientation and rates. GMAT propagates the attitude by computing the angular velocity and then rotates the Spacecraft about that angular velocity vector at a constant rate defined by the magnitude of the angular velocity. You can define the initial attitude using quaternions, Euler angles, the DCM, or the modified Rodriques parameters. You can define the attitude rates using Euler angles rates or angular velocity. When working with Euler angles, the rotation sequence is determined by the EulerAngleSequence field.

The example below configures a spacecraft to spin about the inertial z axis.

          Create Spacecraft aSat;
aSat.Attitude         = Spinner
aSat.ModelRotationZ   = -90
aSat.AngularVelocityZ = 5

Create ForceModel Propagator1_ForceModel
Create Propagator Propagator1
GMAT Propagator1.FM        = Propagator1_ForceModel
GMAT Propagator1.MaxStep   = 10

Create CoordinateSystem attCoordSys
attCoordSys.Origin    = Earth
attCoordSys.Axes      = ObjectReferenced
attCoordSys.XAxis     = V
attCoordSys.YAxis     = N
attCoordSys.Primary   = Earth
attCoordSys.Secondary = aSat

Create OrbitView OrbitView1;
OrbitView1.Add                = {aSat, Earth}
OrbitView1.ViewPointReference = Earth
OrbitView1.ViewPointVector    = [ 30000 0 0 ]

BeginMissionSequence

Propagate Propagator1(aSat) {aSat.ElapsedSecs = 12000.0}
        

SPK Attitude Model

The SpiceAttitude model propagates the attitude using attitude SPICE kernels. To configure a Spacecraft to use SPICE kernels select SpiceAttitude for the Attitude field as shown below.

You must provide three SPICE kernel types for the SpiceAttitude model: the attitude kernel (.bc file), the frame kernel (.tf file) and the spacecraft clock kernel (.tsc file). These files are defined on the Spacecraft SPICE tab as shown below. In addition to the kernels, you must also provide the Spacecraft NAIFId and the NAIFIdReferenceFrame. Below is an illustration of the SPICE tab configured for MarsExpress script found later in this section.

The example below configures a Spacecraft to use SPK kernels to propagator the attitude for Mars Express. The SPK kernels are distributed with GMAT.

          Create Spacecraft MarsExpress
MarsExpress.NAIFId = -41
MarsExpress.NAIFIdReferenceFrame = -41001
MarsExpress.Attitude = 'SpiceAttitude'
MarsExpress.OrbitSpiceKernelName = ...
{'../data/vehicle/ephem/spk/MarsExpress_Short.BSP'}
MarsExpress.AttitudeSpiceKernelName = ...
{'../data/vehicle/ephem/spk/MarsExpress_ATNM_PTR00012_100531_002.BC'}
MarsExpress.SCClockSpiceKernelName = ...
{'../data/vehicle/ephem/spk/MarsExpress_MEX_100921_STEP.TSC'}
MarsExpress.FrameSpiceKernelName = ...
{'../data/vehicle/ephem/spk/MarsExpress_MEX_V10.TF'}

Create Propagator spkProp
spkProp.Type = SPK
spkProp.StepSize = 60
spkProp.CentralBody = Mars
spkProp.EpochFormat = 'UTCGregorian'
spkProp.StartEpoch = '01 Jun 2010 16:59:09.815'

Create CoordinateSystem MarsMJ2000Eq
MarsMJ2000Eq.Origin = Mars
MarsMJ2000Eq.Axes = MJ2000Eq

Create OrbitView Enhanced3DView1
Enhanced3DView1.Add = {MarsExpress, Mars}
Enhanced3DView1.CoordinateSystem = MarsMJ2000Eq
Enhanced3DView1.ViewPointReference = Mars
Enhanced3DView1.ViewPointVector = [ 10000 10000 10000 ]
Enhanced3DView1.ViewDirection = Mars

BeginMissionSequence

Propagate spkProp(MarsExpress) {MarsExpress.ElapsedDays = 0.2}
        

Nadir Pointing Model

The NadirPointing attitude mode configures the attitude of a spacecraft to point a specified vector in the spacecraft body system in the nadir direction. The ambiguity in angle about the nadir vector is resolved by minimizing the angle between two constraint vectors. Note: the nadir pointing mode points the attitude in the negative radial direction (not opposite the planetodetic normal).

To configure which axis points to nadir, set the AttitudeReferenceBody field to the desired celestial body and define the body components of the alignment vector using the BodyAlignmentVector fields. To configure the constraint, set the AttitudeConstraintType field to the desired constraint type, and define the body components of the constraint using the BodyConstraintVector fields. GMAT supports two constraint types, OrbitNormal and Velocity, and in both cases the vectors are constructed using the inertial spacecraft state with respect to the AttitudeReferenceBody.

The script example below shows how to configure a Spacecraft to use an Earth NadirPointing attitude system where the body y-axis points nadir and the angle between the body x-axis and the orbit normal vector is a minimum.

          Create Spacecraft aSat;
GMAT aSat.Attitude                 = NadirPointing;
GMAT aSat.AttitudeReferenceBody    = Earth
GMAT aSat.AttitudeConstraintType   = OrbitNormal
GMAT aSat.BodyAlignmentVectorX  = 0
GMAT aSat.BodyAlignmentVectorY  = 1
GMAT aSat.BodyAlignmentVectorZ  = 0
GMAT aSat.BodyConstraintVectorX = 1
GMAT aSat.BodyConstraintVectorX = 0
GMAT aSat.BodyConstraintVectorX = 0

Create ForceModel Propagator1_ForceModel
Create Propagator Propagator1
Propagator1.FM        = Propagator1_ForceModel
Propagator1.MaxStep   = 10

Create OrbitView OrbitView1;
OrbitView1.Add                = {aSat, Earth}
OrbitView1.ViewPointReference = Earth
OrbitView1.ViewPointVector    = [ 30000 0 0 ]

BeginMissionSequence

Propagate Propagator1(aSat) {aSat.ElapsedSecs = 12000.0}
        

CCSDS Attitude Ephemeris Message

The CCSDS Attitude Ephemeris Message (AEM) is an ASCII standard for attitude ephemerides documented in “ATTITUDE DATA MESSAGES” RECOMMENDED STANDARD CCSDS 504.0-B-1. GMAT supports some, but not all, of the attitude messages defined in the standard. According to the CCSDS AEM specification, “The set of attitude data messages described in this Recommended Standard is the baseline concept for attitude representation in data interchange applications that are cross-supported between Agencies of the CCSDS.” Additionally, the forward of the standard states “Derived Agency standards may implement only a subset of the optional features allowed by the Recommended Standard and may incorporate features not addressed by this Recommended Standard. See the details below for supported keyword types and details for creating AEM files that GMAT can use for attitude modelling.

An AEM file must have the format illustrated below described in Table 4-1 of the standard. The header section contains high level information on the version, originator, and date. The body of the file is composed of paired blocks of Metadata and data. The Metadata sections contain information on the data such as the first and last epoch of the block, the time system employed, the reference frames, the attitude type (quaternion, Euler Angle, etc.) and many other items documented in later sections. The data sections contain lines of epoch and attitude data.

An example CCSDS AEM file is shown below

          CCSDS_AEM_VERS = 1.0
CREATION_DATE = 2002-11-04T17:22:31
ORIGINATOR = NASA/JPL

META_START
COMMENT This file was produced by M.R. Somebody, MSOO NAV/JPL, 2002 OCT 04.
COMMENT It is to be used for attitude reconstruction only.
COMMENT  The relative accuracy of these attitudes is 0.1 degrees per axis.
OBJECT_NAME = MARS GLOBAL SURVEYOR
OBJECT_ID = 1996-062A
CENTER_NAME = mars barycenter
REF_FRAME_A = EME2000
REF_FRAME_B = SC_BODY_1
ATTITUDE_DIR = A2B
TIME_SYSTEM = UTC
START_TIME = 1996-11-28T21:29:07.2555
USEABLE_START_TIME = 1996-11-28T22:08:02.5555
USEABLE_STOP_TIME = 1996-11-30T01:18:02.5555
STOP_TIME = 1996-11-30T01:28:02.5555
ATTITUDE_TYPE = QUATERNION
QUATERNION_TYPE = LAST
INTERPOLATION_METHOD = hermite
INTERPOLATION_DEGREE = 7
META_STOP

DATA_START
1996-11-28T21:29:07.2555 0.56748 0.03146 0.45689 0.68427
1996-11-28T22:08:03.5555 0.42319 -0.45697 0.23784 0.74533
1996-11-28T22:08:04.5555 -0.84532 0.26974 -0.06532 0.45652
< intervening data records omitted here >
1996-11-30T01:28:02.5555 0.74563 -0.45375 0.36875 0.31964
DATA_STOP

META_START
COMMENT This block begins after trajectory correction maneuver TCM-3.
OBJECT_NAME = mars global surveyor
OBJECT_ID = 1996-062A
CENTER_NAME = MARS BARYCENTER
REF_FRAME_A = EME2000
REF_FRAME_B = SC_BODY_1
ATTITUDE_DIR = A2B
TIME_SYSTEM = UTC
START_TIME = 1996-12-18T12:05:00.5555
USEABLE_START_TIME = 1996-12-18T12:10:00.5555
USEABLE_STOP_TIME = 1996-12-28T21:23:00.5555
STOP_TIME = 1996-12-28T21:28:00.5555
ATTITUDE_TYPE = QUATERNION
QUATERNION_TYPE = LAST
META_STOP

DATA_START
1996-12-18T12:05:00.5555 -0.64585 0.018542 -0.23854 0.72501
1996-12-18T12:10:05.5555 0.87451 -0.43475 0.13458 -0.16767
1996-12-18T12:10:10.5555 0.03125 -0.65874 0.23458 -0.71418
< intervening records omitted here >
1996-12-28T21:28:00.5555 -0.25485 0.58745 -0.36845 0.67394
DATA_STOP
        

CCSDS files require many keywords and fields, some are required for all file types, others are Situationally Required (SR) depending upon the type of file (i.e. If ATTITUDE_TYPE = QUATERNION, then QUATERNION_TYPE must be included). The tables below describe GMAT’s implementation starting with header keywords

MetaData Keywords are described in the table below.

                    Create Spacecraft aSat
aSat.Attitude = CCSDS-AEM
aSat.AttitudeFileName = myFile.aem
                  

Data Keywords are described in the table below.

Propagate a spacecraft's attitude using a CCSDS AEM file

          Create Spacecraft aSat ;
GMAT aSat.Attitude = CCSDS-AEM;
GMAT aSat.AttitudeFileName = ...
         '../data/vehicle/ephem/ccsds/CCSDS_BasicEulerFile.aem'

Create Propagator aProp;

Create OrbitView a3DView
a3DView.Add = {aSat,Earth}

BeginMissionSequence;

Propagate aProp(aSat) {aSat.ElapsedSecs = 3600};
        

Precessing Spinner Model

The PrecessingSpinner attitude mode configures the attitude of a spacecraft to have steady-state precession motion with respect to a specified vector defined in the inertial frame. The spin axis must be provided in the spacecraft body frame.

To configure the spin axis of the spacecraft body, set the BodySpinAxis, which is expressed in the body frame, and define the reference vector of the steady-state precession motion using the NutationReferenceVector, which is expressed in the inertial frame. To configure the initial attitude of the spacecraft, set InitialPrecessionAngle to define the initial angle of the precession, set InitialSpinAngle to define the initial angle of the spin, and set NutationAngle to define the nutation angle which is constant. To configure the rate of precession and spin rate, set PrecessingRate and SpinRate which are constant.

The script example below shows how to configure a Spacecraft to have PrecessingSpinner attitude mode where the body z-axis spins with respect to the inertial z-axis. PrecessionRate is set to 1 deg./sec., InitialPrecessionAngle is set to 0 deg./sec., SpinRate is set to 2 deg./sec., InitialSpinAngle is set to 0 deg./sec., and NutationAngle is set to 30 deg.

          Create Spacecraft aSat; 
GMAT aSat.Attitude = PrecessingSpinner;
GMAT aSat.NutationReferenceVectorX = 0;
GMAT aSat.NutationReferenceVectorY = 0;
GMAT aSat.NutationReferenceVectorZ = 1;
GMAT aSat.BodySpinAxisX = 0;
GMAT aSat.BodySpinAxisY = 0;
GMAT aSat.BodySpinAxisZ = 1;
GMAT aSat.InitialPrecessionAngle = 0;
GMAT aSat.PrecessionRate = 1;
GMAT aSat.NutationAngle = 30;
GMAT aSat.InitialSpinAngle = 0;
GMAT aSat.SpinRate = 2;

Create OrbitView OrbitView1;
OrbitView1.Add = {aSat, Earth}
OrbitView1.ViewPointReference = Earth
OrbitView1.ViewPointVector = [ 30000 0 0 ]

Create Propagator aProp
aProp.MaxStep = 10

BeginMissionSequence

Propagate aProp(aSat) {aSat.ElapsedSecs = 12000.0}