Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

Using Rattlesnake

3Using Rattlesnake

This chapter will describe how to use Rattlesnake through its graphical user interface (GUI). Rattlesnake is capable of running several different types of control, therefore the GUI may look different for different tests. In general, the GUI consists of a tabbed interface across the top of the main window, and users must complete each tab before proceeding to the next. The tabs that exist in a given test will depend on which control type is being run. For example, in a combined environments test (see Chapter 16) such as the one shown in Figure 3.1), there is a Test Profile tab that allows the user to define a testing timeline. Additionally, environments such as the MIMO Random Vibration environment (see Chapter 12) require a system identification phase where the controller identifies relationships between the output signals and the control degrees of freedom. Therefore, tests using the MIMO Random Vibration environment will also have a System Identification and Test Predictions tab. Figure 3.2, on the other hand, shows the GUI for a test that only utilizes the Time History environment (see Chapter 14) so these optional tabs are not displayed.

Rattlesnake GUI tabs when running a combined environments test with an environment that requires a system identification.

Figure 3.1:Rattlesnake GUI tabs when running a combined environments test with an environment that requires a system identification.

Rattlesnake GUI tabs when running a single environment with no system identification phase.

Figure 3.2:Rattlesnake GUI tabs when running a single environment with no system identification phase.

Users of Rattlesnake must be aware that depending on their test configuration, their GUI may not appear identical to images shown in this User’s Manual. Additionally, users should be aware that the GUI library used by this software will inherit stylistic features from the operating system. There may therefore be cosmetic differences between the images of the GUI shown in this document and the GUI seen by the user. All images in this document were created using Microsoft Windows 10 or Windows 11 operating systems, so users with Mac or Linux operating systems will note a difference in GUI appearance.

Note that the Rattlesnake enforces an order to operations when defining a particular test by enabling and disabling tabs in the GUI. Initially, only the first tab will be enabled. As the users complete each tab, the next tab will become available. In Figure 3.1 and Figure 3.2, it can be seen that only the initial tab is enabled, and subsequent tabs are disabled.

3.1Environment Selection

When Rattlesnake is opened, the first GUI window that the user will see allows the user to select the environment that they will run (Figure 3.3). Users can select a single environment, or alternatively select a combined environments test (see Chapter 16). The selection made in this dialog box will determine which tabs are set up in the main GUI.

Initial Rattlesnake dialog to select the type of control that will be run.

Figure 3.3:Initial Rattlesnake dialog to select the type of control that will be run.

3.2Global Data Acquisition Settings

The Data Acquisition Setup tab of the Rattlesnake GUI specifies the global test parameters that the controller will use. Parameters are determined to be global when they affect all environments or the controller itself. The three main sections of this portion of the interface are the Channel Table, Environment Table, and Global Data Acquisition Parameters. Figure 3.4. shows this.

Data Acqisition Setup tab in the Rattlesnake Controller where the Channel Table, Environment Table, and Data Acquisition Parameters are specified.

Figure 3.4:Data Acqisition Setup tab in the Rattlesnake Controller where the Channel Table, Environment Table, and Data Acquisition Parameters are specified.

3.2.1Channel Table

The channel table specifies how the instrument channels in a given test are connected to the data acquisition hardware, as well as how the data read from those channels are used by the software.

In general, for a given test there will be a set of excitation devices that use the output signals from Rattlesnake as well as instrumentation to record the test article’s responses to those exciters. Rattlesnake requires each instrument (or each channel on each instrument for multi-axial instruments) as well as each excitation device to have a row in the channel table. This is perhaps contrary to other control software where only the response channels need to be set up in the channel table. However, to maintain the flexibility to run multiple types of hardware devices, some of which having limitations to their triggering capabilities, Rattlesnake must read in the signal from its output directly in order to be able to synchronize its outputs and the responses to those outputs. Therefore, for all Rattlesnake test setups, the output signal should be split using a tee to the exciter and the corresponding input channel. Because of this requirement, one should keep in mind that the number of acquisition channels required on the hardware device for a given test is actually the number of responses plus the number of outputs. Figure 3.5 shows a schematic of a four acquisition channel, two output channel LAN-XI module set up for use with Rattlesnake.

