Marine systems simulation
5 Setting up and running simulations

It is essential to have a simulation scenario when running a simulation in FhSim. Such a simulation scenario both defines the composition of- and the relations between, models. A simulation scenario is in FhSim implemented through an XML file.

In summary, the scenario input file specifies:

• The SimObjects to build the system from.
• How the SimObjects are connected.
• The initial states of the SimObjects.
• Integrator options.
• Output options.

The XML input file contains both mandatory and optional sections as indicated in the following code snippet:

<Contents>
<OBJECTS>
...
</OBJECTS>
<INTERCONNECTIONS>
...
</INTERCONNECTIONS>
<INITIALIZATION>
...
</INITIALIZATION>
<INTEGRATION>
...
</INTEGRATION>
<VARIABLES> <!-- optional block -->
...
</VARIABLES>
</Contents>
Note
The whole file must be surrounded by a <Contents>tag.

For the remainder of this page we will assume that the XML file is called MySystem.xml. Whenever you see <input directory> in a path, you should replace it with the full name of the directory in which the file is located.

# Contents of the scenario files

The input file is divided into different sections, and each has their own specific purpose.

## OBJECTS

The section OBJECTS specifies the simulation objects that are part of the simulation. The SimObjects are usually are compiled into separate shared libraries (dll's on windows), and they are defined by the location and name of the library file, as well as the type name of the individual object. The parameters are also given for each SimObject.

Each SimObject is specified by a <Lib /> tag with the following attributes

• LibName: The library where the implementation of this specific SimObject can be found.
• SimObject: The type of the SimObject.
• Name: A unique name for the SimObject.
• Any number of SimObject specific parameters.

The parameters which are specific to a type of SimObject should normally be described in the documentation for that SimObject. The names and types must match the implementation. If a SimObject has a numeric parameter called Mass, for instance, then Mass="20.0" is valid whereas Mass123="abc" is not. The type is actually not checked though, so Mass="abc" wouldn't raise any errors, but would look quite funny in the simulation. Parameters which have a default value can be omitted.

Example:
The TutorialLib library has a SimObject type called Mass, which describes a mass with three degrees of freedom. It has the parameters Mass, Radius and Color. To add such an object to the simulation, place the following inside the <OBJECTS> section:
<Lib LibName="TutorialLib" SimObject="Mass" Name="mass"
Mass="2000"
Color="0.1, 0.3, 0.9"
/>
Note
It is important to note that the version of the library must match that of the rest of the API. This means that if FhSim is compiled against dynamic standard libraries, and with visualization, then this must be the case also for the SimObject libraries. To simplify this, the recommended naming convention of the SimObject libraries are to use the following suffices to distinguish between libraries of different linking:
• Visualization suffix: "Vis" / ""
• Debug suffix: "_d" / ""

The name of a library may then be assembled as: LibName<Visualization suffix><Debug suffix> One library name on Windows may therefore be:

• FhSimBaseVis_d.dll.
• FhSimBaseVis.dll.

## INTERCONNECTIONS

The subsection Connection in INTERCONNECTIONS specify how the SimObjects are connected. This is done according to simObject names, port tags and constants. Simobjects have a number of input and output ports. All input ports must be connected to an output port, but output ports may be left unconnected. Connections are described through attributes of a <Connection> tag, with the following syntax:

<Connection
someObject.SomeInport="anotherObject.SomeOutport"
...
/>
Note
The <INTERCONNECTIONS> section can only contain a single <Connection> tag, and this tag must therefore describe all connections. For examples, see Examples of simple SimObjects.

The names and possible values of a simobject's states should be specified in the simobject's documentation.

Example:
If the simobject named cable has input ports named PositionA and PositionB, then these can be connected to the Position output port of the simobjects named mass1 and a fixed position like this:
<Connection
cable.PositionA="mass1.Position"
cable.PositionB="0,0,0"
/>

The first case connects the input port PositionA of the SimObject cable to the output port Position of the SimObject mass1. The second sets the input port PositionB of the SimObject cable equal to the vector [0 0 0]. The names of the simObjects are defined in the OBJECTS section of the input file, while the tag names are set in the definition of the SimObjects (in the C++ source code).

## INITIALIZATION

The InitialCondition subsection specifies the initial states of the simObjects. It contains a single <InitialCondition> tag in which the initial conditions of all objects in the system are specified with the following syntax

<InitialCondition
someObject.SomeState="some value"
...
/>

The initialization is done using the simObject names and the state tag names:

    MassOne.Pos="10.0, 0.0, 0.0"

The states which are not initialized, are initially set to zero. There may, however be provided methods in the individual SimObject which sets the initial conditions, either based on the input parameters or input ports. A typical example would be a cable object, which could use positions of the ends to set the initial positions of the nodes in between.

Example:
If the mass object has states called Position and Velocity, which are both 3-vectors, its initial conditions may be specified like this:
<InitialCondition
mass.Position="-13,2,-5"
mass.Velocity="0,0,0"
/>

## INTEGRATION

The INTEGRATION section contains options that influence how the simulation is run, i.e. which simulation method is used, the time steps etc. The Engine subsection sets the integrator options, as for example

IntegratorMethod="2"

## Simulation

The simulation options decides how the integrator performs. The different options are described in the table below:

Property Example Comment
IntegratorMethod 2 0 = Forward Euler.
2 = Runge Kutta 45.
TOutput T0, OutputSpec, T Defines the start time, the times for outputs and the stop time. If the stop time is given as Inf, it is interpreted as infinite. Note that logging is only done if LogStates is 1 and/or FileOutput is set. Examples are shown below.
T Simulation starting at time 0 (default), no output(default) and T is the stop time.
T0,T Simulation starting at time T0, no output(default) and T is the stop time.
T0,To1,T Simulation starting at time T0, output at t = T01 if activated, the stop time is T.
T0, To1,,,ToN, T Simulation starting at time T0, output at t = To1,,,ToN if activated, the stop time is T.
T0, To1:T02, T Simulation starting at time T0, output at every integration step between t = T01 and To2 if activated, the stop time is T.
T0, To1:dT:T02, T Simulation starting at time T0, output at between t = T01 and To2 with dT interval if logging is activated, the stop time is T.
LogStates 1 Bool (0 or 1). Should the output be logged internally by CFhIntegrator? This is not applicable if the simulation is run by the standard FhSim or FhVis executables.
Set to 1 if logging is wanted.
StepSize 0
0.01
Variable step size if 0.
Fixed step size if larger than 0.
HMax 0.1 The maximum allowed step size (for variable step size only).
HMin 0.1 The minimum allowed step size (for variable step size only). An error will be given if the system can not be solved within error tolerances without using a smaller step size.
AbsTol 1e-6 The maximum allowed absolute derivative error (for variable step size only).
RelTol 1e-6 The maximum allowed derivative error relative to the states (for variable step size only).

|UseRSSNormInsteadOfInfNorm| 0 | $$epsilon = \max \frac{\epsilon_i}{|tol_{rel}\cdot x_i|+tol_{abs}}$$ | | 1 | $$epsilon = \sqrt{\sum_{i=0}^{i=N} (\frac{\epsilon_i}{|tol_{rel}\cdot x_i|+tol_{abs}})^2}$$ | | |     , where $$\epsilon$$ = error to compare to allowed tolerance
$$tol_{abs}$$ = the absolute tolerance
$$tol_{rel}$$ = the relative tolerance
$$\epsilon_i$$ = the estimated error in the derivative for state $$i$$. |FileOutput |"OBJECT_SET:DATASTREAM_SET"| The OBJECT_SET string defines a set of simombjects from which some kind of outputstream should be logged to file.
The DATASTREAM_SET string defines which streams should be logged from the aforementioned simobjects.
Logging will take place at timesteps defined in the TOutput property | | "objects:all" | Write all ports and states of all simObjects to result file. | | "objects:ports" | Write the output ports of all simObjects to result file. | | "objects.Mass:states" | Write the states of all Mass simObjects to result file. | | "object.spring1:port.ForceA" | Write the ForceA output port of spring1 to result file. | | "union(object.spring1:ports, objects.Mass:states)" | Write the ports of spring1 AND the states of all Mass objects to result file. | | "minus(objects:all, union(objects.Mass:ports, objects.Cable:states, object.spring1:ForceB))" | Write everything EXCEPT ports from Mass objects, states from Cable objects and ForceB from spring1. | | "" | Empty string. No output to file. |InitialStatesFile | "initialstates.bin" | A binary file containing the initial states. |FinalStatesFile | "initialstates.bin" | A binary file to write all final states to. This can be used for continuing the simulation from an earlier state.

# Input file example 1

This input file models a mass hanging from a linear spring, which again is hanging from a fixed point.

<Contents>
<OBJECTS>
<Lib LibName="base" SimObject="Body/Mass" Name="mass" Mass="1" Material="Simple/Black" Scale="1"/>
<Lib LibName="base" SimObject="Cable/LinearSpring" Name="spring" Stiffness="0.10" RelaxedLength="2.5"/>
</OBJECTS>
<INTERCONNECTIONS>
<Connection
mass.Force="spring.ForceA"
spring.PosA="mass.Pos"
spring.PosB="0,0,0"
/>
</INTERCONNECTIONS>
<INITIALIZATION>
<InitialCondition
mass.Pos="0, 2, 0"
mass.Vel="0, 0, 0"
/>
</INITIALIZATION>
<INTEGRATION>
<Engine
IntegratorMethod="2"
TOutput=" 0.0, 10000000 "
LogStates = "0"
FileOutput = "objects:ports"
stepsize ="0.00003"
HMax="100"
HMin="0.000001"
AbsTol="1e-7" RelTol="1e-7"
/>
</INTEGRATION>
</Contents>

# Input file example 2

This input file models a mass hanging from a cable, which again is hanging from another mass, which is connected to a spring. It uses the TutorialLib library.

<Contents>
<OBJECTS>
<External
Name="ExtObj"
outputPortNames="ExtPort"
Initial_ExtPort="-13,0,-7"
inputPortNames=""
Size_asdfgh=""
/>
<Lib LibName="TutorialLib" SimObject="Mass" Name="mass1"
Mass="2.2"
Color="0.1, 0.9, 0.3"
/>
<Lib LibName="TutorialLib" SimObject="MassPointCable" Name="cable1"
numElements ="49"
elementStiffness="100000.0"
elementBendingStiffness="10.0"
elementMass="0.2"
elementLength="0.2"
elementDamping="0.16"
/>
<Lib LibName="TutorialLib" SimObject="Mass" Name="mass"
Mass="2000"
Material="DiffuseSpecular"
Color="0.9, 0.1, 0.7"
/>
<Lib LibName="TutorialLib" SimObject="Spring" Name="spring"
Stiffness="18000.0"
Length="2.5"
/>
<Lib LibName="TutorialLib" SimObject="Sum" Name="sum"
numInput="2"
numComponent="3"
/>
</OBJECTS>
<INTERCONNECTIONS>
<Connection
mass1.Force="cable1.ForceA"
cable1.PositionA="mass1.Position"
cable1.PositionB="mass.Position"
cable1.VelocityA="mass1.Velocity"
cable1.VelocityB="mass.Velocity"
spring.PositionB="ExtObj.ExtPort"
spring.PositionA="mass.Position"
sum.component0_input="spring.ForceA"
sum.component1_input="cable1.ForceB"
mass.Force="sum.sumPort"
/>
</INTERCONNECTIONS>
<INITIALIZATION>
<InitialCondition
mass1.Position="-13.0, 2, 5.0"
mass1.Velocity="0.0, 1, 0.0"
mass.Position="-13,2,-5"
mass.Velocity="0,0,0"
/>
</INITIALIZATION>
<INTEGRATION>
<Engine
IntegratorMethod="2"
TOutput="0.0, Inf"
LogStates = "0"
stepsize ="0.0003"
HMax="100"
HMin="0.000001"
AbsTol="1e-7"
RelTol="1e-7"
FileOutput=""
/>
</INTEGRATION>
</Contents>

# Running FhSim

Open the command line and go to the directory where the FhSim executables are installed. On Windows, for instance, if this directory is c:\FhSim, you should type

cd /D c:\FhSim

On Linux, if the directory is /opt/FhSim, for example, you should type

cd /opt/FhSim

Now, if you want to run the simulation described by the input file MyDirectory/MyFile.xml without visualization, run

FhSim MyDirectory/MyFile

For developers: To run a debug version of FhSim, run the executables called FhSim_d or FhVis_d instead. Note that we have omitted the .xml extension when passing the input file name to FhSim. If you want to run the simulation with visualization, run

FhVis MyDirectory/MyFile


To exit the visualization, press <Esc>. See Navigating the 3D scene in FhVis to learn how to control the camera.

FhSim can also be ran from outside the install directory. In this case, for FhSim to be able to locate it's runtime dependencies, either the executable you are running must be located in the install directory, or you can set the environment variable FHSIM_DIR pointing to the install directory, and add it in the system PATH (LD_LIBRARY_PATH for Linux).

The first time a program is run with visualization, an OGRE dialog may pop up, where you can set your preferred view settings. It is recommended to select the OpenGL Rendering Subsystem and, if you are likely to do some debugging, turn full screen off. If you want to change the settings later, you need to delete the file ogre.cfg in the resources subdirectory (located in the same directory as the FhSim executables).

# Navigating the 3D scene in FhVis

When navigating in the visualization you are essentially moving a camera. This section holds an overview of the keys to use while the simulation is running.

Movement of camera along local axes

Shortcut Function
W Moves the camera forward
S Moves the camera backward
A Moves the camera left
D Moves the camera right
Q Moves the camera up
E Moves the camera down

Movement of camera along global axes

Shortcut Function
Numpad 7 Moves the camera along positive x-axis
Numpad 4 Moves the camera along negative x-axis
Numpad 8 Moves the camera along positive y-axis
Numpad 5 Moves the camera along negative y-axis
Numpad 9 Moves the camera along positive z-axis
Numpad 6 Moves the camera along negative z-axis

Choice of target viewpoint

Shortcut Function
1 - 9 Selects a target to use as a target viewpoint
0 De-selects target to use as a target viewpoint

Speed of camera movement

Shortcut Function
<Left shift> Increase camera speed
<Left ctrl> Decrease camera speed

Camera view direction (only if no target viewpoint is set)

Shortcut Function
<Arrow up> Increase elevation
<Arrow down> Decrease elevation
<Arrow left> Look to the left
<Arrow right> Look to the right

Special keys

Shortcut Function
X Toggles mesh or surface view
C Toggles view of origin axes
V Decreases the size of the origin axes
B Increases the size of the origin axes
<esc> Quits the simulation