Stepping the Spacecraft

In FreeFlyer, you can use either the Step command or the WhileStepping command to propagate a Spacecraft object forward or backward in time. A common usage, shown in the following image, is to enclose the Step command in a While loop, in order to repeat the propagation over some specified time period. The Step command can also be used (either in a While loop or as a one-time command) to propagate the Spacecraft to a user-specified condition.

The Step command can be used the same way whether an integrator or ephemeris file is used as the propagator. If an integrator is used, the Step command will cause FreeFlyer to use the integrator to calculate the state of the Spacecraft an amount of time in the future or past specified by the Step Mode and Step Size. If an ephemeris file is used, the Step command will cause FreeFlyer to step the Spacecraft to the subsequent ephemeris state in the file or by the amount specified by the Step Size.

The Step Command

You can use the Step command with any Spacecraft object. There are two ways to create a Step command, listed below.

•Add a Step command from the Script Elements section into the Mission Sequence

•Manually type the Step command in a FreeForm script editor

A single Step command will propagate the Spacecraft to a point in the future or past based on the step size property or to the subsequent Ephemeris state. Positive step sizes will propagate the Spacecraft forward in time, and negative step sizes will propagate the Spacecraft backward through time. The syntax to propagate a Spacecraft by one step using its step size is simply:

Stepping to a Condition

FreeFlyer makes it easy for you to propagate a Spacecraft to a condition, such as a certain epoch or a certain point in the Spacecraft orbit, before continuing with other analysis on the Spacecraft. The general syntax for the Step command in FreeForm script in this situation is:

Two types of conditions can be specified: variable conditions (such as "Spacecraft1.TA >= 45"), or predefined orbit conditions (such as "Spacecraft1.OrbitApogee"). The properties and methods that define these conditions are referred to as stop-propagation properties and methods, because the propagator stops once it reaches the specified condition.

The Step Command Editor can also be used to propagate a Spacecraft to a condition:

