Process Control

The following options are available for controlling filter or simulator start and stop times and process noise updates:

Process Control
Option Description
StartMode Specify whether this is the Initial run, a scheduled Restart or an AutoRestart.
(Re)Start time options

Depending on the selection made for StartMode, one of the following will appear:

  • StartTime - If the StartMode is Initial, specify the filter or simulator start time (defaults to scenario start time) here.
  • SelectedRestartTime - If the StartMode is Restart, specify the restart time here.
  • AutoSelectedRestartTime - If the StartMode is AutoRestart, the automatically selected restart time will appear here (read-only).
RestartLastMeasTime
(Filter Only)		 Only displayed when running from a restart record when the Filter is in deep space mode. Displays the time of the last processed observation associated with the selected restart record. Note that this time may be later than the selected restart time. For further details, see the description of the EnableDeepSpaceMode setting for the Filter.
Direction Filter direction (in time)

= Forwards | Backwards (default = Forwards)

when "Backwards" is selected the following are disabled:

  • Restart
  • Smoother
  • VLS

when "Backwards" is selected times are "like Smoother" timing

  • .Start Time > Stop Time
  • .Report/Graphs in Time ascending order
StopMode Select one of the following:
  • LastMeasurement - stop the filter when the last measurement is received
  • StopTime - display a field in which you can specify the desired stop time (defaults to scenario stop time)
  • TimeSpan - set a time duration for the filter or simulator to run before stopping (defaults to the span defined by the scenario start and stop times)
TimeStep
(Simulator only) 		Defines the minimum allowable time between measurements, as well as the grid on which ephemeris will be written if requested. The time step defines the measurement time grid in the absence of custom tracking intervals.
ProcessNoiseUpdateInterval
(Filter only)

Enter a time value in the selected time unit to specify how often process noise is to be updated between measurement passes (see note below). The filter will output data on a union of this uniform time grid and the measurement time grid. The time update grid ensures that process noise is added between measurement passes. This attribute defines the uniform grid used for ephemeris output, if that option is selected.

If the Scenario.Units.DateFormat attribute is set to UTCG, the time upgrade grid will be on an even UTC grid; if it is set to GPSG, it will be on an even GPS grid.

MeasurementProcessingMode
(Filter only) 		Measurements may be processed in either the scalar mode or the simultaneous mode during filter operation. In the scalar mode, a separate measurement update operation is performed for each measurement processed at a given time. In the simultaneous mode, all measurements at a single time are processed together in a single measurement update operation. The simultaneous mode typically improves the run time performance of the filter, but has been seen to exhibit some instability during the filter initialization period if the initial uncertainties are large. You can switch from one mode to the other when running the filter in either initial mode or from a restart record. (See 2nd note below)
CovarianceUpdateForm Select either OptimalGain or Joseph. When OptimalGain is selected, the simplified form of the Kalman measurement update of the covariance, which is possible when selecting the Kalman gain matrix in its linearly optimal form is used. P+ = (I -KH)P-. When Joseph is selected, the more general Joseph form of the covariance measurement update is used. P+ = (I-KH)P-(I-KH)T + KRKT. The optimal gain formulation is more computationally efficient while the Joseph form is more numerically stable. The Joseph form offers less chance of the covariance becoming non-positive definite.
MeasurementModelingMode (Filter only)

The options are Estimation, RefEphem, or RefEphemWithBiases. The default setting is Estimation.

If you select RefEphem, running the filter will only process the measurements, computing residuals and the corresponding measurement error variances using Satellite Reference Trajectories (*.e files) for orbit and orbit covariance values. The filter will not perform estimation. The filter models measurements using the nominal measurement bias and modeling values. Measurement error variance values only consider orbit errors and measurement white noise.

If you select RefEphemWithBiases, running the filter will otherwise behave as with RefEphem, but the filter will include any applicable biases. You should provide biases using OptionalSolveForParams.MeasBiasCorrectionFile.

