How to use?

Modeling and Simulation Environment

The BondSim can be freely downloaded from this web site and installed on your computer. It supports the Windows operating systems - Windows 7, 8.1, 10. After installing the BondSim can be started by double-clicking its shortcut icon on the desktop. It can be also started by clicking the Start button on the taskbar (and All Programs in Window 7). In the start menu that opens, we expand BondSim folder and click the shortcut icon of the installed application. It is also possible to pin BondSim to taskbar by right-clicking the shortcut on the desktop and from the dropped down menu selecting Pin to taskbar command. We may then start BondSim simply by clicking the taskbar icon.

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.

BondSim main frame
Modeling and Simulation Environment

Get Started

To start a modeling session we define first a corresponding project. This can be a new one or an already existing project. The Project menu contains commands for operations on the projects. To illustrate the general modeling technique consider a simple mechanical systems consisting of a body of mass m, which is connected by a spring of stiffness k and damper with linear friction constant b, to a vertical wall (see below). The body can move along the horizontal floor under the action of an external force F.

Simple mechanical system 
Get StartedWe start by creating a new modeling project and select New command in Project menu, or click the New Project toolbar button. The Create New Project dialog opens as shown below. It contains a text box, which serves to define a new project name, and the list box showing already existing projects. We have to type a name that is different of already existing project names, e.g. “Body Spring Damper Problem” (without the quotation marks of course) and click OK button. We can reject the operation by clicking Cancel button.
Create New Project dialog
Get Started

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 screen with opened a new project

Get StartedThe menu now changes and shows the commands that can be applied to the project. If we expand the Model Structure (by clicking on ‘+’ box on its left) it shows only the project entry: Body Spring Damper Problem (see figure below). The tools that are used to create the component model are in the Editing box on the right. It contains several branches. We expand the branches we use most during Bond Graph model development: Ports, Bond Graph Components, Font Size and Text Orientation.

Model Structure and Editing Tools branches expanded
Get Started

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.

Editing Project

We start the the project model development by defining its basic structure. We identify first the basic components the system consists of and how they are interconnected. In this simple problem we may identify the following components:

  • - The system consists of the spring of stiffness k, damper of linear viscosity coefficient b, and body of mass m. The body is connected by the spring and damper.
  • - The wall at the left serves to fix the left ends of the spring and damper. It belongs to the environment, which restricts the possible motion of the system. There is also a force by which environment acts on the body.
  • - The body moves over the ground. By neglecting the friction between the body and the ground, we can neglect the interactions in the vertical direction.

To create the model we generally use the component models tools. Only for very simple processes the elementary models are used. We dragged the corresponding tools and drop them in the project document window.

Note that default font size for Component Model is large one, and for the elementary components the normal size. However, because there are more components we will choose a smaller font, the normal size. In addition the text for the components by default runs horizontally from left to right. We wish, however, to write the Wall title in the vertical direction. Therefore, before we drag and drop the component tool we select Normal in the Font Size branch of the Editing Box, and Vertical in the Text Orientation branch.

Creating Wall component model
Editing Project

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. 

Creating and connecting the components
Editing Project

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

Moving the components up
Editing Project

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

Connecting the component ports by bonds
Editing Project

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

The system level model of Body Spring Damper Problem
The system level model of Body Spring Damper ProblemWe 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.

Source Effort port dialog
Editing ProjectThis dialog serves to define the constitutive relation of the effort (force) that this component delivers at its port. At the top of the window, inside Output Relation box, there are two editing boxes connected by the equality symbol. The effort variable on the left side can be defied in Port Variable box beneath this. We may change it to ‘F’. The right side defines it as a constant eValue. We may retain this symbol, but we will change its value by clicking Parameter button. Edit Parameters dialog opens as shown in the figure below on the left. Next, we select eValue from the list and click Edit button.

Define a parameter

Editing ProjectEditing Project

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.

Output Port dialog
Editing Project
By default the variables are plotted on Y axis. X axis is used for time (in seconds), and thus we generate Y-T plot. We can also plot one of input variables on X axis, and all other to Y axis, and thus create X-Y plots. We can also select None as axis, i.e. not plot the variable. Because, the variables are often of very different ranges, we usually plot jointly the variables of the similar ranges, excluding the others. We do not need to define the scales for axes; they are done automatically during the simulation.

