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 Initial Targets section of the block dialog box 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 Initial Targets section 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 Initial Targets section 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 Initial Targets section 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 Initial Targets section 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.

Variable Initialization Range

When declaring a variable, you can specify the minimum and maximum acceptable values for its initialization, for example:

variables
  x = {value={0,'deg'},priority=priority.high,imin={0,'deg'},imax={360,'deg'}};
end

When multiple initialization solutions exist, this syntax lets you guide the solver towards the preferred solution. For more information, see Block-Level Variable Initialization. If the specified range cannot be satisfied during initialization, the solver issues an error.

The solver tries to satisfy the initialization range for a variable regardless of whether its initialization priority is high, low, or none. It is recommended that you use the priority attribute sparingly. The default priority value, priority.none (which is equivalent to leaving out the priority attribute entirely), is suitable in most cases. Differential variables, in general, need high priority, but it is important to avoid over-specificaton. For more information, see Initialize Variables for a Mass-Spring-Damper System.

The block user can modify the variable priority value, as needed, in the Initial Targets section of the block dialog box prior to simulation. However, the block user does not have control over the variable initialization range. Only the block author can specify the acceptable minimum and maximum values for variable initialization in the component file, both for continuous and for event variables.

The default initialization range is (-inf,inf). Therefore, you do not have to specify both values to define the range, it is sufficient to specify only imin or imax. For example, use this syntax to limit the temperature to positive values:

variables
  T = {value={293.15,'K'},imin={0,'K'}};
end

When you specify imin or imax, these values define an open range.

For model initialization using an operating point, the solver tries to satisfy initialization ranges only for variables that do not have a target in the operating point data tree. For more information, see Using Operating Point Data for Model Initialization.

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 block dialog box.