Domain Equations

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. Similarly, the equations section in a domain file serves to establish the mathematical relationships between the domain Across variables, parameters, and intermediates. Domain equations propagate to the nodes of the corresponding domain type. Like the regular component equations, domain equations are executed throughout the simulation. You can also specify initial domain equations, similar to the initial component equations, to be executed during model initialization only.

When to Use Domain Equations

Use the domain equations when your custom domain has more Across variables than Through variables.

Generally, a domain declaration has an equal number of Through and Across variables. If you want to introduce additional Across variables, you need to establish the mathematical relationship between these variables, to avoid modeling errors. For example, consider a mechanical translational domain where the Through variable is force, and the Across variables are velocity and position:

domain myDomain
  variables
    x = { 0, 'm' }
    v = { 0, 'm/s' };
  end
  variables(Balancing=true)
    f = { 0, 'N' };
  end
  equations
    der(x) == v;
  end
  [...]
end

Here, the equations section contains one equation that establishes the mathematical relationship between the position and velocity. There is a differential relationship between the two domain variables, and therefore you need a domain equation to keep the number of differential equations the same as the number of differential variables.

If the relationship between the domain variables is purely algebraic, and if it can be written explicitly, use an intermediate instead of declaring an extra Across variable and using a domain equation:

domain myDomain
  variables
    x1 = ...
  end
  variables(Balancing=true)
    y = ...
  end
  intermediates
    x2 = f(x1);
  end
  [...]
end

However, if an algebraic relationship between domain variables cannot be written explicitly, use a domain equation:

domain myDomain
  variables
    x1 = ...
    x2 = ...
  end
  variables(Balancing=true)
    y = ...
  end
  equations
    f(x1,x2) == 0;
  end
  [...]
end

Use this formula to calculate the number of domain equations:

$n u m_d o m_e q n s = n u m_a c r o s s - n u m_t h r o u g h,$

where:

num_dom_eqns — Number of domain equations.
num_across — Number of Across variables.
num_through — Number of Through variables.

When compiling a model with domain equations:

The solver applies the domain equations once per connection point between the nodes of the appropriate type.
Connections to reference nodes do not need additional equations because at a reference node, all the Across variables are set to 0. Therefore, the solver does not apply domain equations at these connection points.
If you specify initial domain equations, they are applied according to the same rules.

Syntax Rules

Domain equations can refer to:

Domain Across variables.
Domain parameters.
Domain intermediates.

The syntax of regular domain equations is the same as that of the regular component equations. In particular:

You can use der, delay, and integ operators.
You can use if-else and let expressions.
You can use the same functions as in the component equations, including MATLAB^® functions and Simscape™ functions.
You can use assert statements. Use these assertions to validate domain parameters or to safeguard against the nonphysical values, for example, to check that the pressure and temperature in a fluid domain are above zero. For more information, see Programming Run-Time Errors and Warnings.
When you use assert constructs in domain equations, their predicate conditions are checked once at each connection point between the nodes of the appropriate type. If the connection point includes an implicit reference, asserts do not apply because an implicit reference sets all the Across variables to zero and there is no need to check their values.

You can use the (Initial=true) attribute to specify additional domain equations that are executed during model initialization only. In this case, the syntax rules and restrictions are the same as for the initial component equations. For more information, see Initial Equations.

Example of a Custom Domain with Equations

The Rope Pull In the Position-Based Translational Domain example shows a force pulling on the end of a rope that has a large load on its other end. When the force increases from 0 N to 1,000 N, it excites longitudinal vibrations in the rope.

This example uses a custom mechanical translational domain, where the Through variable is force and the Across variables are velocity, v, and position, x. The domain file contains an equations section that relates the Across variables because the domain has more Across variables than Through variables. The equation establishes the differential relationship between the Across variables, der(x) = v.

Open the model in the example to view the underlying source code and to plot the relative positions of the model elements.