Signal Groups

About Signal Groups

To display, create, and edit interchangeable groups of signal sources and quickly switch the groups into and out of a model, use the Signal Builder block. You can define any piecewise linear signal shape (waveform).

Note

The Signal Builder block is not recommended to work with signal groups. Instead, use the Signal Editor block to display, create, edit, and switch interchangeable scenarios. For more information, see Create and Edit Signal Data. For more information on why you should migrate your models, see Migrate from Signal Builder Block to Signal Editor Block.

Use signal groups when testing a model, especially when using them in conjunction with the Simulink^® Assertion block and the Model Coverage Tool from the Simulink Coverage™.

Solver pane settings in Model Configuration Parameters can affect the Signal Builder block output. See Simulation Phases in Dynamic Systems and Compare Solvers for a description of how solvers affect simulation.

Note

The Signal Builder block adds a port for each signal you create. The block Position parameter limits the number of ports the Signal Builder block can have, and therefore the number of signals you can create. For more information, see the Position parameter at Common Block Properties.

You can also use the signalbuilder function to populate a Signal Builder block.

Supported Waveforms

The Signal Builder block supports these waveforms.

Using the Signal Builder Block with Fast Restart

After you turn on fast restart:

• In between runs, you can change data, rename signals and signal groups, and add new groups. You cannot:

  • Import signals or signal groups

  • Change signal output settings

• You can click the Run all button once. To reenable the Run all button, toggle the fast restart button on the Simulink Editor tool bar. However, Run all does not use fast restart.

Editing Signal Groups

The Signal Builder window allows you to create, rename, move, then delete signal groups from the set of groups represented by a Signal Builder block.

Creating and Deleting Signal Groups

To create a signal group:

1. In Signal Builder, copy an existing signal group.

2. Modify it to suit your needs.

To copy an existing signal group:

1. In Signal Builder, select the group from the list.

2. Select Group > Copy.

   A new group is created.

To delete a group, select the group from the list, and select Group > Delete.

Renaming Signal Groups

To rename a signal group:

1. In Signal Builder, select the group from the list.

2. Select Group > Rename.

3. Edit the existing name in the dialog box or enter a new name. Click OK.

Moving Signal Groups

To reposition a group in the stack of group panes:

1. In Signal Builder, select the pane.

2. To move the group lower in the stack, select Group > Move Down.

3. To move the pane higher in the stack, select Group > Move Up.

Editing Signals

Signal Builder allows you to create, cut and paste, hide, and delete signals from signal groups.

Creating Signals

To create a signal in the currently selected signal group:

1. In Signal Builder, from the Active Group list, select the group you want to add the signal to.

2. Select Signal > New.

   The menu lists the waveforms you can add.

   Waveform	Description	Inputs	Output
   Constant	Constant waveform	None
   Step	Step waveform	None
   Pulse	Pulse waveform	None
   Square	Square waveform	Frequency (Hz) Waveform frequency, in hertz Amplitude Waveform amplitude Y Offset Waveform vertical offset % Duty cycle Percent of the period the signal is positive (a value between 0 and 100)
   Sawtooth	Sawtooth waveform	Frequency (Hz) Waveform frequency, in hertz Amplitude Waveform amplitude Y Offset Waveform vertical offset
   Sampled Sin	Sampled sine waveform	Frequency (Hz) Waveform frequency, in hertz Amplitude Waveform amplitude Y Offset Waveform vertical offset Samples Per Period Number of samples per waveform period
   Sampled Gaussian Noise	Sampled Gaussian noise waveform based on a Gaussian distribution with input mean and standard deviation at input frequency	Frequency (Hz) Waveform frequency, in hertz Mean The mean value of the random variable output Standard Deviation The standard deviation squared of the random variable output Seed (empty to use current state) The initial seed value for the random number generator
   Pseudorandom Noise	Pseudorandom noise waveform based on a binomial distribution with upper and lower values at input frequency	Frequency (Hz) Frequency with which waveform fluctuates between Upper value and Lower value, in hertz Upper value Upper limit of signal Lower value Lower limit of signal Seed The initial seed value for the random number generator
   Poisson Random Noise	Poisson random noise waveform that alternates between 0 and 1	Avg rate (1/sec) Average rate of transition between 0 and 1 Seed (empty to use current state) The initial seed value for the random number generator
   Custom	Custom piecewise linear waveform; custom values must fit within the display area	Time values Vector of two or more time coordinates Y values Vector of two or more signal amplitudes that correspond to the values in Time values The entries in either field can be any MATLAB® expression that evaluates to a vector, including the results from the evaluation of a MATLAB workspace variable. The resulting vectors must be of equal length. Note Signal Builder displays a warning if you add a custom waveform with a large number of data points (100,000,000 or more).