Output channels teed to acquisition channels so they can be read by the controller.

Figure 3.5:Output channels teed to acquisition channels so they can be read by the controller.

The required data input into the channel table varies with the physical or virtual hardware used for the test. For device-specific channel table requirements, see the appropriate section of Part 2: Rattlesnake Hardware Devices. In general, the entries to the channel table are as follows:

To limit the tediousness of inputting channel table information into the GUI by hand, the channel table can be loaded from an Excel spreadsheet or Comma-separated-value file. A channel table can be loaded by clicking the Load Channel Table button under the channel table, which will bring up a file selection dialog, enabling the user to select a file to load. For convenience, a template Excel spreadsheet is attached to this page:

A template Excel file can also be generated by creating a test in Rattlesnake and saving the empty channel table by clicking the Save Channel Table button under the channel table. If a channel table is filled out in Rattlesnake’s GUI, its contents will be saved to the file as well.

A complete test can be loaded by clicking the Load Test from File button. See Section 3.9 for more details.

3.2.2Environment Table

For combined environments tests, an environment table is also provided to the right of the standard Channel Table. This table specifies which channels are used by which environments. A channel can be used for multiple environments, a single environment, or no environments. Channels used by no environments will still be measured and streamed to disk, but will not be sent to any environment for use in the respective control approaches. The environment table is also used to specify which excitation devices are used by which environment.

For single environment tests, the environment table is not visible, and the software assumes that all channels in the channel table are used by the single environment.

If importing a channel table from an Excel spreadsheet for a combined environments test, the Environment Table can be specified as the columns after the main Channel Table information (starting in Column X with one column for each environment) with the environment name specified in row 2 and an entry (e.g. an X or some other mark) in the row corresponding to a given channel if that channel is used for the given environment.

3.2.3Data Acquisition Parameters

The final portion of Data Acquisition Setup tab specifies data acquisition parameters. These parameters may change depending on the hardware selected.

3.2.4Initialize Data Acquisition

With the Data Acquisition Settings specified in the GUI, the Data Acquisition can be initialized by pressing the Initialize Data Acquisition button. At this point, the controller will go through and create the programming interfaces to the hardware device, specify the sampling parameters, and create the channels on the devices. The software will then proceed to the next tab.

Figure 3.6 shows a completed Data Acquisition Setup tab with three response channels and one output channel for a test with two environments A and B. The first response and output channels are used by both environments, while the second response channel is used only by environment A and the third response channel is used only by environment B.

Example of a completed Data Acquisition Setup tab with three response channels and one output channel.

Figure 3.6:Example of a completed Data Acquisition Setup tab with three response channels and one output channel.

3.3Environment Definition

The Environment Definition tab is the second tab in the Rattlesnake software. It is in this tab that the various environments are defined. The main tab will have one sub-tab for each environment, as shown in Figure 3.7.

Sub-tabs for environments A and B in the Environment Definition tab.

Figure 3.7:Sub-tabs for environments A and B in the Environment Definition tab.

Different environment types will have different parameters that can be set. See Part 3: Rattlesnake Environments for a description of each environment type in Rattlesnake and the parameters that define it.

When all environments are defined, the Initialize Environments button can be pressed to proceed to the next portion of the controller.

3.4System Identification

With the environments defined, the controller proceeds to the System Identification tab if required by any environment, shown in Figure 3.8. During this phase of the controller, the controller will develop relationships between the excitation signals and the responses of the test article to those excitation signals. It will also make a measurement of the noise floor of the test.

System identification tab showing various signals and spectral quantities that can be used to evaluate the test.

Figure 3.8:System identification tab showing various signals and spectral quantities that can be used to evaluate the test.

