BondSimulation

When BondSim starts the main program window frame opens (see the figure below). It represents the modeling and simulation environment with the program title at the top, and a menu bar that lists the commands that can be used. There is also a toolbar with short-cut buttons of the often used commands.

The main window area is divided into four main parts. In the middle is a large central area where tabbed document windows are opened in which the models are developed. On the left are two tabbed windows containing Models view and Models library. The first serves to show the model structure of the current modeling project. The models library enables easy access to ready to use projects and component models.

On the right hand side we can see two other windows, which contain Editing and Template tool boxes. These boxes contain tools that are used for creation of the component models using drag and drop technique. Finally, at the bottom is an area which is used for displaying the messages that are sent during the model building, simulation runs or the program database repair.

The dialogue closes and a new empty project document appears in the central part of the frame. Its title is PROJECT: Body Spring Damper Problem. It is the project level document, and serves to define the basic (system) level model. The document window contains a rectangle that defines the document working area in which the model is created. It is bounded by a grey strip, which limits the area where the components may be placed.

The Bond Graph Component branch contains the Bond Graph components tools. The first one, the Component Model, is used to create the general component models in the form of the word models. The others are used for creating of the elementary components, which model the basic physical processes in the project or its components. The models are created by dragging the tool into the document window and dropping it there, but not too close to the grey border. 

The Ports branch contains the tools for inserting ports into the component boundary. The Power-in and Power-out port tools serve to create the power ports. They are created as half-arrows directed into and out of the component, thus indicating the positive sense of power transfer. Control-in and Control-out tools are used for the control ports, i.e. the ports that transfer the signals into or out of the components. The other two ports are more specific and are used when modeling the discrete-time processes. To insert a port its tool is dragged into the document window and dropped at the component boundary.

To edit the component titles default font are used (Arial). But, the different font sizes can be chosen. There are four sizes to choose from: Normal, Small, Medium and Large. The component titles can run horizontally from left to right, or vertically from down to up. Default text direction is the horizontal. However, we may change this by selecting Horizontal or Vertical type in Text Orientation branch of Edit Box.

Now we may construct the Wall component model. Thus, we put the mouse over the Component Model tool, press the left key and drag it to the project document window. As the mouse cursor enters the document area it changes its shape to the cross. We drop the tool near, but not too close to, the left gray border strip by releasing the key. The component is created only if it is completely off the gray strip. Now, a blinking vertical short line appears (the caret), indicating that we are in component title editing mode. Thus, we simply type the text “Wall” and the text starts running vertically up. We click somewhere outside the text to complete the component creation (see the figure on the left)

The component appears surrounded by a red bounding rectangle, which indicates that it is selected. The component already has two power ports at its boundary, a power-in and power-out ones. We note that the component icon also appears in the model three on the left of the document window. It is just beneath the project title. Before we continue editing we will click again to Horizontal in the Text Orientation branch to return to default horizontal running component titles.

In a similar way we create the other components: Spring, Damper and Body (see below). To define the force acting on the body we add elementary component SE (Source Effort) by dragging the corresponding tool and dropping it to the right of the Body.  When dropping it the text “SE” appears and the caret. We accept it as default title by clicking outside of the text. 

Now we have created all components the problem contains. We will rearrange the components and slightly change them. First, we drag Wall by its title and move it upwards near the top of the document. Because the spring and damper are connected to the right side of the wall, we put the mouse on the upper Wall's port and drag it around its boundary and drop it at the right top position; we drag also the bottom port and drop it at the right bottom position. In addition, we assume that spring and damper acts to the wall, and hence the power is transferred into the wall. Thus, we need to change the positive power sense of the bottom port. We can do it simply by clicking the port by mouse to select it, and then click the Change Port toolbar button (one with two opposite ports picture). The power port now is directed into the wall (see the figure below).

Next, we drag Spring upwards by its title until its left port is on the same level as the Wall upper port and drop it there. Similarly, we drag upwards Damper and drop it beneath the Spring. Similarly we did with Body. We also move the SE port from its right side to the left side by dragging it around the component boundary. We drag SE component then by its title and until its port is at the same level as the right Body port and drop it. Note that we can move the components or their ports also by the cursor keys, but have to select them first. Note also that the Body needs an additional power port for connection of the Damper. Thus, we insert the additional port by dragging the Power-out port tool from Ports branch in Editing Box and drop it within the Body component boundary. Note that, as we approach the Body it’s bounding box jumps out. We drop the tool at  bottom left position. The port is created and appears selected (see the figure above).