When using RefEphem or RefEphemWithBiases, you must for all satellites in the Filter.SatelliteList set their Satellite.EstimateOrbit flag to false and specify a Reference Trajectory file as input. Selecting the RefEphem option will cause the Filter StartMode to be set to Initial, the OptionalSolveForParams.MeasBiases to be set to false, the SmootherData.Generate flag to be set to false, and the STKEphemeris.DuringProcess.Generate flag be set to false.

If you select RefEphem, OptionalSolveForParams.MeasBiases is false. If you select RefEphemWithBiases is specified, OptionalSolveForParams.MeasBiases is set to true and OptionalSolveForParams.UseMeasBiasFile is set to true.

If you turn this option back to Estimation (after selecting another option), you must reset these flags.

When using either reference ephemeris option, the filter will model the measurements by interpolating the reference trajectories and propagating the reference covariance as necessary to the time of interest. AGI recommends that you select a smoothed reference ephemeris instead of a filtered reference ephemeris to avoid interpolating across possible discontinuities caused by measurement updates. If the reference trajectory file does not contain velocity covariance, then the filter will propagate the covariance assuming a velocity covariance of zero. If the reference trajectory file does not contain any covariance, then the filter assumes a zero orbit covariance.

Using this feature allows the filter to use a reference ephemeris with covariance in residual calculation and residual covariance calculation. The attribute will cause the filter to stop saving restart files and turn off smoother rough file generation, among other actions. Each action yields a Message Viewer message, but you must reset quantities after making a filter run.

Manual setting of this field can lead to errors in filter settings. AGI recommends that you use the utility ResidualsVersusReference.htm, which will automatically remember and restore settings that this attribute changed.
NumOrbitsAllowedForEpochAlignment Specify the maximum number of revolutions that a satellite orbit may be propagated to align the satellite initial state with the start time of the process. This setting is also used to determine the allowable difference in epochs between a space-based GPS receiver clock state epoch and the initial condition epoch of its host satellite.
GlobalAtmosphericDensityEstimation
(Simulator only)		 Controls for simulating deviations in selected atmospheric density model parameters.
EnableVLS If true and the filter has one or more child VLS objects with their ProcessControl.Generate flag set to true, then those VLS will be executed in conjunction with the Filter execution.
MeasUpdateOrbitStateRepresentation (Filter only)

Select the coordinates to be used when updating the non-linear orbit trajectory during the measurement update operation. Choices are Cartesian coordinates and equinoctial elements. The state update is always computed in Cartesian coordinates but can be linearly transformed to an update in equinoctial elements. For closed orbits where the motion is dominated by the two-body dynamics the equinoctial option typically leads to improved filter accuracy and an increased convergence region. Cartesian coordinates can be used for all classes of orbits including open orbits.

This option is currently incompatible with variable lag smoothing.
EnableDeepSpaceMode
(Filter)		 Configure the Filter to run in deep space mode. In this mode, the estimation state inside the filter is advanced to the Information Time of measurements prior to the execution of the measurement update. The Information Time is approximate time that the tracking signal passes through, or emanates from, the spacecraft. This strategy allows for the current time filter to properly estimate effects occurring local to the spacecraft at the time when the signal is at the spacecraft. This is important for two main reasons:
  • Speed - In the traditional current time filter, the state is advanced to the measurement time tag which is typically at the reception time of the tracking signal at the ground station. In modeling the observation, the state of the spacecraft at the time of signal passage through the satellite is required. In near-Earth scenarios, this time difference is a fraction of a second and is easily accommodated. In deep space scenarios, the time different can be on the order of many minutes to hours, requiring backwards propagation of the satellite state. Maintaining the filter state at a time near the time when the signal passes through the spacecraft, results in a processing scenario that more closely resembles the near-Earth case.
  • Spacecraft effects - Environmental and thruster effects on the spacecraft are localized in time at the spacecraft location. Stochastic models for these effects typically have "decay to mean" type behaviors that lose information content if the spacecraft state has been transitioned across a significant amount of time during measurement modeling. The start/stop of maneuvers can also happen during the time between the measurement time tag and when the signal passed through the spacecraft.

