MATLAB Digest - July 2003

Applied Simulink Modeling Techniques for Varying Signal Widths

(Part II.)

by Dan Lluch

The second of a two-part series, this article details modeling techniques for designing Simulink simulations to handle varying signal widths. These techniques address common issues when algorithms need to be applied N times due to simulation parameters. The article uses an example (available for download from MATLAB Central) based on a simulation that includes an arbitrary number of vehicles.

The requirement of having an arbitrary number of vehicles directly translates to a simulation with an arbitrary number of states that, in turn, has the major challenge of accommodating varying signal widths within the simulation. There are various realizations of a given algorithm within Simulink, just as with any programming language. The methods discussed here will allow realizations to be independent of signal width, thus allowing varying width for different configurations of the simulation.

The first article of the series recounted the history of the topic, introduced the simulation, and provided examples and examined subsystems that exploited inherent Simulink capabilities.

This article concentrates on how you can use application program interfaces (APIs) to parameterize components within the simulation for varying signal widths. Examples using the following APIs will be highlighted and explained:

• Stateflow API
• Virtual Reality Toolbox API
• Simulink Model Construction API

The article first compares structural to nonstructural changes within Simulink. Complementing the primary API topic, this article also describes how to use GUIs to simplify simulation execution by examining a front-end panel.

---

These articles concentrate on the modeling techniques featured in “Building Multi-UAV Simulation Methods”[1], emphasizing the relevant Simulink (and Simulink add-on tools) capabilities.

---

Comparing Structural and Nonstructural Changes within Simulink

As discussed in Part I of this series, there are three subsystems at the highest level of the Simulink diagram that constitute the feedback loop (shown again in Figure 1). They do not undergo any block or signal line changes due to number of vehicles, targets, or obstacles. Therefore, when parameterization causes any given signal to change at initialization, the block diagram does not change structurally; this means there are no new new signal lines, blocks, input/output ports, etc. Part I highlights how Simulink allows varying signal widths without changing the Simulink block diagram structure.

Figure 1: Root level of the simulation. Click on image to see enlarged view.

The remaining two top-level subsystems labeled Virtual Reality Display and Mode Display (Annotation A, Figure 1), however, are blocks that house elements that become structurally different based on the number of vehicles, obstacles, and targets in the simulation. These two subsystems house the Stateflow mode logic visualization and the three-dimensional virtual reality modeling language (VRML) world that shows the vehicles flying among the targets and obstacles.

Simulink and other add-on tools can handle the structural changes requirement programmatically with application program interfaces (APIs). This example uses three APIs: the Stateflow API, the Virtual Reality Toolbox API, and the Simulink Model Construction API. These APIs are another example of how MATLAB interacts with Simulink to enable you to script and batch processes that will operate on elements (e.g., VRML worlds, Stateflow charts, and Simulink diagrams) using M-files. This integration lets you change the structure of these elements automatically through parameterization, allowing these elements to handle varying signal widths in this case.

As mentioned, the VRML world and state machine must change structurally for different simulation runs that have a different number of vehicles, obstacles, and targets. These structural changes are thus parameterized on number and location of vehicles, obstacles, and targets. The process to build the correct element is then scripted using the aforementioned APIs. These scripts can then be incorporated into the simulation initialization process to completely automate the process. Here are some examples of structural changes in the context of this example:

• Stateflow charts that exhibit the addition/subtraction of states, events, and the number/dimension of Simulink input/output data or internal Stateflow data
• VMRL worlds that exhibit change in number, size, or location of objects within the world
• Virtual Reality Toolbox Sink blocks that must change port characteristics (number and signal width) based on Simulink signal inputs
• Simulink block diagrams that change number of ports, lines, mask parameter strings, blocks, etc.

Stateflow API

For any given simulation, Stateflow must have all sizes and data types of inputs, outputs, and internal data scoped within a state chart. When size changes are required, one common approach is to define an array large enough to handle the maximum case; logic is then devised to access only elements that are used at any particular time inside and outside of Stateflow. This approach consumes too much memory and requires excessive design time. A more practical approach is to use the Stateflow API for dynamic resizing (at initialization), which allocates the correct and minimum amount of memory for the simulation.

The Stateflow API is ideal for enabling varying signal widths to pass in and out of the Stateflow machine, since the chart inherently requires a different structure if these widths change. The Stateflow API helped in constructing the correct state chart at initialization for the particular simulation being run. In this example, the construction process was generalized to be valid for any number of vehicles. Figure 2 shows a representative state machine for this simulation.

