GE2 Major Features¶

GE2 has a number of major features. These are listed and details about their use are provided.

The major scene components are described in scene components.

Maneuvers¶

Manuevers are used to specify a change in the state of a body at some future time. For example, a Hohmann transfer requires two changes in the state of the body. The first changes from a circular orbit to an elliptical orbit that intercepts the destination orbit and the second circularizes the orbit when the destination orbit is reached. GE2 implements this with a maneuver mechanism in the GECore API (TransferShip uses this API). The essential idea is that we need to tell GECore to change the state of a specific body by a specified amount at a designated future time.

This is done with the API:

        /// <summary>
        /// Add a maneuver to the list of pending maneuvers. If no timeOffset is given it is assumed
        /// the t_relative in the maneuver is to be added to the current time to establish the overall
        /// maneuver time. 
        /// 
        /// ...
        /// 
        /// </summary>
        /// <param name="id"></param>
        /// <param name="m"></param>
        /// <param name="timeOffsetGE"></param>
        public void ManeuverAdd(int id, GEManeuver m, double timeOffsetWorldTime = double.NaN)

The key information for this is provided in the GEManeuver class. All maneuvers will specify a time they are to be applied. There are four types of maneuvers that can be designated in this class:

    // SET_VELOCITY: Use velocityParam as the new velocity vector
    // APPLY_DV: add velocityParam to the current velocity
    // SCALAR_DV: Change the magnitude of the velocity to the new value, keep direction the same
    //            (use velocityParam.x as the magnitude of the new velocity)
    //            e.g. to increase by 1% set velocityParm.x to 1.01
    public enum ManeuverType { SET_VELOCITY, APPLY_DV, SCALAR_DV };

Depending on the type chosen different parameters in the class are used and are applied differently.

Implementation: The application of a maneuver is performed by calling GEManeuverStruct.ApplyManeuver and providing the current velocity of the body and the velocity of the center body.

In all cases if the body is in orbit around a center body, the center velocity component of the body velocity is subtracted to get a velocity relative to the center body. The maneuver change is computed and then the center body velocity is re-added. This means that all velocity changes for bodies in orbit are relative and do not need to take into account the motion of the body they are orbiting around.

Type	Struct Field Used	Action Taken
`SET_VELOCITY`	`velocityParam`	Sets new velocity to `velocityParam`
`APPLY_DV`	`velocityParam`	Adds to `velocityParam` to current velocity
`SCALAR_DV`	`velocityParam.x`	Sets velocity in same direction as current, with magnitude `velocityParam.x`

As with (almost) all API calls into GE2 the values are provided in world units/time. Also, adding a maneuver can only be done when the GE is not running (if in Job mode), so the code to add a maneuver might need to be in a GE callback to ensure it is executed when the GE physics evolution has paused.

A maneuver may also provide a callback function of the form:

    public delegate void DoneCallback(GEManeuver gem, GEPhysicsCore.PhysEvent physEvent);

This will be called by GE once the physics loop in which the maneuver executes completes. Note that GE2 may have further evolved the system beyond the maneuver time before the callback happens.

The execution of a maneuver also means that any active trajectory predictions will need to be recalculated and GE will undertake this. When using IMMEDIATE execution mode this may chew up some real-time as the computation is performed.

GE does not retain maneuvers after they have been executed.

Implementation Details¶

Internally GE morphs the maneuver into a struct (converting everything into physics units) and makes this information available to GEPhysicsCore (GEPC). As the main physics loop runs the maneuver will be handled in one of two ways:

at the start of each numerical timestep the execution time of the earliest maneuver in the list is examined. If the timestep has progressed beyond the maneuver time, then the maneuver is executed. This causes the appropriate state change to be applied to the indicated body
if the physics core is all on rails then it will normally step directly to the requested maneuver time. If there is a maneuver before this end time it will evolve the system to the maneuver time, apply the maneuver and then continue to the requested end time

In the first case above the maneuver will generally not be executed at exactly the requested time. Generally the time error (due to the \(dt\) step size of numerical integration) will be quite small.

In general the Leapfrog integrator loses precision if a variable timestep is used, hence we avoid integrating to exactly the maneuver time. This logic may be made integrator-dependent in a future release.

Once a maneuver has been executed it is added to a completed list in the GEPC. Once the current GE physics loop completes then GE will call callbacks for those maneuvers that were executed and manage the internal maneuver lists appropriately.

