Specify Common Set of Signal Properties as Value Type

Since R2021b

When a signal represents a recurring type of value, you can define the signal properties once and reuse that specification for each signal that represents the same value type. For example, you can specify the unit, minimum value, maximum value, and dimensions of wind velocity, tire pressure, or water temperature once and reuse that specification.

A value type specifies this fundamental set of signal properties:

• Data type

• Minimum value

• Maximum value

• Unit

• Complexity

• Dimensions

• Dimensions mode (fixed-size or variable-size)

• Description

The property specifications for a value type are relevant wherever the value type appears in a model. Value types do not include instance-specific properties, such as initial values or sample times.

To use value types in your model, you must define each value type using a Simulink.ValueType object.

Determine Whether To Use Value Types

You can specify signal properties individually or with a predefined set of property specifications. Depending on your modeling requirement, the way you define a set of signal properties differs.

Modeling Requirement	Specification Source
Assign or validate the properties of a signal based on a set of instance-specific properties, including the initial value and sample time.	Use a Simulink.Signal object or a Signal Specification block. For the properties that are not instance-specific, consider using a Simulink.ValueType object. You can specify this object as the data type of the Simulink.Signal object or Signal Specification block.
Assign or validate the properties of a signal that is an element of a bus.	Use a Simulink.BusElement object in a Simulink.Bus object. For the properties that are not specific to the bus element, consider using a Simulink.ValueType object. You can specify this object as the data type of the Simulink.BusElement object.
Simplify global changes to a data type a model specifies by creating an alias for a built-in data type, such as int8.	Use a Simulink.AliasType object.
Reuse a numeric data type, such as a floating-point, integer, or fixed-point data type.	Use a Simulink.NumericType object.
Assign or validate the properties of signals based on a set of properties that is fundamental to the application-specific value type of the signal, such as wind velocity.	Use a Simulink.ValueType object.
Assign a value type to a System Composer™ port interface or data element.	Use a systemcomposer.ValueType (System Composer) object.

A value type can define the properties of a signal at an interface. When the ports of model components directly connect to each other, specify the same value type for the blocks that represent those ports. If you specify different value types that have the same properties but different names, the software issues an error. By specifying the same value type at both sides of the interface, you enforce consistency at the interface between the two components. For more information about interface design, see Define Interfaces of Model Components.

The value type propagates through the model until the value type reaches a block that produces new data as output. For example, the value type passes through In Bus Element and Out Bus Element blocks, but it does not pass through Sum or Gain blocks.

When you specify a value type as the data type of a block or object, the properties specified by the value type typically override the properties specified by the block or object.

For example, suppose an Inport block has these settings:

• Unit set to ft/s

• Data type set to a Simulink.ValueType object with a unit of m/s

The Inport block uses m/s as the unit.

When you specify a value type as the data type of a Constant block, the value type overrides the minimum and maximum specified by the block and the data type of the constant value. The value type validates the dimensions, complexity, and unit of the constant value. When these properties do not match, the software issues a warning or error. (since R2023b)

For example, suppose a Constant block has these settings:

• Constant value set to a Simulink.Parameter object with a unit of ft/s

• Output data type set to a Simulink.ValueType object with a unit of m/s

During model compilation, the software issues a warning about the mismatched units. The Constant block uses ft/s as the unit.

For another example, suppose a Constant block has these settings:

• Constant value set to [2 3]

• Output data type set to a Simulink.ValueType object with a dimension of 1

During model compilation, the software issues an error about the mismatched dimensions. Similarly, mismatched complexity results in an error.

Information overlays display the property values, not the value type. Suppose your value type specifies a unit. To see the unit that the model uses, in the Simulink^® Toolstrip, on the Debug tab, select Information Overlays > Units. The unit appears on the related signal line.

Value types do not appear in the generated code. The signal properties that the value types specify appear in the generated code.

Create Value Types

To create or edit value types interactively, use the Type Editor or Model Explorer.

For example, to create a value type in the Type Editor:

1. Open the Type Editor using one of these methods:

   • In the Simulink Toolstrip, on the Modeling tab, in the Design gallery, click Type Editor.

     The Type Editor opens as a docked pane in the model window.

   • In the MATLAB^® Command Window, enter typeeditor.

     The Type Editor opens in a standalone window.

2. How you create value types in the Type Editor depends on whether you open the Type Editor in the context of a model window or as a standalone window.

   • Docked Type Editor — Click the button arrow. Then, select Value type.

   • Standalone Type Editor — Click the down arrow on the far right of the Add section to expand the gallery. Then, select Value Type.

   A new Simulink.ValueType object appears in the interactive table.

