Sim Design

The Fundamentals → Simulation Design

Up to date for Platform 0.41.1

Written by Connor Jakubik

---

Representing objects

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 a System Instance 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.

Representing Environmental Effects

Space Teams has a feature called a FieldEffect which is user-modifiable code that represents a contribution to a continuous field. Gravity is the most obvious example; 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 structure.

Phenomena we intend to model with FieldEffects:

• Gravity
• Gravity Gradient (torque based on inertia matrix and attitude)
• Magnetic Field
• Induced Current (depends on velocity)
• Relative Wind (Free Stream Velocity)
• Free Stream Pressure
• Free Stream Temperature
• Other stream/gas conditions
• Gas Composition
  • Ionization, Isotopes, anisotropy of magnetic fields and stuff
  • Suspended particulates
• Sun Illumination
• Ionizing radiation rate

Representing Rigid Body Dynamics

WIP