Interface/Functional Spec

Explore Results

These have all been committed to JIRA. -SPH

  • OrientationEpoch is not available in GUI.  Should probably expose this field.
  • For bodies such as Venus\Mars, the GUI says RotationDataSource is IAUSimplified.  This is not correct. for those bodies, we use the full IAU-200? model.  We should probably change the label to IAU-200?.  I'll resolve the year of the actual model. -SPH
  • GMAT does not currently use the OrientationEpoch in the computation of the orientation.  This is a P1 must fix.  I have prototype MATLAB code to show how to fix.  -SPH
  • We currently allow moons of moons, and moons of asteroids and comets.  We should probably disallow those.
  • We appear to have two field for defining SPK kernels "SourceFileName" and "OrbitSpiceKernelName"  need to doc or deprecate.


A celestial body model


The CelestialBody resource is a model of a celestial body containing settings for the physical properties, as well as the models for the orbital motion and orientation.  GMAT contains built-in models for the Sun, the 8 planets, Earth's moon, and Pluto.  You can create a custom CelestialBody resource to model a planet, asteroid, comet, or moon. 
See Also:  SolarSystem, Barycenter, LibrationPoint, CoordinateSystem.


See the User Interface Spec spreadsheet for reference information for fields. 


The CelestialBody GUI has three tabs that allow you to set the physical properties, orbital properties, and the orientation model.  CelestialBody resources can be used in ForceModels, CoordinateSystems, LibrationPoints, and Barycenters, among others.  For a built-in CelestialBody, the Orbit and Orientation tabs are largely inactive and the behavior is discussed below.  To create a custom Asteroid - as an example of how to create a custom CelestialBody - perform the following steps.

  1. In the Resource Tree, expand the SolarSystem folder.
  2. Right-click Sun and select Add -> Asteroid.
  3. In the New Asteroid dialog box, type the desired name.

The CelestialBody Properties tab is shown below.  GMAT models all bodies as spherical ellipsoids and you can set the Equatorial Radius, Flattening, and Mu (gravitational parameter) on this dialog box, as well as the texture map used in OrbitView graphics displays. 


 The CelestialBody Orbit tab is shown below for creating a custom CelestialBody.  Settings on this panel are inactive for built-in celestial bodies and the ephemeris for built-in bodies is configured on the Solar System dialog.  The CentralBody field is populated automatically when the object is created and is always inactive.  To configure SPICE ephemerides for a custom body, provide a list of SPK files and the NAIF ID.  See the Remarks section below for more information on configuring SPICE files.

 The CelestialBody Orientation tab is shown below.  Most settings on this panel are inactive for built-in celestial bodies and exceptions for the Earth and Earth's moon are described further below.  To define the orientation for a celestial body you provide a reference epoch, the initial orientation at the reference epoch, and angular rates.  See the Remarks section for a more detailed description of the orientation model.

The Earth and Earth's moon have unique fields to configure their orientation models.  The Earth has an extra field called Nutation Update Interval that can be used when lower fidelity, higher performance simulations are required.  

For Developer and GUI Tester:  RotationDataSource is displayed but inactive for all bodies


Celestial Body Orientation Model

The orientation of built-in celestial bodies is modeled using high fidelity theories on a per-body basis.  The orientation of Earth is modeled using IAU-1976/FK5.  Th orientation of the Moon is modeled using lunar librations from the DE405 file.  The remaining built-in celestial body orientations are modeled using data published by the IAU/IAG and documented by Seidelmann1.

The orientation of a custom CelestialBody is modeled by providing three angles and their rates based on IAU/IAG conventions.  The figure below illustrates the angles.  The angles αo, δo, and W, are respectively the SpinAxisRAConstant, SpinAxisDECConstant, and RotationConstant. The angular rates are respectively SpinAxisRARate, SpinAxisDECRate, and RotationRate.  All angles are referenced to the X-Y plane of the ICRF axis system.  The constant values SpinAxisRAConstant, SpinAxisDECConstant, and RotationConstant are defined to be the values at the epoch defined in OrientationEpoch.

Below is an example illustrating how to configure a CelestialBody according to the IAU 2006 recommended values for Vesta. Note the orientation epoch typically used by the IAU is 01 Jan 2000 12:00:00.00.000 TDB and this must be converted to A1ModJulian which can easily be performed using the Spacecraft Orbit dialog box.