Not all environment types will require a system identification. For environments that simply stream output data, a system identification will generally not be required. However for any environment that aims to produce an output that creates some response on the test article, a system identification will be required to understand the relationships between the excitation signals and the response signals.

There will be one sub-tab for each environment that requires a System Identification. System identification must be run for each sub-tab before the test can be run. When system identification is performed, the software will first perform a noise floor measurement, where all channels are recorded, but no excitation signal is provided. After the noise floor calculation completes, the system identification will begin.

The System Identification tab has been significantly overhauled since the initial version of controller. The system identification now has a number of dedicated parameters on its tab that the user can select. These are:

The new system identification tab also gives the option to select the signal to use for system identification.

The system identification phase can stream time data to disk by selecting a streaming file and clicking the Stream Time Data checkbox. If streaming time data, the noise measurement will be saved to the variable name time_data and the system identification measurement will be saved to the variable name time_data_1 (see Section 3.8 for more information on the structure of this file).

The spectral data from the system identification can be saved to disk by clicking the Save System Identification Data button and selecting the file. When loading system identification data, one must be careful that the loaded data has the same control and excitation degrees of freedom as the current environment, and that they are in the same order. Otherwise the channels in the loaded data will not map correctly to the current environment.

To run the system identification, there are buttons to Preview the Noise or System ID characterizations. When ready, the Start button can be clicked. It will run a Noise Characterization for the specified number of Noise Averages, and then subsequently run the System Identification characterization for the specified number of System ID Averages. If the user wishes to run either the noise or system identification phases continuously, they can click the Preview Noise or Preview System ID buttons.

As the system identification proceeds, the displays in the Progress portion of the tab will be updated.

Data will be plotted as the system identification proceeds. The signals to visualize can be selected by clicking one or more of the References or Responses channels on the right side of the screen. In the bottom right corner, there are options to show or hide various quantities of interest. The System Identification tab can show the following:

In the References section of the window, the user can select the reference channels to visualize:

In the Responses section of the window, the user can select the response channels to visualize:

In the Show section of the window, the user can select which plots are visible and which are hidden.

3.5Test Predictions

Once the system identification phase completes, the controller will compute a test prediction for each environment where system identification was completed. This prediction will be based on the measured transfer functions between output signals and measured responses, as well as the environment parameters specified on the Environment Definition tab. Predictions will be made both for outputs required as well as response accuracy. These predictions will be displayed on the Test Predictions tab.

3.6Test Profiles

The Test Profile tab gives the user the ability to set up a test timeline for complex combined environments tests. The user can add a list of events that will be executed at certain times during the test. The tab will also display a graphical representation of the test timeline.

Events can be added or removed from the test timeline by clicking the Add Event or Remove Event buttons. Users can also load a series of events from an Excel spreadsheet.

For each event, the following parameters are defined:

Figure 3.9 shows an example of a test profile that ramps up the test level of environment A from -6 to 0 dB, and then subsequently starts environment B.

Example test profile showing a ramp up of test level for environment A and subsequently starting environment B.

Figure 3.9:Example test profile showing a ramp up of test level for environment A and subsequently starting environment B.

3.7Run Test

The Run Test tab is where Rattlesnake finally runs the test. This tab again has sub-tabs for the different environments in the test, however these sub-tabs will not be enabled until the data acquisition system is armed.

Rattlesnake gives the user many options to save data to the disk through a set of Radio buttons at the top of this tab. These options are:

When streaming data, it is important to note that the software does not stop streaming until the data acquisition system is disarmed by pressing the Disarm Data Acquisition button. This is because for a combined-environments test, the environments may have down-time between them where no environment is running, and that data should still be saved.

The Run Test tab contains global Arm Data Acquisition and Disarm Data Acquisition buttons that start and stop the data acquisition system. When the data acquisition system is armed, the user can no longer change streaming options, and the sub-tabs for each environment are enabled. The user can then start or stop each environment manually using the Start Environment or Stop Environment buttons on each environment’s sub-tab. The sub-tab for each environment is described more thoroughly in Part 3: Rattlesnake Environments.

