The FreeFlyer ephemeris file type is an ephemeris-file format native to FreeFlyer which is at its very core intended to flexibly allow users to define and fill the ephemeris in a convenient manner based on their needs. The FreeFlyer ephemeris can also be used to create attitude history files. Initial versions of the FreeFlyer ephemeris only allowed you to choose specific sets of columns to use for storing data in the ephemeris, though more recent versions give full flexibility for the user to define their own columns, specify their own column delimiters, manage discontinuities, set column-specific interpolation methods, and add data of multiple types to the ephemeris. This format can both be created in its entirety by FreeFlyer for use, and it can be read in by FreeFlyer in its entirety.
Version History
Over the history of FreeFlyer, many versions of the FreeFlyer ephemeris format have existed. This section describes the major differences between the different versions and the types of columns supported in those ephemerides.
Version |
Column Definition |
Column Types Supported |
Key Differences from Previous Version |
|
v1 |
Fixed column choices are defined in sets:
|
Variable |
N/A |
|
v2 |
Custom columns can be added one at a time or as sets through the same interfaces as in v1. |
Variable |
|
|
v3 |
Custom columns can be added one at a time or as sets through the same interfaces as in v1. |
Variable, String, TimeSpan |
|
Note: If sub-millisecond precision is specified in a FreeFlyer ephemeris of v3 format and it is loaded into FreeFlyer in millisecond timing precision mode, sub-millisecond precision will be rounded appropriately. If this would cause multiple vectors in the ephemeris to overlap, the last vector at that epoch in the ephemeris will be the one that is kept.
Format
The format of the FreeFlyer ephemeris file has changed over time, but there are three core areas of the file that will be discussed here. The header area provides top-level information about the ephemeris itself, the title area provides information on the unique settings of the individual columns themselves, and the body section is where the ephemeris data itself is stored and also where discontinuity information is kept where applicable.
Header
Below is the header format for the most recent version of the FreeFlyer ephemeris format.
HEADER_START FreeFlyer 7.9 Ephemeris FormatVersion = 3 Spacecraft = "Spacecraft1" StartTime = 2492596837.000000000 TAI GSFC MJD (Jan 01 2020 00:00:00.000000000 UTC) StopTime = 2492640007.000000000 TAI GSFC MJD (Jan 01 2020 11:59:30.000000000 UTC) CentralBody = Earth ReferenceFrame = ICRF PrincipalPlane = Equatorial ColumnDelimiter = "," DiscontinuityDelimiter = "|" Project = EphemerisGeneration.MissionPlan FileCreationDate = Mar 14 2024 16:36:38.000 UTC HEADER_END |
FreeFlyer Ephemeris v2 Header Format
The sole difference between this version and the v3 header is that the StartTime and StopTime values are stored in a different format to account for the possibility of higher numerical precision.
|
FreeFlyer Ephemeris v1 Header Format
There are many differences between the v1 header format and the v2 header format, chief of which is the addition of a number of stored settings such as the ColumnDelimiter and the DiscontinuityDelimiter. The HEADER_START and HEADER_END tokens are also present in the v2 format to serve as an optimization in organizing separate sections of the ephemeris.
|
Title
Below is the title format for the most recent version of the FreeFlyer ephemeris format.
TITLE_START COLUMN_LABELS = "ElapsedTime","X","Y","Z","VX","VY","VZ" COLUMN_UNIT_LABELS = "s","km","km","km","km/s","km/s","km/s" SPACECRAFT_PROPERTIES = ElapsedTime,X,Y,Z,VX,VY,VZ COLUMN_INTERPOLATORS = "Independent Variable","8th Order Lagrange","8th Order Lagrange","8th Order Lagrange","8th Order Lagrange","8th Order Lagrange","8th Order Lagrange" COLUMN_TYPES = TimeSpan,Variable,Variable,Variable,Variable,Variable,Variable TITLE_END |
FreeFlyer Ephemeris v2 Title Format
There is a single difference between the v2 title format and the v3 title format. This change is that the v3 format includes a line for COLUMN_TYPES which indicates whether a column is a TimeSpan, a String, or a Variable column.
|
Note: The title section is only found in v2 and higher of the FreeFlyer ephemeris format.
Body
Below is the base body format for the most recent version of the FreeFlyer ephemeris format.
DATA_START 0.000000000, -6.64807999999999993e+03, 1.60991000000000014e+02, -9.82995999999999981e+02, 4.81414999999999982e-01, -6.39538000000000029e+00, -4.27317000000000036e+00 30.000000000, -6.62971024214843601e+03, -3.09277766255046629e+01, -1.11058296208413753e+03, 7.43115543202955364e-01, -6.39794437084698409e+00, -4.23178673633295421e+00 60.000000000, -6.60350181985908512e+03, -2.22810015114161502e+02, -1.23685301479442637e+03, 1.00394087587906378e+00, -6.39294433064653944e+00, -4.18538473556424151e+00 DATA_END |
FreeFlyer Ephemeris v2 Body Format
The primary difference between the v2 and v3 format versions in the body section is that the epoch is now stored as <Seconds>.<Nanoseconds> instead of as a standard double. Additionally, however, all data is now stored in scientific notation instead of as a pure double.
|
FreeFlyer Ephemeris v1 Body Format
The key differences between v1 and v2 in the body format is that v2 enables the use of custom column definitions. In v1 you could only include certain data, such as Spacecraft position, velocity, acceleration, attitude, angular velocity, and angular acceleration. In v2 you can use any Variable value column that you would like. Lastly, the v2 ephemeris format uses BODY_START and BODY_END to indicate the start and end of the ephemeris' data.
Where:
|
Note: The first column in the current FreeFlyer ephemeris version, the epoch, is stored as <seconds>.<nanoseconds> and not a double. This is done because treating it as a double would limit timing precision particularly in nanosecond precision mode. As a note, for a FreeFlyer Ephemeris v2 and v3, the first column can not be changed. The seconds value is formatted as a long long while nanoseconds are parsed as just a long. This distinction is only important if the user is writing their own parser for the FreeFlyer ephemeris format.
Discontinuities
FreeFlyer ephemerides support the tracking of discontinuities in-line with other data. The script example below displays how to mark a discontinuity in the ephemeris File.
Ephemeris Ephemeris1;
//Configure Ephemeris Object Ephemeris1.FFEphemProperties.FormatVersion = 2; //Version 2 or higher is required for marking discontinuities
Put Spacecraft1 to Ephemeris1;
//Mark the discontinuity Ephemeris1.FFEphemProperties.MarkDiscontinuity();
//Perform some discontinuous action, for example: Maneuver the Spacecraft Maneuver Spacecraft1 using ImpulsiveBurn1;
Put Spacecraft1 to Ephemeris1; |
The discontinuity will be indicated in the ephemeris file by including two values for each column of data at the discontinuous epoch: one for the pre-discontinuity state, and one for the post-discontinuity state. Every column entry will be separated by the discontinuity delimiter, which is the pipe character, "|", by default and can be changed with the Ephemeris.FFEphemProperties.DiscontinuityDelimiter property. The resulting title and data sections for the example's ephemeris output are shown below. See the sample Mission Plan Ephemeris with Discontinuity for a more complete example.
TITLE_START COLUMN_LABELS = "Epoch","X","Y","Z","VX","VY","VZ" COLUMN_UNIT_LABELS = "","","","","","","" SPACECRAFT_PROPERTIES = Epoch,X,Y,Z,VX,VY,VZ COLUMN_INTERPOLATORS = "0th Order Interpolation","5th Order Spline","5th Order Spline","5th Order Spline","5th Order Spline","5th Order Spline","5th Order Spline" TITLE_END
DATA_START Jan 01 2020 02:00:00.000, 948.317878353462| 948.317878353462, 398.571281788969| 398.571281788969, -7010.12486870278| -7010.12486870278, 3.95540033868814| 4.95540033868814, -6.36177549843091| -6.36177549843091, 0.17512980239767| 0.17512980239767 DATA_END |
Note: Support for discontinuities is only present in v2 of the FreeFlyer ephemeris format and higher.
Other Features
There are a number of other features supported by the FreeFlyer ephemeris format, many of which are used to resolve higher-fidelity challenges that users face during development of their ground systems. These features include handling discontinuities within the ephemeris file, mapping Spacecraft properties to columns in the ephemeris for ease of use, using customized column and discontinuity delimiters in the ephemeris file, and using vector comments in the ephemeris. All of these features require v2 of the FreeFlyer ephemeris format or higher.
Mapping Properties and using Custom Delimiters
When adding custom columns, you can specify whether the value for the column will be automatically retrieved from a mapped Spacecraft property when the Put command is called, or if the value for the column will be explicitly provided to the Put command. The script example below displays how to add and remove a custom column and set a custom delimiter for the Ephemeris File.
Ephemeris Ephemeris1;
//Configure Ephemeris Object Ephemeris1.FFEphemProperties.FormatVersion = 2; //Version 2 or higher is required Ephemeris1.FFEphemProperties.ColumnDelimiter = '#';
//Add unmapped column Ephemeris1.FFEphemProperties.AddColumn("Mass"); //Where "Mass" is a Variable
//Add mapped columns Ephemeris1.FFEphemProperties.AddColumn("A", "A");//Maps the column to the property Spacecraft.A
//Remove a column Ephemeris1.FFEphemProperties.RemoveColumn("A"); //Removes column |
For the example above, the custom column "A" will be automatically mapped to the Spacecraft property Spacecraft.A. The custom column "Mass" was not mapped to a Spacecraft property, and so the value for this column must be explicitly provided to the Put command. A source value must be provided for each of the unmapped columns using the syntax shown below.
Variable CalculatedMass;
CalculatedMass = Spacecraft1.Mass*0.95;
Put Spacecraft1, CalculatedMass to Ephemeris1; |
The results of this example are shown below.
TITLE_START COLUMN_LABELS = "Epoch"#"X"#"Y"#"Z"#"VX"#"VY"#"VZ"#"Mass" COLUMN_UNIT_LABELS = ""#""#""#""#""#""#""#"" SPACECRAFT_PROPERTIES = Epoch#X#Y#Z#VX#VY#VZ#NO_MAPPING COLUMN_INTERPOLATORS = "0th Order Interpolation"#"5th Order Spline"#"5th Order Spline"#"5th Order Spline"#"5th Order Spline"#"5th Order Spline"#"5th Order Spline"#"5th Order Spline" TITLE_END
DATA_START Jan 01 2020 00:00:00.000# -6648.0800000000# 160.99100000000# -982.99600000000# 0.48141500000000# -6.39538000000000# -4.27317000000000# 950.000000000000 DATA_END |
You can also map elements of array and matrix properties into ephemeris columns, as shown below. You can also create ephemeris columns that map to properties of child objects, such as Spacecraft.OD.Covariance.
// Map a Variable property Ephemeris1.FFEphemProperties.AddColumn("Beta Angle", "BetaAngle");
// Map an element of an Array property of a child object, Spacecraft.OD.Covariance.Diagonal[0] Ephemeris1.FFEphemProperties.AddColumn("First Covariance Diagonal", "OD.Covariance.Diagonal", 0);
// Map an element of a Matrix property, Spacecraft.MOI[0,0] Ephemeris1.FFEphemProperties.AddColumn("MOI[0,0]", "MOI", 0, 0); |
See the sample Mission Plan Ephemeris with Custom Columns for a more complete example.
Note: If mapping a spacecraft property representing an orbital element, use caution in mapping orbital elements from different element sets into one Ephemeris object. Doing so may cause unexpected behavior when propagating the Spacecraft. For example, if the Keplerian true anomaly is mapped to the ephemeris along with the Cartesian position and velocity, the Keplerian true anomaly will be written into the Spacecraft after the position and velocity elements. In this particular case, writing the Keplerian true anomaly may adjust the Spacecraft’s position and velocity, resulting in a slightly different state than the original position and velocity.
Using Vector Comments
In addition to being able to create String columns in a FreeFlyer ephemeris, the user can set a comment for each vector in a FreeFlyer ephemeris that gets added to the end of that vector when written out to file.
Ephemeris Ephemeris1;
//Configure Ephemeris Object Ephemeris1.FFEphemProperties.FormatVersion = 2; //Version 2 or higher is required
//Add a maneuvered state to the ephemeris Maneuver Spacecraft1 using ImpulsiveBurn1; Put Spacecraft1 to Ephemeris1 with comment "Burn #"; //Adds a vector to the ephemeris with a comment
//Change the comment on the current vector in the ephemeris Ephemeris1.FFEphemProperties.SetVectorComment(Ephemeris1.CurrentIndex, "Burn 1"); |
The results of this example are shown below.
TITLE_START COLUMN_LABELS = "Epoch","X","Y","Z","VX","VY","VZ" COLUMN_UNIT_LABELS = "","","","","","","" SPACECRAFT_PROPERTIES = Epoch,X,Y,Z,VX,VY,VZ COLUMN_INTERPOLATORS = "0th Order Interpolation","5th Order Spline","5th Order Spline","5th Order Spline","5th Order Spline","5th Order Spline","5th Order Spline" TITLE_END
DATA_START Jan 01 2020 00:00:00.000, -6648.08000000000, 160.991000000000, -982.996000000000, 0.48141500000000, -6.39538000000000, -4.27317000000000,Burn 1 DATA_END |
See Also