Now we interconnect the components by drawing the bonds between the corresponding ports. Thus, to connect the Wall upper-right port to the left Spring port we put mouse over the Wall port, press it, and drag the mouse (by holding the key pressed) towards the Spring and the bond line appears following the mouse cursor. When the cursor is over the corresponding Spring port, because it is of the correct sense, it becommes selected and we release the key to connect to it. Now, the bond appears in red (selected) and the power-out port merges with it. In similar ways we may connect the other components, i.e. Spring to Body, Damper to Wall, etc. 

When drawing a bond we may click to the intermediate points if we wish, e.g. to form a corner in the bond. Also, when the bond is drawn, it is possible to change its shape by dragging a point on the bond. As we drag it the bond changes its shape as an elastic strip that is fixed at its ends. We release it when we obtain the shape we wish.

Note, that all previous figures, but the last one, were generated by screen capture tool. The last one, however, was generated using Print to File command from Document menu. This command stores the current active document as graph in emf (Enhanced Metafile) file format. Such a file can be used for documenting (as we did here).

The model created thus far, however, is not complete; without the display components that collect and display data generated during the simulation it is really useless. BondSim has two such components: X-Y Display, which displays the input signals as X-T or X-Y plots, and Numerical Display, which displays the current value of the input signal.

The display components contain only the signal ports. Thus, their tools are inside Continuous Signal Components branch of Edit Box. We need to expand this branch first. It contains the other tools as well, such as input generator, function, integrator, nodes, etc. We drag X-Y Display tool and drop it below SE component. Similarly, we can drag the Numerical Display tool and drop it bellow X-Y Display (see the figure below). 

We wish to display the body position and its velocity during the simulation. Thus, we need to extract the corresponding signals from Body component and connect them to the displays. Thus, we have to create such ports first. Hence, we drag Control-out tool from Port branch in Editing Box and drop it at the bottom of Body. We repeat this operation and insert also one more control-out port to the right of it.  Thus, we have created two control-out ports to extract the body position and velocity signals. We will connect the left one (the position port) to both X-Y Display and Numerical Display ports, and the right one (the velocity port) to a X-Y Display port only. 

To branch the position signal we need to create a branching node first by dragging Node tool from Continuous Signal Components and drop it below the left bottom output port of Body. The Node has one input and two output ports. We will move the input port to the top position and drag the Node so that its top input port is straight bellow the Body left output port. Before we interconnect the signal ports we rearrange the bottom and left ports of X-Y Display so that they are tidily positioned on the left side of the display component. Now we may connect the Node input port to the left Body output port, and the node output ports to the input ports of X-Y Display and Numerical Display (see the figure above). Similarly, we connect the bottom right control port of Body to the upper left X-Y Display port. We may also to reshape the bond to look as in the figure above.

Thus, we have created the system level model of the problem in which all basic component models are created and are interconnected. Note that all components created so far also appears in the model tree on the left. The first four components are represented by icons in form of the empty pages, which indicate that it is necessary do define their models.  We will come to this shortly. The other components use the icons reserved for the elementary components, i.e. the components that represent the complete entities. We consider them next.

The SE (Source Effort) is used to define an external force applied to the body. The process that such elementary component describes is defined in its port. Thus, we will open the component port by double clicking it. We may open it also by selecting it (by clicking) and then applying Open Next command from Document menu, or clicking Open Component toolbar button. A SE port dialog opens as shown in the figure below.

A Define Parameter dialog opens as shown in the figure above on the right. We type 500.0 as the new value of the input force (in Newton; note the values of the physical parameters are in SI units). Now we accept the value by clicking OK in Define Parameter dialog, then OK in Edit Parameter dialog, and finally OK in SE Port dialog.

Next we define the symbols used to label the axes of X-Y Display. We can do it by clicking the input ports. Thus, if we click the position port (i.e. the lower one) an Output Port dialog opens as shown in the figure below. We define the variable name as ‘x’, and select Y axis. This means that variable will be plotted along the Y axis.

