Introduction - nasa/gunns GitHub Wiki

General-Use Nodal Network Solver.

GUNNS is a tool set to model flow systems in a time-domain simulation environment such as NASA’s Trick. There are 2 main tools in the set:

• GUNNS: (also called “Core”) generic C++ run-time model classes that can be instantiated, configured and built into a Trick sim.
• GunnsDraw: the model design GUI, used to draw up your models and auto-generate the run-time code from them.

GUNNS has a re-usable common approach to 3 simulation domains, which we call our “flow aspects”:

• Fluid: plumbing, life support systems, coolant loops, etc
• Electrical: generation, distribution, loads
• Thermal: structure temperatures, solar heating, etc

This re-usable approach makes GUNNS compact and flexible, with lower development & maintenance cost.

There can be dynamic interaction between all GUNNS aspects and external models (such as sensor/effectors, environment, etc). However, note that the ‘glue code’ that ties separate aspects together is not included in GUNNS. We often refer to this glue code as the ‘Sim Bus’, which is a separate internal NASA product.

GUNNS uses basic nodal analysis to simulate flow circuits. Models (batteries, pipes, valves, radiator panels, etc) are combined in networks to represent the physical systems. Networks are propagated in the time domain and model parameters are updated cyclically.

GunnsDraw is used to draw up these networks, and run-time code & config files are auto-generated from the drawings. Thus, code deliverables are largely self-documented by their drawings.

In addition to the above 3 ‘flow aspects’, GUNNS can model any system of the form [A]{x} = {b}, provided [A] is a symmetric positive-semi-definite matrix. GUNNS includes 2 other ‘non-flow’ aspects that take advantage of this:

• Dynamics: a rigid single-body 6-degrees of freedom equations of motion
• Radiation: (currently in work, not delivered yet) electromagnetic radiation emission, reflection & absorption between surfaces

We think of GUNNS as being a “medium-fidelity” model. It is generally less accurate than more specialized tools. For instance in the fluid aspect, GUNNS is not a true CFD and has many simplifying assumptions and limitations.

GUNNS is a ‘steady-state’ solver. That is, the computed flows are assumed to be constant during each step, and do not include higher order dynamic effects that a ODE or PDE solver would model. GUNNS does have time-dependent effects, such as Capacitance, and models are time- and input-dependent and change their state and flows from step to step. However because of the steady-state nature of the solution, GUNNS models tend to be inaccurate over short time scales. GUNNS is therefore not good at modeling most high-frequency, transient effects. This can be somewhat improved by cycling the model at smaller time steps, at the expense of using more CPU.

GUNNS’ pedigree is training simulation – it was designed as the successor to the flow system solvers used in NASA’s legacy Space Station Training Facility (SSTF) from the 90’s and 00’s. Training simulation is still its biggest application, as NASA’s Flight Operations Division uses it in several large integrated vehicle trainers. NASA’s Engineering Directorate views GUNNS as a useful tool for making 1st-pass analysis and trade studies for new system designs, before more specialized higher-fidelity tools are applied.

There are many similar tools:

• Easy5
• Matlab/Simulink/Simscape Fluids
• Thermal Desktop, SINDA/FLUINT
• Aspen Custom Modeler
• National Instruments Multisim
• SPICE

The same general algorithm is widely used in the energy sector & electronics:

• Plant & pipeline modeling, petrochemical & nuclear industries
• Electrical distribution & circuits

GUNNS’ value to NASA, as compared to public domain tools:

• It is optimized for the NASA Trick simulation environment
• It can be used for real-time or monte-carlo sims
• It is optimized for space vehicle applications
• It is highly re-usable
• It has less unneeded features and overhead and low 3rd-party licensing costs
• GUNNS won the JSC 2018 Exceptional Software of the Year award, and JSC’s nomination for the agency-wide award, where it received an Honorable Mention.

GUNNS is well-established as a training simulation tool in NASA’s Flight Operations Directorate, and it is seeing growing use in future vehicle design studies in the Engineering Directorate.

• NASA JSC Flight Operations Directorate:
  • TS-21 ISS full-task trainer (SSTF)
  • TS-21 Generic Visiting Vehicle trainer (GVV)
• NASA JSC Engineering Directorate:
  • Crewed vehicle sims (Orion, Lunar Gateway, Artemis landers, surface rovers & other systems)
  • Next-generation space suit sims (xEMU)
  • Moon/Mars habitat & ISRU design & tech demonstration studies
• NASA Commercial Crew Program:
  • Boeing Starliner vehicle trainer
  • NASA/EG’s validation sim for SpaceX Falcon 9/Crew Dragon GN&C
• NASA Commercial Cargo Program:
  • Sierra Space Dreamchaser vehicle trainer
• NASA Commercial Lunar Payload Services Program:
  • Intuitive Machines Nova-C lander sim

Aspect Architecture divides a model of a vehicle hardware device (such as a pump) into separate code objects, each implementing a specific aspect of the device (fluid, thermal, electrical, etc). Traditionally, all aspects of a device were modelled in one code object, or the code architecture was divided by other criteria. By dividing the model up among the flow aspects, Aspect Architecture allows networks of objects of like aspect to be solved as simultaneous systems. This improves fidelity, flexibility, and stability over traditional designs.

GUNNS uses basic nodal analysis to solve a system of simultaneous equations of the form:

[A]{p} = {w}

where [A] is the Admittance Matrix, {p} is the Potential Vector, and {w} is the Source Vector.

