Declaring Domains and Components

Declaration Section Purpose

Both domain and component files contain a declaration section:

  • The declaration section of a domain file is where you define the Through and Across variables for the domain. You can also define the domain-wide parameters, if needed.

  • The declaration section of a component file is where you define all the variables, parameters, nodes, inputs, and outputs that you need to describe the connections and behavior of the component. These are called member declarations.

    In order to use a variable, parameter, and so on, in the setup and equation sections of a component file, you have to first define it in the declaration section.

Definitions

The declaration section of a Simscape™ file may contain one or more member declarations.

TermDefinition
Member
  • A member is a piece of a model's declaration. The collection of all members of a model is its declaration.

  • It has an associated data type and identifier.

  • Each member is associated with a unique member class. Additionally, members may have some specific attributes.

Member class
  • A member class is the broader classification of a member.

  • The following is the set of member classes: variables (domain or component variables), parameters, inputs, outputs, nodes, components. The components member class, not to be confused with the component model class, is discussed in Declaring Member Components.

  • Two members may have the same type, but be of different member classes. For example, a parameter and an input may have the same data type, but because they are of different member classes, they behave differently.

Member Declarations

The following rules apply to declaring members:

  • Like the MATLAB® class system, declared members appear in a declaration block:

    <ModelClass> <Identifier>
       <MemberClass>
          % members here
       end
       ...
    end
  • Unlike the MATLAB class system, <MemberClass> may take on any of the available member classes and dictates the member class of the members defined within the block.

  • Like the MATLAB class system, each declared member is associated with a MATLAB identifier, <Identifier>. Unlike the MATLAB class system, members must be declared with a right-hand side value.

    <ModelClass> <Identifier>
       <MemberClass>
          <Identifier> = <Expression>;
          % more members
       end
       ...
    end
  • <Expression> on the right-hand side of the equal sign (=) is a MATLAB expression. It could be a constant expression, or a call to a MATLAB function.

  • The MATLAB class of the expression is restricted by the class of the member being declared. Also, the data type of the expression dictates data type of the declared member.

Member Summary

The following table provides the summary of member classes.

Member ClassApplicable Model ClassesMATLAB Class of ExpressionExpression MeaningWritable
parametersdomain
component
Numerical value with unitDefault valueYes
variablesdomain
component
Double value with unitNominal value and default initial conditionYes
inputscomponentScalar double value with unitDefault valueNo
outputscomponentScalar double value with unitDefault valueNo
nodescomponentInstance of a node associated with a domainType of domainNo
componentscomponentInstance of a component classMember component included in a composite model (see Declaring Member Components)No

    Note   When a member is writable, it means that it can be assigned to in the setup function. nodes and components are themselves not writable, but their writable members (parameters and variables) are.

Declaring a Member as a Value with Unit

In Simscape language, declaration members such as parameters, variables, inputs, and outputs, are represented as a value with associated unit. The syntax for a value with unit is essentially that of a two-member value-unit cell array:

 { value , 'unit' }

where value is a real matrix, including a scalar, and unit is a valid unit string, defined in the unit registry, or 1 (unitless). Depending on the member type, certain restrictions may apply. See respective reference pages for details.

For example, this is how you declare a parameter as a value with unit:

par1 = { value , 'unit' };

As in MATLAB, the comma is not required, and this syntax is equivalent:

 par1 = { value 'unit' };

To declare a unitless parameter, you can either use the same syntax:

 par1 = { value , '1' };

or omit the unit and use this syntax:

 par1 = value;

Internally, however, this parameter will be treated as a two-member value-unit cell array { value , '1' }.

Declaring Through and Across Variables for a Domain

In a domain file, you have to declare the Through and Across variables associated with the domain. These variables characterize the energy flow and usually come in pairs, one Through and one Across. Simscape language does not require that you have the same number of Through and Across variables in a domain definition, but it is highly recommended. For more information, see Basic Principles of Modeling Physical Networks.

variables begins an Across variables declaration block, which is terminated by an end key word. This block contains declarations for all the Across variables associated with the domain. A domain model class definition can contain multiple Across variables, combined in a single variables block. This block is required.

Through variables are semantically distinct in that their values have to balance at a node: for each Through variable, the sum of all its values flowing into a branch point equals the sum of all its values flowing out. Therefore, a domain file must contain a separate declaration block for its Through variables, with the Balancing attribute set to true.