Alternatively, the user can start or stop the test profile by clicking on the Start Profile or Stop Profile buttons respectively. The profile capability also includes the option to switch the active environment sub-tab when an event is executed so the user can see the results. Note that the profile options only appear when a profile has been defined on the Test Profile tab.

Figure 3.10 shows an example Run Test tab with test profile events.

Run Test Tab.

Figure 3.10:Run Test Tab.

3.8Rattlesnake Output Files

After data is acquired, the user may wish to analyze or plot the data acquired for a given test report. Rattlesnake stores data in a self-documenting netCDF file 1, which can be read by multiple platforms. The output file is described as self-documenting because it contains all parameters necessary to reconstruct a given test using the Rattlesnake controller. Any parameter that is set by the user in the GUI is stored to the netCDF file.

A full description of the netCDF file format is out of this document’s scope, but the important points are briefly described here. NetCDF files have a number of data structures. Variables are multi-dimensional arrays of data. Dimensions describe the axes of the variable arrays. Attributes are used to store small data such as scalars or 1D arrays. NetCDF files can be separated into different groups, and each group can have its own variables, dimensions, and attributes.

The Rattlesnake output files contain the following data members:

3.8.1NetCDF Dimensions

3.8.2NetCDF Attributes

3.8.3NetCDF Variables

3.8.4Channels Group

The netCDF files from Rattlesnake store all channel information into a separate group called channels. Inside the channels group, there is a variable for each column of the channel table. See Section #sec:channel_table for more complete descriptions of each channel variable.

3.8.5Environment Groups

Environment-specific attributes, dimensions, and variables are also stored within a group corresponding to each environment. For example, in the case where there were two environments “A” and “B”, parameters specific to environment “A” would be stored within the group “A” in the netCDF file, and similarly for “B”. See Part 3: Rattlesnake Environments for more information on environment-specific parameters.

3.8.6Reading Rattlesnake Output Files using Python

To read data from a netCDF using Python, it is recommended to use the netCDF4 Python package. This library is a dependency of Rattlesnake, so if the user is not running Rattlesnake via an executable, this package should already be installed in the user’s Python ecosystem.

netCDF4 provides a sleek Python interface into the data of a netCDF4 file. This section will assume the command import netCDF4 as nc4 was used to import the package, so nc4 is used as a shorter alias.

A netCDF4 dataset can be opened using the following command:

dataset = nc4.Dataset('path/to/netcdf4/file.nc4')

after which all data can be accessed through the dataset object.

Attribute names can be queried using the dataset.ncattrs() function and the attribute values can be accessed directly from the dataset object using that name.

>>> dataset.ncattrs()
['sample_rate',
'samples_per_write',
'samples_per_read',
'hardware',
'hardware_file']

>>> dataset.sample_rate
2048

Dimensions can be accessed using the dataset.dimensions property, which gives a Python dict where the keys are the dimension names and the values are references to the dimension. The size of the dimension can be accessed using the size parameter in each dimension object.

>>> dataset.dimensions
{'response_channels': <class 'netCDF4._netCDF4.Dimension'>: name = 'response_channels', size = 30,
'output_channels': <class 'netCDF4._netCDF4.Dimension'>: name = 'output_channels', size = 3,
'time_samples': <class 'netCDF4._netCDF4.Dimension'> (unlimited): name = 'time_samples', size = 31745,
'num_environments': <class 'netCDF4._netCDF4.Dimension'>: name = 'num_environments', size = 2}

>>> dataset.dimensions['response_channels'].size
30