Patch Mode/On-Rails¶

Patch mode is a property of a GSBody that can be enabled if the body is not using a GRAVITY mode propagator. The non-GRAVITY propagators are deterministic (i.e. given a time they can compute a position). This allows the body motion to be described using multiple propagator instances with each responsible for a distinct time interval. Let’s look at two user-cases to make that more concrete.

PIC: Patches for Hohman

First, consider a ship with a Kepler propagator that will start a Hohmann transfer at \(t=t_1\) from an “inner” orbit to an “outer” orbit, evolve on the transfer orbit until \(t=t_2\) and then circularize it’s “outer” orbit and move in this orbit when \(t > t_2\). If the GSBody has patched mode selected then this results in three propagator patches internally:

KEPLER mode (for inner circular orbit) for \(t < t_1\)
KEPLER mode (for transfer orbit) for \(t_1 < t < t_2\)
KEPLER mode (outer circular orbit) for \(t > t_2\) Why do this, instead or say maneuvers? The patches allow GE to determine where the ship should be for any time \(t\). This means that user code can change the GE time forwards or backwards and GE can update the ship position. NOTE: This will only be possible if all the bodies in the GE can be handled in a deterministic way. As soon as even one body requires numerical integration the system is not deterministic and time cannot be jumped around.

The second use case is to handle a scenario called “patched-conics” in Orbital Mechanics textbooks. In this scenario the goal is to model the path of a ship as it traverses from e.g. the Earth’s gravity to the Moon’s gravity in a deterministic way using only one of the Earth or Moon as the source for gravity at a time. As the ship moves in the Earth gravity the trajectory (an ellipse, parabola or hyperbola i.e. a conic) uses an orbit propagator centered on the Earth. Once the ship enters the Moon’s sphere of influence then it switches to a propagator centered on the Moon. This method was historically used to find “first look” trajectories for transfer to the Moon. These were then refined with more careful numerical simulations for real missions. However, in the context of a playable Earth-Moon scenario patched conics can be useful.

TODO: The Early Access version does not yet have a tutorial for setting up an Earth-Moon transfer. The full version will.

Trajectories¶

General N-body interactions do not usually allow simple orbit prediction according to a predictive equation (such as Kepler’s equation). In these cases the future path of the objects must be determined by actually evolving the equations forward in time and recording the result. GE2 supports this via the trajectory feature.

When using scene components. this feature has three elements:

one or more GSDisplayBody that want to display a future trajectory
a LineRenderer assigned to these display bodies to describe the width and color of the trajectory line
the ‘time ahead’ and ‘number of steps’ parameters for the trajectory (set in the GSController inspector)

An example of this setup can be found in the sample scene folder 2_Trajectories in the ‘Going Further’ tutorial section. Here there are two fixed masses (known as the Euler problem [ref]). As a result simple orbit prediction is not applicable.

Internally the primary GravityEngine is creating a second instance of the GravityEngine class with the same initial data and evolving it forward, recording data in a circular buffer. This process is triggered by a call to TrajectorySetup inside the GSController. Trajectory information is then accessed by the GSDisplay component and used to update the line renderers. When something in the system changes, for example a ship maneuvers, then a new future path must be recomputed from the present state. This all happens transparently to the user but it should be noted that this may result in a burst of CPU activity as the new look ahead is determined. This can be mitigated to some extent by using IJOB_LATEUPDATE mode in the GSController.

Trajectory Scripting¶

In scripting use GravityEngine can be configured for trajectories with the API call:

  public void TrajectorySetup(double t_ahead, int numSteps, List<int> bodiesToRecord)

This API call is also used when a trajectory for an additional body is required. Once it has been added to GE setup is re-run. The trajectory will be recomputed from the current state.

To retrieve the trajectory information the code in GSDisplay.TrajectoryUpdate is a good guide. The key GE API calls are:

  NativeArray<GEBodyState> recordedOutput = geTrajectory.RecordedOutputGEUnits();
  NativeArray<int> recordedBodies = geTrajectory.RecordedBodies();

The recordedOutput is a reference to the internal array in GE units. If the buffer were converted to world units each time it was read, then the next iteration would do an extra conversion on the buffer contents and double scale the result. As a result the conversion is done as the points are mapped into the display space.