3. Select the waveform you want to add.

4. Specify the inputs (in the prompt), and click OK.

If you select a standard waveform, Signal Builder adds a signal with that waveform to the group. If you select a custom waveform, you are prompted for Time values and Y values.

You can also use MATLAB workspace variables to create new signals.

1. In the MATLAB Command Window, create data for two variables, t and y.

   t = 1:10
   y = 1:10

   These vectors must be the same size.

2. Create a model and add a Signal Builder block.

3. Double-click the Signal Builder block.

4. Select Signal > New > Custom.

5. In the Custom Waveform window, enter t in the Time values field and y in the Y values field and then click OK.

   The Signal Builder block window displays the new signal as Signal 2.

   

Defining Signal Output

To specify the type of output to use for sending test signals:

1. In Signal Builder, select Signal > Output.

2. From the list, select:

   • Ports

     Default. Sends individual signals from the block. An output port named Signal N appears for each Signal N.

   • Bus

     Sends single, virtual, nonhierarchical bus of signals from the block. An output port named Bus appears.

   Tip

   • You cannot use the Bus option to create a bus of nonvirtual signals.

   • The Bus option enables you to change your model layout without having to reroute Signal Builder block signals. Use the Bus Selector block to select the signals from this bus.

   • If you create a Signal Builder block using the Viewers & Generators Manager or using the Create & Connect Generator option from a signal line context menu, you cannot define signal output. In these cases, the block sends individual signals.

Copying and Pasting Signals

To copy a signal from one group and paste it into another group as a new signal:

1. In Signal Builder, select the signal you want to copy.

2. Select Edit > Copy.

3. Select the group you want to paste the signal into.

4. Select Edit > Paste.

To copy a signal from one axis and paste it into another axis to replace its signal:

1. Select the signal you want to copy.

2. Select Edit > Copy.

3. Select the signal on the axis that you want to update.

4. Select Edit > Paste.

Deleting Signals

To delete a signal, in Signal Builder, select the signal and choose Delete or Cut from the Edit menu. Signal Builder deletes the signal from the current group. Because each signal group must contain the same number of signals, Signal Builder also deletes all signals sharing the same index in the other groups.

Renaming a Signal

To rename a signal:

1. In Signal Builder, select Signal > Rename.

   A dialog box appears with an edit field that displays the current name of the signal.

2. Edit or replace the current name with a new name.

3. Click OK.

You can also edit the signal name in the Name field in the lower-left corner of the Signal Builder window.

Replacing a Signal

To replace a signal:

1. In Signal Builder, select the signal, then select Signal > Replace with.

   A menu of waveforms appears. It includes a set of standard waveforms (Constant, Step, and so on) and a Custom waveform option.

2. Select one of the waveforms.

   If you select a standard waveform, Signal Builder replaces a signal in the currently selected group with that waveform. For other waveforms, the Signal Builder displays a dialog to allow you to provide input for the requested waveform.

Waveform	Description	Inputs
Constant	Constant waveform.	None
Step	Step waveform.	None
Pulse	Pulse waveform	None
Square	Square waveform	Frequency (Hz) Waveform frequency, in hertz Amplitude Waveform amplitude Y Offset Waveform vertical offset % Duty cycle Percent of the period in which the signal is positive. Enter a value between 0 and 100.
Sawtooth	Sawtooth waveform	Frequency (Hz) Waveform frequency, in hertz Amplitude Waveform amplitude Y Offset Waveform vertical offset
Sampled Sin	Sampled sine waveform	Frequency (Hz) Waveform frequency, in hertz Amplitude Waveform amplitude Y Offset Waveform vertical offset Samples Per Period Number of samples per waveform period
Sampled Gaussian Noise	Sampled Gaussian noise waveform based on a Gaussian distribution with input mean and standard deviation at input frequency.	Frequency (Hz) Waveform frequency, in hertz Mean The mean value of the random variable output Standard Deviation The standard deviation squared of the random variable output Seed (empty to use current state) The initial seed value for the random number generator
Pseudorandom Noise	Pseudorandom noise waveform based on a binomial distribution with upper and lower values at input frequency.	Frequency (Hz) Frequency with which waveform fluctuates between Upper value and Lower value, in hertz Upper value Upper limit of signal Lower value Lower limit of signal Seed The initial seed value for the random number generator
Poisson Random Noise	Poisson random noise waveform that alternates between 0 and 1	Avg rate (1/sec) Average rate of transition between 0 and 1 Seed (empty to use current state) The initial seed value for the random number generator
Custom	Custom piecewise linear waveform. Custom values must fit within the display area.	Time values Vector of two or more time coordinates Y values Vector of two or more signal amplitudes that correspond to the values in Time values The entries in either field can be any MATLAB expression that evaluates to a vector. The resulting vectors must be of equal length. Note Signal Builder returns a warning if you add a custom waveform with a large number of data points (100,000,000 or more). You can then cancel the action.