variables(Balancing = true) begins a Through variables definition block, which is terminated by an end key word. This block contains declarations for all the Through variables associated with the domain. A domain model class definition can contain multiple Through variables, combined in a single variables(Balancing = true) block. This block is required.

Each variable is defined as a value with unit:

domain_var1 = { value , 'unit' };

value is the initial value. unit is a valid unit string, defined in the unit registry. See Declare a Mechanical Rotational Domain for more information.

Declaring 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

You can also declare an internal component variable as a value with unit. You can use such internal variables in the setup and equation sections. Component variables are also used in the model initialization process, as described in Variable Priority for Model Initialization.

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.

    Note   For variables with temperature units, there is an additional consideration of whether to apply linear or affine conversion when the block user changes the unit in the Variables tab of the block dialog box. Use the Conversion attribute in the same way as for the block parameters. For details, see Specifying Parameter Units.

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 (i.e., Unused). 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 = { 0, 'm' };
end
function setup
  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.

Declaring Component Parameters

Component parameters let you specify adjustable parameters for the Simscape block generated from the component file. Parameters will appear in the block dialog box and can be modified when building and simulating a model.

You declare each parameter as a value with unit. Specifying an optional comment lets you control the parameter name in the block dialog box. For more information, see Specify Meaningful Names for the Block Parameters and Variables.

The following example declares parameter k, with a default value of 10 N*m/rad, specifying the spring rate of a rotational spring. In the block dialog box, this parameter will be named Spring rate.

parameters
    k = { 10, 'N*m/rad' };   % Spring rate
end

Specifying Parameter Units

When you declare a component parameter, use the units that make sense in the context of the block application. For example, if you model a solenoid, it is more convenient for the block user to input stroke in millimeters rather than in meters. When a parameter is used in the setup and equation sections, Simscape unit manager handles the conversions.

With temperature units, however, there is an additional issue of whether to apply linear or affine conversion (see Thermal Unit Conversions). Therefore, when you declare a parameter with temperature units, you can specify only nonaffine units (kelvin or rankine). When the block user enters the parameter value in affine units (Celsius or Fahrenheit), this value is automatically converted to the units specified in the parameter declaration. By default, affine conversion is applied. If a parameter specifies relative, rather than absolute, temperature (in other words, a change in temperature), set its Conversion attribute to relative (for details, see Member Attributes).

    Note   Member attributes apply to a whole declaration block. If some of your parameters are relative and others are absolute, declare them in separate blocks. You can have more than one declaration block of the same member type within a Simscape file.

Case Sensitivity

Simscape language is case-sensitive. This means that member names may differ only by case. However, Simulink® software is not case-sensitive. Simulink parameter names (that is, parameter names in a block dialog box) must be unique irrespective of case. Therefore, if you declare two parameters whose names differ only by case, such as

component MyComponent 
  parameters 
    A = 0; 
    a = 0; 
  end 
end 

you will not be able to generate a block from this component.

However, if one of the parameters is private or hidden, that is, does not appear in the block dialog box,

component MyComponent 
  parameters(Access=private) 
    A = 0; 
  end 
  parameters 
    a = 0; 
  end 
end 

then there is no conflict in the Simulink namespace and no problem generating the block from the component source.

Public component variables also appear in the block dialog box, on the Variables tab, because they are used for model initialization. These variables therefore compete with each other and with the block parameter names in the Simulink namespace. If a component has a public variable and a parameter whose names differ only by case, such as

component MyComponent 
  variables 
    A = 0; 
  end 
  parameters 
    a = 0; 
  end 
end 

you will not be able to generate a block from this component. As a possible workaround, you can declare the variable as private or hidden. In this case, the variable does not appear on the Variables tab of the resulting block dialog, and therefore there is no namespace conflict. However, if you want to be able to use the variable in the model initialization process, keep it public and change its name, or the name of the parameter.

The case-sensitivity restriction applies only to component parameters and public component variables, because other member types do not have an associated Simulink entity, and are therefore completely case-sensitive.

Declaring Domain Parameters

Similar to a component parameter, you declare each domain parameter as a value with unit. However, unlike component parameters, the main purpose of domain parameters is to propagate the same parameter value to all or some of the components connected to the domain. For more information, see Working with Domain Parameters.

Declaring Component Nodes