GECore Event Listeners¶

There may be events during GECore evolution that are of interest to the game logic. Examples include:

collision event between two bodies
events from an external acceleration component (e.g. a booster running out of fuel)
error conditions from a propagator (e.g. SGP4 propagator detecting an orbit that has decayed)

These events can be communicated to game logic by having the game logic registewr a listener for events. GECore will report all events generated during an Evolve() cycle to each of the registered listeners when the physics loop of the current event loop completes. Event listeners are registered to GECore via the API:

    public void PhysicsEventListenerAdd(PhysicsEventCallback physEventCB)

The required callback method is defined as:

    public delegate void PhysicsEventCallback(GECore ge, GEPhysicsCore.PhysEvent physEvent);

The details of the event are encapsulated in a GEPhysicsCore.PhysEvent. Event types are:

    public enum EventType { COLLISION, SGP4_ERROR, BOOSTER, KEPLER_ERROR, PATCH_CHANGE, MANEUVER_ERROR, MANEUVER };

Type	Description
`COLLISION`	a collision has occured between two bodies with GE2 colliders attached
`SGP4_ERROR`	SGP4 propagation has encountered an error condition
`BOOSTER`	A Booster external acceleration has reported an event (e.g. fuel out)
`KEPLER_ERROR`	A Kepler propagator has reported an error
`PATCH_CHANGE`	Evolution of a patched body has transitioned from one patch to another
`MANEUVER_ERROR`	A requested maneuver could not be applied
`MANEUVER`	A maneuver has been executed

In addition to the event type the GEPhysicsCore.PhysEvent contains details on the body, its position and velocity and the exact time of the event. If the event involves a second body (e.g. collision) state information on that body is also provided. Addition fields can be used to provide auxillary information depending on the event type.

Earth Orbit Propagators: SGP4 and PKEPLER¶

There are two Earth orbit propagators provided by GE2:

SGP4 SGP4 is a satellite propagator developed by NASA and NORAD. It models the effects of a non-spherical Earth, atmosphere and (for higher orbits) lunar/solar perturbation to the satellite’s orbit. See Wikipedia. The initial data for an orbit is accurate to about 1km and over a few days this degrades to 2-3 km.
PKEPLER The canonical textbook, Vallado’s “Funadamentals of Astrodynamics and Applications” provides a simpler model that handles the non-spherical orbit and a very simple (optional) atmospheric drag. This can be used for a simpler model where the oblate Earth effect is necessary, for example it is a key driver of the physics of a Sun-synchronous orbit.

Ephemeris Propagation¶

An ephemeris is a table of values for the position and velocity of a body as a function of time. It is one of the propagator options in GSBody. A body with an ephemeris can be added to GE with the BodyAddWithEphemeris method and an EphemerisData class instance.

For the GSBody use case the inspector will appear as:

The EPHEMERIS mode requires the name of a text file found in a resources folder in the Unity project. This resource file is a CSV format with each line providing a time, position (x, y, z) and velocity (x, y, z) all in the default world units selected for the GSController that will be handling this body.

An example of this can be found in the samples directory 5_Ephemeris in the Samples tree. This example highlights how arbitrary the ephemeris can be by moving two ships in a triangular pattern around a star. It would be more common to adapt output from a satellite simulation tool or from the JPL horizons database to model the motion of a spacecraft or a celestial body.

Gravity Engine 2 v3.0

GE2 Major Features

Contents

GE2 Major Features¶

Maneuvers¶

Implementation Details¶

Patch Mode/On-Rails¶

Trajectories¶

Trajectory Scripting¶

GECore Event Listeners¶

Earth Orbit Propagators: SGP4 and PKEPLER¶

Ephemeris Propagation¶

External Forces: `GSExternalAcceleration`¶

External Acceleration¶

Collisions¶

Implementation¶

Gravity Engine 2 v3.0

GE2 Major Features

Contents

GE2 Major Features¶

Maneuvers¶

Implementation Details¶

Patch Mode/On-Rails¶

Trajectories¶

Trajectory Scripting¶

GECore Event Listeners¶

Earth Orbit Propagators: SGP4 and PKEPLER¶

Ephemeris Propagation¶

External Forces: GSExternalAcceleration¶

External Acceleration¶

Collisions¶

Implementation¶

External Forces: `GSExternalAcceleration`¶