Marine systems simulation
Setup of developer environment

This page is considered work in progress
"The Developer tutorial"-page needs to be updated with tutorial location, folder structure etc.


You will need recent versions of the following tools:

  • A compatible version of FhSim to load this library.
  • conan, which is a python-based package manager for C/C++ projects.
  • A functional C++ development environment, with a fairly recent compiler, gcc >= 8 or msvc++ >= 14.1.
  • CMake build system generator.
  • git version control system.

Add the sintef-public remote conan:

conan remote add sintef-public
conan config set general.revisions_enabled=1

Getting started

FhSim is installed and you are ready to start on your first project. Let's start out by looking at a tutorial project and how it works. The tutorial project models a spring, a cable and a point mass and creates a model based on an input file. This guide focuses on getting your source files up and running, not on how to write them.

The tutorial project can be found in XXX. It consists of two folders and some test files.

Item Contents
build Contains all files for configuring and installing. The compiler's project files will also end up in this folder.
src Contains all source files. This is also where you should add new ones.
*.xml Input files that demonstrate how to set up a simulation with the simobjects in the project.


From the root directory, run the following commands: md build cd build cmake ../src -A x64

This should configure the project, creating the make files or the Visual Studio solution files, according to your platform and settings.

If you want to edit and compile the project from within your IDE, see Section Using an IDE. If you want to compile the project from the command line, see Section Compiling and installing from the command line.

Using an IDE

Inside the build directory you will find the solution file (on Windows) or the make file (on Linux). For Windows, open the solution file in Visual Studio.

The solution files are created anew each time the configure script is run, and any changes you have made to the solution (changing properties, adding files, etc.) will be lost. To add source files and change settings on a permanent basis you have to edit the CMake files. See Sec.
xref for details on how to do this.

Compiling and installing from the command line

To compile the project from the command line, run the following command (after the configure step):

cmake --build . --target install --config Debug
cmake --build . --target install --config Release

This will build and install both debug and release version of the library. The installation adds the library both to the playpen directory and the different SDK's.

Then go to the FhSimPlayPen_<COMPILER_SPEC>/bin directory and run FhSim with the input file test3 with visualization on. Look in Section sec_fhsim_run_windows and sec_fhsim_run_linux for how to do this on Windows and Linux, respectively. The example input file is found in Examples of simple SimObjects.


  • Read through the error logs.
  • Were all the files found? ../project/src/CMakeList.txt holds the files that the script is looking for.
  • Try running the script in debug mode. Write SET cmake_loglevel=4 (with no whitespace before or after the equals sign) in the command window and run the script again.
  • Try delete the build directory or just delete the file CMakeCache.txt before running the configuration again.


Only the configure part is needed to get the project set up for editing and debugging in your IDE of choice. Open the solution file in your IDE, i.e. ../TutorialProject/build/TutorialProject.sln for Visual Studio, and browse the project. You can now compile the project in your IDE. To debug we need to edit a few options and unfortunately there is no way to automate this with a CMake script. See debugging for more information.

The source files

The tutorial project initially consists of several source files, defining classes which are all simobjects. Amongst these classes are CMass and CSpring. The main difference between these are that the CMass contains states and has a very simple output function, while CSpring has no states but a more complex output function. In short, the following are the most important functions in a SimObject:


The constructor is responsible for reading the parameters belonging to the SimObject from the input file and defining the interface of the SimObject, in terms of:

  • Input ports
  • Output ports
  • States


This function is responsible for calculating the time derivative of the states of the SimObject. For the CMass object, this is done by setting the derivatives of the position equal to the velocity, and by setting the derivative of the velocity equal to the acceleration. The acceleration is found using Newton's laws.

Output functions

Each output port is implemented as a method responsible for returning a pointer to the data structure containing the value of the output port.

Adding a new SimObject

One of the strengths of FhSim is the ability to combine different models to create new ones or big systems of different models. Models you have created for one type of problem might be reused to solve another. Lets try to modify the tutorial project by adding another SimObject. We could write new source code or we could link to existing libraries. Lets look at both of these options.

Linking to existing SimObject