Component nodes define the conserving ports of a Simscape block generated from the component file. The type of the conserving port (electrical, mechanical rotational, and so on) is determined by the type of its parent domain. The domain defines which Through and Across variables the port can transfer. Conserving ports of Simscape blocks can be connected only to ports associated with the same domain. For more information, see Basic Principles of Modeling Physical Networks.

When declaring nodes in a component, you have to associate them with an existing domain. Once a node is associated with a domain, it:

  • Carries each of the domain Across variables as a measurable quantity

  • Writes a conserving equation for each of the domain Through variables

For more information, see Defining Relationship Between Component Variables and Nodes.

You need to refer to the domain name using the full path starting with the top package directory. For more information on packaging your Simscape files, see Generate Custom Block Libraries from Simscape Component Files.

The following example uses the syntax for the Simscape Foundation mechanical rotational domain:

nodes
    r = foundation.mechanical.rotational.rotational;
end

The name of the top-level package directory is +foundation. It contains a subpackage +mechanical, with a subpackage +rotational, which in turn contains the domain file rotational.ssc.

If you want to use your own customized rotational domain called rotational.ssc and located at the top level of your custom package directory +MechanicalElements, the syntax would be:

nodes
    r = MechanicalElements.rotational;
end

    Note   Components using your own customized rotational domain cannot be connected with the components using the Simscape Foundation mechanical rotational domain. Use your own customized domain definitions to build complete libraries of components to be connected to each other.

Specifying an optional comment lets you control the port label and location in the block icon. For more information, see Customize the Names and Locations of the Block Ports. In the following example, the electrical conserving port will be labelled + and will be located on the top side of the block icon.

nodes
    p = foundation.electrical.electrical; % +:top
end

Declaring Component Inputs and Outputs

In addition to conserving ports, Simscape blocks can contain Physical Signal input and output ports, directional ports that carry signals with associated units. These ports are defined in the inputs and outputs declaration blocks of a component file. Each input or output is defined as a value with unit, where value can be a scalar, vector, or matrix. For a vector or a matrix, all signals have the same unit.

Specifying an optional comment lets you control the port label and location in the block icon. For more information, see Customize the Names and Locations of the Block Ports.

The following example declares an input port s, with a default value of 1 Pa, specifying the control port of a hydraulic pressure source. In the block diagram, this port will be named Pressure and will be located on the top side of the block icon.

inputs
    s = { 1, 'Pa' };   % Pressure:top
end

The next example declares an output port v as a 3-by-3 matrix of linear velocities.

 outputs
   v = {zeros(3), 'm/s'}; 
 end

Declare a Mechanical Rotational Domain

The following file, named rotational.ssc, declares a mechanical rotational domain, with angular velocity as an Across variable and torque as a Through variable.

domain rotational
% Define the mechanical rotational domain
% in terms of across and through variables

  variables
    w = { 1 , 'rad/s' }; % angular velocity
  end

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

end

In a component, each node associated with this domain will:

  • Carry a measurable variable w (angular velocity)

  • Conserve variable t (torque)

For more information, see Defining Relationship Between Component Variables and Nodes.

Declare a Spring Component

The following diagram shows a network representation of a mass-spring-damper system, consisting of four components (mass, spring, damper, and reference) in a mechanical rotational domain.

The domain is declared in a file named rotational.ssc (see Declare a Mechanical Rotational Domain). The following file, named spring.ssc, declares a component called spring. The component contains:

  • Two rotational nodes, r and c (for rod and case, respectively)

  • Parameter k, with a default value of 10 N*m/rad, specifying the spring rate

  • Through and Across variables, torque t and angular velocity w, later to be related to the Through and Across variables of the rotational domain

  • Internal variable theta, with a default value of 0 rad, specifying relative angle, that is, deformation of the spring

component spring
  nodes
    r = foundation.mechanical.rotational.rotational;
    c = foundation.mechanical.rotational.rotational;
  end
  parameters
    k = { 10, 'N*m/rad' };   % spring rate
  end
  variables
    theta = { 0, 'rad' };    % introduce new variable for spring deformation
    t = { 0, 'N*m' };        % torque through
    w = { 0, 'rad/s' };      % velocity across
  end
  % setup here
  % branches here
  % equations here
end

    Note   This example shows only the declaration section of the spring component. For a complete file listing of a spring component, including the setup and equations, see Mechanical Component — Spring.

Was this topic helpful?