You can also edit the signal name in the Name field in the lower-left corner of the Signal Builder window.

Changing a Signal Index

To change a signal index:

1. In Signal Builder, select the signal, then select Signal > Change Index.

   A dialog box appears with a drop-down list field containing the existing index of the signal.

2. From the drop-down list, select another index and select OK. Or select an index from the Index list in the lower-left corner of the Signal Builder window.

Hiding Signals

By default, the Signal Builder window displays the group waveforms in the group pane. To hide a waveform:

1. In Signal Builder, select the waveform, then select Signal > Hide.

2. To redisplay a hidden waveform, select the Group pane, then select Signal > Show.

3. Select the signal from the list. Alternatively, you can hide and redisplay a hidden waveform by double-clicking its name in the Signal Builder signal list.

Creating Signal Group Sets Manually

This topic describes how to create signal group sets manually. If you have signal data files, such as those from test cases, consider importing this data as described in Importing Signal Group Sets.

To create an interchangeable set of signal groups:

1. Drag an instance of the Signal Builder block from the Simulink Sources library and drop it into your model.

   

   By default, the block represents a single signal group containing a single signal source that outputs a square wave pulse.

2. Use the block signal editor to create additional signal groups, add signals to the signal groups, modify existing signals and signal groups, and select the signal group that the block outputs.

   Note

   Each signal group must contain the same number of signals.

3. Connect the output of the block to your diagram.

   The block displays an output port for each signal that the block can output.

You can create as many Signal Builder blocks as you like in a model, each representing a distinct set of interchangeable groups of signal sources. When a group has multiple signals, the signals might have different end times. However, Signal Builder block requires the end times of signals within a group to match. If a mismatch occurs, Signal Builder block matches the end times by holding the last value of the signal with the smaller end time.

See Simulating with Signal Groups for information on using signal groups in a model.

Signal Data Files and Data Reformatting Function for Following Procedures

The procedures in the following sections use these three files: 3Grp_3Sig.xls, SigBldCustomFile.xls, and createSignalBuilderSupportedFormat.m. To access these files, open the live script.

Importing Signal Group Sets

The topics in this section describe how to import signal data into the Signal Builder block. You should already have a signal data file whose contents you want to import. For example, you might have signal data from previously run test cases. See Importing Signal Groups from Existing Data Sets for a description of the data formats that the Signal Builder block accepts.

Signal Builder accepts signals only of type double.

If you import a Simulink.SimulationData.Dataset data set, the block imports it as its own group.

Importing Signal Groups from Existing Data Sets

You might have existing signal data sets that you want to enter into the Signal Builder block. The File > Import from File command on the Signal Builder window starts the Import File dialog box. This dialog box is modal, which means that focus cannot change to another MATLAB window while the dialog box is running. If you want to see changes in the Signal Builder window after you import data, do one of the following:

• Close the Import File dialog box.

• Set up the Import File dialog box and Signal Builder window side by side.

Note

You cannot undo the results of importing a signal data file. In addition, you cannot undo the last action performed before opening the Import File dialog box. When you close the Import File dialog box, the Undo last edit and Redo last edit buttons on the Signal Builder window are grayed out. These buttons are grayed out regardless of whether you imported a data file.

The Import File dialog box accepts the following appropriately formatted file types:

• Microsoft^® Excel^® (.xls, .xlsx)

• Comma-separated value (CSV) text files (.csv)

• MAT-files (.mat)

Tip

To import signal data from a Microsoft Excel spreadsheet, consider using the From Spreadsheet block. The From Spreadsheet block incrementally loads data from the spreadsheet during simulation. If you use a From Spreadsheet block, you do not need to do anything to handle changes to sheet values.

You can import your data set file only if it is appropriately formatted.

For Microsoft Excel spreadsheets:

• The Signal Builder block interprets the first row as signal name. If you do not specify a signal name, the Signal Builder block assigns a default one with the format Imported_Signal #, where # increments with each additional unnamed signal.

• The Signal Builder block interprets the first column as time. In this column, the time values must increase.

• The Signal Builder block interprets the remaining columns as signals.

• If there are multiple sheets:

  • Each sheet must have the same number of signals (columns).

  • Each sheet must have the same set of signal names (if any).

  • Each column on each sheet must have the same number of rows.

