Sim Design

The Fundamentals → Simulation Design

Up to date for Platform 0.41.1

Written by Connor Jakubik

Prerequisites:

• All other pages in Fundamentals section

---

Space Teams PRO Simulation Design

This page provides design discussion about how a user can most effectively make use of the Space Teams features to model a variety of scenarios that may be difficult to develop as a from-scratch simulation. There are many design decisions we have taken in the core development of Space Teams that may introduce unfamiliar concepts for the simulation developer.

---

1. Time control and sim evolution through time

• Interfacing with start process in C++ Systems and Python Systems
• C++ Init and update functions and their time guarantees
  • Taskflow
• How to use context sim-time
• Python time considerations
• Purposes of Async vs Deterministic scheduler
• Custom sim time control (Runtime_ForTime)

WIP

---

2. Representing objects

Entity and Parameter Data Structure Organization:

Space Teams entities are used to represent objects in the simulation. A key design question to consider when creating a simulation is how to model a complex object with lots of data and sub-components. Design opportunities to address this include using multiple entities, complex nested parameter data structures, and a few other concepts. Here are some criteria that will help you decide:

1. Is the object a piece of software or a microcontroller/computer that does not need modeling as a "real" component?
   1. If yes, consider using only a System Instance to model this object.
   2. If the object requires realistic subsystem modeling, i.e. power supply turning off means a microcontroller no longer is running, using an Entity (with one or more System Instances as well for the "behavior") will better enable multiple simulation components to contribute to the live properties of the object. A separate System or Resource Flow Solver/Integrator will likely have responsibility for setting the power-on state of the microcontroller, and Systems cannot reach into other Systems' Instance Parameters or local variables in the code, so the commonly accessed live properties should reside in an Entity's parameters.
2. Does the object have a physical significance - does it have a body frame?
   1. If no, then a single Data-type Entity with No_Body Propagator may be sufficient. The entity will have no meaningful Location/Rotation, and can be used purely as a data-holder.
   2. If yes, you should use a Static, Custom, or other Propagator, and that Entity will have a meaningful body frame.
3. When should multiple entities be used instead of a single entity to model an object?
   1. If the object is a simple, inert object such as a metal cube, it should probably be modeled as a single entity.
   2. If the object has multiple frames that may be moved in the design separately, or has a hierarchy of attachment of sub-parts to rigid bodies, even if they should stay static, that is a good reason to insert multiple entities in the frame tree to serve as parent frames for the sub-parts.
   3. If the object has moving parts that are significant for the simulation, these moving parts should be separate Entities.
   4. If the object has multiple copies of a sub-part, these should each be a separate entity with replicated parameters instead of an array-of-structs or struct-of-arrays approach within a single Entity's parameters.
      1. There are some exceptions to this for performance concerns.

Placement of Entity body frames relative to their physical structure:

1. The entity body frame should be placed relative to a physical structure in a convenient way to incorporate further design changes.
   1. For example, for an aircraft or spacecraft structure, there is typically a datum frame that is used as the basis frame for the configuration of the structure geometry and all components. This is a good frame to use as the body frame of an Entity to enable directly copying offsets from a design document or configuration control solution.
   2. Center of mass is sometimes variable, so this should not be used as the definition of the body frame.
      1. NOTE: Various Propagators in Space Teams may or may not have support for center of mass offset from body frame. As of v0.41.1, ST_Rigid_Body does not yet support center of mass offset.
   3. Of course, the actual way this works is the graphics model, mass properties, and other data are changed to put their coordinate origin at the chosen body frame.