When in deep space mode, the StopTime of the filter is associated with the time of the filter estimation state. Since the typical effect of light time delay is to have the estimation state at an epoch earlier than the time tags of measurements, it is possible that measurements with time tags later than the stop time will be processed. The same concept applies to restart epochs. To improve operator awareness of this nuance, a separate read-only field will be shown below the selected restart record which displays the time of the last processed measurement.

Not all measurement types require the subtraction of light time delay to be localized at the spacecraft. Accelerometer measurements, for example, take measurements locally to the spacecraft. When processing a combination of local and non-local measurements (ex: DSN TCP and Accelerometer), the LookAheadBufferSize in the Scenario settings should be made large enough so that the merged measurement set can be properly sorted into Information Time order. For an example where the one-way light time delay is approximately 20 minutes, the buffer should be sized to comfortably hold at least 20 minutes worth of combined observations.
EnableDeepSpaceMode
(Simulator)		 Configure the simulator to run in deep space mode. The deep space simulator capability works by running through the simulation timeline twice. The first pass of the simulator servers to generate a state history that covers the entire time frame of the simulation. It also includes a buffer, prior to the simulation start time, to accommodate the measurement modeling at the start time of the simulation. This requires spacecraft states prior to the simulation start time. The second pass through the simulation time period generates the measurements using the time history from the first pass. All input times to the simulator are interpreted as indicating the times when measurements are desired.

The deep space mode of the simulator currently has two important limitations:

  • Maneuver events, prior to the start time of the simulation but within the light time delay window, are not accounted for
  • When running in restart mode, the simulation state history generated prior to the restart time will not exactly match with the state history over the same time period. This is to support the simulation of measurements with the light time delay window of the simulation. The state history is generates the restart period from the simulation run.
DynamicStateSpace
(Filter Only)

The filter can be configured to add/drop particular types of states as they are needed. This feature can be used to improve the processing speed of the filter, improve the processing speed of fixed interval and variable lag smoothing and reduce output file size which results in faster reporting and graphing operations. For each type of state, select between Manual (all possible states are included in state space) and Automatic (states are added when needed at the initial epoch and restart points and dropped when not needed). The following table describes the Automatic mode behavior.

Dynamic State Space Options
Type Description
MeasBiases Measurement bias states are added to the state when observations from the associated tracker exist in the filter processing interval. Measurement bias states are dropped when their correlations to the rest of the estimation state falls below the CorrelationThreshold at the restart time and there are no measurements from the associated tracker in the filter processing interval.
FiniteManeuverCorrections

Finite maneuver correction states are added to the state when the stop time of the finite maneuver is after the start of the filter run. Finite maneuver correction states are dropped when their correlations to the rest of the estimation state falls below the CorrelationThreshold at the restart time and the restart time is after the stop time of the maneuver.

Dynamic state space functionality is currently limited to unique maneuver states. Permanent maneuver states are always placed into state space.
CorrelationThreshold The value below which correlations in the state error covariance matrix are considered to be negligible.

Threshold values typically need to be set to larger values when using the Unscented Filter - MeasurementAndTime option in the Filter.HigherOrderCorrections settings when the standard EKF time update is used. The difference in sensitivity is believed to be due to numerical noise, which results from the differencing operations in the UKF time update.
InstantManeuverEstimation
(Filter only)

Corrections to modeled instant maneuvers can be estimated during the filter process. These estimates are facilitated through the use of fixed epoch smoothers where two smoothed states are estimated at the time of the instant maneuver. The first smoothed state does not contain the velocity change associated with the maneuver and the second smoothed state, at the same epoch, does contain the velocity change. The maneuver estimate is derived by differencing of the two smoothed states. Maneuver estimates which have not completed based on the completion criteria listed below may still be reported at the end of the filter run, but will continue in a subsequent filter run which is initialized from a restart record. A maneuver estimate is considered to be complete when any of the associated completion criteria are met. The following options are available for the estimation of the instant maneuvers during the filter process.

