Interval Methods

Interval Methods in FreeFlyer provide a means to precisely calculate the start and stop times of a specified event. The precise time for each event can be calculated to millisecond-level accuracy in Millisecond Mode Mission Plans, and to nanosecond-level accuracy in Nanosecond Mode Mission Plans. The accuracy does not depend on the spacecraft’s propagation step size. Three configuration settings are used to control the accuracy of the event times:

•FF_Preferences.IntervalEventSkipAccuracy - Controls the minimum event duration for events that will not be skipped by the searching algorithm. The default value is 10 seconds, meaning that events shorter than 10 seconds may not be detected by default.

•FF_Preferences.IntervalEventStopAccuracy - Controls the accuracy to which the time boundaries of events are resolved. The default value is 0.1 seconds, meaning that the start and end times of an event will be accurate to within 0.1 seconds by default.

•FF_Preferences.IntervalEventReportingBehavior - Controls whether the start and end of propagation are reported as interval method events if an event is ongoing at the start or end of propagation.

There are interval methods available for calculating entry and exit from contact between spacecraft and other assets, passes through umbral and penumbral shadow, intersection times between a spacecraft and a Proximity Zone, and more. For a complete list of the Interval Methods available in FreeFlyer, see the List of Interval Methods in the Appendix. A summary of the available instantaneous and interval methods is presented on the Contact Method Summary page.

Interval Methods Summary

1.String Version: If an interval method is reported out to a file, it generates a custom-formatted report containing pre-defined header, summary, and detailed data fields. The output of interval methods can be complex, as shown in the PassData section below. As such, each interval method should be reported to a separate file when using the String version of the interval method, and you should not include any other data in the same report. Additionally, you should not save the results of the string version of an interval method to a String object for subsequent parsing or manual reporting. When reporting the string directly to a file, FreeFlyer will close the file at the end of the Mission Plan execution or when you Close a ReportInterface and flush out any partial events that had been noted but not yet reported to the file. The example below shows how to generate a report file using the Spacecraft.ContactTimes() interval method:

Report Spacecraft1.ContactTimes(GroundStation1) to “ContactTimesReport.txt”;

The Spacecraft.Access and Spacecraft.PassData examples below also demonstrate this approach.

Note: If you wish to create a custom-formatted report in the Console, a DataTableWindow, or send results to a custom-formatted output file, you should use the Array version of the interval method.

2.Array Version: Interval methods can also be used to populate arrays with event data. The data in these arrays can then be used to perform further analysis within your Mission Plan or generate custom, user-defined reports. In this form, the interval method returns the number of events that have occurred from one execution of the line to the next (i.e., between each propagation step), and then stores any data about the event crossings in the provided arrays. This provides the ability to perform additional analysis of the state at the time of the event crossing. This example shows how to populate arrays with event times and event types using the ProximityZone.Intersects() interval method:

numEvents = ProximityZone1.Intersects(Spacecraft1, EventTimeArray, EventTypeArray, EventRangeArray);

The numEvents variable indicates the number of intersection entries/exits that occurred during the last propagation step – this variable can then be used to trigger further analysis on the event data in the arrays.

The Spacecraft.ShadowTimes and VisibilityCalculator.VisibilityTimes examples below also demonstrate this approach.

If an event starts before the beginning of the propagation span, FreeFlyer will label the start of the propagation as the start of the event by default. Likewise, if an event extends past the end of the propagation span, FreeFlyer labels the end of propagation as the end of the event when the interval method is reported using its String version. FreeFlyer does not propagate backward to find the start of an event that occurred before the start of the propagation span, or continue propagating after the end of the propagation span in order to find the end of an event. To prevent FreeFlyer from labeling the start or end of propagation as an event, use the FF_Preferences.IntervalEventReportingBehavior property.

Proper Syntax

Interval Methods are considered "Properties and Methods with a State," which means that FreeFlyer internally stores historical data when these methods are called. Although this functionality is very powerful, it is important to use it correctly. When using an interval method, it is important to call the method for every step of the analysis. So, for a typical analysis loop, you might have something like this. The Spacecraft.PassData interval method reports when a GroundStation can see a Spacecraft.

Never use an interval method inside an If statement that checks the state of the event. For example, the Spacecraft.Contact instantaneous method can be used to report whether a GroundStation can see a Spacecraft, but the PassData interval method needs to be able to evaluate the times when contact is lost in order to accurately calculate the crossing time from AOS to LOS. If the call to PassData is placed inside this If statement (as shown in the following example), it would report incorrect results.

Interval Methods with Lists