Create Asteroid Vesta
Vesta.CentralBody         = Sun;
Vesta.OrientationEpoch    = 21544.99962789878;  %  Note that currently the only available format for OrientationEpoch is A1ModJulian
Vesta.SpinAxisRAConstant  = 301.9;
Vesta.SpinAxisRARate      = 0.9;
Vesta.SpinAxisDECConstant = 90.9;
Vesta.SpinAxisDECRate     = 0.0;
Vesta.RotationConstant    = 292.9;
Vesta.RotationRate        = 1617.332776;

Note: The orientation models available for Earth and Luna have additional fields for configuration.   Earth has an additional field called  Nutation Update Interval that controls the update frequency for the Nutation matrix.  For high fidelity applications, NutationUpdateInterval should be set to zero.  The RotationDataSource field for Earth and Luna defines the theory used for the rotation of those bodies.  Currently, only FK5IAU1980 and DE405 are available for Earth and Luna respectively and the field is displayed for information purposes only.  Future versions of GMAT will support DE421 for Luna and IAU-2000A theory for Earth.

Configuring Orbit Ephemerides

The ephemerides for built-in celestial bodies is specified by the SolarSystem.EphemerisSource field and the same source is used for all built-in bodies.  Ephemerides for a custom CelestialBody are provided by SPICE files.   Archives of available SPICE files are the JPL NAIF site here and the Solar System Dynamics site here .  JPL provides utilities to create custom SPICE files in the event existing kernels don't satisfy requirements for your application.  To create custom SPICE kernels, see the documentation provided by JPL.  The list of NAIF Ids for celestial bodies is located here.

Note that the DE files model the barycenter of planetary systems.  So for Jupiter, when using DE405, you are modelling Jupiter's location as the barycenter of the Jovian system.  SPICE kernels differentiate the barycenter of a planetary system from the location of the individual bodies.  So when using SPICE to model Jupiter, you are modeling the location of Jupiter using Jupiter's center of mass. 

To specify the SPICE kernels for a custom CelestialBody, use the NAIFId, CentralBody, and SourceFileName fields.  GMAT is distributed with an SPK file for CERES which has a NAIF ID 2000001.  Here is how to configure a CelestialBody to use the CERES SPICE ephemeris data.

Create CelestialBody Ceres
Ceres.CentralBody = Sun;
Ceres.SourceFilename = '../data/planetary_ephem/spk/ceres_1900_2100.bsp' 

Note: GMAT currently only supports a single ephemeris model for custom bodies (SPICE)  and this is set using PosVelSource field.  The default for PosVelSource is SPICE and it is not necessary to configure this field in the current version of GMAT.

Warning: NIAF distributes SPICE kernels for many celestail bodies and each kernel is consistent with a particular primary ephemeris release such as DE421. For high precision analysis it is important to ensure that the ephemerides used for a custom celestial body is consistent with the ephemeris source selection in SolarSystem.EphemerisSource field. Often SPICE kernels are distributed with a ".cmt" file and in that file the line that contains the ephemeris model looks like this:

Configuring Physical Properties

GMAT models all celestial bodies as spherical ellipsoids.  To define the physical properties use the Flattening, EquatorialRadius, and Mu fields.    


Configure a CelestialBody to model Saturn's moon Titan.  Note you must obtain the SPICE kernel named "sat351.bsp" from here and place it it the directory identified in the script snippet below.

Create Moon Titan;
GMAT Titan.NAIFId               = 606;   
GMAT Titan.OrbitSpiceKernelName = {'../data/planetary_ephem/spk/DE421AllPlanets.bsp', '../data/planetary_ephem/spk/sat351.bsp'};
GMAT Titan.EquatorialRadius     = 2575;
GMAT Titan.Flattening           = 0;
GMAT Titan.Mu                   = 8978.5215;
GMAT Titan.PosVelSource         = 'SPICE';
GMAT Titan.CentralBody          = 'Saturn';
GMAT Titan.RotationDataSource   = 'IAUSimplified';
GMAT Titan.OrientationEpoch     = 21545;
GMAT Titan.SpinAxisRAConstant   = 36.41;
GMAT Titan.SpinAxisRARate       = -0.036;
GMAT Titan.SpinAxisDECConstant  = 83.94;
GMAT Titan.SpinAxisDECRate      = -0.004;
GMAT Titan.RotationConstant     = 189.64;
GMAT Titan.RotationRate         = 22.5769768;

Test Procedures

Unique Validation Tests




1.  Seidelmann, P. K., “Report of the IAU/IAG Working Group on Cartographic Coordinates and Rotational Elements of the Planets and Satellites: 2000,” Celestial Mechanics and Dynamical Astronomy, Vol. 82, No. 1, 2002, pp. 83 – 111.































































































































  • No labels

1 Comment

  1. Testing - adding a comment.