To complete the project model it is necessary to develop models of all components we have created. At their creation they are empty and are represented by theirs word models, i.e. the components defined by their names (titles) and the ports. We need to add their model document. We show it on the example of Body component. In the similar way we can do it for the other components.

The components in BondSim are the containers of their model documents. To open its document we simply double click the component title. In this case we double clisk "Body" title. We can do it by selecting it first (i.e. by clicking its title) and then by applying Open Next command in Document menu, or applying the shortcuts (Open Component toolbar, or pgup key). Because it is a new component its document does not exists and program asks if we wish to edit a new model of Body. If we agree a new tabbed document is created and shown in the central part of the frame next to the project document (see the Figure below).

It is similar to the project document we met earlier. It is empty, but contains on the outside of the document bounding rectangle the document ports. These ports are in the form of narrow rectangles with attached half-arrows and exactly correspond to the component ports. Thus, power is transferred from outside through the component ports and then out of the document ports into the component document. In the same way the power is transferred back from the inside thorough the document port and out of the component port. In this way the component and its document are two sides of the same coin.

To define the model of the body we insert the components, which constitute its model, into the document and connect them internally and to the document ports. To start with we insert 1 junction, which serves as the balance of forces acting on the body. It is also common velocity junction, i.e. its ports have the same flows - the body velocity. To create it we drag 1 junction tool from Bond Graph Components in Editing Box and drop it at the intersection of line connecting the left and right power ports and the vertical line through the bottom power port. We click outside of the component to retain its default title (‘1’). The component already has three power ports and we change their senses of the power transfer to correspond to that of the document ports (using Change Port toolbar button). Thus, the right one has to be the power-in port, and the left and bottom ports are the power-out. We connect then the ports of the junction to the document ports (see figure below on the left). 

The body has inertia. We, thus, insert an inertial component by dragging the corresponding tool and dropping it above the 1 junction. Again, we accept the default symbol (‘I’). The component has a single port on the left, and we drag it to face the 1 junction. To connect it to the junction we need to insert a power-out port at top of the 1 junction and connect it to the inertial component (see the figure below on the right). Thus, the input force acting on the body is equal to sum of body inertial force, and spring and damper forces. In Bond Graphs this is represented neatly.

Because we need to output information on the body velocity and its position, we will drag Control-out port tool and drop it at the lower-right corner of the 1 junction (see the figure below). This port extracts the body velocity. To branch this signal we insert a Node by dragging the corresponding tool from Continuous Signal Components and dropping it to the right and below of 1 junction. We connect the component input port to the output port of 1 junction. Its right output port we connect to the bottom right document output port. Thus, the body delivers its velocity to the right Body output port.

To generate the body position we need first to integrate the body velocity over time. To that end we drag and drop Integrator from Continuous Signal Components and drop it below the Node. We move the integrator input port from left to the top and the output port from the right to the bottom. We may need to move the Integrator so that its upper port lines up with the lower Node's port. Now we connect these two ports by a bond, and its lower port to the corresponding document output port. In this way we generated the Body position signal and deliver it to the output port.

At the lower-left part of the dialog window there are the blocks that define the port variables; they have predefined local names. These variables are used to define the constitutive relation at the top of the dialog. We may change these freely. Thus, we change the flow to v (for velocity), and the state variable to p (momentum). Now we modify the constitutive relation at the top too. It defines the body momentum p as product of body mass m and its velocity v. It uses I0 as the inertial parameter and we change it to m and flow to v. Note that the effort variable was already set as time derivative of the momentum (per Newton’s second law). Finally, we need to define the body mass as a new parameter. We did it similarly as we did with the force parameter in SE component earlier using Parameters button. We insert the new parameter m and define its value as 5.0 (kg). Close these dialogs.

Note also that in Inertial Port dialog there is also a field which defines the initial value of the body momentum. By default it is set to zero. We assume that the body starts from the rest and, thus, we accept this value. Now we close the dialog by OK button. The all changes we have made including the new parameter are stored in I component object in the memory.

We will apply similar operations to Integrator ( ∫ ) ports. First we will define the integrator’s input symbol. Thus, we double click the input port and in the dialog that opens we type-in v as the symbol of the body velocity (see the figure below on the left) and accept it by OK. Next, we double click the integrator’s output port (see Figure below on the right). We change the output variable name to x (for the position). The integrator constitutive relation is automatically set. Its initial value was already set to 0.0. We may accept this, which means that the body displacement is measured from its zero initial position. We close dialog by OK button.

