Main Content

variables

Declare domain or component variables

Parent Section: component | domain

Syntax

variables
    v1 = {value,'unit'};
end

Description

variables begins a variables declaration section, which is terminated by an end keyword:

  • In a component file, this section contains declarations for the variables associated with the component.

  • In a domain file, this section contains declarations for the Across variables associated with the domain. Additionally, domain files must have a separate variables declaration section, with the Balancing attribute set to true, which contains declarations for the Through variables associated with the domain.

Component Variables

In a component file, the following syntax defines an Across, Through, or internal variable, comp_var1, as a value with unit. value is the initial value. unit is a valid unit string, defined in the unit registry.

variables
    comp_var1 = {value,'unit'};
end

For component variables, you can additionally specify the initialization priority, the acceptable initialization range, and the nominal value and unit by declaring the variable as a field array.

variables
    comp_var2 = {value = {value,'unit'},
                 priority = priority.value,
                 imin={value,'unit'},imax={value,'unit'},
                 nominal = {value,'unit'}};
end

The first field in the array is value (value with unit). The other fields are optional and can come in any order.

The priority field can be one of three values listed in the following table:

Priority field in Simscape™ languageResulting default priority in the block dialog box
priority = priority.highHigh
priority = priority.lowLow
priority = priority.none (this is the default)None

Note

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. The block user can modify the variable priority value, as needed, in the Variables tab of the block dialog box prior to simulation.

The imin and imax fields let you specify the minimum and maximum acceptable values for variable initialization, for example:

variables
  x = {value={0,'deg'},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.

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.

Note

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 nominal field must be a value with unit, where value is the nominal value, that is, the expected magnitude of the variable. unit is a valid unit string, defined in the unit registry.

Note

It is recommended that you use the nominal attribute sparingly. The default nominal values, which come from the model value-unit table, are suitable in most cases. The block user can also modify the nominal values and units for individual blocks by using either the block dialog box or set_param and get_param functions, if needed. For more information, see Modify Nominal Values for a Block Variable.

You can also specify the variable name, the way you want it to appear in the Initial Targets section of the block dialog box, as a comment:

variables
    comp_var1 = {value,'unit'}; % Variable name
end

Domain Variables

In a domain file, the following syntax defines an Across variable, domain_across_var1, as a value with unit. value is the initial value. unit is a valid unit string, defined in the unit registry.

variables
    domain_across_var1 = {value,'unit'};
end

You can specify initialization ranges for domain Across variables, for example, to exclude negative values for pressure or temperature. The syntax is the same as for component variables:

variables
    domain_across_var1 = {value={value,'unit'},imin={value,'unit'},imax={value,'unit'}};
end

In a domain file, the following syntax defines a Through variable, domain_through_var1, as a value with unit. value is the initial value. unit is a valid unit string, defined in the unit registry.

variables(Balancing = true)
    domain_through_var1 = {value,'unit'};
end

Examples

expand all

This example initializes the variable w as 0 rad/s:

variables
    w = {0,'rad/s'}; % Angular velocity
end

In the Initial Targets section of the block dialog box, this variable will be named Angular velocity and will have the default initialization priority of none. The block user will be able to change this initialization priority as needed.

This example initializes the variable x as 0 mm, with high priority:

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

In the Initial Targets section of the block dialog box, this variable will be named Spring deformation and will have the high initialization priority by default. The block user will be able to change this initialization priority as needed.

This example initializes the domain Through variable t (torque) as 1 N*m:

variables(Balancing = true)
    t = {1,'N*m'};
end

Version History

Introduced in R2008b