This form is good for simulating fluid, thermal, and electrical flow systems. GUNNS currently uses the Cholesky Decomposition direct numerical method to solve the above system for {p} . It can also use the Successive Over-Relaxation indirect method, though this is still only a prototype and is not reliable yet. It can also solve the system on NVIDIA GPU’s with the CUDA library, which can be faster than running on CPU’s for large networks.

To simulate all 3 flow aspects, GUNNS uses a lot of analogous concepts that they share. Here are a few of the big ones:

Analogous Concept	Fluid Aspect	Electrical Aspect	Thermal Aspect
Potential	Pressure	Voltage	Temperature
Flow	Mass Flow	Current	Heat Flux
Capacitance	~Volume (n*β)	C = I*dt/dV	m * Cp
Conductance	Area	1/R	Thermal Conductance

There are others, such as Power, etc. We get a lot of code & conceptual reuse from this analogy. This allows developers who might normally specialize in only one of the aspects to more easily work with the other aspects in GUNNS.

GUNNS was designed around and is optimized for this analogy, but it could in theory also be used for other types of systems besides our 3 flow aspects. The only requirement for a system is that it can be described with [A] {p} = {w} and that [A] be a symmetrical positive semi-definite matrix. The recently added Dynamics aspect, and the in-development Radiation aspect are examples.

The picture below illustrates some fluid and electrical devices that are analogous. These fluid and electrical circuits are equivalent. The fluid accumulator and the electrical capacitor both store quantity via their capacitance. The fluid pump and the electrical battery both create a potential rise that causes flow. The fluid check valve and the electrical diode only allow one-way flow. The various fluid pipes & valves resist flow just like the various electrical resistors and switches:

This does not mean, however, that you could use a GunnsDraw electrical network in place of a fluid network when their circuitry appears equivalent. There are many important differences between the implementation of each aspect, so you still need to use the appropriate one.

See Intro Course 2.4: Basic Components.

Large networks have high CPU demand, because CPU demand scales as the cube of the number of nodes in a network. There are several ways we mitigate this CPU cost:

• We divide vehicle systems into smaller networks where possible. Networks of similar aspect can interface and flow between themselves (fluid-fluid, thermal-thermal, etc). Separate networks do not solve simultaneously, as there is one simultaneous system of equations for each network. As long as the break between the smaller networks is at a location in the overall vehicle system where the halves are loosely-coupled (in the dynamics sense), the propagation of the two smaller networks flowing between them is stable and almost identical to the results of a single network, with a large savings in CPU.
• The solver can automatically find isolated islands in a network and solve them separately. This can save CPU cost in the same way as breaking large networks up into smaller ones can, described above.
• We usually slow down the execution rate of networks to as slow as we can get away with. This is usually determined by the external interfaces; for instance if the vehicle flight software polls its fluid sensors at 10 Hz, then we update those fluid networks at that rate. Updating less often creates choppy or static-looking data for the flight software, and updating more often just burns more CPU with no benefit to the flight software.
• Networks can be solved on NVIDIA GPU’s, which can be faster than the CPU for large networks.

GUNNS is highly customizable and extendable:

• Users can develop their own link & spotter classes from scratch or extend GUNNS Core classes as needed. Both types of classes have an object-oriented interface with polymorphism, for a standard & consistent interface with the solver & network. Links and spotters can be extended through inheritance, or associated though composition or aggregation, etc.
• We welcome users contributing to an open-source library of reusable links & spotters.
• The network class (auto-generated by GunnsDraw) can itself be extended to add custom functionality as needed.
• More on customization here: User Customization.

GunnsDraw is a set of offline scripts and custom shape libraries to use Draw.io as a drag & drop GUI to build GUNNS networks of all aspects. The user drags links, nodes & spotters from a shape library onto a drawing and hooks them together. Objects are configured with initial condition values (tank volumes, electrical resistances, initial fluid states, etc). The drawing is then exported as auto-generated C++ code that can be included into a sim.

Here is an example screenshot of a fluid network being drawn in GunnsDraw:

In addition to GunnsDraw, GUNNS thermal aspect networks (and eventually, radiation aspect networks) can be imported from Thermal Desktop. Thermal Desktop is a commercial 3D CAD GUI. We have a plug-in to Thermal Desktop that exports drawings into XML files that configure & initialize thermal networks at run-time. Once set up, changes to these networks are entirely compile-free.

Below is an example screenshot of Thermal Desktop. This example is TS21 SSTF’s model of the ISS Node 3 module with attached cupola and PMA. This was exported as a thermal aspect network for inclusion with others in SSTF.

A simulation developer’s general process for using GUNNS is shown below:

GUNNS is not a complete vehicle model. The GUNNS core repository only contains classes to model the fluid, thermal, and electrical asepcts. We also include some other generic models for things like sensor/effectors, motor, controllers (what we call “signal” & “mechanical” aspects, etc.) that are designed to work with the core aspect models. These are in the gunns/gunns-ts-models folder.

GUNNS is only partially documented. All of our documentation is here on this Wiki or linked to from it.

The fluid aspect in particular has many simplifying assumptions and limitations, described here.

GUNNS is optimized for the NASA Trick simulation framework, and really benefits from also using the thread-safe sim bus and the Health & Status reporting system. Note that the thread-safe sim bus software is not included in GUNNS and isn’t released. This is a major limitations for external users that don’t have an equivalent replacement for it. More on those dependencies here.

More on GUNNS Core dependencies here.