• Signal Builder block interprets each worksheet as a signal group.

This example 3Grp_3Sig.xls contains an acceptably formatted Microsoft Excel spreadsheet. It has three worksheets named Group1, Group2, and Group3, representing three signal groups.

For CSV text files:

• Each file contains only numbers. Do not name signals in a CSV file.

• The Signal Builder block interprets the first column as time. In this column, the time values must increase.

• The Signal Builder block interprets the remaining columns as signals.

• Each column must have the same number of entries.

• The Signal Builder block interprets each file as one signal group.

• The Signal Builder block assigns a default signal name to each signal with the format Imported_Signal #, where # increments with each additional signal.

This example contains an acceptably formatted CSV file. The contents represent one signal group.

0,0,0,5,0
1,0,1,5,0
2,0,1,5,0
3,0,1,5,0
4,5,1,5,0
5,5,1,5,0
6,5,1,5,0
7,0,1,5,0
8,0,1,5,1
9,0,1,5,1
10,0,1,5,0

For MAT-files:

• The Signal Builder block supports data store logging that the Simulink.SimulationData.Dataset object represents and interprets this data as a single group.

• The Signal Builder block supports Simulink output saved as a structure with time.

• The Signal Builder block supports the Signal Builder data format. This format is a group of cell arrays that must be labeled.

• Signal Builder block does not support:

  • Simulink output as only a structure

  • Simulink output as only an array

Note

Signal Builder returns a warning if you import a large number of data points (100,000,000 or more). You can then cancel the action.

This example contains an acceptably logged MATLAB workspace. Use the MATLAB workspace Save command to save the variables to a MAT-file. Import this file to the Signal Builder block.

Replacing All Signal Data with Selected Data

Simulink software creates a default Signal Builder block with one signal. To replace this signal and all other signal data that the block might display:

1. Create a model and drag a Signal Builder block into that model.

2. Double-click the block.

   The Signal Builder window appears with its default Signal 1.

3. In Signal Builder, select File > Import from File.

   The Import File dialog box appears.

4. In the File to Import field, enter a signal data file name or click Browse.

   The file browser appears.

5. If you select the file browser, navigate to and select a signal data file. Select 3Grp_3Sig.xls.

   Note

   If you try to import an improperly formatted data file, an error message pops up.

   The Select data to import pane contains the signal data from the file. Click the expanders to display all the signals.

   

6. Select the signals you want to import. To import all the signals, click Select All.

7. From the Select placement of data list, select the action to take on the signal data. Select Replace existing dataset.

   The Confirm Selection button is activated. Validate your signal selection before the Signal Builder block performs the specified action. If the dialog detects an error, it displays an error message.

8. Click the Confirm Selection button.

9. Click Apply to replace the existing signal data with the contents of this file.

   When selecting Replace existing dataset, the software gives you the opportunity to save the existing contents of the Signal Builder block.

   

10. Click a button, as follows:

    To...	Click...
    Save the contents of the Signal Builder block before replacing it with the new signal data. Note This selection prompts you to save the Signal Builder block in a model name of your choice. The software saves only the Signal Builder block and no other model content.	Yes, save as
    Replace the contents of the Signal Builder block without saving them first.	No, import without saving
    Stop the replacement process.	Cancel

    For this example, select No, import without saving to replace the contents of the Signal Builder block.

11. The Signal Builder block updates with the new signal data. Click OK to close the Import File dialog box and inspect the Signal Builder block.

    

12. Click OK.

13. Inspect the updated Signal Builder window to confirm that your signal data is intact.

14. Close the Signal Builder window and save and close the model. For example, save the model as signalbuilder1.

Appending Selected Signals to All Existing Signal Groups

You can import signals from a signal data file and append selected signals to the end of all existing signal groups. If the signal names to be appended are not unique, the software renames them by incrementing each name by 1 or higher until it is a unique signal name. For example, if the block and data file contain signals named thermostat, the software renames the imported signal to thermostat1 upon appending. If you add another signal named thermostat, the software names that latest version thermostat2.

This topic uses signalbuilder1 from the procedure in Replacing All Signal Data with Selected Data.

1. In the MATLAB Command Window, type signalbuilder1.

2. Double-click the Signal Builder block.

   The Signal Builder window appears.

3. In the Signal Builder window, select File > Import from File.

   The Import File dialog box appears.

4. In the File to Import field, enter a signal data file name or click Browse.

   The file browser is displayed.

5. If you select the file browser, navigate to and select a signal data file. Select 3Grp_3Sig.xls.

   Note

   If you try to import an improperly formatted signal data file, an error message pops up.

   The Select data to import pane contains the signal data from the file. Click the expander to display all the signals.

