Spacecraft Attitude Spec and Test
Procedures
Explore
Known Bugs
Failing Tests
Other Findings
Summary of Proposed Changes.
Requirements
Interface/Functional Spec
Overview
Description
Fields
GUI
Remarks
Overview of Available Attitude Models
Overview of State Representations
Coordinate System Fixed Attitude Model
Spinner Attitude Model
SPK Attitude Model
Examples
Test Procedures
Assumptions
Existing Tests
Recommended Additional Tests
Attitude Features Under Development
Requirements
Interface/Functional Spec
Attitude File
Nadir Pointing
Body Pointing
Attitude Slew
Vector Constrained
Spin about a Vector
Precessing-Nutating Spinner
Test Procedures
Explore
Known Bugs
Known bugs committed in JIRA against this feature.
Failing Tests
Tests failing in the nightly regression reports related to this feature.
Other Findings
Summary of Proposed Changes.
The overall philosophy is described in the section called “Overview of Available Attitude Models”
below.
Script Changes
●
●
●
●
●
GMT-3426. CoordinateSystemFixed model should no longer “remember” the initial offset
and the attitude is defined simply by the selected CoordinateSystem.
GMT-3248. Spinner attitude is always with respect to internal system, i.e.
CoordinateSystem has no affect on state.
GMT-3427. Setting Attitude rep or attitude rate for CoordinateSystemFixed or SPK attitude
throws warning or exception. Note: for backwards compatibility we may need to NOT
throw a warning or error. We may just want to document and then test that the fields don’t
affect the results.
GMT-3429. Setting CoordinateSystem on Spinner or SPK throws warning or exception.
We may just want to document and then test that the fields don’t affect the results.
GMT-3427. GetGeneratingString should not write out attitude rep data for
CoordinateSystemFixed and SpiceAttitude. Probably should implement to make this
general because we will be adding many modes that will not need to write out attitude data.
GUI Changes
● GMAT-3425 When SPICE attitude is selected, the only active field is EulerAngleSequence
●
To Do
●
●
●
●
●
●
●
GMAT-3425 When CoordinateSystemFixed is selected, the only active fields are
CoordinateSystem and EulerAngleSequence.
Update field spec
Determine if angular velocity is expressed in the body or inertial system.
Get text for ModifiedRodriques parameters
Write GUI spec.
Review the whole doc.
Determine how 321 determines order of rotation (R1*R2*R3??) or (R3*R2*R1)
Add SPK kernels required for examples to test system and application folder.
Requirements
FRR-3.1.0
The system shall allow the user to define the initial
spacecraft attitude using any of the following state
representations:
FRR-3.1.1
1)
Quaternion
FRR-3.1.2
2)
Direction cosine matrix
FRR-3.1.3
3)
Euler angles (any of the 12 permutations)
FRR-3.1.4
3)
Modified Rodriques Parameters
FRR-3.2.0
The system shall allow the user to define the spacecraft
attitude rate using any of the following state
representations:
FRR-3.2.1
1)
Angular velocity
FRR-3.2.2
2)
Euler angle rates
FRR-3.3
The system shall convert between any attitude
representation in FRR-3.1.
FRR-3.4
The system shall convert between any attitude rate
representation in FRR-3.2.
FRR-7.1.0
The system shall allow the user to propagate spacecraft
attitude using the following kinematic models:
FRR-7.1.1
1)
FRR-7.1.2
2)
Fixed offset with respect to any coordinate system
defined in FRR-35.
FRR-7.1.3
3)
Spinning spacecraft (no precession or nutation).
SPK attitude kernel
Interface/Functional Spec
Overview
For Technical Writers and Reviewers: This section will appear in the user docs as a subsection
of help related to Spacecraft. For example, the main page will contain a high level description of
Spacecraft, and then links to subfeatures like orbit and epoch. For this reason, the Overview
and Description sections for this feature do not follow the conventions for “simple” resources.
Description
GMAT models the orientation and rate of rotation of a spacecraft using several different
mathematical models. Currently, GMAT assumes that a spacecraft is a rigid body. The currently
supported attitude models are Spinner, CoordinateSystemFixed, and SpiceAttitude. The Spinner
model is a simple, inertially fixed spin axis model. The CoordinateSystemFixed model allows you
to use any CoordinateSystem supported by GMAT as the attitude of a spacecraft. The
SpiceAttitude model allows you to define the spacecraft attitude based on SPICE attitude kernels.
Fields
See the User Interface Spec spreadsheet for reference information for fields. This section is
usually empty other than the hyperlink.
GUI
Note to Developers, Testers, TechWriters: The GUI for this feature is heavily dependent on
the setting for the Attitude field and changes dramatically based on that setting. Since the
behavior of the attitude dynamics is dramatically different for each mode, I covered the GUI in
the Remarks section below. -SPH
Remarks
Overview of Available Attitude Models
GMAT models the orientation and rate of rotation of a spacecraft using several different
mathematical models. 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 table below describes which
interface elements such as the AttitudeCoordinateSystem, attitude representation, attitude rate
fields among others are required/supported for a given model. Attitude representations fields
include the DCM, EulerAngles, Quaternion, and MRPs (Modified Rodriguez Parameters). Attitude
rate fields include the body angular velocity and the Euler angle rates. If a field is marked as
inactive for a particular model, fields of that type have no effect for that model. Similarly, fields
marked as active do affect the attitude for a particular model.
Attitude Model
Coord. Sys.
Attitude
Representation
Attitude
Rate
Euler
Sequence.
Spinner
Inactive
Active
Active
Active
CoordinateSystemFixed
Active
Inactive
Inactive
Active
SpiceAttitude
Inactive
Inactive
Inactive
Active
Overview of State Representations
Quaternion
The quaternion is a four element, non-singular attitude representation. GMAT’s quaternion
representation includes the three “vector” components as the first three elements in the quaternion
and the “rotation” component as the last element in the quaternion. In assignment mode, you can
set the quaternions element by element like this
aSpacecraft.Q1
aSpacecraft.Q2
aSpacecraft.Q3
aSpacecraft.Q4
=
=
=
=
0.5;
0.5;
0.5;
0.5;
or simultaneously set the entire quaternion like this.
aSpacecraft.Quaternion = [0.5 0.5 0.5 0.5];
GMAT normalizes the quaternion before use. In command mode, you must enter the entire
quaternion as a single vector to avoid scaling components of the quaternion before the entire
quaternion is set.
DirectionCosineMatrix (DCM)
The Direction Cosine Matrix is a 3x3 array that contains cosines of the angles between the x, y,
and z body axes and the x, y, and z inertial axes. The direction cosine matrix must be orthonormal and you define the DCM element by element. Here is an example the shows how to
define the attitude using the DCM.
aSpacecraft.DCM11
aSpacecraft.DCM12
aSpacecraft.DCM13
aSpacecraft.DCM21
aSpacecraft.DCM22
aSpacecraft.DCM23
aSpacecraft.DCM31
aSpacecraft.DCM32
aSpacecraft.DCM33
=
=
=
=
=
=
=
=
=
1;
0;
0;
0;
1;
0;
0;
0;
1;
Euler Angles
Euler angles are a sequence of three rotations about coordinate axes to transform from one
system to another system. GMAT supports all 12 Euler angle sequences. Here is an example
setting attitude using a “321” sequence.
aSpacecraft.EulerAngleSequence = '321';
aSpacecraft.EulerAngle1 = 45;
aSpacecraft.EulerAngle2 = 45;
aSpacecraft.EulerAngle3 = 90;
Caution: The Euler angles have singularities that can cause issues during modeling. We
recommend using other representations for this reason.
Modified Rogriques parameters
Need text description
aSpacecraft.MRP1 = 0.2928932188134525;
aSpacecraft.MRP2 = 0.2928932188134524;
aSpacecraft.MRP3 = 1.149673585146546e-017;
Euler Angles Rates
The Euler angle rates are the first time derivative of the Euler angles and can be used to define the
body rates. Euler angle rates use the same sequence as the EulerAngles. The example below
shows how to define the EulerAngle rates for a spacecraft.
aSpacecraft.EulerAngleSequence = '321';
aSpacecraft.EulerAngleRate1 = -5;
aSpacecraft.EulerAngleRate2 = 20;
aSpacecraft.EulerAngleRate3 = 30;
Angular Velocity
The angular velocity is the angular velocity of the spacecraft body with respect to the inertial frame,
expressed in the inertial frame. The example below shows how to define the AngularVelocity for a
spacecraft.
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.
Caution: For the CoordinateSystemFixed attitude model, the attitude is completely
described by the selected coordinate system. If you are working in the script, setting
attitude parameters (Euler Angles, Quaternion etc.) or setting attitude rate parameters such
as (Euler Angle Rates etc.) has no effect.
Note to Developer, Tester, and Tech Writer. This GUI will need
significant rework before testing and documenting.
For WCS. I propose we hide all of the settings on RHS of this panel when
Attitude is CoordinateSystemFixed. My reasoning is that typically, when
a field is inactive, it means the applied value is displayed, but you are
not allowed to change it. In this case however, the value in the GUI is
not the applied value, it is not used at all. This is very confusing.
Specifically I think when Attitude = CoordinateSystemFixed or
SpiceAttitude, the AttitudeInitialConditions and
AttitudeRateInitialConditions group boxes should not appear at all.
WCS Approved this.
Figure 1 Spacecraft Attitude configuration
The script example below shows how to configure a spacecraft to use a spacecraft VNB attitude
system.
Create Spacecraft aSat;
GMAT aSat.Attitude
= CoordinateSystemFixed;
GMAT aSat.ModelRotationZ
= -90;
GMAT aSat.AttitudeCoordinateSystem = 'attCoordSys';
Create ForceModel Propagator1_ForceModel;
Create Propagator Propagator1;
GMAT Propagator1.FM
= Propagator1_ForceModel;
GMAT Propagator1.MaxStep
= 10;
Create CoordinateSystem
GMAT attCoordSys.Origin
GMAT attCoordSys.Axes
GMAT attCoordSys.XAxis
GMAT attCoordSys.YAxis
attCoordSys;
= Earth;
= ObjectReferenced;
= V;
= N;
GMAT attCoordSys.Primary
= Earth;
GMAT attCoordSys.Secondary = aSat;
Create OrbitView OrbitView1;
GMAT OrbitView1.Add
= {aSat, Earth};
GMAT OrbitView1.ViewPointReference = Earth;
GMAT 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. 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, EulerAngles, the Direction Cosine Matrix, or
the Modified Rodriques Parameters. You can define the attitude rates using Euler angles rates or
AngularVelocity. When working with EulerAngles, the rotation sequence is determined by the
EulerAngleSequence field.
Caution: If you are working in the script, setting the CoordinateSystem for the Spinner
attitude model has no effect.
Figure 2 Spacecraft Attitude - Angular Velocity configuration
The example below configures a spacecraft to spin about the inertial z axis.
Create Spacecraft aSat;
GMAT aSat.Attitude
GMAT aSat.ModelRotationZ
GMAT aSat.AngularVelocityZ = 5;
= Spinner
= -90;
Create ForceModel Propagator1_ForceModel;
Create Propagator Propagator1;
GMAT Propagator1.FM
= Propagator1_ForceModel;
GMAT Propagator1.MaxStep
= 10;
Create CoordinateSystem
GMAT attCoordSys.Origin
GMAT attCoordSys.Axes
GMAT attCoordSys.XAxis
GMAT attCoordSys.YAxis
attCoordSys;
= Earth;
= ObjectReferenced;
= V;
= N;
GMAT attCoordSys.Primary
= Earth;
GMAT attCoordSys.Secondary = aSat;
Create OrbitView OrbitView1;
GMAT OrbitView1.Add
= {aSat, Earth};
GMAT OrbitView1.ViewPointReference = Earth;
GMAT 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.
Caution: For the SpiceAttitude model, the attitude is completely described by the spice
kernels. When working in the script, setting the CoordinateSystem, attitude parameters
(Euler Angles, Quaternion etc.) or attitude rate parameters such as (Euler Angle Rates etc.)
has no effect.
Figure 3 SPK Attitude Model
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.
Figure 4 SPK Model - SPICE configuration
The example below configures a spacecraft to use SPK kernels to propagator the attitude for
MarsExpress. The SPK kernels are distributed with GMAT.
Create Spacecraft MarsExpress;
GMAT MarsExpress.NAIFId = -41;
GMAT MarsExpress.NAIFIdReferenceFrame = -41001;
GMAT MarsExpress.Attitude = 'SpiceAttitude';
GMAT MarsExpress.OrbitSpiceKernelName =
{'../data/vehicle/ephem/spk/MarsExpress_Short.BSP'};
GMAT MarsExpress.AttitudeSpiceKernelName =
{'../data/vehicle/ephem/spk/MarsExpress_ATNM_PTR00012_100531_002.BC'};
GMAT MarsExpress.SCClockSpiceKernelName =
{'../data/vehicle/ephem/spk/MarsExpress_MEX_100921_STEP.TSC'};
GMAT MarsExpress.FrameSpiceKernelName =
{'../data/vehicle/ephem/spk/MarsExpress_MEX_V10.TF'};
Create Propagator spkProp;
GMAT
GMAT
GMAT
GMAT
GMAT
spkProp.Type = SPK;
spkProp.StepSize = 60;
spkProp.CentralBody = Mars;
spkProp.EpochFormat = 'UTCGregorian';
spkProp.StartEpoch = '01 Jun 2010 16:59:09.815';
Create CoordinateSystem MarsMJ2000Eq;
GMAT MarsMJ2000Eq.Origin = Mars;
GMAT MarsMJ2000Eq.Axes = MJ2000Eq;
Create OrbitView Enhanced3DView1;
GMAT Enhanced3DView1.Add = {MarsExpress, Mars};
GMAT Enhanced3DView1.CoordinateSystem = MarsMJ2000Eq;
GMAT Enhanced3DView1.ViewPointReference = Mars;
GMAT Enhanced3DView1.ViewPointVector = [ 10000 10000 10000 ];
GMAT Enhanced3DView1.ViewDirection = Mars;
BeginMissionSequence;
Propagate spkProp(MarsExpress) {MarsExpress.ElapsedDays = 0.2};
Examples
Note to Developers, Testers, TechWriters: The examples are heavily dependent upon
attitude mode so I included them along with the discussion of the modes in the Remarks
section.. -SPH
Figure 5 SPK Model - SPICE configuration example
Test Procedures
Assumptions
If you are making assumptions about how tests will be performed or that other test areas will cover
some of this functionality describe that here.
Existing Tests
Describe existing test types using a row for each class of test.
Priority
Status
Summary
Recommended Additional Tests
Nominal Tests
Priority
Status
Summary
[for Resources only] Cloning the resource in the Mission
Sequence, using all non-default values in all field
configurations
Edge/Corner/Stres
Priority
Status
Summary
Unique Validation
Priority
Status
Unique Mode Tests
Summary
Priority
Status
Summary
Unique GUI Tests
These are tests that are unique to the GUI interface for this feature that are not covered by the
standard GUI test template and procedures.
Priority
Status
Summary
Attitude Features Under Development
Requirements
Interface/Functional Spec
Attitude File
●
●
Function definition: For a given user-specified attitude representation type (e.g., Euler angle) and time, GMAT
saves attitude history as a text file.
Inputs (by user): Attitude representation(one of Euler, quaternion, DCM), time step
●
Function description: For any mission scenario, GMAT can save the attitude and its rate history as a text file
upon user-request. The time to write attitude history will be specified by the user through either GUI or script.
Detailed specification including GUI screenshot will be described in a so-called specification document for
each item.
Nadir Pointing
The nadir attitude mode configures the attitude of the spacecraft to point a specified vector in the
nadir direction while minimizing the angle between two constraint vectors. The Nadir pointing
mode points the attitude in the negative radial direction (not opposite planetodetic normal). You
can define the AttitudeReferenceBody, the AttitudeConstraintType, and the reference and
constraint vectors in the body system. GMAT aligns the vector defined in the
AttitudeReferenceVector with the negative of the position vector w/r/t the AttitudeReferenceBody.
The ambiguity in angle about the nadir vector is resolved by minimizing the angle between the
AttitudeConstraintVector and the vector defined by the AttitudeConstraintType
field. The example below shows how to configure an Earth-nadir attitude constrained so that the
angle between the body z-axis and orbit normal is minimized.
Create Spacecraft aSat;
GMAT aSat.Attitude
GMAT aSat.AttitudeReferenceBody
GMAT aSat.AttitudeConstraintType
GMAT aSat.AttitudeReferenceVector
GMAT aSat.AttitudeConstraintVector
=
=
=
=
=
NadirPointing;
‘Earth’
‘OrbitNormal’
[1,0,0];
[0,0,1];
Open Issue: The GUI prototype below is not complete. When Vector data types are
supported, then this GUI needs to have a combo box for AttitudeReferenceVector and
AttitudeConstraintVector. The combo box will populate with vectors created and named by
the user, and the option “User Defined”. If “User Defined” is selected, then the GUI draws
the text boxes shown below to allow the user to type in the components of the vector. -SPH
Note to Dev. Team: Below is an early idea on how to integrate the vector
data type into the nadir attitude model.
Create Vector SunVector
SunVector.Type
= RelativePostion
SunVector.ReferencePoint = aSat;
SunVector.OtherPoint
= Sun;
Create Spacecraft aSat;
GMAT aSat.Attitude
GMAT aSat.AttitudeReferenceBody
GMAT aSat.AttitudeConstraint
GMAT aSat.AttitudeReferenceVector
GMAT aSat.AttitudeConstraintVector
=
=
=
=
=
NadirPointing;
‘Earth’
SunVector;
[1,0,0]
[0,011];
Name
Metadata
AttitudeReferenceBody
The celestial body used to define nadir.
AttitudeConstraintType
AttitudeReferenceVector
AttitudeConstraintVector
Data
Type
Celestial
Body
Range
Celestial
Body
Default
Earth
Units
N/A
The constraint type for resolving attitude
ambiguity.
Data
Type
Predefine
d String
Range
OrbitNor
mal,
Velocity
Default
OrbitNor
mal
Units
N/A
The vector in the body frame to align with the
opposite of the radial vector.
Data
Type
3x1 Array
or Vector
Object
Range
3x1 Array
or Vector
Object
Default
[1,0,0];
Units
N/A
The constraint vector of the attitude system.
Data
Type
3x1 Array
or Vector
Object
Range
3x1 Array
or Vector
Object
Default
[0,0,1];
Units
N/A
Body Pointing
●
●
●
Function definition: For a given arbitrary body (either celestial or artificial body), GMAT rotates a satellite’s
attitude to point the body. Therefore, it is more or like a generalized version of Nadir pointing.
Input (by user): Initial position of the satellite (in inertial frame) whose attitude being controlled, target
object’s position and velocity in inertial frame.
Function description: As a user defines the target object, the vector {Ros}I from the satellite to the object in I
frame can be calculated. Then GMAT lets Z-axis of the B frame be aligned to the vector calculated. Y-axis of
the B frame should be aligned to the vector calculated by the cross product of orbit-normal vector of the
satellite and the vector {Ros}I to specify the attitude of satellite uniquely. Angular rate can be calculated
numerically from the attitude angle history.
Spin about a Vector
●
●
●
Function definition: For a given vector and rotation rate, GMAT rotates the satellite with respect to the vector.
Input (by user): Reference vector RiI, initial attitude ABi(t0), rotation rate {ωIB}i
Function description: GMAT first calculates initial attitude matrix (with respect to the Inertial system) ABI(t0)
with ABi(t0) given by the user. Then, GMAT calculates rotation rate {ωIB}B which expressed in body frame.
Finally, GMAT calculates ABI(t) for arbitrary time t with given rotation rate.
Attitude Slew
●
●
●
Function definition: For a given initial and final attitudes (defined in the Inertial system), GMAT rotates the
satellite with constant angular velocity.
Input (by user): Initial attitude ABI(t0), final attitude ABI(tf), transfer time ttransfer .
Function description: First of all, GMAT needs to find an eigen-axis and an angle of rotation according to the
user-specified initial and final attitudes. For a given transfer time (slew time) ttransfer, GMAT calculates
rotation rate {ωIB}B which is assumed to be constant. Finally, GMAT calculates ABI(t) for arbitrary time t
with given rotation rate.
Vector Constrained
●
●
●
Function definition: For a given vector and plane, GMAT lays the vector on the plane.
Input (by user): Normal vector of the target plane in I frame, one more constraint vector to align(e.g. Z-axis in
I frame)
Function description: When the user provides the information described above, GMAT lets Z-axis of the B
frame be aligned to the plane normal vector provided. Y-axis of the B frame should be aligned to the vector
calculated by the cross product of orbit-normal vector of the satellite and the plane normal vector to specify the
attitude of satellite uniquely. Time-dependent rate of angular velocity could be calculated numerically using
the attitude’s angle history.
●
Precessing-Nutating Spinner
●
●
●
Function definition: For a given initial precession, nutation and spin rate, GMAT rotates the satellite.
Input (by user): Principal moments of inertia(I for spinning axis, I0 for two other axes). Spin axis in body
frame (z axis usually), initial attitude ABi(t0), constant nutation angle θ and constant spinning rate p.
Function description: It is assumed that the satellite is in steady-state precession for simplification. In this case,
precession rate , nutation angle θ, and spinning rate p will be constant. Given the information above, spinning
rate can be calculated as follows;
And, Angular rate {ωIB}B can be calculated as,
Using the specified angular rate, GMAT can calculate the attitude with respect to the inertial frame (3-1-3
rotation).
Does the input below uniquely define the attitude or is more information required? -SPH
Create Spacecraft aSat;
GMAT aSat.Attitude
GMAT aSat.Attitude.BodySpinVector
GMAT aSat.Attitude.Spinner.NutationAngle
GMAT aSat.Attitude.Spinner.SpinAngle
GMAT aSat.Attitude.Spinner.SpinRate
GMAT aSat.Attitude.Spinner.PrecessionAngle
GMAT theSat.AngularVelocityZ = 0;
GMAT aSat.Attitude.Spinner.PrecessionRate
= PrecessingSpinner
= [1 0 0];
= 30;
= 25;
= 20;
= 25;
= 20;
Attitude Ephemeris File
●
Function Definition:
http://public.ccsds.org/publications/archive/504x0b1.pdf
Test Procedures