SimObjects are compiled into a shared library – a dll/so file – which are loaded by FhSim at runtime. Herein, a sketch of the procedure for creating a new SimObject is presented, and we outline how to create a new SimObject library with a set of SimObjects. It is practical to use existing implementations as starting point for new developments. We have written a SimObject template tool to make it easier to create a new SimObject library that follow good coding practices, see SimObject template tool.

Creating a new SimObject

Steps for creating a new SimObject

Suppose you have an existing SimObject library and want to add a new SimObject. To create new SimObject, simply inherit from the SimObject class and implement necessary functions:

Create new source and header files, usually by taking an existing SimObject implementation as starting point. Use #include <SimObject.h> in your header file.
Extend appropriate variables in CMakeLists.txt with the new file names.
Add an include directive for your new header file to the SimObject library's module header file and add ADD_SIMOBJECT_REF(<Class name>, <Object reference name>); or ADD_SIMOBJECT_REF3(<Namespace>, <Class name>, <Object reference name>); in the getSimObject function of the corresponding cpp file.
Compile and load its configuration using your newly defined object reference name. Build with either cmake --build . --config Release, conan build .., or via your IDE.

Note: If your SimObject library is created from the SimObject template tool, there is a DEVELOPING.md file on the project root that contains a step-by-step cheat sheet.

Central methods to implement for a new SimObject

Constructor

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

Output port 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. If more than one output port depends on running the same code for updating some data, it is recommended to put these calculations in a common method, which is called from all port functions, and to start the method by a test to check if the method have already been run in this time step.

OdeFcn: This method is responsible for calculating the derivative of the states of the SimObject.

Other methods: See SimObject for other (optional) methods you can implement for your SimObject.

Creating a new SimObject library

SimObject libraries are loadable modules (dll or so files) that contain one or more classes inheriting from the SimObject interface. Each implemented SimObject must be referenced using ADD_SIMOBJECT_REF or ADD_SIMOBJECT_REF3 macros in a CMake MODULE target. The MODULE target must link to the target FhSim::fhsim, which contains the SimObject base implementation. Suppose fhsim_example.cpp contains a class my::deep::space::VanDerPol and Pendulum, both implementing the SimObject interface. To create a SimObject library with these models, we add to fhsim_example.cpp:

#include <dllLib.h>
IMPORT_EXPORT SimObject* getSimObject(std::string subClassName,
    std::sttring simObjectName, ISimObjectCreator* creator)
{
  ADD_SIMOBJECT_REF3(my::deep::space,VanDerPol,Oscillator/VanDerPol);
  ADD_SIMOBJECT_REF(Pendulum,Oscillator/Pendulum);
  return nullptr;
}

An excerpt of the CMakeLists.txt is:

find_package(FhSim CONFIG REQUIRED)
add_library(fhsim_example MODULE fhsim_example.cpp fhsim_example.h)
target_link_libraries(fhsim_example PRIVATE FhSim::fhsim)

The resulting dll/so is now a SimObject library with two SimObjects: Oscillator/VanDerPol and Oscillator/Pendulum.

SimObject template tool

The simobject template tool is a command line interface that help create a minimal SimObject library, with ready-made scripts for CMake, conan and documentation. If you are lucky, you are almost completely relieved the burden of writing build system scripts.

Installation

Install it from the following URL:

python -m pip install https://artifactory.smd.sintef.no/artifactory/dist/fhsim/simobject.tar.gz

If you have access to the git repository, install the development version from there:

python -m pip install git+ssh://git@git.code.sintef.no/fhsim/simobject_template.git

Usage

Run simobject --help to get available commands. A user scenario is typically

simobject new config_dir
Edit config_dir/simobject.cfg in a text editor. A simobject.cfg file will be on the format:

[SimObjectLibrary]
name = fhsim_awesome
short_name = fhawe
author = John Doe
author_email = John.Doe@examplemail.com
url = https://www.example.com
homepage = https://www.fhsim.no
license = LICENCE_SHORTHAND
description = A SimObjectLibrary for the purpose of learning how to develop in FhSim.
topics = FhSim, Simulation, Marine, Robotics, Cybernetics

simobject create config_dir --output-folder generated_dir
cd generated_dir && git init
mkdir build && cd build
conan install .. && conan build ..
- If required system packages are missing, the conan execution might abort with error messages displayed. See Conan docs on how to control this behaviour.
Write you own SimObjects, see DEVELOPING.md and README.md in the generated directory.

Example SimObjects

To better understand the implementation of SimObjects, view the implementation of a linear spring and a mass object. The following files are disclosed:

Table of Contents