The FhSim shared library of projects consists of a number of different simobjects. Consult the documentation of FhSim libraries for a list of implemented simobjects. Sometimes there is no need to reinvent the wheel, sometimes you can just link to the libraries containing the source for the SimObject you need. All we have to do is add a few lines in CMakeLists.txt file to tell the compiler that we want to link to that specific library. We add the following at appropriate places in CMakeLists.txt (in the tutorial project this has already been done). See the CMake part of the FhSim guide for more about these files.

Adding a new source file

For simplicity we copy the CMass SimObject and rename it to create a new class called CMassNew. Place this in the ../TutorialProject/src folder among the other source files. Copying and modifying an existing source file is usually a good way to start as the structure of simobjects are often similar. Add the new file to the project by editing CMakeLists.txt found in ../TutorialProject/src (should also show up in your IDE). Add CMassNew.h to the set(HEADER ...) line and CMassNew.cpp to the set(SRC ...) line. Configure the project again and you are set to write your new source files. Let's keep it simple for now and just rename any instance of CMass to CMassNew, including the #ifndef statement in the header file. When compiling the Tutorial Project, a library of the source files is made which is used when simulating. We need to add our new SimObject to the TutorialLib. Include the header file in SimObjectsLib.h and a reference to the SimObject in SimObjectsLib.cpp. Now we have a new SimObject, though the usefulness of many differently named, but otherwise equivalent objects can be debated. Install the project, and let's try testing it.

The input files

Each SimObject constructor takes as argument an instance of the class ISimObjectCreator. This class handles the input files and the connection between different models as specified in the given input file. Load up the input file named test. For more information see the FhSim user's guide. If you remember from the first simulation of TutorialProject we had a spring with a big mass attached to it. Extending from the big mass was a cable with a smaller mass at the end. We now want to add a second cable from the smaller mass and attach a CMassNew SimObject in the end of it.

  1. In <OBJECTS>, copy the input for the MassPointCable named cable1 to create a new one called cable2 with the parameters of your choosing.
  2. In <OBJECTS>, copy the input for one of the Masses and create a new one called mass2 with parameters of your choosing. Also change the SimObject parameter so that this input will be to an instance of your newly created MassNew object.
  3. In <OBJECTS>, change the numInput parameter of sum from 2 to 3
  4. In the <Connection> tag under <INTERCONNECTIONS>, add the following attributes to make the new connections:
    mass2.Force = "cable2.ForceA"
  5. In <INITIALIZATION>, set some initial conditions for the positions and velocity of mass2.

Instead of our new Mass object we could add the mass object with 6 degrees of freedom. This mass object has a few more ports so you have to change the input file slightly in order to simulate with visualization. Try doing that to see if you've understood how simobjects are declared and how they are connected. Hint: Modify the existing file, exchange one mass object with 6D mass. One possible solution:

LibName="FhSimBaseLib" SimObject="Body/6DBody"

The names and types of the parameters for each SimObject instance are not arbitrary, but specified in the implementation of the SimObject. They can be declared with a default value which will be used if no value is given in the input file. If no default value was declared, this would raise an error.

Save this input file as e.g. MyTest.xml and try running the simulation with visualization. If you were successful, feel free to congratulate yourself. You have just created and visualized your first simobject!

FhSim development

FhSim related repositories and directories

Here follows an overview of repositories related to FhSim and their directory structure.

Repository Availability Directory Contents
fhsim Internal The FhSim core project
fhsimbase Open Shared SimObjects and FhSim resources
sfhbase Internal Internal SimObjects and FhSim resources

Debugging a project

General IDE settings

  1. Open the solution file in Visual Studio. This is usually found under <project>/build.
  2. Open the Solution Explorer by selecting View->Solution Explorer.
  3. In the Solution Explorer, right-click on the INSTALL project and choose Set as start-up project.


  1. The input file must be created according to standards.
  2. In the top of the IDE, choose Release or Debug in the drop down box.
  3. In the Solution Explorer, right-click on the project building the executable and choose Properties.
  4. Choose Configuration properties -> Debugging. The following values should be present:
    • Command (Use full path to executable, for example C:/_work/FhSimPlayPen_<COMPILER_SPEC>/exe/FhVis_d for visualization)
    • Command arguments (<Absolute or relative path to input file>)
    • Working directory (FhSimPlayPen_<COMPILER_SPEC>/exe)
  5. Run the program by pressing <F5> or by selecting Debug -> Start debugging.
  6. If you get a "No Debugging Information" warning here, don't worry, just press Yes to continue.