You can use interval methods with Lists of objects. For example, you may want to loop through a List of GroundStations and report pass data between a Spacecraft and each GroundStation in the List, as shown in the example below. Each time the GroundStation argument passed to the PassData interval method is changed, FreeFlyer keeps track of this internally as a new state.

Variable i;

Spacecraft sc;

List<GroundStation> gsList;

gsList.Count = 3;

While (sc.ElapsedTime < TIMESPAN(1 days));

For i = 0 to gsList.Count-1;

Report sc.PassData(gsList[i]) to "PassDataReport.txt";

End;

Step sc;

End;

Run "notepad.exe PassDataReport.txt";

Note: In millisecond timing precision mode, properties and methods with a state are automatically reset at the start of each iteration of a For loop; the "without reset" keywords must be used to prevent the state from being reset. This is necessary so that the historical data tracked within the interval method is not reset at the start of each iteration of the For loop. This is explained in further detail on the Properties and Methods with a State page.

Interval Method Example: Spacecraft.Access

The Spacecraft.Access Method returns the start time, end time, and duration of a Spacecraft's view of a Region, GroundStation, CelestialObject, or another Spacecraft.

In the example below, the first Report command, which generates "AccessReport.txt", calculates mySpacecraft's access to myGroundStation. The Access time is based on any active Sensors on the Spacecraft.

The second Report command shows how to use the Access method using only one of the Sensors on a Spacecraft that has multiple Sensors. The Report, generating "SensorReport.txt", calculates the access of mySpacecraft to the Sun, using only mySpacecraft.Sensors[0].

Spacecraft.Access Example

Output Excerpt from "AccessReport"

Access Event Entry Epoch Exit Epoch Duration(min)

myGroundStation --> mySpacecraft Jan 01 2020 18:54:54.506835937 Jan 01 2020 18:56:25.986328125 1.524658203

myGroundStation --> mySpacecraft Jan 02 2020 07:00:29.443359375 Jan 02 2020 07:03:27.788085937 2.972412109

myGroundStation --> mySpacecraft Jan 03 2020 18:44:12.832031250 Jan 03 2020 18:46:47.885742187 2.584228516

myGroundStation --> mySpacecraft Jan 04 2020 06:49:57.802734375 Jan 04 2020 06:51:57.260742187 1.990966797

myGroundStation --> mySpacecraft Jan 05 2020 07:33:38.920898437 Jan 05 2020 07:35:16.040039062 1.618652344

myGroundStation --> mySpacecraft Jan 05 2020 18:33:35.185546875 Jan 05 2020 18:36:39.975585937 3.079833984

Output Excerpt from "SensorReport"

Access Event Entry Epoch Exit Epoch Duration(min)

Sun --> mySpacecraft_Sensor1 Jan 01 2020 00:09:14.150390625 Jan 01 2020 00:20:14.428710937 11.004638672

Sun --> mySpacecraft_Sensor1 Jan 01 2020 01:48:10.576171875 Jan 01 2020 01:59:11.147460937 11.009521484

Sun --> mySpacecraft_Sensor1 Jan 01 2020 03:27:07.001953125 Jan 01 2020 03:38:07.719726562 11.011962891

Sun --> mySpacecraft_Sensor1 Jan 01 2020 05:06:03.354492187 Jan 01 2020 05:17:04.438476562 11.018066406

Interval Method Example: Spacecraft.PassData

The Spacecraft.PassData method provides detailed information on the contact between a GroundStation and a Spacecraft. For each contact period, the content of the information is presented in two parts, Summary and Detailed. The Summary, which is provided first, includes:

The Detailed section is presented in tabular form at the frequency of the propagation step size during the contact period, and provides:

Spacecraft.PassData Example

Output Excerpt

Contact myGroundStation to mySpacecraft

AOS LOS Duration(min) MaxElevation(deg)

Jan 01 2020 06:19:55.825195312 Jan 01 2020 06:27:47.944335937 7.868652344 25.201605860

Epoch Azimuth(deg) Elevation(deg) Range(km) RangeRate(km/sec)

Jan 01 2020 06:19:55.825195312 41.435311272 10.003623663 2189.441030164 -5.386444260

Jan 01 2020 06:20:00.000000000 41.943987785 10.312267826 2167.031598449 -5.348902080

Jan 01 2020 06:25:00.000000000 118.954660392 23.022054964 1481.673470996 2.261181911

Jan 01 2020 06:27:47.944335937 152.504608539 9.997339828 2175.405126641 5.388411819

Contact myGroundStation to mySpacecraft

AOS LOS Duration(min) MaxElevation(deg)

Jan 01 2020 07:57:38.129882812 Jan 01 2020 08:05:20.727539062 7.709960938 24.685316686