To choose the proper button it is necessary to know how BondSim stores the projects. The project title that was created at beginning is stored in the project index (really a map, dictionary). Every project has a different name and corresponding files are stored in the corresponding BondSim program model directory in the corresponding file. The program generates the filenames automatically. We communicate with the program by the project name. The program locates the name in the project index, finds the corresponding filename and opens the project. These files, however, are not common files, but the special compounded files that have the structure of file system inside the file. They contain storages, which have roles of the directories, and streams which play the roles of the files.  

In the current implementation the project file has structure of the corresponding model tree. At the first level there is a storage, which corresponds to the project. It contains a stream that store the project document. Every component, which is not an elementary one, corresponds to the storage which contains a stream that store the component document. This document contains the other components, etc. In this way the structure of the project is stored in the same way in the storage medium (a disk) as in the memory. The elementary component, because they are rather simple, stores all data in the component object itself. When we close a document it is normally stored in its component. The stored document is not saved on the disk yet. We must store it down the model tree until the project document is reached and then the complete structure is saved to the disk. 

Thus, returning to the Save Dialog shown above, if we select Save button the dialog closes and the current document is stored in its component storage. If on other hand Save to all button is clicked the documents are stored down the model three until the project document is reached, and then the complete structure is saved to the disk in the corresponding file. We may also select Don’t save button, which means the rejecting of the changes made and closing the document. If we select Cancel button the document closing is rejected and the document stays open.

After all component models are defined we obtain the complete model of the project Body Spring Damper Problem as shown below. The changes made with respect to the previous model are seen in the model tree as well.  Now Wall, Spring, Damper and Body are represented by the storage icons, which serves as the branches of the model tree (see in the figure below on the left). 

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.

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.

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).

The model equations consist of a mixture of differential and algebraic equations. They are solved jointly during the simulation as a system of Differential Algebraic Equations (DAEs). In addition to the mathematical model equations, the box lists the differentiated variables, and the indexes of the purely algebraic equations. The next are the initial values of the variables and finally the parameters used by the model.

In addition to equations, the model contains the Jacobian matrices defined also in the symbolic (analytic) form (not shown). Using the matrices in the analytical form (and not as the numerical ones) adds much to robustness of the BondSim solver. The matrices are very sparse, containing on average less then tree elements per row. They are solved using default Sparse 1.4 solver. (It is a similar package as used in well-known the SPICE package in electronics.) There is also another, a more recent solver that can be selected at the start of the simulation (KLU). But in general, the Sparse solver works well.

Thus, the natural frequency of the system is about 24 Hz, hence the period is 1/24 ≈0.04 s. We can expect that the transients die out after about five periods, or 0.2 s. Thus, we use a slightly greater Simulation interval, e.g. 0.5 s, to be sure that the transient has settled down. We set the Output interval and Maximum stepsize to one hundredth of this value, i.e. to 0.005 s. The maximum step-size should not be greater than the output interval, but may be shorter. It is usually set to the same value as the output interval. We can choose a smaller value for the output interval if we wish to get better resolution and the smoother diagrams. This means, however, that there are more calculations and the simulation run needs more computer time and memory resources. The last parameter Output Delay in ms (milliseconds) is not used and might be left at the default value (0 ms). (It is used when BondSim simulation is used to drive 3D models in BondSim3DVisual.)

Default error tolerances are set to 10^-6 for both the absolute and the relative errors and we can accept them both. The integration method is the BDF (Backward Differentiation Formula) method with default sparse matrix linear equation solver (Sparse 1.4). We accept it. By the way there is only one solver that is used for all problems. Only some optional parameters may be changed, such as linear equation solver, error criteria, etc. 

When the simulation starts, the messages in the Output window, under the Run tab, inform the user on the simulation actions completed. Simultaneously, at the right end of the status bar, a progress bar appears. This shows the progress of the simulation. When the simulation finishes, the progress bar disappears and a message informs the user of this fact. If the simulation time is short, as is in this case, the progress bars shortly appears and disappears.

Note that in the central window there is a tabbed window containing the X-Y plot. We can activate this window by clicking its tab. However, before we do this we may select the variables we wish to be shown in the plot because they are of quite different ranges. To exclude e.g. the body velocity we double click the corresponding port (the top left one) and select None (see Editing Project, Output Port dialog). Now we may activate the plot document. The resulting plot is shown in the next figure. 