Instant Maneuver Options
Type Description
Estimate Produce estimates to modeled instant maneuvers during the time span of the filter run.
Formulation Two formulations of fixed epoch smoothers are available to support the estimation process. The Frazer form of the fixed epoch smoother maps observation residuals from the current filter epoch back to the fixed epoch associated with the smoothed estimate. This form is very computationally efficient since it does not require any matrix inversion operations. The Carlton-Rauch form of the fixed epoch smoother maps filter state corrections from the current filter epoch back to the fixed epoch associated with the smoothed estimate. This form does require matrix inversions but may be more numerically stable than the Frazer form.
UseMaximumLag Use a maximum lag completion criterion for the fixed epoch smoother estimates. The lag is defined as the time between the epoch of the fixed epoch smoother and the current filter epoch. It is recommended to always use the maximum lag completion criterion to avoid the possibility of the fixed epoch smoother estimate never reaching completion.
MaximumLag Fixed epoch smoother estimates are considered to be complete when this amount of time has elapsed between the epoch of the fixed epoch smoother and the current filter epoch when the fixed epoch smoother estimate and UseMaximumLag is set to true.
UseCovarianceReduction Use a covariance reduction completion criterion for the fixed epoch smoother estimates. The covariance reduction of the fixed epoch smoother estimate is measured as largest relative change in a diagonal element of the smoothed state error covariance matrix.
MinimumCovarianceReduction Fixed epoch smoother estimates are considered to be complete when the covariance reduction associated with N consecutive accepted measurements are all below this threshold. Covariance reduction is measured as largest relative change in a diagonal element of the smoothed state error covariance matrix. A covariance reduction of 0.001 would therefore mean that the largest relative change in a diagonal element would be 0.1%. The value of N is set via the attribute NumMeasForCovarianceReduction.
NumMeasForCovarianceReduction The number of consecutive accepted measurements for which the MinimumCovarianceReduction threshold must be satisfied in order for a fixed epoch smoother estimate to be considered complete.
HigherOrderCorrections
(Filter only)

Special algorithms to account for higher order effects are available to augment the ODTK optimal sequential filter. These algorithms consist of the Gauss 2nd order filter and two underweighting schemes: residual variance scaling and a covariance reduction limit. All higher order augmentations are specific to the ODTK Filter. These options for the mitigation of higher order effects should not be required in most normal circumstances.

Second Order Gaussian Filter

The capability to add in the additional terms associated with the Gaussian second order filter is accessible through the HigherOrderCorrections scope of the Filter attributes. Set the MitigationMethod to SecondOrderGaussian to expose the attributes. The Gaussian second order filter provides augmentation of measurement processing in terms of an adjusted residual and additional measurement deweighting and an augmentation of the time update in terms of an acceleration bias. Controls exist to allow for the inclusion of any or all of these augmentations. The selected second order effects can be included all the time or only when needed based on an automatic detection scheme.

The inclusion of second order terms in measurement processing requires the computation of second order partial derivatives (Hessians) of the measurement models. These computations are provided analytically for the most commonly used measurement models in ODTK. Measurement Hessians are computed numerically for those measurement models which do not support second order derivatives analytically. The need to compute measurement Hessians results in slightly slower execution times. The second order effect on the time update is accounted for through the computation of an acceleration bias on all orbit sub-states. The complete acceleration bias representation would require the computation of Hessians for all acceleration models involved in the trajectory propagation. The approach taken in ODTK is to only compute the Hessian of the two-body acceleration since all other accelerations are typically at least three (3) orders of magnitude smaller than the two body acceleration.

In all cases examined to the time of this writing, the inclusion of second order augmentation in the measurement update, specifically the measurement de-weighting, has proven to be much more important than the inclusion of second order effects in the time update.

Underweighting

The capability to augment the linear residual error variance with additional underweighting is accessible through the HigherOrderCorrections scope of the Filter attributes. Set the MitigationMethod to Underweighting to expose the attributes. There are two underweighting schemes implemented: residual variance scaling and a covariance reduction limit. The concept behind underweighting is to decrease the corrections made during measurement processing when the effects of non-linearity are significant. The main effect of underweighting is to slow the contraction of the covariance which can help prevent the filter from "over correcting" and subsequently rejecting valid tracking data.


UnscentedFilter

