Waterfall

View vectors of data over time

Library

Sinks

dspsnks4

Description

The Waterfall block displays multiple vectors of data at one time. These vectors represent the input data at consecutive sample times. The input to the block can be real or complex-valued data vectors of any data type including fixed-point data types. However, the input is converted to double-precision before the block processes the data. The Waterfall block displays only real-valued, double-precision vectors of data.

The data is displayed in a three-dimensional axis in the Waterfall window. By default, the x-axis represents amplitude, the y-axis represents samples, and the z-axis represents time. You can adjust the number of sample vectors that the block displays, move and resize the Waterfall window, and modify block parameter values during the simulation. The Waterfall window has toolbar buttons that enable you to zoom in on displayed data, suspend data capture, freeze the scope's display, save the scope position, and export data to the workspace. The toolbar buttons are labeled in the following figure, which shows the Waterfall window as it appears when you double-click a Waterfall block.

Sections of This Reference Page

Waterfall Parameters

You can control the display and behavior of the Waterfall window using the Parameters dialog box.

Note

You can alter the Waterfall parameters while the simulation is running. However, when you make changes to values in text boxes, you must click Enter or click outside the text box before the block accepts your changes.

To open the Parameters dialog box, click the Scope parameters button.
The Parameters dialog box appears.
Click on the different panes to enter parameter settings.

Display Parameters

The following parameters control the Waterfall window's display.

Display traces: Enter the number of vectors of data to be displayed in the Waterfall window.
Update interval: Enter the number of vectors the block should store before it displays them to the window.
Colormap: Choose a colormap for the displayed data.
Transparency: Specify the transparency of the newest and oldest data vectors. Placing the slider in the left-most position tells the block to make the data vector transparent. Placing the slider in the right-most position tells the block to make the data vector opaque. The intermediate data vectors transition between the two chosen transparency values.

Axes Parameters

The following parameters control the axes in the Waterfall window.

Y Min: Enter the minimum value of the y-axis.
Y Max: Enter the maximum value of the y-axis.
Axis color: Enter a background color for the axes. Specify the color using a character vector. For example, to specify black, enter 'k'.
X Axis: Enter the x-axis label.
Y Axis: Enter the y-axis label.
Z Axis: Enter the z-axis label.

Data History Parameters

The following parameters control how many input data vectors the Waterfall block stores. They also control how the data is exported to the MATLAB^® workspace.

History traces

Enter the number of vectors (traces) that you want the block to store.

When the buffer is full

Use this parameter to control the behavior of the block when the buffer is filled:

Overwrite — The old data is replaced with the new data.
Suspend — The block stops storing data in the buffer; however, the simulation continues to run.
Extend — The block extends the buffer so that it can continue to store all the input data.

Data logging

Use this parameter to control which data is exported from the block:

Selected — The selected data vector is exported.
All visible — All of the data vectors displayed in the Waterfall window are exported.
All history — All of the data vectors stored in the block's history buffer are exported.

Export variable: Enter the name of the variable that represents your data in the MATLAB workspace. The default variable name is ExportData.
Export at end of simulation: Select this check box to automatically export the data to the MATLAB workspace when the simulation stops.

Triggering Parameters

The following parameters control when the Waterfall block starts and stops capturing data.

Begin recording

This parameter controls when the Waterfall block starts capturing data:

Immediately — The Waterfall window captures the input data as soon as the simulation starts.
After T seconds — The Time, T parameter appears in the dialog box. Enter the number of seconds the block should wait before it begins capturing data.
After N inputs — The Count, N parameter appears in the dialog box. Enter the number of inputs the block should receive before it begins capturing data.
User-defined — The Function name parameter appears in the dialog box. Enter the name of a MATLAB function that defines when the block should begin capturing data. For more information about how you define this function, see Scope Trigger Function.

Stop recording

This parameter controls when the Waterfall block stops capturing data:

Never — The block captures the input data as long as the simulation is running.
After T seconds — The Time, T parameter appears in the dialog box. Enter the number of seconds the block should wait before it stops capturing data.
After N inputs —The Count, N parameter appears in the dialog box. Enter the number of inputs the block should receive before it stops capturing data.
User-defined — The Function name parameter appears in the dialog box. Enter the name of a MATLAB function that defines when the block should stop capturing data. For more information about how you define this function, see Scope Trigger Function.

Re-arm trigger

This parameter controls when the Waterfall block begins waiting to capture data. It is available only when you select After T seconds, After N inputs, or User-defined for the Stop recording parameter:

