ContactLocator

Data configuration

The ContactLocator implementation is based on the NAIF SPICE toolkit, which uses a different mechanism for environmental data such as celestial body shape and orientation, planetary ephemerides, body-specific frame definitions, and leap seconds. Therefore, it is necessary to maintain two parallel configurations to ensure that the event location results are consistent with GMAT's own propagation and other parameters. The specific data to be maintained is:

SolarSystem.PCKFilename = '..\data\planetary_coeff\pck00010.tpc'
Earth.EquatorialRadius = 6378.1366
Earth.Flattening = 0.00335281310845547

See SolarSystem and CelestialBody for more details.

Search interval

The ContactLocator search interval can be specified either as the entire ephemeris interval of the Target, or as a user-defined interval. Each mode offers specific behavior related to handling of light-time delay and discontinuous intervals.

If UseEntireInterval is true, the search is performed over the entire ephemeris interval of the Target, including any gaps or discontinuities. If light-time delay is enabled, the search interval is truncated by the approximate light time to allow SPICE to determine the exact light-time delay between the participants during the search. If LightTimeDirection is Transmit, the beginning of the interval is truncated. If LightTimeDirection is Receive, the end of the interval is truncated. In either case, the other end of the interval is trimmed slightly via bisection to avoid stepping beyond the end of the ephemeris due to numeric precision issues. This trimming is typically less than 1 s. The endpoints of gaps or discontinuities are not modified, so these are not fully supported if light-time delay is enabled. If light-time delay is disabled, the entire interval is used directly, with no endpoint manipulation.

If UseEntireInterval is false, the provided InitialEpoch and FinalEpoch are used to form the search interval directly. This interval is consistent with the Observer clock, and does not support the inclusion of gaps or discontinuities from the Target ephemeris. The user must ensure than the provided interval results in valid Target ephemeris epochs after light-time delay and stellar aberration have been applied.

These rules are summarized in the following table, where t₀ and t_f are the beginning and end of the Target ephemeris, respectively, and lt is the light time between the Target and the Observer.

Run modes

The ContactLocator works in conjunction with the FindEvents command: the ContactLocator resource defines the configuration of the event search, and the FindEvents command executes the search at a specific point in the mission sequence. The mode of interaction is defined by ContactLocator.RunMode, which has three options:

Search algorithm

The ContactLocator uses the NAIF SPICE GF (geometry finder) subsystem to perform event location. Specifically, the following two calls are used for the search:

Both functions implement a fixed-step search method through the interval, with an embedded root-location step if an event is found. Proper selection of StepSize differs between the two functions.

For the basic line-of-sight search, without third-body occultations, StepSize can be set as high as one-half the period of the event function. For an elliptic orbit, this is up to one-half the orbit period.

For third-body occultations, StepSize should be set equal to the length of the minimum-duration event to be found, or equal to the lenght of the minimum-duration gap between events, whichever is smaller. To guarantee location of 10-second occultations, set StepSize = 10.

If no third-body occultations are to be found, you can increase performance of the search by increasing StepSize per the notes above.

For details, see the reference documentation for the two functions linked above.

Report format

When WriteReport is enabled, ContactLocator outputs an event report at the end of each search execution. The report contains the following data:

A sample report is shown below.

Target: DefaultSC

Observer: GroundStation1
Start Time (UTC)            Stop Time (UTC)               Duration (s)         
01 Jan 2000 13:18:45.268    01 Jan 2000 13:29:54.824      669.55576907    
01 Jan 2000 15:06:44.752    01 Jan 2000 15:18:22.762      698.01023654    


Number of events : 2


Observer: GroundStation2
Start Time (UTC)            Stop Time (UTC)               Duration (s)         
01 Jan 2000 13:36:13.792    01 Jan 2000 13:47:51.717      697.92488540    


Number of events : 1

Event location with SPK propagator

When using the SPK propagator, you load one or more SPK ephemeris files using the Spacecraft.OrbitSpiceKernelName field. For the purposes of event location, this field causes the appropriate ephemeris files to be loaded automatically on run, and so use of the Propagate command is not necessary. This is an easy way of performing event location on an existing SPK ephemeris file. See the example below.

Perform a basic contact search in LEO:

          SolarSystem.EphemerisSource = 'DE421'

Earth.EquatorialRadius = 6378.1366
Earth.Flattening = 0.00335281310845547

Create Spacecraft sat
sat.DateFormat = UTCGregorian
sat.Epoch = '15 Sep 2010 16:00:00.000'
sat.CoordinateSystem = EarthMJ2000Eq
sat.DisplayStateType = Keplerian
sat.SMA = 6678.14
sat.ECC = 0.001
sat.INC = 0
sat.RAAN = 0
sat.AOP = 0
sat.TA = 180