3. Use the interactive table or Property Inspector to specify the desired property values of the value type.

To create value types programmatically, use the Simulink.ValueType function.

For example, create a value type for wind velocity.

windVelocity = Simulink.ValueType

windVelocity = 
  ValueType with properties:

          DataType: 'double'
               Min: []
               Max: []
              Unit: ''
        Complexity: 'real'
        Dimensions: 1
    DimensionsMode: 'Fixed'
       Description: ''

To edit the properties of the value type programmatically, use dot notation.

windVelocity.DataType = 'single';
windVelocity.Min = 11;
windVelocity.Max = 17;
windVelocity.Unit = 'm/s';
windVelocity.Dimensions = [2 4 3];
windVelocity.Description = 'Wind velocity value type'

windVelocity = 
  ValueType with properties:

          DataType: 'single'
               Min: 11
               Max: 17
              Unit: 'm/s'
        Complexity: 'real'
        Dimensions: [2 4 3]
    DimensionsMode: 'Fixed'
       Description: 'Wind velocity value type'

Value types created programmatically are initially stored in the base workspace.

Specify Value Types

Use a value type to specify signal properties for these blocks and objects:

• Inport block

• Outport block

• In Bus Element block

• Out Bus Element block

• Signal Specification block

• Constant block (since R2023b)

• Simulink.BusElement objects

• Simulink.Signal objects (since R2023a)

• Simulink.Parameter objects (since R2023a)

To associate a block or object with a value type, set the data type of the block or object to ValueType: <object name> and replace <object name> with the Simulink.ValueType object name.

You can specify a value type as the data type either before or after defining the value type. However, before you simulate the model, the Simulink.ValueType object must be defined and loaded.

During model development, you can modify signals to match value types or modify value types to match signals. If you do not want to change the value type, you can:

• Create a value type that matches the changes to the signal and use the new value type for the blocks that the changed signal connects to.

• Revert the signal changes so that the signal continues to match the associated value type.

When value types do not match at an interface, you can:

• Specify the same value type at both ports.

• Remove the value type specification from one of the ports.

• Insert a Signal Specification block between the ports. The Signal Specification block returns a mismatch warning instead of an error when it receives a different value type than the one it specifies.

Save Value Types

You can save value types to these locations:

• Data dictionary

• Script

• Function

• MAT file

If you do not save the value types, then when you reopen a model that uses the value types, you must recreate the Simulink.ValueType objects.

Choose where to store value types based on your modeling requirements.

Modeling Requirement	Location
Store data for large models and model hierarchies.	Use a data dictionary. When you save to a data dictionary from the base workspace, you get all the variables used by the model, not just the Simulink.ValueType objects. To save changes to a data dictionary, use the Type Editor or Model Explorer. To update a model to use a data dictionary, see Migrate Models to Use Simulink Data Dictionary.
Use MATLAB for traceability and model differencing.	Use a script or function. To create a script or function that defines one or more Simulink.ValueType objects, use the Type Editor or Model Explorer.
Save and load value types faster.	Use a MAT file. To create a MAT file that contains Simulink.ValueType objects from the base workspace, use the Type Editor, Model Explorer, or save function.

To save value types stored in the base workspace, you can use any MATLAB technique that saves the contents of the base workspace. However, the resulting file contains everything in the base workspace, not just the value types.

When you modify value types, you must resave them to keep the changes.

Map Value Types to Models

Before you simulate a model, all the value types that the model uses must be loaded into the base workspace or a data dictionary used by the model. Mapping value types to models is important for automation and consistency across models.

• By identifying all of the value types that a model requires, you can ensure that they are loaded before model execution.

• By identifying all models that use a value type, you can ensure that changes to the value type do not cause unexpected changes in any of the models that use the value type.

To ensure the necessary value types load before model execution, consider these approaches:

• Projects — Automatically load or run files that define value types by configuring the files to run when you open a project. For details, see Project Management.

• Data dictionaries — Store value types with variables and other objects for one or more models.

  To share a value types among models, you can link each model to a dictionary and create a common referenced dictionary to store the object. For an example, see Partition Dictionary Data Using Referenced Dictionaries.

• Databases — Capture mapping information in an external data source, such as a database.

• Model callbacks — Load or run files that define value types by using a model callback, such as PreLoadFcn. For more information, see Model Callbacks.

  If a model uses only a few value types, consider copying the Simulink.ValueType object code directly into the callback, instead of loading a file.

To find where a value type is used in an open model, see Finding Blocks That Use a Specific Variable.