Never — The Waterfall Scope block starts and stops capturing data as defined by the Begin recording and Stop recording parameters.
After T seconds — The Time, T parameter appears in the dialog box. Enter the number of seconds the block should wait before it begins waiting to capture data.
After N inputs — The Count, N parameter appears in the dialog box. Enter the number of inputs the block should receive before it begins waiting to capture data.
User-defined — The Function name parameter appears in the dialog box. Enter the name of a MATLAB function that defines when the block should begin waiting to capture data. For more information about how you define this function, see Scope Trigger Function.

The triggering process is illustrated in the state diagram below.

Scope Trigger Function

You can create custom scope trigger functions to control when the scope starts, stops, or begins waiting to capture data.

These functions must be valid MATLAB functions and be located either in the current folder or on the MATLAB path.

Each scope trigger function must have the following form

y = functionname(blk,t,u),

where functionname refers to the name you give your scope trigger function. The variable blk is the Simulink^® block handle. When the scope trigger function is called by the block, Simulink automatically populates this variable with the handle of the Waterfall block. The variable t is the current simulation time, represented by a real, double-precision, scalar value. The variable u is the vector input to the block. The output of the scope trigger function, y, is interpreted as a logical signal. It is either true or false:

Begin recording scope trigger function
- When the output of this scope trigger function is true, the Waterfall block starts capturing data.
- When the output is false, the block remains in its current state.
Stop recording scope trigger function
- When the output of this scope trigger function is true, the block stops capturing data.
- When the output is false, the block remains in its current state.
Re-arm trigger scope trigger function
- When the output of this scope trigger function is true, the block waits for a begin recording event.
- When the output is false, the block remains in its current state.
  Note
  The Waterfall block passes its input data directly to the scope trigger functions. These functions do not use the transformed data defined by the Transform parameters.

The following is an example of a scope trigger function. This function, called trigPower detects when the energy in u exceeds a certain threshold.

function y = trigPower(blk, t, u)