Variables can be accessed similarly to dimensions using the dataset.variables property. Variables have many properties that may be interesting to the users, including the netCDF dimensions that were used to size the variable (accessible with the dimensions parameter) or the actual shape of the array (accessible with the shape parameter). The data inside the dimension can be accessed by slicing or indexing the array, or simply passing it to a numpy array. Note that slicing or indexing the variable returns the data in a numpy masked array which allows data to potentially to be missing from the array. Rattlesnake does not use the missing data capabilities of the netCDF file, so data can safely be transformed directly to a regular numpy array.

>>> dataset.variables
{'time_data': <class 'netCDF4._netCDF4.Variable'>
float64 time_data(response_channels, time_samples)
unlimited dimensions: time_samples
current shape = (30, 31745)
filling on, default _FillValue of 9.969209968386869e+36 used,
'environment_names': <class 'netCDF4._netCDF4.Variable'>
vlen environment_names(num_environments)
vlen data type: <class 'str'>
unlimited dimensions: 
current shape = (2,),
'environment_active_channels': <class 'netCDF4._netCDF4.Variable'>
int8 environment_active_channels(response_channels, num_environments)
unlimited dimensions: 
current shape = (30, 2)
filling on, default _FillValue of -127 ignored}

# Get the dimensions used by the variable
>>> dataset.variables['time_data'].dimensions
('response_channels', 'time_samples')

# Get the shape of the variable
>>> dataset.variables['time_data'].shape
(30, 31745)

# Access via slice returns a masked array
>>> dataset.variables['time_data'][0,0]
masked_array(data=-0.00312098,
mask=False,
fill_value=1e+20)

# Can pass directly to a numpy array to get the full variable data
>>> np.array(dataset.variables['time_data'])
array([[-3.12098493e-03,  4.26820006e-03,  3.77395182e-03, ...,
         2.00690958e-01,  3.38505511e-01,  0.00000000e+00],
        [-6.10438702e-03,  1.50628999e-02, -1.50619535e-02, ...,
         2.67639515e-01,  5.50047023e-01,  0.00000000e+00],
        [-3.42732089e-03,  7.76593927e-03, -2.66239267e-03, ...,
         2.05434816e-01,  3.21815820e-01,  0.00000000e+00],
         ...,
        [ 3.71743658e-06, -8.77497995e-08, -8.80558595e-06, ...,
         -5.26559214e-06,  0.00000000e+00,  0.00000000e+00],
        [-1.32020650e-05,  2.74453772e-05, -2.01551409e-05, ...,
         -1.02501347e-05,  0.00000000e+00,  0.00000000e+00],
        [-5.96816619e-07, -1.47868461e-05, -5.24157875e-05, ...,
         -1.61722666e-05,  0.00000000e+00,  0.00000000e+00]])

Group names in the netCDF dataset can be queried using dataset.groups, which returns a dictionary similar to the dimensions and variables. Groups can also be accessed by indexing the dataset directly with the group name. A group object can be treated exactly the same as the root-level dataset, and will have its own set of attributes, dimensions, and variables.

>>> dataset['channels'].variables['node_number']
<class 'netCDF4._netCDF4.Variable'>
vlen control(response_channels)
vlen data type: <class 'str'>
path = /channels
unlimited dimensions: 
current shape = (30,)

3.8.7Reading Rattlesnake Output Files using Matlab

Matlab can also be used to read netCDF files from Rattlesnake. The Matlab ncdisp function can be used to quickly determine which parameters are in a file.

>>> ncdisp('path/to/netcdf/file.nc4')
Source:
           path/to/netcdf/file.nc4
Format:
           netcdf4
Global Attributes:
           sample_rate       = 2048
           samples_per_write = 512
           samples_per_read  = 512
           hardware          = 2
           hardware_file     = 'path/to/hardware/file.exo'
Dimensions:
           response_channels = 30
           output_channels   = 3
           time_samples      = 31745 (UNLIMITED)
           num_environments  = 2
