Marine systems simulation
5 How to run 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 from which to build the system.
  • 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. See Input file example 1 and Input file example 2 for complete input files.

Running FhSim

Open a command terminal. Suppose FhSim is installed to /home/john/fhsim-playpen or C:\Users\john\fhsim-playpen. Navigate to this directory and go to the directory where the FhSim executables are installed – the bin folder. In the following we use Windows as example. Linux is similar, only that local executables are run with a ./ prefix.

cd /D C:\Users\john\fhsim-playpen\bin

Suppose you want to run the simulation described by the input file C:\Users\john\fhsim-playpen\examples\input\MySystem.xml without visualization. You simply write:

FhSim ..\examples\input\MySystem

Replace FhSim with FhVis if you want to run with visualization. Use FhRtSim or FhRtVis if you want to run with real time requirements. To exit the visualization, press <Esc>. See 3D scene navigation to learn how to control the camera.

The first time a program is run with visualization, an Ogre3D dialog may pop up where you can set your preferred view settings. You can change the settings later, but you will need to delete the file ogre.cfg, which is located in the resources subdirectory.

You can get the available command line program options by typing FhVis --help:

Allowed options:
--help produce help message
--version print FhVis version
--input-file arg model description file
--output-file arg (=modeloutput.csv) comma separated values result file
--output-file-from-input arg (=0) create output file name based on input
file
--log-file arg (=logoutput.txt) output file for fhsim messages
--resource-path arg (=../resources/) path to the visualization resources
configuration file "resources.cfg"
--console-verbosity arg (=2) verbosity of fhsim messages to the
console [0-4]
--file-verbosity arg (=2) verbosity of fhsim messages to the
message file [0-4]
--frame-rate arg frame rate used by visualization
--stim-mode arg (=0) run in stim-supported mode

Scenario file contents

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 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"
Radius="0.70"
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:

  • fhsim_baseVis_d.dll.
  • fhsim_baseVis.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 contain multiple <Connection> tag. This can be useful for grouping connections, making reading the input file easier.

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. Simulations can be integrated with two different integration frameworks: the classic FhSim integration framework referred to as Engine and the external Sundials integration framework. The integration framework and its options are specified in the <Engine> or <Sundials> subsections.

Engine options

Engine options decide how the integrator executes and how outputs are written to file. The 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 \(\text{epsilon} = f_0() \), see below
1 \(\text{epsilon} = f_1() \), see below
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.

\( f_0 = \max \frac{\epsilon_i}{|tol_{rel}\cdot x_i|+tol_{abs}}\) and \( f_1 = \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\).

Sundials options

Warning
The integration of Sundials into FhSim is still experimental. Use at your own risk.

Please see the Sundials documentation for more information about the Sundials integration framework.

Property Example Comment
sundials_method cvodes The integration infrastructure Sundials will use. Currently, only cvodes and arkode are supported. CVODES is a suite of nonlinear and DAE solvers. ARKODE is a suite of adaptive-step time integrations solvers for ODEs.
cvodes_method BDF The method used by CVODES. Currently, only BDF and ADAMS are supported.
arkode_method ERK The method used by ARKODE. Currently, only ERK and DIRK are supported.
t_start 0 The start time of the simulation.
t_end 10 The end time of the simulation.
dt 0.1 The step size for when output is written to file. Notice that this is not the step size used by the integrator, which may be adaptive based on the options.
reltol 1e-6 The relative tolerance used by the integrator.
abstol 1e-6 The absolute tolerance used by the integrator.
jtype DENSE Sundials can estimate a Jacobian matrix, but must know how large the matrix should be. The parameter "jtype" in the integrator controls the patterns of the Jacobian matrix. Currently, only dense, sparse and none are supported. Can only be set with cvodes or arkode in combination with DIRK.
linear_solver SPGMR Linear solver. The available options are SPGMR or DENSE. Can only be set with cvodes or arkode in combination with DIRK.
nonlinear_solver NEWTON Nonlinear solver. The available options are newton or fixed_point. Can only be set with cvodes or arkode in combination with DIRK.
print_step_info 1 In combination with verbose level 4, this will print to console or write to log file information about the integration steps.
file_output objects:ports Similar to FileOutput in the Engine options.
initial_states_file "initialstates.bin" A binary file containing the initial states.
final_states_file "initialstates.bin" A binary file to write all final states to. This can be used for continuing the simulation from an earlier state.

Several additional options are available, please see the documentation for the CVODES, ARKODE/DIRK and ARKODE/ERK integrators. The options can be set with parameters with the same name as in the official Sundials documentation. If a parameter is not yet available in FhSim, an error will be thrown during start-up. A few examples are shown below.

Property Example Comment
ERKStepSetFixedStep 0.1 Fixes the step size used by the integrator. Can only be set with arkode in combination with ERK. Generally not recommended.
ERKStepSetTableNum HEUN_EULER_2_1_2 Sets the explicit Butcher table when using arkode in combination with ERK. See the available options in the official documentation.
ARKStepSetTableNum SDIRK_2_1_2 Sets the implicit Butcher table when using arkode in combination with DIRK. See the available options in the official documentation.

3D scene navigation

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
<Tab> Resets 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

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"
UseRSSNormInsteadOfInfNorm="0"
/>
</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"
Radius="0.20"
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"
Radius="0.70"
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"
UseRSSNormInsteadOfInfNorm="0"
FileOutput=""
/>
</INTEGRATION>
</Contents>

Input file example 3

Same as example 2, but with Sundials integration.

<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>
<Sundials
t_start = "0.0"
t_end = "10"
dt = "0.1"
print_step_info = "0"
sundials_method = "cvodes"
cvode_method = "BDF"
reltol = "1e-7"
abstol = "1e-7"
jtype = "dense"
lin_type = "SPGMR"
nonlin_type = "newton"
file_output = "objects:all"
/>
</INTEGRATION>
</Contents>