Figure 2: Representative Stateflow chart. Click on image to see enlarged view.

Examining the Stateflow Mode Visualization and Tracking Chart

Recall for this example that each vehicle’s motions are dictated by four instincts: collision avoidance (ac_acoid), obstacle avoidance (obs_avoid), target acquisition (tgt_aquire), and formation keeping (form_keep). Modes were defined to represent which instinct most affects each vehicle’s motion at any particular time (for more information, refer to history and background in Part I or [2]). A Stateflow chart presents this mode information. Each vehicle in the simulation has a parallel superstate with each possible mode represented as a substate within that superstate (figure 2). The challenge is to create a state machine for any number of vehicles (NUM_AC), which can also monitor each vehicle’s mode. By inspection, the structure of the state chart must change as follows:

• Number of parallel superstates must change since one exists for each vehicle
• Variable used for mode tracking (MODE_COUNT) is sized [NUM_AC*4]
• Number of input events (representing a dominant instinct change) from Simulink must change since that will be NUM_AC*4

The Stateflow API enables this solution and approach, which you can see in the MAKE_UAVMODES function M-file (~110 executable lines). One key point is that the function copies the superstate for each vehicle from a user-made template (using the Stateflow clipboard feature). Using a template enables a file location to quickly modify the representation of that superstate. Also, note that within this function, the event triggers that dictate when any given vehicle transitions from one mode to another are also defined correctly for any number of vehicles. Therefore, given N number of vehicles, this function constructs a state chart that houses N superstates, 4xN number of event inputs from Simulink, and will allow tracking of the 4xN individual vehicle modes for any given simulation. Here is a code fragment showing how the API defines all Simulink external events inside the Stateflow environment. Notice how it is parameterized on the number of vehicles (NUM_AC).

%
% define all external events
%
for i=1:num_ac*4
  e_h = Stateflow.Event(chart);
  e_h.Name = ['e' num2str(i)];
  e_h.Scope = 'INPUT_EVENT';
  e_h.Trigger = 'RISING_EDGE_EVENT';
end

Figures 3 and 4 show the same subsystem in two different configurations (five and seven vehicles) of the simulation. You can see the signal widths change automatically on the Simulink block portion of this subsystem via methods discussed in Part I. There is the following subtle effect within the Simulink/Stateflow interaction (Annotation A) when changing the number of vehicles. Namely, solely the varying width event input in the uav_modes Stateflow chart points to the inherent structural changes described above.

Figure 3: Stateflow mode display subsystem for five UAVs. Click on image to see enlarged view.

Figure 4: Stateflow mode display subsystem for seven UAVs. Click on image to see enlarged view.

For more information on the details and goals behind the API construction of this Stateflow chart, please refer to reference [1].

Virtual Reality Toolbox API

This example uses the Virtual Reality Toolbox to drive a virtual reality world that houses all the vehicles, targets, and obstacles. Making the simulation valid for any number of vehicles, targets, and obstacles poses similar structural change requirements to the virtual reality elements of the Stateflow chart (above). Figures 5 and 6 show the VRML world for two configurations of the simulation.

Figure 5: Five UAVs, three obstacles (rear view). Click on image to see enlarged view.

Figure 6: Seven UAVs, three obstacles, two targets (side view). Click on image to see enlarged view.

For the changes to occur automatically as shown in Figures 5 and 6, two main areas involving virtual reality elements within the simulation must change structurally. Namely, the structure of the VRML world and the Simulink subsystem that houses the virtual reality elements must be different between simulation runs. For the case of the VRML world, the ASCII file that defines it will have different lines of code as a function of vehicles, targets, and obstacles. For the case of the Simulink subsystem, blocks will require a different number of ports with a different number of lines feeding them. The Virtual Reality Toolbox API and the Simulink Model Construction API enable these changes.

Figures 5 and 6 show the structural changes relating to the VRML world (TEMP.WRL) by showing a different number of objects. This world is dynamically created at initialization as a function of number and position of vehicles, obstacles, and targets.

Figures 7 and 8 both show the contents of the Virtual Reality display subsystem (Figure 1, Annotation A).

Figure 7: Virtual Reality display subsystem for five vehicles. Click on image to see enlarged view.

Figure 8: Virtual Reality display subsystem for seven vehicles. Click on image to see enlarged view.