6. Select the signals you want to import. In this example, there are three groups, myGroup1, myGroupB, and myGroup_Three. Select all the signals in myGroup1.

   

7. From the Select placement of data list, select the action to take on the signal data. Select Append selected signals to all groups.

   The Confirm Selection button is activated. Validate your signal selection before the Signal Builder block performs the specified action. If the signal data selection is not appropriate, Confirm Selection remains grayed out. For example, Confirm Selection remains grayed out if the number of signals you select is not the same as the number of signals in the Signal Builder group that you want to replace.

8. Click the Confirm Selection button.

   The confirmation also enables the OK and Apply buttons.

9. Click Apply to append the selected signals to all the signal groups in the Signal Builder block.

10. The Signal Builder block updates with the new signal data. Click OK to close the Import File dialog box and inspect the Signal Builder block.

    

11. Click OK.

12. Inspect the updated Signal Builder window to confirm that your signal data is intact. Notice that the software has renamed the signals Sig1, Sig2, and Sig3 from the signal data file to Sig4, Sig5, and Sig6 in the Signal Builder block.

13. Close the Signal Builder window and save and close the model. For example, save the model as signalbuilder2.

Appending Selected Signals to Sequential Existing Signal Groups

You can append signals, in the order in which they are selected, to the end of sequential signal groups. This statement means that you select the same number of signals as there are signal groups, and sequentially append each signal to a different group. The software renames each appended signal to the name of the last appended signal.

This topic uses signalbuilder1 from the procedure in Replacing All Signal Data with Selected Data.

1. In the MATLAB Command Window, type signalbuilder1.

2. Double-click the Signal Builder block.

3. Note how many groups exist in the Signal Builder block. For example, this Signal Builder block has three groups, myGroup1, myGroupB, and myGroup_Three.

   

4. In the Signal Builder window, select File > Import from File.

5. In the File to Import field, enter a signal data file name or click Browse.

6. If you select the file browser, navigate to and select a signal data file. Select 3Grp_3Sig.xls.

   Note

   If you try to import an improperly formatted signal data file, an error message window appears.

   The Select data to import pane contains the signal data from the file. Click the expander to display all the signals.

7. Select the signals you want to import. In this example, there are three groups, myGroup1, myGroupB, and myGroup_Three. Select all the signals in myGroup1.

   

8. From the Placement for Selected Data list, select the action to take on the signal data. Select Append selected signals to different groups (in order).

   The Confirm Selection button is activated. Validate your signal selection before the Signal Builder block performs the specified action.

9. Click the Confirm Selection button.

   The confirmation also enables the OK and Apply buttons.

10. Click Apply to append the signals.

    The Signal Builder block updates with the new signal data. Click OK to close the Import File dialog box and inspect the three groups of the Signal Builder block.

    The topmost signal group, myGroup1, shows all signals by default, including the new Sig4.

    

11. Click another group name, for example, myGroupB. Notice that Sig4 exists for the group, hidden by default.

    

12. To show Sig4 on this pane, double-click Sig4 in the Selection Status area of the pane. The graph is updated to reflect Sig4.

    

13. Close the Signal Builder window and save and close the model. For example, save the model as signalbuilder3.

Appending Signal Groups to Existing Groups

You can append one or more signal groups to the end of the list of existing signal groups. If the block already has a signal group with the same name as the one you are adding, the software increments the group name by 1 or higher until it is unique before adding it. For example, if the block and data file contain groups named MyGroup1, the software renames the imported group to MyGroup2 upon appending. If you add another group named MyGroup1, the software names that latest version MyGroup3.

This topic uses signalbuilder1 from the procedure in Replacing All Signal Data with Selected Data.

1. In the MATLAB Command Window, type signalbuilder1.

2. Double-click the Signal Builder block.

   The Signal Builder window appears.

3. Note how many groups exist in the Signal Builder block, and how many signals exist in each group. The Signal Builder block requires that all groups have the same number of signals. For example, this Signal Builder block has three groups, myGroup1, myGroupB, and myGroup_Three. Three signals exist in each group.

   

4. Double-click the block.

5. In the File to Import text field, enter a signal data file name or click Browse.

6. If you select the file browser, navigate to and select a signal data file. Select 3Grp_3Sig.xls.

   The Data to Import pane contains the signal data from the file. Click the expander to display all the signals.

7. Evaluate the number of signals in the groups of this data file. If the number of signals in each group equals the number of signals in the groups that exist in the block, you can append one of these groups to the block.