Setting the background colour of FhVis animation

The default background colour appears to be black. In order to change the background colour of an animation, the following lines can be added to the RenderInit method of an object:

Ogre::ColourValue backgroundColour(0.9, 0.9, 0.9);
m_pCamera = (CFhCamera*) m_pVisMgr->GetPtr("CFhCamera");
Ogre::RenderWindow * pRenderWindow =

Creating Mesh models from Solidworks

Ogre uses .mesh and .material files for 3D objects. This is a guideline for creating such models using a tool such as Solidworks.

  1. Get someone to make a model for you in Solidworks
  2. Export this as a VRML file
  3. Download and install Blender, an open source 3D program.
  4. Download and install the Ogre export script as outlined on the Ogre forum
  5. You can now export the model to a .mesh.xml file
  6. Use the OgreXmlConverter tool to convert to .mesh and .material files.
  7. Place these files somewhere on the Ogre resources path and set the mesh name of the object to that of the .mesh file

Cable and rope properties

Table 2 (Synthetic Fiber Rope Properties) from See also

Material Rope construction Strength kN/cm2 Stiffness kN/cm2 Remarks
Nylon braided 25 82 Dry strengths only, wet strength 10-20% less
Nylon plaited 20 87
Polyester braided 25 210 Wet and dry strengths, including jacket
plaited 20 160
7-strand 45 400
parallel strand 50 550
parallel fiber 35 1000
Aramid 36-strand 70 3300 Including jacket
parallel strand 65 2100
parallel fiber 95 4300 K29, including jacket
parallel fiber 90 8000 K49, including jacket
HMPE braided 55 1500 Unjacketed
7-strand 55 2000 Including jacket
parallel strand 65 3000
Steel 7-strand 85 6800

\[6 \times 36 \text{IWRC}\]

bridge strand 110 14000 Not including jacket
Solid bar 140 21000 4340 steel
Strength and stiffness are given as approximate values. Actual properties may vary widely. Cross sections are based on cylindrical enclosed area including jacket where applicable. Multiply by 1430 to convert to lb/in2.


General troubleshooting

If you get compilation errors

  • You may have to install the DirectX SDK (if compilation errors suggest this)

