{{>toc}}

TODO this page is in work…

New for release v17.0, we added a Dynamics aspect. The initial capability in this release includes:

• a single rigid-body 6 degrees of freedom equations of motion and state derivative model
• body state can be integrated either at the body center of mass, or at some offset from the center of mass such as at a structure frame origin, etc.
• hooks to an external integration method (optimized for Trick) to integrate the body state
• the 6 “aerodynamic” Euler sequences: RPY, RYP, PYR, PRY, YRP, YPR, for initializing and outputting the rotational state
• various vector, matrix & quaternion math utilities
• a body mass properties container for interfacing with an external mass properties model
• body force & torque containers for interfacing with external force & torque models

This is from the NASA Technology Disclosure MSC-26290-1:

• Existing tools available to ER for modeling the dynamics of moving bodies are very capable, but are overly complicated & bulky for very simple applications, such as a single rigid-body Equations of Motion (EOM). A simpler and easer-to-use alternative was desired.
• Other tools such as JSC Engineering Orbital Dynamics (JEOD), Multi-Body Dynamics (MBDYN) and Multi-Body JEOD (MBJEOD) have rigid, flexible & multi-body dynamics, space environment & interaction models, but some simple applications only need a single rigid-body EOM with minimal environment. Examples of such applications include simple planetary rover models, and space vehicle Reaction Control System (RCS) maneuver jet selection algorithms.
• In the past, developers would typically pull in the JEOD package into their sim, or write their own EOM model.
• Adding JEOD bloats the size of a small project, which is unfortunate considering the project may only use a very small fraction of JEOD’s capability. JEOD also has a considerable learning curve that adds a training impact for engineers inexperienced with it. Writing a new EOM model is “re-inventing the wheel”, and costly compared to including an already existing and appropriately scoped implementation.
• Refer to https://dynamics.jsc.nasa.gov/doku.php?id=theory:rigid for a derivation of the 6-DOF rigid dynamics solved by this implementation. The final equation in the reference (paraphrased here as: {a} = {F} / [m]) is what is solved by the GunnsDynSingleRigidStateDeriv, re-using the generic GUNNS ability to solve such linear systems of equations.
• GUNNS was designed to be generic enough to simulate domains other than the traditional “flow” circuit aspects (fluid, thermal, electric). This dynamics implementation is the first application of that idea.
• The architecture of the dynamics aspect differs significantly from that of the flow aspects, which demonstrates GUNNS’ flexibility. In the dynamics aspect, the GUNNS link (GunnsDynSingleRigidStateDeriv) is also a network (includes the solver and nodes), whereas in the flow aspects, the network is a separate class (containing links, solver & nodes). This difference is illustrated in UML class diagrams: compare Figure 5: “Dynamics Class Diagram” with that of the flow aspects architecture here: https://tricklab.jsc.nasa.gov/redmine/projects/gunns/wiki/Run-Time_Architecture.

This is from the NASA Technology Disclosure MSC-26290-1:

• In operation, the model is constructed as follows: The user will instantiate one GunnsDynSingleRigidEom for the body, one GunnsDynSingleRigidEomInputData for its initial state, one GunnsDynSingleRigidMassProps for its mass properties, and zero or more GunnsDynAppliedForce and GunnsDynAppliedTorque objects for applied forces & moments (F&M), respectively. The mass properties and F&M objects are owned by the user’s simulation models, so that the user can update them in run-time. The user or the simulation environment must implement a state integrator such as Runga-Kutta, etc. Trick already provides integrators for Trick simulations.
• After construction but before run-time propagation, the model is initialized as follows: The user will populate the GunnsDynSingleRigidEomInputData with initial conditions, including position & velocity state, rotational position & velocity state in a desired Euler angles sequence, and a pointer to the body mass properties. Pointers to the applied F&M objects are registered with the GunnsDynSingleRigidEom’s mStateDeriv object (the internal GunnsDynSingleRigidStateDeriv). Finally, the GunnsDynSingleRigidEom’s initialize method is called to complete the initialization.
• After initialization, the model is propagated in run-time during each time step as follows: The user’s mass properties and applied F&M models are updated to change those parameters as desired. Then the GunnsDynSingleRigidEom’s update method is called to calculate the new body state derivative. Then the GunnsDynSingleRigidEom’s integ method is called to integrate state derivative into the new body state, and to finalize the new state output (update Euler angles, normalize the quaternion, etc.) In Trick sims, the update and integ methods are called from derivative and integration jobs, respectively, in the Trick dynamics loop.

This is from the NASA Technology Disclosure MSC-26290-1:

