3. Specification of Hand Guided Tearing

There are two ways to use hand guided tearing in JModelica.org:

3.1. Paired Tearing

In some situations it is crucial that an equation and a variable form a tearing pair. This is where the hand guided tearing pair annotations comes into play. It allows the user to specify exactly which tearing pairs to form. The tearing pairs that are specified are torn before any automatic tearing comes into play. The pairs are also torn without any regard for solvability of the system. This means that if the user specifies to many pairs, they will all be used and the torn block becomes unnecessarily complex. If the final system is unsolvable after all pairs are torn, the automatic algorithm will kick in and finalize the tearing.

There are two ways to specify hand guided tearing pairs.

  • On component level

  • On system level

3.1.1. Specify Tearing Pairs on Component Level

Tearing pairs can be specified in the annotation for the equation that should become residual equation. This type of hand guided tearing is limited to the name scope that is visible from the equation. In other words, the equation has to be able to "see" the variable that should be used as iteration variable.

Syntax

It is possible to place annotations for tearing pairs in the annotation block for the residual equation. The syntax for tearing pair on component level has the following syntax:

"annotation" "("
  "__Modelon" "("
    ResidualEquation
  ")"
")"

Where ResidualEquation has the following format:

record ResidualEquation
  Boolean enabled = true;
  Real iterationVariable;
end ResidualEquation;
Example
model A
  ...
  Real z;
  ...
equation
  ...
  x = y + 1 annotation(__Modelon(ResidualEquation(iterationVariable=z)));
  ...
end A;

3.1.2. Specify Tearing Pairs on System Level

Tearing pairs on system level are necessary when the residual equation and iteration variable are located in different name scopes. In other words, the equation can not "see" the iteration variable.

Before it is possible to specify tearing pairs on system level it is necessary to define a way to identify equations.

Syntax

It is possible to place annotations for tearing pairs on system level in the annotation block for the class deceleration.

"annotation" "("
  "__Modelon" "("
    "tearingPairs" "=" "{" Pair* "}"
  ")"
")"

Where Pair has the following format:

record Pair
  Boolean enabled = true;
  Equation residualEquation;
  Real iterationVariable;
end Pair;
Example

Here follows an example where the equation is identified by a name tag and then paired with a variable.

model A
  model B
    ...
    x = y + 1 annotation(__Modelon(name=res));
    ...
  end B;
  model C
    ...
    Real z;
    ...
  end C;
  B b;
  C c;
  ...
  annotation(__Modelon(tearingPairs={Pair(residualEquation=b.res,iterationVariable=c.z)}));
end A;

3.2. Unpaired Tearing

It is also possible to specify that an equation or variable should be used in tearing without pairing. This is useful when there is no requirement that a certain equation is bound to a specific variable. The paring is instead done by the compiler during compilation. An error is given If the number of unpaired equations is unequal to the number of unpaired variables.

3.2.1. Specify an Equation as Unpaired Residual Equation

By marking an equation as unpaired residual equation it will be paired to an unpaired iteration variable during tearing.

Syntax

It is possible to place annotations for residual equations in the annotation block for an equation. The syntax for residual equation annotation has the following syntax:

"annotation" "("
  "__Modelon" "("
    ResidualEquation
  ")"
")"

Where ResidualEquation has the following format

record ResidualEquation
  Boolean enabled = true;
end ResidualEquation;

NOTE: This syntax has similar syntax as specifying tearing pairs on component level seeSection 3.1.1. - However the iterationVariable field is unspecified.

Example
x = y + 1 annotation(__Modelon(ResidualEquation));

3.2.2. Specify a Variable as Unpaired Iteration Variable

By marking a variable as unpaired iteration variable it will be paired to an unpaired residual equation during tearing.

Syntax

It is possible to place annotations for unpaired iteration variable in the annotation block for a variable. The iteration variable annotation has the following syntax:

"annotation" "("
  "__Modelon" "("
    IterationVariable
  ")"
")"

Where IterationVariable can be described as:

record IterationVariable
  Boolean enabled = true;
end IterationVariable;
Example
Real x annotation(__Modelon(IterationVariable));