Create ForceModel fm
fm.CentralBody = Earth
fm.PrimaryBodies = {Earth}
fm.GravityField.Earth.PotentialFile = 'JGM2.cof'
fm.GravityField.Earth.Degree = 0
fm.GravityField.Earth.Order = 0
fm.GravityField.Earth.TideModel = 'None'
fm.Drag.AtmosphereModel = None
fm.PointMasses = {}
fm.RelativisticCorrection = Off
fm.SRP = Off

Create Propagator prop
prop.FM = fm
prop.Type = RungeKutta89

Create GroundStation GS
GS.CentralBody = Earth
GS.StateType = Spherical
GS.HorizonReference = Ellipsoid
GS.Location1 = 0;
GS.Location2 = 0;
GS.Location3 = 0;

Create ContactLocator cl
cl.Target = sat
cl.Observers = {GS}
cl.Filename = 'Simple.report'

BeginMissionSequence

Propagate prop(sat) {sat.ElapsedSecs = 10800}
        

Perform a contact event search from an Earth ground station to a Mars orbiter, with Phobos occultations:

          % Mars orbiter, 2 days, Mars and Phobos eclipses

SolarSystem.EphemerisSource = 'SPICE'
SolarSystem.SPKFilename = 'de421.bsp'

Mars.OrbitSpiceKernelName = '../data/planetary_ephem/spk/mar063.bsp'

Earth.EquatorialRadius = 6378.1366
Earth.Flattening = 0.00335281310845547

Create Spacecraft sat
sat.DateFormat = UTCGregorian
sat.Epoch = '11 Mar 2004 12:00:00.000'
sat.CoordinateSystem = MarsMJ2000Eq
sat.DisplayStateType = Cartesian
sat.X = -1.436997966893255e+003
sat.Y = 2.336077717512823e+003
sat.Z = 2.477821416108639e+003
sat.VX = -2.978497667195258e+000
sat.VY = -1.638005864673213e+000
sat.VZ = -1.836385137438366e-001

Create ForceModel fm
fm.CentralBody = Mars
fm.PrimaryBodies = {Mars}
fm.GravityField.Mars.PotentialFile = 'Mars50c.cof'
fm.GravityField.Mars.Degree = 0
fm.GravityField.Mars.Order = 0
fm.Drag.AtmosphereModel = None
fm.PointMasses = {}
fm.RelativisticCorrection = Off
fm.SRP = Off

Create Propagator prop
prop.FM = fm
prop.Type = RungeKutta89

Create Moon Phobos
Phobos.CentralBody = 'Mars'
Phobos.PosVelSource = 'SPICE'
Phobos.NAIFId = 401
Phobos.OrbitSpiceKernelName = {'mar063.bsp'}
Phobos.SpiceFrameId = 'IAU_PHOBOS'
Phobos.EquatorialRadius = 13.5
Phobos.Flattening = 0.3185185185185186
Phobos.Mu = 7.093399e-004

Create Moon Deimos
Deimos.CentralBody = 'Mars'
Deimos.PosVelSource = 'SPICE'
Deimos.NAIFId = 402
Deimos.OrbitSpiceKernelName = {'mar063.bsp'}
Deimos.SpiceFrameId = 'IAU_DEIMOS'
Deimos.EquatorialRadius = 7.5
Deimos.Flattening = 0.30666666666666664
Deimos.Mu = 1.588174e-004

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

Create GroundStation GS
GS.CentralBody = Earth
GS.StateType = Spherical
GS.HorizonReference = Ellipsoid
GS.Location1 = 36.3269
GS.Location2 = 127.433
GS.Location3 = 0.081

Create ContactLocator cl
cl.Target = sat
cl.Observers = {GS}
cl.OccultingBodies = {Sun, Mercury, Venus, Luna, Mars, Phobos, Deimos}
cl.Filename = 'Martian.report'
cl.StepSize = 5

BeginMissionSequence

Propagate prop(sat) {sat.ElapsedDays = 2}
        

Perform contact location on an existing SPK ephemeris file:

          
            SolarSystem.EphemerisSource = 'DE421'

Earth.EquatorialRadius = 6378.1366
Earth.Flattening = 0.00335281310845547

Create Spacecraft sat
sat.OrbitSpiceKernelName = {'../data/vehicle/ephem/spk/Events_Simple.bsp'}

Create GroundStation GS
GS.CentralBody = Earth
GS.StateType = Spherical
GS.HorizonReference = Ellipsoid
GS.Location1 = 0
GS.Location2 = 0
GS.Location3 = 0

Create ContactLocator cl
cl.Target = sat
cl.Observers = {GS}
cl.Filename = 'SPKPropagation.report'

BeginMissionSequence