•Once the Step editor is open, select the "Step to Condition?" box (Arrow #1) to access conditions.

•Define the desired end condition (Arrow #2).

•More than one condition can be specified (Arrow #3).

•The script output from any condition created in the editor is shown (Arrow #4) for reference and can be copied into a FreeForm script editor.

Stepping to a Variable Condition

The example below demonstrates stepping a Spacecraft object to a specific TAI epoch in Modified Julian Date format:

If an ephemeris file is used for propagation, and the epoch is not explicitly specified in an ephemeris file, FreeFlyer will interpolate the state of the Spacecraft at that epoch.

Step Spacecraft1 to (Spacecraft1.Epoch == "Jan 04 2020 06:00:00.000".ParseCalendarDate());

Note: As of FreeFlyer 7.3, the default timing precision mode is nanosecond precision mode. For older Mission Plans that have not yet been converted from millisecond precision mode, the syntax for working with epochs and calendar date/time strings is different. A few samples are shown below; see the timing precision mode page for more information.

Step Spacecraft1 to (Spacecraft1.Epoch == 25167.5);

Step Spacecraft1 to (Spacecraft1.Epoch == "Mar 24 2024 06:00:00.000".EpochScan());

The example below demonstrates stepping a Spacecraft object to a specific true anomaly:

The Step-to syntax allows the propagator to proceed forwards or backwards in time in order to reach the specified goals. The direction to search for the goal condition is determined by the propagator step size; set the step size to a positive value to restrict the results to times in the future, or a negative value to search for an event in the past.

(Spacecraft1.Propagator AsType RK89).StepSize = TIMESPAN(-300 seconds); // Use a negative step size to propagate backwards in time

Step Spacecraft1 to (Spacecraft1.BLJ2A > 6500);

The "and" and "or" logical operators can be used to create compound conditions that impose multiple restrictions on the state to Step to. See the Usage Guidelines for more information about stepping to compound conditions.

Step Spacecraft1 to (Spacecraft1.BLJ2A > 6500 and Spacecraft.InShadow() == 0);

When propagating a Spacecraft using the Step-to syntax, FreeFlyer will take many internal steps rather than stepping to the end condition all at once. If the Spacecraft's propagator is using a fixed step size, FreeFlyer will take internal steps according to the propagator's step size. If the propagator is using a variable step size, then the Integrator.StepToTake proparty dictates the next step size of the propagator. FreeFlyer will automatically take smaller integration steps as needed in order to maintain the propagator's error tolerance settings. If the error tolerance cannot be achieved by reducing the internal step size to the smallest allowed time increment, then FreeFlyer will throw a runtime error. In nanosecond mode, the smallest allowed time increment is one nanosecond.

Note: When using the "Step to" syntax with a hard condition (i.e. using the "==" operator rather than ">=" or "<="), FreeFlyer will first check to see if the condition is currently true before propagating the Spacecraft. If the condition is already true, then FreeFlyer will start by taking one internal step to ensure that the propagator proceeds to the next stopping condition rather than remaining at the current condition indefinitely. See the Usage Guidelines for more information.

The Spacecraft.StepToEpoch() method can also be used to propagate a Spacecraft object to a specific epoch and is particularly useful for stepping to an offset time from an initial epoch. See the Commands Versus Methods section of the Usage Guidelines for details on stepping to time-based conditions.

// Step the Spacecraft to the specified epoch

Spacecraft1.StepToEpoch(TIMESPAN(28850 days));

// Step 1 day into the future

Spacecraft1.StepToEpoch(Spacecraft1.Epoch + TimeSpan.FromDays(1));

The WhileStepping Command

The WhileStepping command is an alternative to the Step command that allows you to execute other FreeFlyer script during the propagation. The WhileStepping command is similar to a While statement, and it can contain script to View the Spacecraft, Put the Spacecraft's state to an Ephemeris, Plot some properties, or perform any number of other actions. The example below demonstrates how you would use the WhileStepping command in FreeFlyer script to step a Spacecraft one day into the future and generate some output while performing that propagation.

Spacecraft mySpacecraft;

TimeSpan epoch = mySpacecraft.Epoch;

// Step 1 day into the future

WhileStepping mySpacecraft to (mySpacecraft.Epoch >= (epoch + TimeSpan.FromDays(1)));

View mySpacecraft;

Report mySpacecraft.Epoch;

End;

Stop-Propagation Properties and Methods

"Stop-Propagation" properties and methods were designed for use with the Step command, as shown in the syntax examples below. The propagator stops once it reaches the specified condition.

Step Spacecraft1 to (Spacecraft1.OrbitApogee());

Step Spacecraft1 to (Spacecraft1.AscendingNode);

If the Spacecraft is using a propagator with a positive step size, it will advance forward in time to the next time the condition is met, and if the Spacecraft is using a propagator with a negative step size, it will advance backward in time to the last time the condition was met.

The stop-propagation conditions Spacecraft.OrbitPeriapsis(), Spacecraft.OrbitApoapsis(), Spacecraft.OrbitPerigee(), and Spacecraft.OrbitApogee() are computed considering the full effects of the Spacecraft's force model on the orbit. Note that, for low orbits with small eccentricity, the J2 effect can cause two numerical "apogees" and "perigees" within a single orbit period. Additionally, because these methods use the full force model to identify the apsis event, it is expected that the Keplerian true anomaly (Spacecraft.TA) will not necessarily be equal to 0 or 180 degrees after stepping to an apsis.

When evaluating an instantaneous Stop-Propagation condition rather than stepping to it (for example, "Report Spacecraft1.AscendingNode", which would report either a 0 or 1 depending on whether the Spacecraft is currently at the ascending node), a time-based tolerance is used to determine whether the Spacecraft's current state meets the stopping condition. If the Spacecraft is within that time-based proximity of the event, then the Stop-Propagation property or method will return true. This tolerance is set by the FF_Preferences.OrbitPointTolerance property.

Spacecraft1.StepToApsis(0); // Steps to periapsis

Spacecraft1.StepToApsis(1); // Steps to apoapsis

Spacecraft1.StepToNode(0); // Steps to ascending node

Spacecraft1.StepToNode(1); // Steps to descending node

Usage Guidelines

Following the guidelines discussed below will help you get the results you expect when stepping a Spacecraft to a condition in FreeFlyer.

Commands Versus Methods

FreeFlyer allows propagation to stopping conditions by using either the "Step to <condition>" command syntax or an equivalent method such as StepToEpoch() or StepToApsis(). When the stopping condition is time-based in any way, it is best to use the method version, which evaluates the condition before any propagation occurs.

Spacecraft1.StepToEpoch(Spacecraft1.Epoch + TIMESPAN(1 days)); // Stopping condition is evaluated before propagation

The command syntax can not be used to step to a condition like the one in the example above, because the condition is re-evaluated at each internal step and can never be met. Instead, the desired epoch would need to be saved before calling the Step-to command as shown below:

TimeSpan desiredEpoch = Spacecraft1.Epoch + TIMESPAN(1 days);

Step Spacecraft1 to (Spacecraft1.Epoch == desiredEpoch);

Implementing the method form is also recommended in the context of using the debugger, as the command form will force the debugger to remain on the "Step to" line while each internal step is taken.

Choosing a Step Size

When stepping to a condition, in order to avoid getting "stuck" at the starting condition, FreeFlyer takes a single step at the propagator's normal step size away from the initial state, then begins looking for the next instance of the stopping condition. This means that it is possible for the propagator to step over a valid stopping condition if the event falls within that first step size increment, and continue propagating to the next event instead. Because of this, the user should be sure to manage the step size appropriately for the condition that they are attempting to meet. Note that this behavior applies for both forward and backward propagation.

Compound Conditions

FreeFlyer allows the user to define compound conditions to step to using the "and" and "or" logical operators. When stepping to or evaluating a compound condition, if the expected result is not observed, it can be helpful to split the conditions into multiple "step to" evaluations in order to simplify the debugging process.

Poorly Defined or Undefined Stopping Conditions

When propagating to a condition, FreeFlyer assumes that the stopping condition can be represented linearly over a nanosecond time interval (or millisecond, if using millisecond timing precision mode). In order for the underlying algorithm to converge, the stopping condition should be formulated in a way that will avoid discontinuities or highly non-linear evaluations. It is the user's responsibility to formulate a stopping condition that is well-defined for their scenario.

In some extreme cases, numeric noise can become significant at very small step sizes. The FF_Preferences.PropagationStoppingConditionTolerance property can be used to scope the search space to a domain where the noise is less dominant.