equations

Define component or domain equations

Syntax

equations
   Expression1 == Expression2;
end

Description

equations begins the equation section in a component or domain file; this section is terminated by an end keyword.

In a component file, the purpose of the equations section is to establish the mathematical relationships among a component’s variables, parameters, inputs, outputs, time and the time derivatives of each of these entities. All members declared in the component are available by their name in the equation section.

Similarly, the equations section in a domain file serves to establish the mathematical relationships between the domain Across variables, parameters, and intermediates. Use the domain equations when your custom domain has more Across variables than Through variables. For more information, see Domain Equations.

The equation section of a Simscape™ file is executed throughout the simulation. You can also specify equations that are executed during model initialization only, by using the (Initial=true) attribute. For more information, see Initial Equations.

The following syntax defines a simple equation.

equations
   Expression1 == Expression2;
end

The statement Expression1 == Expression2 is an equation statement. It specifies continuous mathematical equality between two objects of class Expression. An Expression is a valid MATLAB^® expression. Expression may be constructed from any of the identifiers defined in the model declaration.

The equation section may contain multiple equation statements. You can also specify conditional equations by using if statements as follows:

equations
   if Expression 
       EquationList 
   { elseif Expression 
       EquationList } 
   else 
       EquationList 
   end
end

Note

The total number of equation expressions, their dimensionality, and their order must be the same for every branch of the if-elseif-else statement.

You can declare intermediate terms in the intermediates section of a component or domain file and then use these terms in any equations section in the same component file, in an enclosing composite component, or in a component that has nodes of that domain type.

You can also define intermediate terms directly in equations by using let statements as follows:

equations
   let 
      declaration clause
   in 
      expression clause 
   end 
end

The declaration clause assigns an identifier, or set of identifiers, on the left-hand side of the equal sign (=) to an equation expression on the right-hand side of the equal sign:

  LetValue = EquationExpression

The expression clause defines the scope of the substitution. It starts with the keyword in, and may contain one or more equation expressions. All the expressions assigned to the identifiers in the declaration clause are substituted into the equations in the expression clause during parsing.

Note

The end keyword is required at the end of a let-in-end statement.

The following rules apply to the equation section:

• EquationList is one or more objects of class EquationExpression, separated by a comma, semicolon, or newline.

• EquationExpression can be one of:

  • Expression

  • Conditional expression (if-elseif-else statement)

  • Let expression (let-in-end statement)

• Expression is any valid MATLAB expression. It may be formed with the following operators:

  • Arithmetic

  • Relational (with restrictions, see Use of Relational Operators in Equations)

  • Logical

  • Primitive Math

  • Indexing

  • Concatenation

• In the equation section, Expression may not be formed with the following operators:

  • Matrix Inversion

  • MATLAB functions not listed in Supported Functions

• The colon operator may take only constants or end as its operands.

• All members of the component are accessible in the equation section, but none are writable.

Supported Functions

The following MATLAB functions can be used in the equation section. The table contains additional restrictions that pertain only to the equation section. It also indicates whether a function is discontinuous. If the function is discontinuous, it introduces a zero-crossing when used with one or more continuous operands.

All arguments that specify size or dimension must be unitless constants or unitless compile-time parameters. For array operations, two operands must be of the same size, or one must be a scalar.

Supported Functions

Name	Restrictions	Discontinuous
ones
zeros
cat
horzcat
vertcat
length
ndims
numel
size
isempty
isequal		Possibly, if arguments are real and have the same size and commensurate units
isinf		Yes
isfinite		Yes
isnan		Yes
plus
uplus
minus
uminus
mtimes
times
mpower
power
mldivide	First argument must be a scalar
mrdivide	Second argument must be a scalar
ldivide
rdivide
mod		Yes
sum
cumsum	direction and nanflag arguments are not supported
movsum	nanflag and Name,Valuearguments are not supported
prod
floor		Yes
ceil		Yes
fix		Yes
round		Yes
eq	Do not use with continuous variables
ne	Do not use with continuous variables
lt
gt
le
ge
and		Yes
or		Yes
logical		Yes
sin
cos
tan
asin
acos
atan
atan2		Yes
log
log10
sinh
cosh
tanh
exp	Limiting applied during initialization and simulation to avoid nonfinite (Inf or NaN) values. Limiting is not applied when exp is used as an argument inside functions such as isinf, isnan, or isfinite, to ensure the correct predicate evaluation.
sqrt
abs		Yes
sign		Yes
any		Yes
all		Yes
min		Yes
max		Yes
double
int32		Yes
uint32		Yes
erf
erfc
repmat
reshape	Expanded empty dimension is not supported
dot
cross
diff	In the two argument overload, the upper bound on the second argument is 4, due to a Simscape limitation

Initial Equations

The (Initial=true) attribute lets you specify equations that are executed during model initialization only:

equations (Initial=true)
   Expression1 == Expression2;
end

The default value of the Initial attribute for equations is false, therefore you can omit this attribute when declaring regular equations.

For more information on when and how to specify initial equations, see Initial Equations.

Examples

For a component where x and y are declared as 1x1 variables, specify an equation of the form y = x²:

equations
  y == x^2;
end

For the same component, specify the following piecewise equation:

$$y=\{\begin{array}{ll}x\hfill & \text{for }-1<=x<=1\hfill \\ x^2\hfill & \text{otherwise }\hfill \end{array}$$

This equation, written in the Simscape language, would look like:

equations
  if x >= -1 && x <= 1
    y == x;
  else
    y == x^2;
  end
end

If a function has multiple return values, use it in a let statement to access its values. For example:

equations
  let 
    [m, i] = min(a);
  in
    x == m;
    y == i;
  end
end

Version History

Introduced in R2009a

R2023a: Domain equations

Domain equation have been introduced in R2023a. In previous releases, the equations section was allowed only in a component file.