Variables:
    time_data                  
           Size:       31745x30
           Dimensions: time_samples,response_channels
           Datatype:   double
    environment_names          
           Size:       2x1
           Dimensions: num_environments
           Datatype:   UNSUPPORTED DATATYPE
    environment_active_channels
           Size:       2x30
           Dimensions: num_environments,response_channels
           Datatype:   int8
Groups:
    /channels/
        Variables:
            node_number      
                   Size:       30x1
                   Dimensions: /response_channels
                   Datatype:   UNSUPPORTED DATATYPE
       .            
       .
       .

Attributes, dimensions, and other metadata can be read into Matlab using the ncinfo function. Variables information must be read using the ncread function.

>>> finfo = ncinfo('path/to/netcdf/file.nc4')

finfo = 

  struct with fields:

      Filename: 'C:\Users\dprohe\Documents\Local_Respositories\Combined_Environments_Controller\test_data\BARC_Exodus_Test\barc_combined.nc4'
          Name: '/'
    Dimensions: [1x4 struct]
     Variables: [1x3 struct]
    Attributes: [1x5 struct]
        Groups: [1x3 struct]
        Format: 'netcdf4'
        
>>> finfo.Dimensions(1)

ans = 

  struct with fields:

         Name: 'response_channels'
       Length: 30
    Unlimited: 0
    
>>> time_data = ncread('path/to/netcdf/file.nc4','time_data')

One issue with the Matlab interface is that string variables are unsupported. This means that the majority of the channel information cannot be read through the Matlab netCDF interface. However, they can be read using the lower level h5read function.

>>> ncread(file,'channels/node_number')
Error using netcdf.getVar (line 137)
12 is not a recognized netCDF datatype.

Error in internal.matlab.imagesci.nc/read (line 605)
                data = netcdf.getVar(gid, varid);

Error in ncread (line 66)
vardata = ncObj.read(varName, varargin{:});

>>> h5read(file,'/channels/node_number')

ans =

  30x1 cell array

3.9Loading Rattlesnake Tests

It can be tedious to set up a test from scratch each time a test is to be run, so Rattlesnake offers two ways to load test settings from files.

On the Data Acquisition Setup page, selecting the Load Test From File button allows the user to load in a netCDF data file that was output from Rattlesnake. As all the test metadata is stored to this file, Rattlesnake can read the file and set itself up accordingly to reproduce a given test. Note that difficulties may arise using this approach if parameters specified by file paths are no longer valid. For example, if the control law is read from a given file on one computer, but the file is in a different place on a separate computer, Rattlesnake will not be able to find the file.

The second way to load in an entire test is by using the Test Profile functionality in the Combined Environments mode. While this capability was designed to make it easier to load in complex multi-environment test setups, it can be used just as effectively for single environment tests. See Chapter 16 for more information.

3.10Channel Monitor

To aid with understanding the test levels and headroom available for the sensors in the test, a Channel Monitor is available where the levels are shown for each channel. The channel monitor is displayed by clicking on the Channel Monitor button on the lower left side of the GUI. The display shows both an instantaneous level (green) as well as a running historical maximum (blue). If a channel reaches the Warning or Abort level, it will be flagged with a yellow or red tint, respectively. These warnings “latch”; once the level is reached, it will stay highlighted in the channel monitor until the Clear Alerts button is clicked. Figure 3.11 shows an example channel monitor.

View of the Channel Monitor dialog box showing several channels that have reached the “warning” level (highlighted yellow) and one channel that has reached the “abort” level (highlighted red).

Figure 3.11:View of the Channel Monitor dialog box showing several channels that have reached the “warning” level (highlighted yellow) and one channel that has reached the “abort” level (highlighted red).

The aspect ratio of the Channel Monitor can be customized to different sizes modifying the Channels per Row.

References
  1. Unidata. (2019). Network Comon Data Form (netCDF) version 4.4.1.1. Software. 10.5065/D6H70CW6
Rattlesnake Vibration Controller
Acquiring and Running Rattlesnake
Rattlesnake Vibration Controller
Part 2: Rattlesnake Hardware Devices