Documentation

Through and Across Component Variables

When you declare Through and Across variables in a component, you are essentially creating instances of domain Through and Across variables. You declare a component variable as a value with unit by specifying an initial value and units commensurate with units of the domain variable.

The following example initializes the Through variable t (torque) as 0 N*m:

variables
    t = { 0, 'N*m' };
end

Internal Component Variables

You can also declare an internal component variable as a value with unit. You can use such internal variables throughout the component file, for example, in the equations section or in the intermediate term declarations. Component variables are also used in the model initialization process, as described in Variable Priority for Model Initialization.

The following example declares and initializes three variables:

variables
    f = { 0, 'N' };   % Force
    v = { 0, 'm/s' }; % Velocity
    x = { 0, 'm' };   % Spring deformation
end

Force and velocity are the component Through and Across variables, later to be connected to the domain Through and Across variables using the branches section. Spring deformation is an internal component variable, to be used for model initialization.

You can declare internal component variables of type integer or real as event variables by setting the Event=true attribute. For more information, see Event Variables.

Variable Priority for Model Initialization

When you generate a custom Simscape™ block from a component file, the Variables tab of this block will list all the public variables specified in the underlying component file, along with the initialization priority, target initial value, and unit of each variable. The block user can change the variable priority and target, prior to simulation, to affect the model initialization. For more information, see Variable Initialization.

The default values for variable priority, target value, and unit come from the variable declaration in the component file. Specifying an optional comment lets you control the variable name in the block dialog box. For more information, see Specify Meaningful Names for the Block Parameters and Variables.

In most cases, it is sufficient to declare a variable just as a value with unit, omitting its priority, which is equivalent to priority = priority.none. The block user can set the variable priority, as needed, in the Variables tab of the block dialog box prior to simulation.

In some cases, however, setting a variable to a certain priority by default is essential to the correct operation of the component. To specify a high or low default priority for a component variable, declare the variable as a field array. For example, the following declaration initializes variable x (spring deformation) as 0 mm, with high priority:

variables
    x = { value = { 0 , 'm' }, priority = priority.high }; % Spring deformation
end

In this case, the Spring deformation variable will appear in the Variables tab of the block dialog box with the default priority High and the default target value and unit 0 mm, but the block user can change the variable priority and target as usual.

If you want a variable to always have high initialization priority, without letting the block user to change it, declare the variable as private:

variables(Access=private)
  x = { value = { 0 , 'm' }, priority = priority.high };
end

In this case, the block user does not have control over the variable priority or initialization target, because private variables do not appear in the Variables tab of the block dialog box.

If you want the variable to always have a certain initialization priority, such as High, but let the block user specify the target value, declare the variable as private and tie it to an initialization parameter:

parameters
  p = { 0, 'm' }; % Initial deformation
end
variables(Access=private)
  x = {value = p, priority = priority.high }; 
end

In this case, the value of the Initial deformation parameter, specified by the block user, is assigned as the initial target to variable x, with high initialization priority. Depending on the results of the solve, this target may or may not be satisfied when the solver computes the initial conditions for simulation. For more information, see Initial Conditions Computation.

For composite components, member components are declared as hidden and therefore their variables do not appear in the Variables tab of the block dialog box. However, you can use a top-level parameter to let the block user specify the initial target value of a member component variable. For more information, see Specifying Initial Target Values for Member Variables.

Nominal Value and Unit for a Variable

Nominal values provide a way to specify the expected magnitude of a variable in a model, similar to specifying a transformer rating, or setting a range on a voltmeter. For more information, see System Scaling by Nominal Values.

Each model has an underlying table of nominal value-unit pairs. In general, all variables in a model are scaled based on the nominal value corresponding to their physical unit. You can override this scaling for an individual variable in a component file by providing a nominal value and unit as a variable declaration attribute.

variables
    x = { value = { value , 'unit' }, nominal = {value, 'unit'} }; 
end

When you generate a custom Simscape block from a component file, nominal value and unit form the nominal declaration attribute translate into default values for block parameters x_nominal and x_nominal_unit (where x is the variable name).

For example, this variable declaration:

variables
    i = { value = { 0 , 'A' }, nominal = {1, 'mA'} }; % Current
end

produces the following default values for block parameters:

and looks like this in the Property Inspector.