Equations Section Purpose

The purpose of the equations section in a component file is to establish the mathematical relationships between the variables, parameters, inputs, and outputs of the component, the simulation time, and the time derivatives of each of these entities. The equations section of a Simscape™ file is executed throughout the simulation.

A Simscape language equation consists of two expressions connected with the == operator. Unlike the regular assignment operator (=), the == operator specifies continuous mathematical equality between the two expressions (for more information, see Specifying Mathematical Equality). The equation expressions may be constructed from any of the identifiers defined in the model declaration. You can also access global simulation time from the equation section using the time function.

For a list of MATLAB^® functions that you can use in the equation section, see Supported Functions.

Specifying Mathematical Equality

Simscape language stipulates semantically that all the equation expressions returned by the equation section of a Simscape file specify continuous mathematical equality between two expressions. Consider a simple example:

equations
   Expression1 == Expression2;
end

Here we have declared an equality between Expression1 and Expression2. The left- and right-hand side expressions are any valid MATLAB expressions (see the next section for restrictions on using the relational operators: ==, <, >, <=, >=, ~=, &&, ||). The equation expressions may be constructed from any of the identifiers defined in the model declaration.

The equation is defined with the == operator. This means that the equation does not represent assignment but rather a symmetric mathematical relationship between the left- and right-hand operands. Because == is symmetric, the left-hand operand is not restricted to just a variable. For example:

component MyComponent
  [...]
  variables
    a = 1;
    b = 1;
    c = 1;
  end
  equations
    a + b == c;
  end
end

The following example is mathematically equivalent to the previous example:

component MyComponent
  [...]
  variables
    a = 1;
    b = 1;
    c = 1;
  end
  equations
    0 == c - a - b;
  end
end

Use of Relational Operators in Equations

In the previous section we discussed how == is used to declare mathematical equalities. In MATLAB, however, == yields an expression like any other operator. For example:

(a == b) * c;

where a, b, and c represent scalar double values, is a legal MATLAB expression. This would mean, take the logical value generated by testing a’s equivalence to b, coerce this value to a double and multiply by c. If a is the same as b, then this expression will return c. Otherwise, it will return 0.

On the other hand, in MATLAB we can use == twice to build an expression:

a == b == c;

This expression is ambiguous, but MATLAB makes == and other relational operators left associative, so this expression is treated as:

(a == b) == c;

The subtle difference between (a == b) == c and a == (b == c) can be significant in MATLAB, but is even more significant in an equation. Because the use of == is significant in the Simscape language, and to avoid ambiguity, the following syntax:

component MyComponent
  [...]
  equations
    a == b == c;
  end
end

is illegal in the Simscape language. You must explicitly associate top-level occurrences of relational operators. Either

component MyComponent
  [...]
  equations
    (a == b) == c;
  end
end

or

component MyComponent
  [...]
  equations
    a == (b == c);
  end
end

are legal. In either case, the quantity in the parentheses is equated to the quantity on the other side of the equation.

With the exception of the top-level use of the == operator, == and other relational operators are left associative. For example:

component MyComponent
  [...]
  parameters
    a = 1;
    b = 1;
    c = false;
  end
  variables
    d = 1;
  end
  equations
    (a == b == c) == d;
  end
end

is legal and interpreted as:

component MyComponent
  [...]
  parameters
    a = 1;
    b = 1;
    c = false;
  end
  variables
    d = 1;
  end
  equations
    ((a == b) == c) == d;
  end
end

Equation Dimensionality

The expressions on either side of the == operator need not be scalar expressions. They must be either the same size or one must be scalar. For example:

equations
  [...]
  <3x3 Expression> == <3x3 Expression>;
  [...]
end

is legal and introduces 9 scalar equations. The equation expression:

equations
  [...]
  <1x1 Expression> == <3x3 Expression>;
  [...]
end

is also legal. Here, the left-hand side of the equation is expanded, via scalar expansion, into the same expression replicated into a 3x3 matrix. This equation expression also introduces 9 scalar equations.

However, the equation expression:

equations
  [...]
  <2x3 Expression> == <3x2 Expression>;
  [...]
end

is illegal because the sizes of the expressions on the left- and right-hand side are different.

Equation Continuity

The equation section is evaluated in continuous time. Some of the values that are accessible in the equation section are themselves piecewise continuous, that is, they change continuously in time. These values are:

Piecewise continuous indicates that values are continuous over compact time intervals but may change value at certain instances. The following values are continuous, but not time-varying:

Time-varying countable values, for example, integer or logical, are never continuous.

Continuity is propagated like a data type. It is propagated through continuous functions (see Supported Functions).

Working with Physical Units in Equations

In Simscape language, you declare members (such as parameters, variables, inputs, and outputs) as value with unit, and the equations automatically handle all unit conversions.

However, empirical formulae often employ noninteger exponents where the base is either unitless or in known units. When working with these types of formulae, convert the base to a unitless value using the value function and then reapply units if needed.

For example, the following formula gives the pressure drop, in Pa, in terms of flow rate, in m^3/s:

p == k * q^1.023 

where p is pressure, q is flow rate and k is some unitless constant. To write this formula in Simscape language, use:

p == { k * value(q, 'm^3/s')^1.023, 'Pa' } 

This approach works regardless of the actual units of p or q, as long as they are commensurate with pressure and volumetric flow rate, respectively. For example, the actual flow rate can be in gallons per minute, the equation will still work and handle the unit conversion automatically.