Entity Propagation

Physics and Propagation → Entity Propagation

Up to date for Platform 0.41.1

Written by Connor Jakubik.

Prerequisites:

• https://github.com/SimDynamX/SpaceTeamsPro/wiki/Sim-Structure

---

Entity Propagation

Space Teams PRO supports taking physics state inputs from many parts of the simulation and other sources such as live telemetry. To combine all these data streams, we have devised a system where each Entity can have a different source for its state data and incorporate physical effects without coupling the model code to the propagator code.

Field Effects

Gravity models and other "environmental" effects such as electromagnetic forces are handled by "Field Effects". For each Field Name, a set of scalar-, vector-, or matrix-returning Field Effects are loaded. When code anywhere in the simulation samples a Field Effect, the location of the sampling and field name are passed in as arguments. The Field Effects code samples every Field Effect with the corresponding Field Name and adds the results. The Field Effects libraries that are used in a simulation are loaded by all applications that are in that simulation, to make this functionality available and equivalent no matter what program the user code is running in.

The "Gravity" field name holds a set of Vector Field Effects, and in typical simulations these are spherical gravity models for all major bodies as well as non-homogenous gravity models for objects that are close enough to need them. When sampling this Field Effect, the apparent acceleration due to gravity of a body at the sampling position is returned. All vector values in this process also include the frame they are expressed in, to use the arbitrary frame transformation system.

PhysEffects

"PhysEffect"s are objects that represent a physical effect on an Entity, such as an additional force or torque. PhysEffects are forces or state overrides that are consumed by a Propagator to factor in physics that aren't already known by the Propagator. Any code in the simulation can add, update, or remove PhysEffects per-Entity. An example would be a spacecraft that is already orbiting with gravity, using the ST_Rigid_Body propagator, being accelerated by thruster firings that are modeled using PhysEffects.

PhysEffects have one of these types:

• Force
• Torque
• Impulse
• AngImpulse
• Acceleration
• AngAcceleration
• DeltaLocation
• DeltaVelocity
• DeltaRotation
• DeltaAngVelocity
• LocationOverride
• VelocityOverride
• AccelerationOverride
• RotationOverride
• AngVelocityOverride
• AngAccelerationOverride

All PhysEffects can use a start-time variable to schedule or delay their impact. Override_ PhysEffects substitute their value in the next update and are deleted after use. Delta_ PhysEffects add their value to the propagated state at the end of an update and are deleted after use. Impulses can have a Start and End time which are used to apply the impulse over a non-zero time, possibly over multiple update cycles. Force, Torque, Acceleration, and AngAcceleration are not consumed after their first use, and optionally have start and end times.

In Code

Adding or updating a PhysEffect:

C++

auto effect = PhysEffect(PhysEffectType::Torque, body_fixed_frame);
effect.setVector({1,0,0});
en->setPhysEffect("MyTorqueEffect", effect);

Python

WIP

Removing a PhysEffect:

C++

en->removePhysEffect("MyTorqueEffect");

Python

WIP

Propagator Choice

Each Entity is assigned a Propagator, which is responsible for handling Field Effects and PhysEffects as applicable. This Propagator exists in one program in the simulation and serves as the source of truth for the entity’s state. The propagator choices are:

• No_Body:
  • This Entity does not have a "body" in the world; location and frames are meaningless to it. Trying to set a location, for example, on an entity with this propagation type is invalid.
  • 3D Clients like UE don't react to any changes in propagation-relevant parameters.
  • No automatic attempt to propagate this Entity.
  • No reaction to PhysEffects.
  • Entity not blocked by collisions.
• ST_Rigid_Body:
  • 3D Clients like UE react to changes in Location, Velocity, Acceleration, Rotation, Angular Velocity, and Angular Acceleration.
  • Automatically applies Propagator system, which propagates linear/angular Velocity and Location based on PhysEffects and the Gravity FieldEffect.
  • Handles PhysEffects.
  • Entity not blocked by collisions.
• SPICE:
  • Automatically applies Spicy system, which uses NAIF SPICE to drive entity state from ephemerides.
  • Does not take into account PhysEffects or FieldEffects.
  • Entity not blocked by collisions.
• Unreal_Chaos: (PARTIALLY IMPLEMENTED)
  • Automatically sets up Unreal's Chaos physics engine for this entity, which propagates based on PhysEffects and the Gravity FieldEffect.
  • The program that "possesses" (takes responsibility for controlling) this Entity feeds its physics state back into parameters.
  • Handles all PhysEffects.
  • Entity collides with objects in the sim.
• Unreal_Pawn: (PARTIALLY IMPLEMENTED)
  • Retrieves entity state from Unreal client pawn, which is controlled by a user.
  • The program that "possesses" (takes responsibility for controlling) this Entity feeds its physics state back into parameters.
  • Does not take into account PhysEffects or FieldEffects.
  • Entity may collide with objects in the sim based on custom programming.
• Custom:
  • Responsibility for updating Location/Velocity/other state parameters is left to a System that the user applies to this Entity.
  • User code should handle PhysEffects and Gravity FieldEffect if the propagator is physics-driven.
  • Entity not blocked by collisions.
• Static: (PARTIALLY IMPLEMENTED as of v0.37.0)
  • Directly reads Location and Rotation parameters and ignores velocity of the entity, assuming it is static with respect to its Resident Frame.
  • Responsibility for updating Location/Rotation parameters is left to a System that the user applies to this Entity.
  • Does not take into account PhysEffects or FieldEffects.
  • Entity not blocked by collisions.

There are two methods to directly affect an Entity’s motion: state setting functions and PhysEffects. State-setting functions like setLocVelAcc(), setRotation(), setAngVelocity(), and setAngAcceleration() are meant to be used by code that IS the propagator for the entity. For example, if an entity’s Propagator is set to Custom, other code could drive the entity’s state from telemetry by using these functions. PhysEffects can only be used if the entity has a Propagator that handles them. This approach is good for user code that, for example, adds the impulses of thruster firings to an Entity.

Using FieldEffects and PhysEffects, many varied parts of a simulation can affect the dynamics of an Entity without typical distributed-systems issues with synchronization and timing.

Changing Propagator Mid-Sim

Not yet a stable feature.

WIP