Main Content

Instrumentation Properties

View and edit signal logging and visualization properties

Description

Use the Instrumentation Properties dialog box to configure logging and visualization settings for logged signals, including a data access callback function to process logged data during simulation and logging sample time.

Instrumentation Properties dialog box

Open the Instrumentation Properties

  • Right-click the logging badge on a signal that is marked for logging and select Properties.

Parameters

Logging and Visualization

Select this option to specify a name for logged signal data that is different from the name of the signal in the model. By default, logged signal data uses the name of the signal specified in the model.

The Use custom name property is the same as the Logging name property that you configure through the dialog box.

Programmatic Use

To specify the signal logging name programmatically, use the set_param function to configure the DataLoggingNameMode and DataLoggingName parameters for the port handle that corresponds to the block output port that produces the signal. For an example, see Signal-Specific Logging Name Specified Programmatically.

When you want to reduce the effective sample rate for logged data, select Decimate data and specify the desired decimation factor in the text box. For example, if you specify a decimation factor of 2, every other signal value is logged.

Consider data requirements for each signal before reducing the number of data points logged in simulation. Decimation can cause aliasing if the effective sample rate is too low.

For more information, see Specify Signal Values to Log and Limit the Size of Logged Data.

When you only want to save or analyze the data from the end of a simulation, you can configure logging to capture only the last n signal values. Select Limit data points to last and specify the number of data points you want to log.

When you only log the last simulation values, dashboard blocks and the Simulation Data Inspector do not display data during simulation. Consider data requirements for each signal before you reduce the number of data points logged in simulation.

For more information, see Specify Signal Values to Log and Limit the Size of Logged Data.

Programmatic Use

To configure this option programmatically, use the set_param function to specify the DataLoggingLimitDataPoints and DataLoggingMaxPoints parameters for the port handle that corresponds to the block output port that produces the signal.

Specify the sample time to use for logging the data for the selected signal. By default, the logging sample time is inherited (-1) from the block that produces the signal. For continuous logging sample time, specify the value as 0. To use a discrete sample time for logging data, specify the sampling interval as a scalar.

Specifying a logging sample time may add a new sample time to the model. When you specify a logging sample time, the model calculates a value for the exact time hits. When you use a fixed-step solver, the logging sample time you specify must be a multiple of the base rate for the model.

Logging sample time is not supported for signals inside conditional subsystems or conditional referenced models.

Specify how multidimensional data is logged and interpreted by the Simulation Data Inspector. By default, signals are logged as sample-based, with each element in a multidimensional sample treated as a channel.

When logging a frame-based signal, set Input processing to Columns as channels (frame based). A frame-based signal buffers a batch of samples to create a frame of data. When you log the data as frame-based, each column in a sample is treated as a channel, and the row dimension is treated as evenly-spaced samples within the channel.

Programmatic Use

To programmatically configure or access the Input processing property for a logged signal, use the Simulink.sdi.setSignalInputProcessingMode function and the Simulink.sdi.getSignalInputProcessingMode function.

Complex signal data is logged as a single signal. Use the Complex format property to specify how to display a complex signal in the Simulation Data Inspector. By specifying the complex format in the Instrumentation Properties, you save the preference in the model so logged data is displayed consistently for each simulation. You can also modify the complex format for a signal in the Simulation Data Inspector, after data is logged from simulation or imported.

For all complex formats, you plot the complex signal as one signal. Some formats display components of the plotted signal as separate traces.

  • Real-Imaginary — Plot real and imaginary components as separate traces.

    The signal line color specifies the color of the real component. The imaginary component uses a different shade of the specified line color.

  • Magnitude-Phase — Plot magnitude and phase components as separate traces.

    The signal line color specifies the color of the magnitude component. The phase component uses a different shade of the specified line color.

  • Magnitude — Plot only the magnitude component.

  • Phase — Plot only the phase component.

When you specify a value for the Subplots property, the signal is plotted on the corresponding subplot or subplots in the Simulation Data Inspector. You can use this property to save a plotting configuration in the model. However, the property does not affect the subplot layout in the Simulation Data Inspector or clear signals that are already plotted.

When enabled, you can configure the line style and color used to display the signal in the Simulation Data Inspector and on Dashboard Scope blocks and save the preference in the model so the signal is displayed consistently across MATLAB® sessions.

Specifying the line style and color in the model does not prevent you from changing the line style and color in the Simulation Data Inspector. The Dashboard Scope block and the Simulation Data Inspector always display a signal using the line style and color specified in the logged signal properties, as displayed in the Properties pane in the Simulation Data Inspector.

Line style, width, and color used to display the signal on Dashboard Scope blocks and in the Simulation Data Inspector.

Specifying the line style and color in the model does not prevent you from changing the line style and color in the Simulation Data Inspector. The Dashboard Scope block and the Simulation Data Inspector always display a signal using the line style and color specified in the logged signal properties, as displayed in the Properties pane in the Simulation Data Inspector.

Dependencies

To enable the Line parameter, select Custom style and color.

Data Access

When enabled, you can specify a data access callback function that processes or visualizes the logged signal data during simulation. The function receives data in packets asynchronously throughout the simulation, and the function executes each time it receives new data. For more information, see Access Data in a MATLAB Function During Simulation.

Name of the data access callback function that processes or visualizes signal data during simulation. The data access callback function always receives signal data as the first argument and may also receive simulation time and a function parameter as additional arguments. When the function receives all three arguments, simulation time is the second argument. For more information, see Access Data in a MATLAB Function During Simulation.

For more information about writing MATLAB functions, see Create Functions in Files.

Option to send simulation time along with signal data to the data access callback function during simulation. The data access callback function always receives signal data as the first argument and may also receive simulation time and a function parameter as additional arguments. When a function receives all three arguments, simulation time is the second argument. For more information, see Access Data in a MATLAB Function During Simulation.

When you specify a value for the Function parameter, the data access callback receives the specified value as a second or third argument depending on whether time is included with data sent to the callback function. When you use the same data access callback function to process data for more than one signal, specify a function parameter to identify which signal data the function receives in a given call. For more information, see Access Data in a MATLAB Function During Simulation.

Introduced in R2018a