y = (u'*u > 2300);

The following is another example of a scope trigger function. This function, called count3, triggers the scope once three vectors with positive means are input to the block. Then, the function resets itself and begins searching for the next three input vectors with positive means. This scope trigger function is valid only when one Waterfall block is present in your model.

function y = count3(blk, t, u)

persistent state;
if isempty(state); state = 0; end
if mean(u)>0; state = state+1; end
y = (state>=3);
if y; state = 0; end

Transform Parameters

The following parameters transform the input data to the Waterfall block. The result of the transform is displayed in the Waterfall window.

Note

The block assumes that the input to the block corresponds to the Transform parameter you select. For example, when you choose Complex-> Angle, the block assumes that the input is complex. The block does not produce an error when the input is not complex. Therefore, you must verify the format of your input data to guarantee that a meaningful result is displayed in the Waterfall window.

Transform

Choose a transform that you would like to apply to the input of the Waterfall block:

None — The input is displayed as it is received by the block.
Amplitude-> dB — The block converts the input amplitude into decibels.
Complex-> Mag Lin — The block converts the complex input into linear magnitude.
Complex-> Mag dB — The block converts the complex input into magnitude in decibels.
Complex-> Angle — The block converts the complex input into phase.
FFT-> Mag Lin Fs/2 — The block takes the linear magnitude of the FFT input and plots it from 0 to the Nyquist frequency.
FFT-> Mag dB Fs/2 — The block takes the magnitude of the FFT input, converts it to decibels, and plots it from 0 to the Nyquist frequency.
FFT-> Angle Fs/2 — The block converts the FFT input into phase and plots it from 0 to the Nyquist frequency.
Power-> dB — The block converts the input power into decibels.

Function

This parameter is only available when you select User-defined fcn for the Transform parameter. Enter a function that you would like to apply to the input of the Waterfall block. For more information about how you define this function, see Scope Transform Function.

Expression

This parameter is only available when you select User-defined expr for the Transform parameter. Enter an expression that you would like to apply to the input of the Waterfall block. The result of this expression must be real-valued. When you write the expression, be sure to include only one unknown variable. The block assumes this unknown variable represents the input to the block. When the block believes your expression is invalid, the following window appears.

When you click No, your expression is not applied to the input. When you click Yes and your expression is invalid, your simulation stops and Simulink displays an error.

Scope Transform Function

You can create a scope transform function to control how the Waterfall block transforms your input data. This function must have a valid MATLAB function name and be located either in the current folder or on the MATLAB path.

Your scope transform function must have the following form

y = functionname(u),

where functionname refers to the name you give your function. The variable u is the real or complex vector input to the block. The output of the scope transform function, y, must be a double-precision, real-valued vector. When it is not, the simulation stops and Simulink displays an error. Note that the output vector does not need to be the same size as the input vector.

Examples

The following examples illustrate some capabilities of the Waterfall block.

Exporting Data

You can use the Waterfall block to export data to the MATLAB workspace:

Open and run the dspanc example.
While the simulation is running, click the Export to Workspace button.
Type whos at the MATLAB command line.
The variable ExportData appears in your MATLAB workspace. ExportData is a 40-by-6 matrix. This matrix represents the six data vectors that were present in the Waterfall window at the time you clicked the Export to Workspace button. Each column of this matrix contains 40 filter coefficients. The columns of data were captured at six consecutive instants in time.
You can control what data is exported using the Data logging parameter in Data history pane of the Parameters dialog box. For more information, see Data History Parameters.

Capturing Data

You can use the Waterfall block to interact with your data while it is being captured:

Open and run the dspanc example.
While the simulation is running, click the Suspend data capture button.
The Waterfall block no longer captures or displays the data coming from the Downsample block.
To continue capturing data, click the Resume data capture button.
To freeze the data display while continuing to capture data, click the Snapshot display button.
To view the Waterfall block that the data is coming from, click the Go to scope block button.
In the Simulink model window, the Waterfall block that corresponds to the active Waterfall window flashes. This feature is helpful when you have more than one Waterfall block in a model and you want to clarify which data is being displayed.

Linking Scopes

You can link several Waterfall blocks together in order to capture the effect of a model event in all of the Waterfall windows in the model:

Open the dspanc example.
Drag a second Waterfall block into the example model.
Connect this block to the Output port of the LMS Filter block as shown in the figure below.
Run the model and view the model behavior in both Waterfall windows.
In the dspanc/Waterfall window, click the Link scopes button.
In the same window, click the Suspend data capture button.
The data capture is suspended in both scope windows.
Click the Resume data capture button.
The data capture resumes in both scope windows.
In the dspanc/Waterfall window, click the Snapshot display button.
In both scope windows, the data display freezes while the block continues to capture data.
To continue displaying the captured data, click the Resume display button.

Selecting Data

The following figure shows the Waterfall window displaying the output of the dspanc example:

To select a particular set of data, click the Select button.
Click on the Time Bar at the bottom right of the axes to select a vector of data.
The Waterfall block highlights the selected trace.
While the simulation is running, in the bottom right corner, the Waterfall window displays the relative index of the selected trace. For example, in the previous figure, the selected vector is two sample times away from the most current data vector. When the simulation is stopped, the Waterfall window displays both the relative index and the simulation time associated with the selected trace.
To deselect the data vector, click it again.
Click-and-drag along the Time Bar.
Your selection follows the movement of the pointer.

You can use this feature to choose a particular vector to export to the MATLAB workspace. For more information, see Data History Parameters.

Zooming

You can use the Waterfall window to zoom in on data:

Click the Zoom camera button.
In the Waterfall window, click and hold down the left mouse button.
Move the mouse up and down and side-to-side to move closer and farther away from the axes.
To resize the axes to fit the Waterfall window, click the Fit to view button.

Rotating the Display

You can rotate the data displayed in the Waterfall window:

Click on the Orbit camera button.
In the Waterfall window, click and hold down the left mouse button.
Move the mouse in a circular motion to rotate the axes.
To return to the position of the original axes, click the Restore scope position and view button.

Scaling the Axes

You can use the Waterfall window to rescale the y-axis values:

Open and run the dspanc example.
Click the Rescale amplitude button.
The y-axis changes so that its minimum value is zero. The maximum value is scaled to fit the data displayed.

Alternatively, you can scale the y-axis using the Y Min and Y Max parameters in the Axes pane of the Parameters dialog box. This is helpful when you want to undo the effects of rescaling the amplitude. For more information, see Axes Parameters.

Saving Scope Settings

The Waterfall block can save the screen position and viewpoint of the Waterfall window:

Click the Save scope position and view button.
Close the Waterfall window.
Reopen the Waterfall window.
It reopens at the same place on your screen. The viewpoint of the axes also remains the same.

Supported Data Types

Port	Supported Data Types
Input	Double-precision floating point Single-precision floating point Fixed point (signed and unsigned) 8-, 16-, and 32-bit signed integers 8-, 16-, and 32-bit unsigned integers

The Waterfall block accepts any of these data types as input. However, the input is converted to double-precision before the block processes the data. The Waterfall block displays only real-valued, double-precision vectors of data.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using Simulink® Coder™.

This block can be used for simulation visibility in systems that generate code, but is not included in the generated code.

HDL Code Generation
Generate Verilog and VHDL code for FPGA and ASIC designs using HDL Coder™.

This block can be used for simulation visibility in subsystems that generate HDL code, but is not included in the hardware implementation.

PLC Code Generation
Generate Structured Text code using Simulink® PLC Coder™.

This block can be used for simulation visibility in systems that generate code, but is not included in the generated code.

Fixed-Point Conversion
Design and simulate fixed-point systems using Fixed-Point Designer™.

This block accepts fixed-point input, but converts it to double for display.

Documentation

Waterfall

Library