Epoch Azimuth(deg) Elevation(deg) Range(km) RangeRate(km/sec)

Jan 01 2020 07:57:38.129882812 343.201420121 10.003078374 2191.215989595 -5.420000590

Jan 01 2020 08:00:00.000000000 317.249113102 21.079710580 1565.522311510 -2.977750395

Jan 01 2020 08:05:00.000000000 238.233610780 11.569935717 2069.138821348 5.170478558

Jan 01 2020 08:05:20.727539062 235.574157873 9.996855882 2178.605866646 5.385971325

Interval Method Example: Spacecraft.ShadowTimes

The Spacecraft.ShadowTimes interval method returns the entry time, exit time, and duration of a Spacecraft's pass through the shadow of the spacecraft's central body. Events are reported for Penumbra, Umbra, or Annular shadow condition geometries.

In this example, the two-argument form of Spacecraft.ShadowTimes is used. This form provides the ability to perform additional analysis of the state at the time of the event crossing, such as calculation of mySpacecraft.Height. Similar syntax is used for the ShadowTimes, EarthShadowTimes, and MoonShadowTimes methods.

Value	EventType
1	Entry into Annular Shadow
2	Exit from Annular Shadow
101	Entry into Umbral Shadow
102	Exit from Umbral Shadow
201	Entry into Penumbral Shadow
202	Exit from Penumbral Shadow

ShadowTimes Example

Variable i;

Variable numEvents;

Array EventType;

TimeSpanArray EventTime;

While (mySpacecraft.ElapsedTime < TIMESPAN(1 days));

View mySpacecraft;

numEvents = mySpacecraft.ShadowTimes(EventTime, EventType);

For i = 0 to numEvents-1;

Step mySpacecraft to (mySpacecraft.Epoch == EventTime[i]);

Report mySpacecraft.EpochText, mySpacecraft.Height, numEvents, EventTime[i].ConvertToCalendarDate(), EventType[i];

End;

Step mySpacecraft;

End;

Output Excerpt

mySpacecraft.EpochText	Height	numEvents	EventTime	EventType
Jan 01 2020 00:06:53.232421875	718.287251739	2.000000000	Jan 01 2020 00:06:53.232421875	102.000000000
Jan 01 2020 00:07:03.193359375	718.477289811	2.000000000	Jan 01 2020 00:07:03.193359375	202.000000000
Jan 01 2020 01:11:50.815429687	724.129643457	2.000000000	Jan 01 2020 01:11:50.815429687	201.000000000
Jan 01 2020 01:12:00.703125000	724.108452345	2.000000000	Jan 01 2020 01:12:00.703125000	101.000000000
Jan 01 2020 01:45:49.877929687	718.172223320	2.000000000	Jan 01 2020 01:45:49.877929687	102.000000000

Interval Method Example: VisibilityCalculator.VisibilityTimes

The VisibilityCalculator.VisibilityTimes interval method returns the start and end times of visibility across any or all of the Segments associated with the VisibilityCalculator. Each Segment has a defined observer and target, and can be configured with user-specified occulting bodies, celestial object shape models, and refraction models. The example below shows how to compute the times when any of a set of three Sensors on a Spacecraft can see a particular GroundStation.

// Create the observers and target

GroundStation gs;

Spacecraft sc;

sc.AddSensor("sensor1");

sc.AddSensor("sensor2");

sc.AddSensor("sensor3");

// Create the VisibilityCalculator and Segments

VisibilityCalculator VisibilityCalc;

VisibilityCalc.VisibilityRequirement = 1; // Any

VisibilityCalc.AddSegment("sensor1-to-gs");

VisibilityCalc.AddSegment("sensor2-to-gs");

VisibilityCalc.AddSegment("sensor3-to-gs");

Variable i;

Variable numEvents;

TimeSpanArray EventTimes[0];

Array EventTypes[0];

StringArray EventTypeLabels = {"", "Start of visibility", "End of visibility"};

// Set up the Segments

For i = 0 to VisibilityCalc.Segments.Count-1;

sc.Sensors[i].BoresightAngles[2] = i*20;

VisibilityCalc.Segments[i].SetObserver(sc.Sensors[i]);

VisibilityCalc.Segments[i].SetTarget(gs);

End;

// Propagate and determine visibility times when *any* of the Sensors can see the GroundStation

While (sc.ElapsedTime < TIMESPAN(1 days));

numEvents = VisibilityCalc.VisibilityTimes(sc.Epoch, EventTimes, EventTypes);

For i = 0 to numEvents-1;

Report EventTimes[i].ConvertToCalendarDate(), EventTypeLabels[EventTypes[i]];

End;

View sc, gs;

Step sc;

End;

Interval Methods