If you get run-time errors without or before


  • Check the logfile LogOutput.txt (name and directory specified in the FhSim executable.
  • Check that the input file does not contain Vis.dll, .dll or other extensions.

If you get run-time errors when visualization starts

  • Check the logfile Resources/Ogre.log
  • Delete the file Resources/Ogre.cfg, to be able to specify
    • the screen resolution
    • use of OpenGl or Direct3D
    • full screen or windowed mode
  • Verify correct OpenGL drivers
  • Verify correct DirectX drivers


  • Ensure that you have followed the installation and setup description closely.
  • Ensure that your computer is up to date:
  • Windows update
  • Microsoft update (especially that Visual Studio 2005 with service pack 1 is installed)


  • Be sure to have followed the steps in fhsim_prerequisites_installation and fhsim_installation


Running FhSim

I receive the error: "The method RegRenderRes could not be found!"

  • Be sure that all dll library loaded by the input file are of the same linking as the executable (debug/release, static/dynamic, with/without visualization).

I receive the error: "The library Ois*.dll could not be found!"

  • Be sure that the working directory is correctly set, if starting via Visual Studio.
  • Try running the executable from the command line.
  • Check that the missing dll is present in the working directory.
  • Obsolete: Run CreateTests from a command window and check that there are no errors.

I receive the error: "Unhandled exception at 0x7c422e38 in sim.exe: 0xC0000005: Access violation reading location 0xcdcdcde5".

  • Assure that the executable and the libraries mentioned in the input file are linked similarly (debug/release, static/dynamic, with/without visualization).

I receive the error: "ERROR! The license for the dll simulation object of type"

  • You need to regenerate the license. To do this, run the BuildAll.cmd command in the $WORK/fhSim/Build directory.

I receive the error: "ERROR! Could not load library ....."

When a simulation is started, the following process happens:

  1. FhSim is told which input file to use, either in code or through the command line.
  2. The input file is parsed.
  3. From the parsed input file, it is found which libraries (dlls) to be used for each SimObject.
  4. If the library names do not end with .dll, the names are appended with:
    • Vis if visualization is enabled
    • _d if it is a debug build
    • .dll
  5. The simObjects are instantiated from the specified simObject libraries (dlls).

Any errors must be interpreted with this process in mind.

Hints and tricks

SimObject libraries

It is suggested to use CMake to create install targets or post-build events to copy the necessary binaries to the Playpen directory.

CMake and Visual Studio

  • CMake creates the Visual Studio solutions and projects.
  • Afterwards, Cmake is automatically rerun when compiling in Visual Studio.
  • New source files must be added to CMakeLists.txt in the corresponding directory.
  • Changes in project settings that should last must be provided in CMakeLists.txt.
  • There is a shortcut to the corresponding CMakeLists.txt in Visual Studio for each project, found in the Solution Explorer.

Inserting special characters in Windows

If you know the keystroke value of the special character you want to insert, you can insert the special character directly into your document by using your keyboard. To do so, open the document and position the cursor where you want the special character to appear. Then, with <NUM LOCK> on, press and hold the <ALT> key, and then press the keys on the numeric keypad that represent the keystroke value of the character you want to input. After you finish typing, release the <ALT> key, and Windows generates the character you specified. NB! In Windows you need to include prepending zeros.

Example: With <NUM LOCK> on and <ALT> pressed, type at the numpad: "0169". This creates the copyright symbol ©.

ASCII codes can be found at for example:

Visual Studio macros

This section contains some macros which can be used in Visual Studio to make the workflow more efficient. The macros include mostly functionality to:

  • Format documents
  • Swap between header and source file
  • Write Doxygen comment sections


To install these macros:

  1. Copy all of the section Source code.
  2. Open Visual Studio.
  3. Open the Macros IDE by pressing <alt> + F11.
  4. Create a new module by opening the Project Explorer, right-click on an item and select new -> module. Name this FormatDocs. You may use another name, but the name must be the same as that referenced as "Public Module". Open the module by double clicking on it.
  5. Select all text in the module and delete it.
  6. Paste the contents of the clipboard into the module.
  7. Replace names and initials in the macros with your own.
  8. Save the module by pressing <ctrl> + s.
  9. Set up the keyboard shortcuts as desired. The ones I use are mentioned in the leading comment in the source code of each macro. To do this:
    1. In Visual Studio: Tools -> Options -> Environment -> Keyboard.
    2. In Show commands containing, type in FormatDocs.
    3. Go down the list until you find the macro you are looking for.
    4. While this is selected: Press the shortcut keys in the field Press shortcut keys.
    5. Press Assign.

Source code

Option Strict Off
Option Explicit Off
Imports System
Imports EnvDTE
Imports EnvDTE80
Imports System.Diagnostics
Imports Microsoft.VisualStudio.VCProjectEngine

Public Module FormatDocs
    ' Shortcut: `[ctrl] + [alt] + d`
    ' Formats all open documents
    Sub FormatOpenDocuments()
        For i = 0 To DTE.Documents.Count()
            End Try
        Next i
    End Sub

    Sub FormatDocument()
        ' Shortcut: `[ctrl] + [alt] + f`
        ' Formats the active document
            Dim selection As EnvDTE.TextSelection
            selection = DTE.ActiveDocument.Selection()
            ' Find the current position in the file
            Dim currentPoint As EnvDTE.EditPoint
            currentPoint = selection.TopPoint.CreateEditPoint()
            Dim line As Integer
            line = currentPoint.Line

            'DTE.ActiveDocument.Selection.GotoLine(line - 30)

        End Try
    End Sub

    Sub InsertHeaderClassComment()
        ' Shortcut: `[ctrl] + [alt] + 1`
        ' Inserts a Doxygen comment block in the header file
        DTE.ActiveDocument.Selection.Text = "////////////////////////////////////////////////////////////////////////////////////////////////////"
        DTE.ActiveDocument.Selection.Text = "/// \class                         "
        DTE.ActiveDocument.Selection.Text = GetClassName()
        DTE.ActiveDocument.Selection.Text = "////////////////////////////////////////////////////////////////////////////////////////////////////"
        DTE.ActiveDocument.Selection.Text = "///"
        DTE.ActiveDocument.Selection.Text = "/// \brief "
        DTE.ActiveDocument.Selection.Text = "/// \author            Karl-Johan Reite"
        DTE.ActiveDocument.Selection.Text = "///"
        DTE.ActiveDocument.Selection.Text = "///                 <b>Copyright "
        Dim sel As TextSelection = DTE.ActiveDocument.Selection
        sel.Insert(Format(Date.Today, "yyyy"))
        DTE.ActiveDocument.Selection.Text = " by SINTEF Fisheries and Aquaculture</b>"
        DTE.ActiveDocument.Selection.Text = "////////////////////////////////////////////////////////////////////////////////////////////////////"
    End Sub

    Sub InsertSourceClassComment()
        ' Shortcut: `[ctrl] + [alt] + 2`
        ' Inserts a Doxygen comment block in the source file

        DTE.ActiveDocument.Selection.Text = "////////////////////////////////////////////////////////////////////////////////////////////////////"
        DTE.ActiveDocument.Selection.Text = "/// \class                         "
        DTE.ActiveDocument.Selection.Text = GetClassName()
        DTE.ActiveDocument.Selection.Text = "////////////////////////////////////////////////////////////////////////////////////////////////////"
        DTE.ActiveDocument.Selection.Text = "/// "
        DTE.ActiveDocument.Selection.Text = "/// "
        DTE.ActiveDocument.Selection.Text = "////////////////////////////////////////////////////////////////////////////////////////////////////"
    End Sub

    Sub InsertSourceFunComment()
        ' Shortcut: `[ctrl] + [alt] + 3`
        ' Inserts a Doxygen comment before a source file function definition.
        ' If the function name is selected, this is used in the comments.
        Dim bHasCopied As Boolean
        Dim iSelectionLength = DTE.ActiveDocument.Selection.ToString.Length
        Dim objSel As TextSelection = DTE.ActiveDocument.Selection
        If Not objSel.IsEmpty Then
            'If (iSelectionLength > 3) Then
            bHasCopied = True
            DTE.ActiveDocument.Selection.LineUp(False, 1)
            bHasCopied = False
        End If
        DTE.ActiveDocument.Selection.Text = "////////////////////////////////////////////////////////////////////////////////////////////////////"
        DTE.ActiveDocument.Selection.Text = "//=================================================================================================="
        DTE.ActiveDocument.Selection.Text = "// FUNCTION NAME:          "
        If (bHasCopied) Then
        End If
        DTE.ActiveDocument.Selection.Text = "//=================================================================================================="
        DTE.ActiveDocument.Selection.Text = "/// "
        DTE.ActiveDocument.Selection.Text = "/// "
        DTE.ActiveDocument.Selection.Text = "/// \param [in]  "
        DTE.ActiveDocument.Selection.Text = "/// "
        DTE.ActiveDocument.Selection.Text = "////////////////////////////////////////////////////////////////////////////////////////////////////"
    End Sub

    Sub OpenPartnerFile()
        ' Shortcut: `[ctrl] + [alt] + s`
        ' Switches between the .cpp and .h file of the same name in the same folder.
        Dim filename As String
        Dim partnerFilename As String
        filename = DTE.ActiveDocument.FullName
        If (filename.EndsWith(".h")) Then
            partnerFilename = filename.Substring(0, filename.Length() - 2) + ".cpp"
        End If
        If (filename.EndsWith(".cpp")) Then
            partnerFilename = filename.Substring(0, filename.Length() - 4) + ".h"
        End If
    End Sub

    Sub LineSeparateParameterList()
        ' Shortcut: `[ctrl] + [alt] + p`
        ' If an argument list is selected, a new line is inserted after each comma.
        If (DTE.ActiveDocument.Selection.ToString().Length > 5) Then
            DTE.Find.Action = vsFindAction.vsFindActionReplaceAll
            DTE.Find.FindWhat = ", "
            DTE.Find.ReplaceWith = ",\n    "
            DTE.Find.Target = vsFindTarget.vsFindTargetCurrentDocumentSelection
            DTE.Find.MatchCase = True
            DTE.Find.MatchWholeWord = False
            DTE.Find.MatchInHiddenText = True
            DTE.Find.PatternSyntax = vsFindPatternSyntax.vsFindPatternSyntaxRegExpr
            DTE.Find.ResultsLocation = vsFindResultsLocation.vsFindResultsNone
            DTE.Find.Action = vsFindAction.vsFindActionReplaceAll
        End If
    End Sub

    Sub InsertForLoop3()
        ' Shortcut: `[ctrl] + [alt] + å`
        ' Creates a for-loop with an integer from 0 to   -# If a
        ' name is selected, this is used as the index variable,
        ' otherwise "i" will be used.
        Dim sVariable As String
        Dim objSel As TextSelection = DTE.ActiveDocument.Selection
        If Not objSel.IsEmpty Then
            sVariable = objSel.Text
            sVariable = "i"
        End If

        DTE.ActiveDocument.Selection.Text = "for (int "
        DTE.ActiveDocument.Selection.Text = sVariable
        DTE.ActiveDocument.Selection.Text = " = 0; "
        DTE.ActiveDocument.Selection.Text = sVariable
        DTE.ActiveDocument.Selection.Text = " < 3; "
        DTE.ActiveDocument.Selection.Text = sVariable
        DTE.ActiveDocument.Selection.Text = "++) "
        DTE.ActiveDocument.Selection.Text = "{"
        DTE.ActiveDocument.Selection.Text = "}"
    End Sub

    Sub SetDebugoptions()
        ' Shortcut: `[ctrl] + [alt] + r`
        ' Sets the settings "Working directory" and "Command Arguments" under "Debugging" to an initial value.
        Dim prj As EnvDTE.Project
        Dim i, iNumProjects As Integer
        iNumProjects = DTE.Solution.Projects.Count
        For i = 1 To iNumProjects
            For j = 1 To DTE.Solution.Projects.Item(i).ConfigurationManager.Count

              DTE.Solution.Projects.Item(i).Object.Configurations.Item(1).DebugSettings.WorkingDirectory = "$(playpen)\\exe"
              DTE.Solution.Projects.Item(i).Object.Configurations.Item(1).DebugSettings.CommandArguments = "$(input)\\!test\\onemass"
            Next j
        Next i
    End Sub

    Function GetClassName()
        Dim filename As String
        Dim classname As String
        Dim iPoint As Integer
        Dim iLastSlash As Integer
        filename = DTE.ActiveDocument.FullName
        iPoint = filename.LastIndexOf(".")
        iLastSlash = filename.LastIndexOf("\")
        classname = filename.Substring(iLastSlash + 1, iPoint - iLastSlash - 1)
        Return classname
    End Function
End Module

Important tools and software used within FhSim


Recommended tools

  • doxygen (Automated documentation)
  • stexbar (Windows explorer add-on)
  • Notepad++(A text editor)
  • Sysinternals (Lots of tools for monitoring file access, processes, TCP etc.)

Nice to have

  • cygwin (Linux shell)
  • automated_gui_testin
  • beyondcompare3 (Comparing files and folders)
  • which.bat (Which executable is run)
  • 7-zip (A file compression tool)
  • InfraRecorder CD/DVD burning software
  • Simian (Finding duplicate code)
  • Visual Assist X

Remote support

  • RealVNC


Download CMake from the CMake homepage. Remember to let CMake update the path info when you install it.

Installing Win32::GuiTest

  1. Install ActiveState Perl
  2. Start the Visual Studio command shell: Start -> All Programs -> Microsoft Visual Studio 2005 -> Visual Studio Tools -> Visual Studio 2005 Command Prompt
  3. Install GuiTest

    perl -MCPAN -e shell
    cpan>force install Win32::GuiTest