• This update creates a new aspects/dynamics/ aspect source code area in the gunns/ repository, and adds software to generically model a single rigid-body 6-Degrees of Freedom (6-DOF) EOM and related user interfaces.
• Figure 5: “Dynamics Class Diagram” presents the UML class diagram of the software implementation. The GunnsDynSingleRigidStateDeriv class is the heart of the implementation, and the rest is essentially user interface. GunnsDynSingleRigidStateDeriv is what extends and re-uses the core GUNNS capability. It extends GunnsBasicLink, so it is a GUNNS link. It also contains its own GUNNS solver & nodes, with which it assembles & solves the 6-DOF F=ma equation for the state derivative (body translational & rotational accelerations). GunnsDynSingleRigidEom has an interface to an external integrator for integration of the body state.

This is from the NASA Technology Disclosure MSC-26290-1:

• An offset of the center of mass from the reference frame origin causes the 3 rotational rows and the 3 translational rows of the 6×6 mass matrix to be coupled. By solving the state derivative as one 6-DOF set as opposed to separate 3-DOF solutions of the translational & rotational sets, GUNNS offers direct solution of the reference frame origin rather than the center of mass. This is useful since the body is usually defined relative to some body-fixed reference frame, not its center of mass. JEOD only directly solves the center of mass state and relies on an extra relative kinematics package to find the state of another point.
• The GUNNS solver only decomposes the mass matrix when it has changed. This happens automatically, and requires no extra steps from the user when they update the body mass properties. This saves computation time when the mass properties are static. JEOD also does this, but not automatically – the user must call an extra function to update the dynamics mass matrix when the mass properties have been changed.
• The GUNNS solver automatically takes advantage of sparsity in the body mass matrix for computational speed. Thus, when there is no center of mass offset described above, GUNNS automatically solves the uncoupled rotational & translational states separately, which is faster than solving the coupled case. Similarly, sparsity in the body’s inertia tensor (zero products of inertia) causes rows of the rotational state to be uncoupled, further increasing computational speed.
• This dynamics implementation is a much simpler and smaller package than JEOD. It is far less capable than JEOD, but is more appropriate in size & capability for simple projects. This implementation will have a smaller learning curve than JEOD for new users.

• JEOD runs about twice as fast as GUNNS
• GUNNS lacks any environment models, such as gravity
• GUNNS cannot model multi-body or flexible-body dynamics

This is from the NASA Technology Disclosure MSC-26290-1:

• We found that most of the work in implementing a dynamics model is in providing the myriad of possible user interface options & flexibility. There are still many interface options that our implementation lacks, and will always lack, compared to JEOD. These kinds of interfaces don’t re-use any GUNNS capability, nor do they offer much re-use value back to the rest of GUNNS. Therefore we will leave a lot of these interfaces up to the user to implement.
• Another issue that this implementation uncovered was that the GUNNS solver had previously assumed that off-diagonals in the [A] matrix had to be <= 0, but this is not strictly true for the definition of a positive-definite matrix. With this implementation, now the solver can handle positive values as well.

JEOD has this:

vehicle body core_body state rot Q_parent_this (inrtl to body) T_parent_this³³ (inrtl to body) ang_vel_mag ang_vel_this³ (omega, body frame) ang_vel_unit³ (unit vect. of ang_vel_this) trans position (inrtl frame) velocity (inrtl frame) derivs Qdot_parent_this non_grav_accel³ rot_accel³ (appears to be body frame) trans_accel³ (appears to be body frame)

GUNNS equivalent is this:

EOM (GunnsDynSingleRigidEom) mState mRotational mEuler mAngles mSequence (123, etc) mQuaternion⁴ (inrtl to body) mTransMatrix⁹ (inrtl to body) mVelocityMag mVelocity³ (omega, body frame) mVelocityUnit³ (unit vector of mVelocity) mTranslational mPosition³ (inrtl frame) mVelocity³ (inrtl frame) mStateDeriv mAcceleration³ (body frame) mAngAcceleration³ (body frame) mQdot⁴ (deriv. of Q_inertl_body)

We’ve validated against JEOD for a simple case, described below. GUNNS agrees exactly with JEOD in this case.

Initial position & velocity are {0, 0, 0}.
Initial Euler angles are {0, 0, 0} and angular rates are {0, 0, 0}.
Body mass is 1.0e6 (kg).
Body center of mass is at {0, 0, 0} offset from the body reference frame.
Body I _xx: 1.0e7 (kg*m2)
Body I _xy: -2.0e4
Body I _xz: -3.0e4
Body I _yy: 4.0e7
Body I _yz: -5.0e4
Body I _zz: 6.0e7

A single force of {3000, 0, 0} (N) is applied at an offset of {1, 1, 1} (m) in the body reference frame.

Trick’s Euler integrator is used, with a time step of 0.01 (s).

The output Euler angles are in the 123 sequence.