The capability to use all or parts of the scaled unscented Kalman Filter (UKF) is available as an option in the HigherOrderCorrection settings. Set the MitigationMethod to UnscentedFilter to expose the attribute. The Filter can be considered a recursive machine of time and measurements updates. Time updates transition the state of the filter from one time to the next. Measurement updates fold in measurement information to improve the estimated state. Options are provided to replace the baseline update algorithms, from the Extended Kalman Filter (EKF), with the update algorithms of the UKF. The UKF may provide better track custody than the EKF in scenarios where the orbit uncertainty grows very large due to highly uncertain dynamics or long gaps in observations.

ODTK does not currently have a matching Unscented Smoother. Filters in the UKF configuration can output *.rough information for input into the existing Fixed-Interval smoother. Smoother performance may be degraded in cases where the state-error covariance is large. VLS operations are not available in conjunction with UKF processing.

Filter.ProcessControl.HigherOrderCorrections
Type Description
Mitigation Method Technique to be used to account for higher order effects encountered during estimation with the Filter. SecondOrderGaussian enables the computation of second order augmentation terms to time and/or measurement updates. Underweighting allows for the selection of a method by which observations are further de-weighted to account for non-linearity effects. Selecting None dictates that the Filter run in normal linear mode.
IterateMeasUpdate One method of addressing non-linearity effects in the measurement update process is to allow for multiple iterations in the measurement state update. This is a local iteration which is performed on a measurement by measurement basis. This option is not supported when the Filter is running in the Simultaneous measurement processing mode.
ResidualToWNIterationThreshold When IterateMeasUpdate is enabled, a threshold value of the ratio of the current residual over the current measurement white noise sigma may be specified as an exit condition for the iterative process. The iteration process will be considered to be converged when the computed ratio falls below the specified value. For example, a value of 1.0 would indicate that the iteration process should terminate when the resulting residual is smaller than the one sigma measurement noise.
MaxMeasUpdateIterations When IterateMeasUpdate is enabled, a maximum number of iterations may be specified.

HigherOrderCorrections.SecondOrderGaussian
Type Description
UpdateTypes The second order Gaussian filter provides augmentation terms which apply to both the time and measurement updates. The application of those augmentations may include both MeasurementAndTime updates, only Measurement updates or only Time updates.
MeasUpdateType The second order Gaussian filter augmentation of the measurement update consists of two parts. An augmentation of the residual computation and an augmentation to the de-weighting of the measurement residual.
Mode The second order augmentation terms identified by UpdateTypes and MeasUpdateType can be applied at all times during the estimation process or only when required based on detection metrics.
MeasUpdateNonlinearDetectionThreshold When the second order Gaussian Mode is set to include augmentation of the measurement update via AutoDetect, a threshold value of the ratio of expected second order de-weighting contribution over the measurement white noise varaince is required. The augmentation will be applied when the computed ratio is larger than the input value. For example, a value of 0.5 would indicate that augmentation should be applied when the expected second order contribution to the residual error variance is greater than one half the measurement white noise variance.
TimeUpdateNonlinearDetectionThreshold When the second order Gaussian Mode is set to include augmentation of the time update via AutoDetect, a threshold value of the ratio of expected second order acceleration bias over the current two body acceleration. The augmentation will be applied when the computed ratio is larger than the input value.
DeweightingScaleFactor When the second order Gaussian Mode is set to include augmentation of the measurement update and the MeasUpdateType is set to include the second order contribution to the residual deweighting, the computed second order augmentation to the deweighting is multiplied by the provided scale factor.
RcvrClockPartialsTransition Only applies to GNSS measurements when the receiver tags the observation with the raw receiver clock time. If true, the partials will be transitioned across the clock phase error interval. The user needs to weigh the benefit to computational time cost.

