Documentation |
The equation section of a Simscape™ file follows the declaration, setup, and structure sections. It is executed throughout the simulation. The purpose of the equation 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.
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.
This example shows implementation for a simple algebraic system:
y = x^{2}
x = 2y + 1
The Simscape file looks as follows:
component MyAlgebraicSystem variables x = 0; y = 0; end equations y == x^2; % y = x^2 x == 2 * y + 1; % x = 2 * y + 1 end end
You can access global simulation time from the equation section using the time function. time returns the simulation time in seconds.
The following example illustrates y = sin (ωt), where t is simulation time:
component parameters w = { 1, ‘1/s' } % omega end outputs y = 0; end equations y == sin( w * time ); end end
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
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
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.
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:
variables
inputs
outputs
time
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:
parameters
constants
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).
You can specify conditional equations by using if statements.
equations [...] if Expression [...] elseif Expression [...] else [...] end [...] end
Each [...] section may contain one or more equation expressions.
You can nest if statements, for example:
equations [...] if Expression [...] if Expression [...] else [...] end else [...] end [...] end
Every if requires an else.
The total number of equation expressions, their dimensionality, and their order must be the same for every branch of the if-elseif-else statement. However, this rule does not apply to the assert expressions, because they are not included in the expression count for the branch.
Every branch of the if-elseif-else statement must define the same variable in terms of others. For example, you can design a hydraulic orifice with if-else branches for turbulent and laminar flow, where each branch defines flow rate in terms of pressure. However, a conditional expression similar to the following
if x > 0 i == 0; else v == 0; end
is forbidden.
For a component where x and y are declared as 1x1 variables, specify the following piecewise equation:
$$y=\{\begin{array}{ll}x\hfill & \text{for}-1=\text{}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
Another way to write this equation in the Simscape language is:
equations y == if x>=-1 && x<=1, x else x^2 end end
Textbooks often define certain equation terms in separate equations, and then substitute these intermediate equations into the main one. For example, for fully developed flow in ducts, the Darcy friction factor can be used to compute pressure loss:
$$P=\frac{f\xb7L\xb7\rho \xb7{V}^{2}}{2D}$$
where P is pressure, f is the Darcy friction factor, L is length, ρ is density, V is flow velocity, and D is hydraulic area.
These terms are further defined by:
$$f=\frac{0.316}{{\mathrm{Re}}^{1/4}}$$
$$\mathrm{Re}=\frac{D\xb7V}{\nu}$$
$$D=\sqrt{\frac{4A}{\pi}}$$
$$V=\frac{q}{A}$$
where Re is the Reynolds number, A is the area, q is volumetric flow rate, and ν is the kinematic viscosity.
In Simscape language, you can define intermediate terms and use them in one or more equations by using the let expressions. The following example shows the same equations written out in Simscape language:
component MyComponent [...] parameters L = { 1, 'm' }; % length rho = { 1e3, 'kg/m^3' }; % density nu = { 1e-6, 'm^2/s' }; % kinematic viscosity end variables p = { 0, 'Pa' }; % pressure q = { 0, 'm^3/s' }; % volumetric flow rate A = { 0, 'm^2' }; % area end equations let f = 0.316 / Re_d^0.25; % Darcy friction factor Re_d = D_h * V / nu; % Reynolds number D_h = sqrt( 4.0 * A / pi ); % hydraulic area V = q / A; % flow velocity in p == f * L * rho * V^2 / (2 * D_h); % final equation end end end
After substitution of all intermediate terms, the final equation becomes:
p==0.316/(sqrt(4.0 * A / pi) * q / A / nu)^0.25 * L * rho * (q / A)^2 / (2 * sqrt(4.0 * A / pi));
A let expression consists of two clauses, the declaration clause and the expression clause.
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.
Here is a simple example:
component MyComponent [...] variables x = 0; y = 0; end equations let z = y + 1; in x == z; end end end
In this example, the declaration clause of the let expression sets the value of the identifier z to be the expression y + 1. Thus, substituting y + 1 for z in the expression clause in the let statement, the code above is equivalent to:
component MyComponent [...] variables x = 0; y = 0; end equations x == y + 1; end end end
There may be multiple declarations in the declaration clause. These declarations are order independent. The identifiers declared in one declaration may be referred to by the expressions for identifiers in other declarations in the same declaration clause. Thus, in the code example shown in the previous section, the identifier Re_d (Reynolds number) is used in the expression declaring the identifier f (Darcy friction factor). The only requirement is that the expression references are acyclic.
The expression clause of a let expression defines the scope of the substitution for the declaration clause. Other equations, that do not require these substitutions, may appear in the equation section outside of the expression clause. In the following example, the equation section contains the equation expression c == b + 2 outside the scope of the let expression before it.
component MyComponent [...] variables a = 0; b = 0; c = 0; end equations let x = a + 1; in b == x; end c == b + 2; end end
These expressions are treated as peers. They are order independent, so this example is equivalent to
component MyComponent [...] variables a = 0; b = 0; c = 0; end equations c == b + 2; let x = a + 1; in b == x; end end end
and, after the substitution, to
component MyComponent [...] variables a = 0; b = 0; c = 0; end equations b == a + 1; c == b + 2; end end
You can nest let expressions, for example:
component MyComponent [...] variables a = 0; b = 0; c = 0; end equations let w = a + 1; in let z = w + 1; in b == z; c == w; end end end end
In case of nesting, substitutions are performed based on both of the declaration clauses. After the substitutions, the code above becomes:
component MyComponent [...] variables a = 0; b = 0; c = 0; end equations b == a + 1 + 1; c == a + 1; end end
The innermost declarations take precedence. The following example illustrates a nested let expression where the inner declaration clause overrides the value declared in the outer one:
component MyComponent [...] variables a = 0; b = 0; end equations let w = a + 1; in let w = a + 2; in b == w; end end end end
Performing substitution on this example yields:
component MyComponent [...] variables a = 0; b = 0; end equations b == a + 2; end end
You can use if statements within both declarative and expression clause of let expressions, for example:
component MyComponent [...] variables a = 0; b = 0; c = 0; end equations let x = if a < 0, a else b end; in c == x; end end end
Here x is declared as the conditional expression based on a < 0. Performing substitution on this example yields:
component MyComponent [...] variables a = 0; b = 0; c = 0; end equations c == if a < 0, a else b end; end end
The next example illustrates how you can use let expressions within conditional expressions. The two let expressions on either side of the conditional expression are independent:
component MyComponent [...] variables a = 0; b = 0; c = 0; end equations if a < 0 let z = b + 1; in c == z; end else let z = b + 2; in c == z; end end end end
This code is equivalent to:
component MyComponent [...] variables a = 0; b = 0; c = 0; end equations if a < 0 c == b + 1; else c == b + 2; end end end
This example shows using an identifier list, rather that a single identifier, in the declarative clause of a let expression:
component MyComponent [...] variables a = 0; b = 0; c = 0; d = 0; end equations let [x, y] = if a < 0, a; -a else -b; b end; in c == x; d == y; end end end
Here x and y are declared as the conditional expression based on a < 0. Notice that each side of the if statement defines a list of two expressions. A first semantic translation of this example separates the if statement into
if a < 0, a; -a else -b; b end => { if a < 0, a else -b end; if a < 0, -a else b end }
then the second semantic translation becomes
[x, y] = { if a < 0, a else -b end; if a < 0, -a else b end } => x = if a < 0, a else -b end; y = if a < 0, -a else b end;
and the final substitution on this example yields:
component MyComponent [...] variables a = 0; b = 0; c = 0; d = 0; end equations c == if a < 0, a else -b end; d == if a < 0, -a else b end; end end
You can use the tablelookup function in the equations section of the Simscape file to interpolate input values based on a set of data points in a one-dimensional or two-dimensional table. This functionality is similar to that of the Simulink^{®} and Simscape Lookup Table blocks. It allows you to incorporate table-driven modeling directly in your custom block, without the need of connecting an external Lookup Table block to your model.
The following example implements mapping temperature to pressure using a one-dimensional lookup table.
component TtoP inputs u = {0, 'K'}; % temperature end outputs y = {0, 'Pa'}; % pressure end parameters (Size=variable) xd = {[100 200 300 400] 'K'}; yd = {[1e5 2e5 3e5 4e5] 'Pa'}; end equations y == tablelookup(xd, yd, u, interpolation=linear, extrapolation=nearest); end end
xd and yd are declared as variable-size parameters with units. This enables the block users to provide their own data sets when the component is converted to a custom block, and also to select commensurate units from the drop-downs in the custom block dialog box. The next illustration shows the dialog box of the custom block generated from this component.
Note Currently, you can not use variable-size parameters in the equations section outside of the tablelookup function. To avoid repeating the same variable-size parameter declarations in each component that needs to use them in its tablelookup function, you can declare variable-size domain parameters and propagate them to components for interpolation purposes. For more information, see Propagation of Domain Parameters. |
The following rules apply to the one-dimensional arrays xd and yd:
The two arrays must be of the same size.
For cubic or spline interpolation, each array must contain at least three values. For linear interpolation, two values are sufficient.
The xd values must be strictly monotonic, either increasing or decreasing.
If these rules are violated by... | You get an error... |
---|---|
The block author, in the component Simscape file | At build time, when running ssc_build to convert the component to a custom block |
The block user, when entering values in the block dialog box | At simulation time, when attempting to simulate the model containing the custom block |
The TtoP component uses linear interpolation for values within the table range, but outputs the nearest value of yd for out-of-range input values. The following illustration shows a block diagram, where the custom TtoP block is used with a linear input signal changing from 0 to 1000, and the resulting output.
See the tablelookup reference page for syntax specifics and more examples.
Use the assert construct to implement run-time error and warning messages for a custom block. In the component file, you specify the condition to be evaluated, as well as the error message to be output if this condition is violated. When the custom block based on this component file is used in a model, it will output this message if the condition is violated during simulation. The Warn attribute of the assert construct specifies whether simulation stops when the predicate condition is violated, or continues with a warning.
The following component file implements a variable resistor, where input physical signal R supplies the resistance value. The assert construct checks that this input signal is greater than or equal to zero:
component MyVariableResistor % Variable Resistor % Models a linear variable resistor. The relationship between voltage V % and current I is V=I*R where R is the numerical value presented at the % physical signal port R. If this signal becomes negative, simulation % errors out. % inputs R = { 0.0, 'Ohm' }; end nodes p = foundation.electrical.electrical; % +:left n = foundation.electrical.electrical; % -:right end variables i = { 0, 'A' }; v = { 0, 'V' }; end branches i : p.i -> n.i; end equations assert( R >= 0, 'Negative resistance is not modeled' ); v == p.v - n.v; v == i*R; end end
If a model contains this Variable Resistor block, and signal R becomes negative during simulation, then simulation stops and the Simulation Diagnostics window opens with a message similar to the following:
At time 3.200000, an assertion is triggered. Negative resistance is not modeled. The assertion comes from: Block path: dc_motor1/Variable Resistor Assert location: between line: 29, column: 14 and line: 29, column: 18 in file: C:/Work/libraries/+MySimscapeLibrary/+ElectricalElements/MyVariableResistor.ssc
The error message contains the following information:
Simulation time when the assertion got triggered
The message string (in this example, Negative resistance is not modeled)
An active link to the block that triggered the assertion. Click the Block path link to highlight the block in the model diagram.
An active link to the assert location in the component source file. Click the Assert location link to open the Simscape source file of the component, with the cursor at the start of violated predicate condition. For Simscape protected files, the Assert location information is omitted from the error message.
See the assert reference page for syntax specifics and more examples.
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.