Formations

Formations are a container for one or more Spacecraft objects. Formations are a specialized version of a List of Spacecraft (you can create a List of most types of FreeFlyer objects). The benefit of a Formation over a List of Spacecraft is that the Formation provides additional control over the visualization of the Spacecraft, and allows you to read TLE data into each Spacecraft in the Formation using a single line of script.

Note: The Save, Restore, Get, and Put commands cannot be used with Formations.

Creating a Formation

Unlike Lists, Formation objects can be created via the Object Browser as well as through FreeFlyer Script. The Formation object editor consists of two pages. From the first page, you can define the initialization source for the states of each Spacecraft in the Formation. The choices are:

Properties Page of the Formation Object Editor

On the second page, you can control visualization options for the Formation. You can choose whether to visualize each Spacecraft as a point, or to draw using a 3D model. These options maps to the ViewAsGroup and GroupPointSize properties discussed below.

Visualization Page of the Formation Object Editor

The format for the creation of Formation objects in FreeFlyer script follows the same syntax as creation of most other FreeFlyer objects:

Setting the Number of Spacecraft in a Formation

When you first create a Formation in FreeFlyer script, it will be empty. To begin editing a Formation, start by setting its "Count", or length. This specifies how many Spacecraft the Formation will contain. The Count can be set using any numeric value, including functions which return numeric values, such as the GetNumberOfSGP4States() function used below.

Note that a Formation's count can also be set during its initial creation, as shown below:

The number of elements in a Formation can be increased or decreased at any time by changing the value of the Formation.Count. You can also use the Formation.Clear() method to reset the Formation back to empty. To remove individual elements from a Formation, use the Formation.RemoveAt() method, as shown below:

Note: When you remove elements from a Formation, the removed Spacecraft objects will continue to exist in memory if there were any other references to those objects. The Spacecraft will be removed from the Formation, but it will only be cleared completely from memory if the Formation was the only thing that held a reference to that Spacecraft. References can be created in various ways, such as by the using reference assignment operator (:=), or by displaying the object in output views (e.g. the View command). References are also held when you use methods with state - you can call the ResetMethodStates() method on the Spacecraft before clearing it from the Formation to remove those references. References are also held when you use the Save command; those references can be released by calling Object.ClearSavedStates().

Editing a Formation

As mentioned above, the Formation object allows access to additional properties and methods for visualization and data input. These are:

Once the Count is set, you can begin to edit the properties of the individual Formation elements. You can do this individually for each element, or use a For loop to set properties for all elements at once.

You can also use reference assignment (the := operator) to configure a Spacecraft object contained within a Formation to refer to another Spacecraft object that you created separately. This will cause any references to that Formation element to refer to the specified Spacecraft object. The example below demonstrates using reference assignment with a Spacecraft contained in a Formation:

Setting the Propagator

All Spacecraft in a Formation or List of Spacecraft are created using the default Propagator and ForceModel. The default Propagator is the highest fidelity Propagator available with your license level. For example, with the Mission license, all Formation elements are created with an RK89 Propagator.

The properties of the Propagator of a Spacecraft within a Formation or List can be accessed through syntax such as:

To override the default Propagator with another type of Propagator, such as an Ephemeris, use the SetPropagatorType method, as shown below. See the Working with Integrators or Working with Ephemerides chapters for more information.

To set the attitude motion model for an element of a Formation, use the SetAttitudeMotionModel method:

Propagating and Maneuvering Formations

One of the primary advantages of using Lists and Formations is the capability to Step the entire constellation forward in time with a single command. This ensures that each Spacecraft in the List or Formation is synched at the same epoch, and is much less cumbersome that stepping each Spacecraft individually.

You can also step an individual element of the List or Formation. This could be useful if you want to Maneuver one Spacecraft in the constellation using a FiniteBurn, and the step the remaining Spacecraft to the new epoch. Of course, in order to maneuver using a finite burn, Tanks and Thrusters must be configured as well.

Note: Similar to stepping the Spacecraft object, the Formation.Step() method can also be used in place of a Step command.

Output and Visualization

Formations can be visualized using the View and Map commands as well as the ViewWindow object. The example below shows how to create two output views of the Formation created in the examples above. This could be constructed using FreeFlyer script or the command editors.

3D View of myFormation when viewed as a Group

3D View of myFormation when not viewed as a Group

See Also