HigherOrderCorrections.Underweighting
Type Description
Method Two underweighting options are available: ResidualVarianceCorrectionLimit and ResidualVarianceScaling. ResidualVarianceCorrectionLimit underweighting increases the residual error variance to limit the contraction of the state error covariance in the measurement direction so that the ratio of the pre-fit residual error variance over the post-fit residual error variance is no larger than a user specified value. ResidualVarianceScaling underweighting multiplies the computed residual error variance by a user supplied scale factor.
Mode If the Method is set to ResidualVarianceScaling, the scaling of the residual error variance can be applied at all times during the estimation process or only when required based on a detection metric.
ResidualVarianceScaling The nominal computed residual error variance is scaled by this user supplied factor. A value of 1.0 corresponds to nominal (not underweighted) operation.
MeasUpdateNonlinearDetectionThreshold When the Method is set to ResidualVarianceScaling and the Mode is set to AutoDetect, a threshold value of the ratio of expected second order de-weighting contribution over the measurement white noise is required. The underweighting will be applied when the computed ratio is larger than the input value. For example, a value of 0.5 would indicate that augmentation should be applied when the expected second order contribution to the residual error variance is greater than one half the measurement white noise variance. Note that this threshold is computed in the same way as in the second order Gaussian filter.
ResidualVarianceCorrectionLimit The maximum allowed ratio of the pre-fit residual error variance over the estimated post-fit residual error variance. Underweighting is applied to increase the pre-fit residual error variance to limit the contraction of the state error covariance in the measurement direction so that the ratio of the pre-fit residual error variance over the estimated post-fit residual error variance is no larger than this value. For example, a value of 1000 would indicate that underweighting would be applied when necessary to prevent the contraction of covariance in the measurement direction by more than a factor of 1000.
HigherOrderCorrections.UnscentedFilter
Type Description
UpdateTypes Selected update types are performed using the Unscented Kalman Filter algorithm. If UpdateTypes is set to MeasurementAndTime, the Filter runs as a UKF. Setting UpdateTypes to Measurement results in the Filter using an Extended Kalman Filter (EKF) time update in combination with the measurement update from the UKF. This combination can be desirable when the main source of non-linearity is in the measurement model since the EFK time update is much faster than that of the UKF. The UKF formulation is based on the scaled-unscented transform using (2N+1) samples where N is the dimension of the state. The UKF time update is performed by selecting samples from the scaled lower-triangular square root of the error-covariance. These samples propagate forward and construct a new mean and covariance at the end of the time update interval. The UKF measurement update is performed by using similar samples of the estimation state to create a distribution of expected measurement values from which the mean and measurement error-variance are determined.
CurvilinearUse When set to SamplingAndMeasUpdate, sampling of the state-error covariance to compute the measurement value distribution and the measurement update is performed in curvilinear coordinates instead of Cartesian coordinates. As the orbit uncertainty becomes large, expression of the covariance in curvilinear coordinates can often provide a better representation of the orbit-error distribution. This option is only available when UpdateTypes is set to Measurement.
ResampleOnProcessNoiseGrid When set to true, computed process noise is added to the state-error covariance at times on the regular process noise grid as defined by the ProcessNoiseUpdateInterval. This addition of process noise requires that the state-error covariance be resampled to generate new sigma points for the next step in the time update of the state. Repeated sampling can, in cases of large orbit uncertainty, result in rapid expansion of the orbit-error covariance. If this option is set to false, then a single set of sigma points propagates across the entire time update interval. Under this configuration, the process noise is added to the covariance generated from the sigma points at intermediate times for the output to the *.filrun and ephemeris files. This option is only available when UpdateTypes is set to MeasurementAndTime.
Alpha The difference between state samples and the current mean generated using the standard unscented transform are scaled by α as part of the unscented transform. This scaling operation is important to keep loyalty of the samples since the size of the sample to mean distance in the standard unscented transformation increases with the dimension of the state.
Beta β is a free parameter in unscented transformation that you can select in a manner to increase the match between the sample points and higher order moments of the error distribution. A value of two (2) is optimal for Gaussian error distributions.
Kappa κ is a secondary scaling parameter in unscented transformation and is typically set to zero. Negative values can lead to an error-covariance that is not positive definite.

If you set the process noise update interval too large, problems may arise in subsequent calculations.

The ODTK filter processes all measurements up to and including a restart record. Upon restart, ODTK does not process measurements at the restart time. In Scalar mode only measurements at exactly the restart time are not processed; in Simultaneous mode measurements at the restart time + epsilon are not processed where epsilon is 0.01 sec.