The plot shows the body position response to a step of the input force. Due to low damping in the system the body goes up and down several times until it finally settles at the position of about 4.5 mm. We can examine the values of the variable by clicking the curve. The horizontal and vertical lines appear which intersect on the curve. The corresponding time and variable values appear below the plot. The exact value can be easily evaluated as F/k = 0.00444...  m and compare with the shown value.

We can apply different operations on the generated plot by right-clicking on the plot. A drop-down menu appears from which different commands can be selected (see the figure below).

where F0 is the force amplitude and ω the circular frequency of the applied harmonic force.  We will analyze the system response under different force's frequencies. We start by setting frequency equal to the natural frequency of the system (evaluated in Running Simulations) ω = 150 rad/s. This corresponds to the resonance and we expect that the amplitudes of body vibrations (after the transients has died out) rise to a rather high value, much larger than the static one,

In order to find the response to such an input we double-click the SE port and type in the editing box (see Editing Project, Source Effort port dialog) F0*sin(w*t). The edit box accepts only ASCII characters, and thus, we use F0 for the amplitude of the driving force and instead of common symbol ω for the circular frequency we write “w”. We have to define the values of theses parameters. We do it in a similar way as we set parameters earlier. We click the Parameter button and in the Edit Parameters dialog windows that opens we type in the edit box at the top the symbol F0 and then click insert. In the dialog box that opens we type in the 500.0 as the value of the force amplitude (in N). We close the dialog by pressing OK button. Next, we type in w, insert it, and as the value we write 150.0; we close it again by OK button. Finally, we close Edit Parameter dialog by OK button, and Source Effort Port dialog also by OK. If we didn’t make errors in typing the new force constitutive relation is accepted and the program upgrades the built-in model and informs us on this.

Now we can repeat the simulation by pressing the Run command. We check the Restart button and as the simulation interval choose 1.0 s and set the output interval to 0.001 s for a better resolution. The results are shown in the figure below.

We see that the outputs now oscillate trying to follow the input. There is a transient in the amplitudes, which settle after about 0.3. The steady-state position amplitude has a large value, which is about five times of the static value found earlier.

We repeat the simulations using a much lower input frequency, e.g. w = 15 rad/s. Because the input frequency is now much lower we increase the simulation interval to e.g. 5s, retaining the other parameters values. The results are shown in the figure below on the left. Now we see that the body follows well the input force with the amplitude practically equal to the static value.

We repeat the simulation again by using this time much higher input frequency, e.g. w = 1500 rad/s. The results are shown in the figure below on the right. We see now that steady-state amplitude is very low (about 0.0444 mm), and thus the body cannot follows the input well. Because it is difficult to observe such a low value it appears as the body is not moving at all.

It contains four branches: Projects, Components, Electrical and Mechanical Components. In the figure above on the left the Project branch was expanded and there are the number of the projects from different branches of engineering. Similarly, the component branches contain the complete components models. 

To access a project we right-click on the project we are interested in as shown in the figure above on the right. A menu drops down showing several commands that we can use.

If we select Open command, the right-clicked project opens in the central parts of the frame as any other project. The only difference is that the library projects is in the read-only mode, and thus cannot be edited. We can walk freely along its model tree to overview it. When finished we close the root document (in the central window or in the model tree).

We may delete any project by Delete command. The project is not deleted right away, but is moved into Waste Bin (similarly to Windows Recycle Bin) from which it can be recovered back, or removed completely.

Finally, we can select Copy to the Workspace, which creates a copy of the project and store it into the model workspace. During this operation a complete new model tree is created as a clone of the original library project model tree. We can access this new project by Open command in the Project menu and edit it as we wish, or apply the other operations. 

There are three groups of the library components. The first are the components created in the standard component form, e.g.  2D and 3D multibody component models. There are also more specialized electrical and mechanical components. The component could be opened for overviewing or deleted by right clicking similarly as with the projects. We do not, however, can copy them into the workspace; instead the components can be dragged and dropped directly into the document window.  This is illustrated in the figure below in which the complete model of a diode is dragged and dropped into a document. This operation makes a clone of the library component and inserts it into the document at the selected place.