2. In the absence of a design datum frame, we have some guidelines for how to choose frame axes relative to a vehicle in Space Teams:

      +z (up)
       |
       |_____ +y (left)
      /
     /
    +x (forward)
   

   1. What can be used as +X/forward axis:
      • Vehicle datum axis.
      • Negated main thrust vector, rounded off to line up with the vehicle's structure.
      • Nominal velocity vector, rounded off to line up with the vehicle's structure.
      • Pointing axis for a device like a camera, laser, antenna, etc.
      • Pointing from the center of an object to its "front side". For example, a soft drink bottle would have its logo on its forward axis.
   2. "Up" can be:
      • Up from the pilot's perspective, if they face towards +X.
      • Nominal lift vector, rounded off to line up with the vehicle's structure.
      • Perpendicular to the ground for nominal horizontal flight.
      • Perpendicular to the ground for nominal ground travel.
      • If none of the other "Up" criteria apply, "Up" can be one of the things from the forward axis criteria (as long as it's perpendicular to the chosen forward axis).
3. For sub-parts of a connected set of Entities, the way to set a "Parent Frame" is to set the "Dynamics"/"ResidentFrame" EntityRef parameter to the Entity name of the parent. This is done automatically when using Assembly-type Entities.

---

3. Representing Environmental Effects

There are a few options for how to model environmental effects in Space Teams. The most basic approach is to directly program environmental models such as gravity, radiation, or atmosphere where they are being used to simulate a vehicle or component, but that does not allow for efficient reuse of those models in other sims. A System can be used to make the environmental model modular, but there are design issues with this. If the environmental effect is used as part of a Propagator such as ST_Rigid_Body, there is no good way to reach into another System from inside the Propagator to sample the model on demand. This on-demand sampling is required to do things such as RK4 integration with recalculated accelerations per sub-step.

Space Teams has a feature called a FieldEffect which is user-modifiable code that represents a contribution to a continuous field. FieldEffects are loaded independently by every program in the simulation. Simulation code can sample a Field from anywhere in the program on demand, and the thread-local context sim-time works as expected.

Gravity is the most obvious example of a FieldEffect. Gravity is modeled in Space Teams through a set of FieldEffects that each contribute a model of the gradient of the gravity potential of one celestial body. When a FieldEffect is being sampled, the inputs are a field name and a FramedLocVelAcc state vector structure, and the output is either a scalar, a FramedVector, or a FramedMatrix3x3. The physical significance of each named "Field" is the responsibility of the simulation developer, but we have some well-known field names that we are standardizing around.

Well-known FieldEffects:

• Gravity
  • Vector-type
  • Acceleration of a free flyer at the given state wrt assumed-inertial frame.
  • Units: $\frac{\mathrm{m}}{\mathrm{s}^2}$
  • Example contributor FieldEffects:
    • Earth Spherical Gravity
    • Earth Spherical Harmonic Gravity Anomaly
    • Phobos Polyhedral Gravity
• Gravity_Gradient
  • Matrix3x3-type
  • Gravity gradient tensor (WIP)
  • Units: (WIP)
• Relative_Wind
  • Vector-type
  • Free stream velocity of atmosphere flow relative to the input state vector.
  • Units: $\frac{\mathrm{m}}{\mathrm{s}}$
• Free_Stream_Pressure
  • Scalar-type
  • Free stream pressure of atmosphere.
  • Units: $\mathrm{Pa}$
  • Example contributor FieldEffects:
    • Earth NRLMSISE-00
    • Mars-GRAM
• Stagnation_Pressure
  • Scalar-type
  • Stagnation pressure of atmosphere flow relative to the input state vector.
  • Units: $\mathrm{Pa}$
• Free_Stream_Temperature
  • Scalar-type
  • Free stream temperature of atmosphere.
  • Units: $\mathrm{K}$

Other phenomena that might be modeled by FieldEffects

• Gravitational_Potential
  • Scalar-type
  • Units: (WIP)
• Magnetic_Field
• Induced_Current (depends on velocity)
• Illumination
• Sun_Illumination
• Ionizing_Radiation_Rate
• Other stream/gas conditions
• Gas Composition
  • Ionization, Isotopes, anisotropy of magnetic fields, etc
  • Suspended particulates
• Ionizing radiation rate

---

4. Working with Ephemerides

The recognized standard for space ephemeris computation is the NAIF SPICE toolkit. Pending the release of SPICE 2, the CSPICE library is the only viable option for using this toolkit in our software. This library is not threadsafe, so we have needed to create some structures to make ephemeris-sampling easier across all Space Teams programs.

As part of the SimGlobals library in Space Teams, we have the SampleEphemeris() function. This function calls into the EphemerisSystem, which is a specialized object that is similar to a FieldEffect but is a singleton in each process. Our implementation of CSPICE uses a mutual exclusion lock for thread safety of access to this library, and is used as the EphemerisSystem for each process.

---

5. Representing Rigid Body Dynamics

• How entities correspond to rigid bodies
• Sim-time extrapolation dynamics vs raw state values in parameters
• Selecting a Propagator
• Using Space Teams Frames

WIP

---

6. Representing Consumables and Energy Flow

• Choosing whether to model something with simple code in a System vs using Advanced Resource Flow
• Advanced Resource Flow details
  • Heat Transfer
  • Fluid Flow

WIP

---

7. Integrating STP with other simulations

• STP receiving input from an external source
  • Async vs lock-step
  • Extrapolation
• Controlling other programs from STP