8. Select the group you want to import. In this example, there are three groups, myGroup1, myGroupB, and myGroup_Three. Select myGroupB.

   

9. From the Placement for Selected Data list, select the action to take on the signal group. Select Append groups.

   The Confirm Selection button is activated. Validate your signal selection before the Signal Builder block performs the specified action.

10. Click the Confirm Selection button.

    The confirmation also enables the OK and Apply buttons.

11. Click Apply to append the signals.

    The Signal Builder block updates with the new signal data. Click OK to close the Import File dialog box and inspect the groups of the Signal Builder block.

    Notice the addition of the new signal group as the last pane. Because there is already a signal group named myGroupB, the software automatically increments the new signal group name by 1. Select myGroupB1.

    

12. Close the Signal Builder window and save and close the model. For example, save the model as signalbuilder4.

Appending Signals with the Same Name to Existing Signal Groups

If you append a signal whose name is the same as a signal that exists in the Signal Builder block, the software increments the name of the appended signal by 1. The software repeats incrementing until the appended signal name is unique. For example:

1. Assume your Signal Builder block has a signal group, myGroup1, with the signals Sig1, Sig2, and Sig3.

2. Append a signal named Sig1 to myGroup1.

3. Observe that the software increments Sig1 to Sig4 before appending it to myGroup1.

Appending a Group of Signals with Different Signal Names

If you append a signal group whose signal names differ from those that exist in the Signal Builder block, the software changes the names of the existing signals to be the same as the appended signals. For example,

1. Assume your Signal Builder block has a signal group, myGroup1, with the signals Sig1, Sig2, and Sig3.

2. Append a signal group named myGroup2 whose signal names are SigA, SigB, and SigC.

3. Observe that the software:

   • Appends myGroup2.

   • Renames the signals in myGroup1 to be the same as those in myGroup2.

Importing Data with Custom Formats

This topic describes how to import signal data formatted in a custom format. You should already have the signal data from a file whose contents you want to import. See Importing Signal Groups from Existing Data Sets for a description of the data formats that the Signal Builder block accepts. If your data is not formatted using one of these data formats, use the following workflow to import the custom formatted data. This workflow uses the following files, located in the folder matlabroot\help\toolbox\simulink\examples (open), as examples:

• SigBldCustomFile.xls — Signal data Microsoft Excel file using a format that Signal Builder block does not accept, for example:

  

• createSignalBuilderSupportedFormat.m — Custom MATLAB function that reads Microsoft Excel spreadsheets. This example function reformats the custom data, in a format that the Signal Builder block supports, as follows:

  • grpNames — Cell array that contains group name character vectors with number of rows = 1, number of columns = number of groups.

  • sigNames — Cell array that contains signal name character vectors with number of rows = 1, columns = number of signals.

  • time — Cell array that contains time data with number of rows = number of signals, columns = number of groups.

  • data — Cell array that contains signal data with number of rows = number of signals, columns = number of groups.

  Signal Builder has the following requirements for this custom function:

  • Number of signals in each group must be the same.

  • Signal names in each group must be the same.

  • Number of data points in each signal must be the same.

  • Each element in the time and data cell array holds a matrix of real numbers. This matrix can be [1xN] or [Nx1], where N is the number of data points in every signal.

1. Identify the format of your custom signal data, for example:

   SigBldCustomFile.xls

2. Create a custom MATLAB function that:

   1. Uses a MATLAB I/O function to read your custom formatted signal data. For example, createSignalBuilderSupportedFormat.m.

   2. Formats the custom formatted signal data to one that the Signal Builder block accepts, for example, a MAT-file.

3. Use your custom MATLAB function to write your custom formatted signal data to a file that Signal Builder block accepts. For example:

   createSignalBuilderSupportedFormat('SigBldCustomFile.xls', 'OutputData.mat')

4. Import the reformatted signal data file, OutputData.mat, into the Signal Builder block (see Importing Signal Group Sets).

Editing Waveforms

Signal Builder allows you to change the shape, color, and line style and thickness of the waveforms output by a group.

Reshaping a Waveform

Signal Builder allows you to change the waveform by selecting and dragging its line segments and points with the mouse or arrow keys or by editing the coordinates of segments or points.

Selecting a Waveform

To select a waveform, left-click the mouse on any point on the waveform.

The Signal Builder displays the waveform points to indicate that the waveform is selected.

To deselect a waveform, left-click any point on the waveform axis that is not on the waveform itself or press the Esc key.

Working with Points

You can work with points in a waveform:

• To select a point in a waveform, first select the waveform. Then, position the mouse cursor over the point. The cursor changes shape to indicate that it is over a point.

  

  Left-click the point with the mouse. The Signal Builder draws a circle around the point to indicate your selection.

  