The final change that we will apply to the System model above is to change Numerical Display title to Position. To that end we disconnect its connecting bond first, by selecting it (i.e. clicking) and then press the delete key. Next, we choose small font from Font Size branch of Editing Box. After that we select the display component and right click it. From drop-down menu we select Edit Text. As the caret appears we delete title “Display” and type in “Position”. Now we click outside of this text to end editing. No we reconnect the display component port to the Node. We select again the Font Sizes back to normal. The final form of the system level model is shown below.
The final form of the system level model

Developing Component Models

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

A new document created when opening Body component
Developing Component Models

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.

Body model: (left) Efforts branching, (right) Added body inertia

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.

The model of Body
Developing Component ModelsTo complete the Body model we need to define the constitutive relations that describe the elementary components, which make the model. We start with the inertial component and open its port by double clicking it. (We may also do it by selecting the port and applying command Open Next from Document menu.) The Inertial Port dialog opens as shown below.
Editing Body inertia
Developing Component Models

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.

Integrator input (left) and output (right) dialogs
Developing Component Models Developing Component Models

Now we can close the Body document by clicking document window control (×) button. Because the document was changed, before closing the document the program asks us what we wish to do next by showing the following message dialog.

Save dialog options
Developing Component Models

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.

Operations on the project model

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

The complete project model with all components closed
Project ModelIf we expand a component branch (by clicking ‘+’ icon) the corresponding document will open in the center. Thus, e.g. if we expand Body branch its model opens in the center as shown below. Similarly, by collapsing the branch (clicking ‘–‘ icon) the corresponding document windows closes as well. Thus, we may use the model tree to open or close the components (the model branches).

The project model with expanded Body branch 
Project Model

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

Generated Mathematical Model

After the model has been built we may explore the mathematical model the program generates. However, because the model is generated in a byte form, we must translate it first into the common mathematical form that can be more easily reviewed. We can do it by clicking Equations toolbar button (in form of a pencil), or by choosing command Show Model >Write Equations in Simulation menu. The text box below lists the mathematical model for the problem we deal with. For this relatively simple problem, there are 13 equations expressed in implicit form in which all the terms are moved to the left side of the equations. The Y(i), i = 1,…, 13, are the machine generated system variables. The equations generated by BondSim are typically very simple consisting of on average two to three terms per equation. There can be thousands of such equations.

Box 1. Model equations
Generated Mathematical Model
To see the meaning of the system variables we may put the mouse cursor over the ports of the elementary components and tooltip windows appear showing the port variables. Thus, e.g. if we open Spring and put cursor over the capacitor port, a tooltip window appears as shown in the figure below. The window shows that Y(2) is the capacitor effort (the spring force), Y(7) is the flow (the spring extending velocity), and Y(8) is the state variable (the spring extension).

The tooltip showing the port variables
Generated Mathematical Model

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.

Running Simulations

The model is created with zero initial conditions for all variables (with exception of the variables we set differently). We have changed only the value of the input force. Thus, the response of the system corresponds to the system step response to the applied force. After the model was built we may start the simulation by clicking the Run toolbar button (a large red arrow), or choosing Run command in Simulation menu. A dialogue appears which serves to input the necessary simulation parameters (see below). 

Simulation option dialog

Running SimulationsWe check the Restart button, which indicates that we wish to start the simulation from the beginning, not to continue the pervious run. The Reset plot box is checked automatically. This means that the previous plots if any are removed before the start of the new simulation. We may remove the Reset plot check if we wish to plot the next simulation results over the results of the previous one.

We need also to define the duration of Simulation interval, Output interval, Maximum stepsize, the simulation Method and Error tolerances. These values depend on the problem being simulated. To define them we conduct a short analysis. 

The problem parameters that were already set during the model development were: 

•    The body mass m = 5 kg
•    The spring stiffness k = 112.5 kN/m
•    Linear damping coefficient b = 150 N∙s/m
•    The input force F = 500 N

Thus, we can find the natural frequency of the system as

   Running Simulations

Similarly, the damping ratio is given by

