Enumerations

Enumerations in Simscape Language

Simscape™ language supports MATLAB^® enumerations in:

Component parameters
Event variables and when clauses
Equation predicates
Conditional declaration predicates
Function arguments (such as an interpolation method in tablelookup)
Mode charts

You define enumerations using a MATLAB enumeration class. For more information, see Enumerations.

The enumeration class must derive from the int32 type, for example:

classdef offon < int32
   enumeration
     off (0)
     on (1)
   end
end

Save the enumeration class definition in a .m file with the same name as the class. For more information, see Rules and Restrictions.

You can then use this enumeration in a component parameter:

parameters
   fl_c = offon.off; % Fluid compressibility
end

In the resulting block dialog, the Fluid compressibility parameter will have a drop-down list of values, off and on, with off as the default.

Specifying Display Strings for Enumeration Members

When using enumerations in component parameters, you can specify user-friendly strings to be displayed in the block dialog, instead of member identifiers:

classdef damping < int32
   enumeration
     direct (0)
     derived (1)
   end
   methods(Static)
       function map = displayText()
         map = containers.Map;
         map('direct') = 'By damping value';
         map('derived') = 'By no-load current';
       end
   end
end

You can then use this enumeration in a component parameter, for example:

parameters
   r_damp = damping.direct; % Rotor damping parameterization
end

In the resulting block dialog, the Rotor damping parameterization parameter has a drop-down list of values:

By damping value
By no-load current

By damping value is the default value.

For a detailed example of using enumeration with display strings in a component parameter, see Use Advanced Techniques to Customize Block Display.

Evaluating Enumeration Members

If an enumeration class derives from a built-in numeric class, the subclass inherits ordering and arithmetic operations that you can apply to the enumerated names. Enumeration classes used in Simscape language must derive from the int32 type. Therefore, when used in mathematical expressions, enumeration members convert to integers according to the specified value. For example, the Switch with Hysteresis component uses this enumeration:

classdef switching < int32
   enumeration
     open (0)
     closed (1)
   end
   methods(Static)
       function map = displayText()
         map = containers.Map;
         map('open') = 'Switch is open';
         map('closed') = 'Switch is closed';
       end
   end
 end

The enumeration is used in the Initial Mode parameter declaration:

parameters
    ...
    InitMode = switching.open;    % Initial Mode
end

Then, the initial section of the mode chart uses the Initial Mode parameter value in the predicate expression:

initial
   OPEN : InitMode <= 0;
end

When the Initial Mode parameter value is Switch is open, the corresponding enumeration member, open (0), evaluates to 0, and the predicate is true. Therefore, at the start of simulation the switch is open.

Conversely, when the parameter value is Switch is closed, the corresponding enumeration member, closed (1), evaluates to 1, and the predicate is false. For more information, see Switch with Hysteresis.

Using Enumeration in Event Variables and `when` Clauses

The previous sections discussed using enumerations to declare component parameters with a discrete set of acceptable values. However, you can also use enumerations to declare event variables, because they also have a discrete set of values.

Event variables are piecewise constant, that is, they change values only at event instants (by using the when clause), and keep their values constant between events.

For example:

variables (Event = true)
   x = myEnum.a;
end
events
   when edge(time > {1.0, 's'})
     x = myEnum.b;
   end
end

Using Enumeration in Predicates

The Switch with Hysteresis component shows an example of using an enumerated parameter in a mode chart predicate.

Another good practice is using enumerated parameters in conditional declaration predicates, to define block variants. For example, you can have two variants of a pipe, one that accounts for resistive properties only and the second that also models fluid compressibility:

component MyPipe
  parameters
     fl_c = offon.off; % Fluid compressibility
  end
  [...] % other parameters, variables, branches
  if fl_c == offon.off
    equations
       % first set of equations, resistive properties only 
    end
  else
    variables
       % additional variable declarations, needed to account for fluid compressibility 
    end
    equations
       % second set of equations, including fluid compressibility 
    end
  end
end

In this example, the block parameter Fluid compressibility is using the offon enumeration:

classdef offon < int32
   enumeration
     off (0)
     on (1)
   end
end

In the resulting block dialog, the Fluid compressibility parameter has a drop-down list of values, off and on, with off as the default. If the parameter is set to off, the first set of equations gets activated and the block models only the resistive properties of the pipe. If the block user changes the value of the parameter, then the else branch gets activated, and the compiled model includes the additional variables and equations that account for fluid compressibility. For more information on defining block variants, see Defining Component Variants.

Likewise, you can use enumerated parameters and event variables in equation predicates:

parameters
   p = myEnum.a;
end
variables
   x = 0;
   y = 0;
end
equations
   if p == myEnum.a 
     y == x * 100;
   elseif p == myEnum.b
     y == x * 0.01;
   else 	% (p == myEnum.c)
     y == x;
   end
end

Using Enumeration in Function Arguments

Another way to use enumerations is in function arguments. For example, the tablelookup function has two interpolation methods, linear and smooth, and three extrapolation methods, linear, nearest, and error.

The Foundation library includes built-in enumerations, interpolation.m and extrapolation.m:

classdef interpolation < int32
   enumeration
       linear (1)
       smooth (2)
   end
   methods(Static)
    function map = displayText()
      map = containers.Map;
      map('linear') = 'Linear';
      map('smooth') = 'Smooth';
    end
  end
end

classdef extrapolation < int32
   enumeration
       linear (1)
       nearest (2)
       error (3)
   end
   methods(Static)
    function map = displayText()
      map = containers.Map;
      map('linear') = 'Linear';
      map('nearest') = 'Nearest';
      map('error') = 'Error';
    end
  end
end

These enumerations are located in the folder matlabroot\toolbox\physmod\simscape\library\m\+simscape\+enum.

You can use these enumerations to declare component parameters, and then use these parameters as function arguments:

parameters
    interp = simscape.enum.interpolation.linear; % Interpolation method
    extrap = simscape.enum.extrapolation.linear; % Extrapolation method
end
equations
    o == tablelookup(xd, yd, x, interpolation = interp_method, extrapolation = extrap_method);
end

Instead of providing fully qualified names, you can use the import statement to reduce the amount of typing:

import simscape.enum.*
...
parameters
    interp = interpolation.linear; % Interpolation method
    extrap = extrapolation.linear; % Extrapolation method
end
equations
    o == tablelookup(xd, yd, x, interpolation = interp, extrapolation = extrap);
end

Rules and Restrictions

Enumeration definitions are global. You define an enumeration once, in a separate file, and can then use the same enumeration in multiple components.

The file containing the enumeration class definition must reside on the MATLAB path or in a namespace folder. For more information about namespace folders, see Organizing Your Simscape Files.

Parameters that have enumerated values are marked as Compile-time only in the block dialogs.

Similar to MATLAB enumerations, you can define more than one identifier for the same integer value, for example:

classdef myColor < int32
   enumeration
     red (0)
     blue (1)
     yellow (2)
     green (0)
   end
 end

The first identifier in the enumeration block with a given integer value is the actual identifier, and subsequent identifiers are aliases.

Note

Although multiple identifiers with the same integer value are allowed, it is recommended that you use unique integer values within a Simscape language enumeration set, for better clarity.