• To insert a point, select the waveform and Shift+click the section for the point.

• To deselect the point, press the Esc key.

• To delete a point, select the point and press the Backspace or Delete keys.

• To edit a point with the signalbuilder function, use the signalbuilder set function to replace the waveform. You cannot programmatically remove a point.

Selecting Segments

To select a line segment, first select the waveform that contains it. Then, left-click the segment. The Signal Builder thickens the segment to indicate that it is selected.

To deselect the segment, press the Esc key.

Moving Waveforms

To move a waveform, select it and use the arrow keys on your keyboard to move the waveform in the desired direction. Each key stroke moves the waveform to the next location on the snap grid (see Snap Grid) or by 0.1 inches if the snap grid is not enabled.

Dragging Segments

To drag a line segment to a new location, position the mouse cursor over the line segment. The mouse cursor changes shape to show the direction in which you can drag the segment.

Press the left mouse button and drag the segment in the direction indicated to the desired location. You can also use the arrow keys on your keyboard to move the selected line segment.

Dragging points

To drag a point along the signal amplitude (vertical) axis, move the mouse cursor over the point. The cursor changes shape to a circle to indicate that you can drag the point. Drag the point parallel to the y-axis to the desired location. To drag the point along the time (horizontal) axis, press the Shift key while dragging the point. You can also use the arrow keys on your keyboard to move the selected point.

Snap Grid

Each waveform axis contains an invisible snap grid that facilitates precise positioning of waveform points. The origin of the snap grid coincides with the origin of the waveform axis. When you drop a point or segment that you have been dragging, the Signal Builder moves the point or the segment points to the nearest point or points on the grid, respectively. The Signal Builder Axes menu allows you to specify the grid horizontal (time) axis and vertical (amplitude) axis spacing independently. The finer the spacing, the more freedom you have in placing points but the harder it is to position points precisely. By default, the grid spacing is 0, which means that you can place points anywhere on the grid; i.e., the grid is effectively off. Use the Axes menu to select the spacing that you prefer.

Inserting and Deleting points

To insert a point, first select the waveform. Then hold down the Shift key and left-click the waveform at the point where you want to insert the point. To delete a point, select the point and press the Del key.

Editing Point Coordinates

To change the coordinates of a point, first select the point. The Signal Builder displays the current coordinates of the point in the Left Point edit fields at the bottom of the Signal Builder window. To change the amplitude of the selected point, edit or replace the value in the Y field with the new value and press Enter. The Signal Builder moves the point to its new location. Similarly edit the value in the T field to change the time of the selected point.

Editing Segment Coordinates

To change the coordinates of a segment, first select the segment. The Signal Builder displays the current coordinates of the endpoints of the segment in the Left Point and Right Point edit fields at the bottom of the Signal Builder window. To change a coordinate, edit the value in its corresponding edit field and press Enter.

Changing the Color of a Waveform

To change the color of a waveform, select the waveform and then select Color from the Signal Builder Signal menu. The Signal Builder displays the MATLAB color chooser. Choose a new color for the waveform. Click OK.

Changing a Waveform Line Style and Thickness

The Signal Builder can display a waveform as a solid, dashed, or dotted line. It uses a solid line by default. To change the line style of a waveform, select the waveform, then select Line Style from the Signal Builder Signal menu. Select a line style from the menu.

To change the line thickness of a waveform, select the waveform, then select Line Width from the Signal menu. Edit the thickness value and click OK.

Signal Builder Time Range

The Signal Builder time range determines the span of time over which its output is explicitly defined. By default, the time range runs from 0 to 10 seconds. You can change both the beginning and ending times of a block time range (see Changing a Signal Builder Time Range).

If the simulation starts before the start time of a block time range, the block extrapolates its initial output from its first two defined outputs. If the simulation runs beyond the block time range, the block by default outputs values extrapolated from the last defined signal values for the remainder of the simulation. The Signal Builder Simulation Options dialog box allows you to specify other final output options (see Signal values after final time for more information).

Note

When you click the Start simulation button on the Signal Builder block toolbar, the simulation uses the stop time of the model. The end of the time range specified in the waveform is not the stop time for the model.

Changing a Signal Builder Time Range

To change the time range, select Change Time Range from the Signal Builder Axes menu.

In the dialog box, edit the Min time and Max time fields as necessary to reflect the beginning and ending times of the new time range, respectively.

Exporting Signal Group Data

You can export data that defines Signal Builder block signals groups to a MAT-file, the MATLAB Workspace, or the Signal Editor block.

