Building the Mathematical Model

Before we start a simulation run we have to build the mathematical model that will be repeatedly solved during the simulation. To that end open the project model first ( if it is not already opened) and assure that it is complete. We click then Build button on the toolbar, or select Build command from the Simulation menu.

During the build operation the complete model tree is traversed in the background several times. First the model is checked for the proper component connections and the system-wide variables are defined. These variables are used to generate the corresponding mathematical model. The all elementary components that model contains, i.e. the leaves of the model tree, are visited and corresponding relationships that define their models are parsed and translated to the suitable forms. Because the method used for solving the resulting model equations needs the matrices of partial derivatives they are also generated in the symbolic (not numeric) form using the built in computer algebra package.

The all model expressions are generated in a byte form. It is not human readable, but has one to one relationship to the common mathematical form. This is a form that enables efficient processing. At the start of the simulation run this form is further transformed (compiled) by Windows Framework into a machine form, which enables extremely efficient evaluation of the model expressions.

During the build operation the messages are generated, which show advancing of the build operation. They appear in the Output window at the bottom of the program screen (under Build tab). Typical messages shown during a successful build operation are shown below:

- Building the simulation model
- Creating model variables
- Compiling the model equations
- Creating the partial derivative matrices
- The build finished OK!

If during the build operation an error was encountered the build operation is stopped and the corresponding error message appears in the Output window. The component document where the error was detected opens in the central part of the program screen.

To illustrate a typical error behavior we open Body document and break the bond between 1 junction and the left document port and thus disconnect Body and Spring components.  We close the document then and save it to the project (disk). We click the Build tool button and the program asks if we would like to save the project to the disk first. We may reject this and the build operation continues. However, it is shortly stopped because an error was found and the corresponding messages are written in Output window (see the figure below). The program opens Spring document and selects the right 0 junction port where the error was found. The error message “Improper port connections!” refers to this port. We know that it is not connected further, but we can show this directly.

The error found during model build operation
Building the Mathematical ModelTo check the connection of this selected port we click the Joined Port toolbar button (or Show Joined command in View menu). The search starts from this port (because it is selected) and follows the connected bond trying to find the connected port. All connected ports and bonds are shown in blue. The search first reaches the right Spring document port, then goes out of the Spring and back into the project document in which the Spring is contained and activates this window. Next, it follows the bond and tries to enter Body. The search is stopped there because there is no inside connection to this port (see the Figure below). The document shows Spring enclosed in a box, which indicates that the component is open. The bond connecting it with Body is shown in blue color and in addition the connected to port is shown outlined. This indicates that the port is not connected inside the Body component.
Joint Port search
Building the Mathematical Model

We can apply the backward search by clicking the Body port shown at the end of the search. The search is repeated in the opposite direction and returns back to the starting window (Spring). This way we can walk back and forward as we wish. These operations apply also to the models having several levels of the connected components (i.e. the branches in the model tree). All traversed (and opened) components documents are shown as the stacked tabbed windows. We can remove the search links by clicking anywhere outside of it.

We can easily correct this error by reconnecting the bond we earlier broke!  Repeating the build operation we obtained the screen shown below. The messages at the bottom show that the build operation was successfully completed.

The correctly built project screen
Building the Mathematical Model

During the build operation every component that is not closed is going to be closed and we are asked eventually to save it. Only the project (root) document stays open. But, as can be seen in the figure above, a window labeled X-Y Plot is opened as well. However, it is not active one being overlapped by the root model window. When the simulation starts the program begins sending the data to these windows to ploted them. In the problem shown above these are the signals of the body velocity and position. We display these plots by activating their window (by clicking to its tab). Note that we cannot close the plot window. It disappears only when we close the project document window (by clicking x button in the title bar, or collapsing the project branch in the model tree).