These subsystems clearly display the difference in signal lines and number of ports. Most notably, the VR Sink required an input port for each vehicle, as opposed to an input port for all vehicles with variable-width capabilities. Position vectors from Simulink then drive the vehicles within the world. The VRML world and the block diagram construction shown in the above figures are built automatically through the Virtual Reality Toolbox and the Simulink Model Construction APIs within the MAKE_UAVVR function (~150 executable lines). The following code fragment example adds all targets to the virtual reality world. Notice how the script is parameterized based on whether target acquisition is turned on, as well as the size and location of the targets.

% Add a sphere node for each target if target
% acquisition is on make the diffuse color so that
% one can see through it.
if (targets.tgt_aquire_on)
   for i=1:length(targets.radius)     end
end


Simulink Model Construction API

The model construction API can help you change and interrogate a Simulink model to obtain information. This capability is corner stoned on the FIND_SYSTEM command (see Appendix A of Part I). These commands can be scripted in an M-file allowing for the automation of model manipulation and construction. The Simulink Model Construction API is used with the above examples involving the Stateflow and Virtual Realtity Toolbox APIs since those changes described above also will affect the Simulink block diagram construction aspects. It is also used to parameterize actions based on the number of vehicles, obstacles, and targets within this MultiUAV simulation. Examples include:

• Finding certain objects within the Simulink model
• Setting or obtaining properties of Simulink objects (i.e., handles, mask parameter values, positions, etc.)
• Adding and deleting lines and blocks

Here is a sample code fragment from MAKE_UAVVR that houses some of these capabilities. This code fragment helped reconnect the blocks in Figures 7 and 8.

h_vrsink=find_system('vehicles','referenceblock','vrlib/VR Sink');
h_vrsink=char(h_vrsink); % handle to the parent of the VR Sink block
h_vrsubsys = get_param(h_vrsink, 'parent'); % handle to the Multiport block within the same
% subsystem as the VR
h_multi = find_system(h_vrsubsys,'regexp','on',...
'referenceblock','dspindex/Multiport');
h_multi = char(h_multi); % add a line for each multiport output (num_ac)
for i=1:num_ac end


The subsections of grouped code perform these actions:

1. Locate the Virtual Reality Toolbox Sink block (extract a handle) within the model
2. Identify the parent of the Sink block
3. Locate the Multiport block (extract a handle) within the parent subsystem
4. Add a line from each port on the Multiport block to the appropriate port on the Virtual Reality Sink block (notice parameterization on NUM_AC)

GUI for Simplifying Simulation Execution

Timing these API executions during initialization becomes extremely important since there are order dependencies within this process. For instance, you cannot add a signal unless both ports exist. MATLAB helps you design GUIs based on the event/callback mechanism. A front-end GUI (shown in Figure 7) addresses the order-dependent issues by batching the process after you hit the Update Sim button. The batched process is outlined here:

1. Construct the VRML world and update the VR Sink block properties (MAKE_UAVVR)
2. Construct the Stateflow chart (MAKE_UAVMODES)
3. Update the model diagram with VR subsystem port information
4. Reconnect the VR subsystem ports (MAKE_UAVVR)

Figure 7: Front-end GUI.

Additionally, this front-end GUI is designed to be a single interface that controls vehicles, obstacles, and targets for any given simulation run, including:

• Number and initial conditions of vehicles
• Target acquisition toggle (on/off)
• Number and location of the targets
• Obstacle avoidance toggle (on/off)
• Number and location of the obstacles

This GUI links MATLAB, where the data that parameterizes the simulation model exists, and the Simulink environment, where the simulation model is realized.

This article completes the two-part series that reviewed various applied modeling techniques for handling varying signal widths within a Simulink simulation. This topic was chosen in response to customer questions regarding the many applications available in using these methods. The goal was to help demonstrate some of these techniques using Simulink in a real-life example. There are instances when more than one approach could be used for any given algorithm, just as with any programming language. The non-trivial task of choosing an appropriate method for any particular case is left to the designer.

Further Reading on Featured APIs

Please refer to the documentation for further information:

- On the scope and capabilities of each API:

• Stateflow API
• List of API examples
• Virtual Reality Toolbox API
• Simulink Model Construction API
• Model and Block Parameters

-On creating GUIs within the MATLAB environment:

• Creating graphical user interfaces

References
[1] Lluch D., "Building Multi-UAV Simulation Methods," Paper No. AIAA-2002-4977, AIAA MST, 2002
[2] Anderson M., Robbins A., "Formation Flight as a Cooperative
Game," Paper No. AIAA-98-4124, AIAA GNC, 1998