To export Signal Builder signal data, formatted as Simulink.SimulationData.Dataset, to a MAT-file, select File > Export Data > To MAT-file.

• File name — Enter a name for the MAT-file to contain the data.

• Group indices — Enter one or signal group numbers for which you want to export the data, specified as a scalar or vector. Numbers must correspond to an existing group in the block.

Alternatively, you can use the signalbuilder get function to return one or more data sets. For example:

[ds1 ds2]=signalbuilder(block,'get',[group1 group2])

To export signal data to the MATLAB workspace, select File > Export Data > To Workspace.

The Signal Builder exports the data by default to a workspace variable named channels. To export to a differently named variable, enter the variable name in the Variable name field. The Signal Builder exports the data to the workspace as the value of the specified variable.

The exported data is an array of structures. The structure xData and yData fields contain the coordinate points defining signals in the currently selected signal group.

To access all the data in the signal groups of a Signal Builder block, use the signalbuilder get function:

[time, data]=signalbuilder(block,'get',signal,group)

For example:

% For time 0 to 5, create three signal groups.
block = signalbuilder([], 'create', [0 5], {[2 2] [4 4] [7 8];[0 2] [0 4] [7 10]});
% Get the signals for all three groups.
[time, data]=signalbuilder(block,'get',[1 2],[1:3])

time =

  2×3 cell array

    [1×2 double]    [1×2 double]    [1×2 double]
    [1×2 double]    [1×2 double]    [1×2 double]


data =

  2×3 cell array

    [1×2 double]    [1×2 double]    [1×2 double]
    [1×2 double]    [1×2 double]    [1×2 double]

To access signal data from the Signal Builder block and export it to the Signal Editor block, select File > Export Data > To Signal Editor block.

1. From the Signal Builder block, select File > Export > To Signal Editor block.

   Tip

   Alternatively, click .

2. In the file browser, specify a file name to contain the saved signal data.

   A Signal Editor block appears in the model.

3. To export the signal data to the Signal Editor block, double-click the block and verify the exported file name in the File name parameter.

4. To view the imported signal data in the Signal Editor user interface, click Launch Signal Editor ().

Simulating with Signal Groups

You can use standard simulation commands to run models containing Signal Builder blocks or you can use the Run or Run all button in the Signal Builder window (see Running All Signal Groups).

If you want to capture inputs and outputs that the Run all button generates, consider using the SystemTest™ software.

Activating a Signal Group

During a simulation, a Signal Builder block always outputs the active signal group. The active signal group is the group selected in the Signal Builder window for that block, if the dialog box is open. Otherwise, the active group is the group that was selected when the dialog box was last closed. To activate a group, open the group Signal Builder window and select the group.

Running Different Signal Groups in Succession

The Signal Builder toolbar includes the standard Simulink buttons for running a simulation. This facilitates running several different signal groups in succession. For example, you can open the dialog box, select a group, run a simulation, select another group, run a simulation, and so on, all from the Signal Builder window.

Running All Signal Groups

To run all the signal groups defined by a Signal Builder block, open the block dialog box and click the button from the Signal Builder toolbar. The Run all button runs a series of simulations, one for each signal group defined by the block. If you installed Simulink Coverage on your system and are using the Model Coverage Tool, the Run all button configures the tool to collect and save coverage data for each simulation in the MATLAB workspace and display a report of the combined coverage results at the end of the last simulation. This allows you to quickly determine how well a set of signal groups tests your model.

Note

To stop a series of simulations started by the Run all command, enter Ctrl+C at the MATLAB command line.

Simulation from Signal Builder Block

To control simulations from the Signal Builder block, select File > Simulation Options.

Signal values after final time

The setting of this control determines the output of the Signal Builder block if a simulation runs longer than the period defined by the block.

• To output the last defined value of each signal in the currently active group for the remainder of the simulation, select Hold final value. For example:

  

• To output values extrapolated from the last defined value of each signal in the currently active group for the remainder of the simulation, select Extrapolate. For example:

  

• To output zero for the remainder of the simulation, select Set to zero. For example:

  

Sample time

To output a continuous signal, enter 0 in the Sample time parameter. For example, the following display shows the output of a Signal Builder block set to output a continuous Gaussian waveform over a period of 10 seconds.

To output a discrete signal, enter the sample time of the signal in this parameter. The following example shows the output of a Signal Builder block set to emit a discrete Gaussian waveform having a 0.5 second sample time.

Enable zero crossing

To have the Signal Builder block detect zero-crossing events, set Enable zero crossing On (default). The Signal Builder block sets the zero-crossing detection on the From Workspace block that you use to create the Signal Builder signal groups. For more information, see Zero-Crossing Detection.