Running Simulations

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 response of the body position
Running Simulations

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

Post processing of simulation results

Running SimulationsThe Show data command creates a window, which lists time-variable data points symmetrically about the right-clicked point. The next command Expand enables expanding of a part of the plot by drawing a selection rectangle, which define a part of the plot that we wish to expand. The operation is explained in the message at the bottom of the screen. This command does have sense if there are generated enough points so that expanded curve is not a trivial one, e.g. consisting of only few points.

The next commands apply the specific post-processing operations on the data points such as the time averaging or applying different Fast Fourier Transform operations. 

There is also a command to append the marks to the curves. The descriptions could be also added to the plot as well as the pointing arrows. These are mostly used for documentation purpose.

The plotted curves could be exported in form of text files of the plotted values. Such files could be imported into e.g. MS Excel or similar programs for further processing.


Continuing the Simulations

When we are in simulation mode the model editing is restricted. We can open any component for inspecting e.g. by double-clicking its title (or in other way), but changing the model including its parameters is disabled. The only exceptions to this rule are the input components - Source Effort, Source Flow and signal Input Generator. We can freely edit their constitutive relations and the local parameters (i.e. the parameter defined inside the component, not in the documents). When we close the component by clicking OK button the program automatically update the built in model and informs us on this by a message in Output window. In this way it is possible to continue the simulation to study the model behavior under different input conditions. If we wish to make the other changes in the model we must to close the simulation session by clicking the “stop” toolbar button, or select End Simulation command in Simulation menu, change the model and rebuild it. 

As an example we continue analyzing the behavior of Body Spring Damper Problem under a different external excitation. We assume the input force is sinusoidal, i.e.

Continuing the Simulations

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,

Continuing the Simulations 

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.

Response to harmonic driving force at the resonance (150 rad/s)
Continuing the Simulations

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.

Responses to harmonic driving force at the frequencies: 15 rad/s (left)  and 1500 rad/s( right)
Continuing the SimulationsContinuing the Simulations

Using Templates

When developing the models instead of standard components models in the form of word models, it is also possible to use components from the Template Box on the right side of Modeling and Simulation Environment. This box contains the component tools for representing them by standard engineering schemas (see the Figure below). Currently there are the components inside the Electrical Component branch, which are designed according to the standard schemes commonly used in Electrical engineering. There are also the components in Mechanical Component branch, which currently contain components that use the mechanical schemes used in vibrations. The other mechanical schemes will be added later. Finally there is also Component Orientation branch which permits drawing the components horizontally or vertically.  It is used when creating components such as resistors, capacitors, etc. By default the drawing is horizontal. We can change this to drawing the vertically. After the component is created, it is advised to switch the drawing direction back to Horizontal.  

Template Box Components
Using TemplatesTo illustrate use of such forms of components model we create an electrical resistor by dragging and dropping its tool from the Template Box (see the figure below). To do it we need first to activate Template Box, and then expand Electrical Component branch. If we need a horizontal resistor we simply pick it, drag it to the central document window and drop it somewhere inside it. For a vertical one we expand also Component Orientation branch and select Vertical orientation. The resistor component is created and the caret appears. We can now edit the resistor title. Thus. we may change it to R100, meaning e.g. that it is the resistor of nominal resistance 100 (Ohms). When we finished with editing we click somewhere outside of it, as with other components, and the component creation is completed and it appears showing its title and its ports. Notice that it is only the component model. Its model document we may add in the usual way (see Development Component Models).
Creating a resistor
Using Templates
The next figure shows model of a RLC project developed by using the electrical templates.

RLC project with electrical template components
Using Templates

Using Libraries

To simplify development of the projects or components model BondSim contains a library of the projects and component models. They are held in the library part of the workspace, separate from the ordinary projects. For the user convenience they are listed in Library tab on the left side of Modeling and Simulation Environment. The content of the library is shown below on the left.
Contents of library                            Library drop-down menu
Using Libraries                         Using Libraries

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. 

Dragging and dropping of a library component
Using LibrariesThere is one more command in the drop-down menu – Repair. This command serves to repair the library workspace. These commands in addition to the workspace restore operation enables also recovery of the originally installed library projects or components that we lost, e.g. removed from the system.