This section handles the creation of new models in FhSim. If, however, you only want to run pre-existing models without doing programming whatsoever, please consider installing FhSim using an installer instead.

Prerequisites

You will need recent versions of the following tools:

conan >=2, which is a python-based package manager for C/C++ projects.
A functional C++ development environment, with a fairly recent compiler, gcc >= 10, msvc++ >= 14.2 or Apple clang 17 on macOS (Apple silicon).
CMake >=3.24, <4 build system generator.
git version control system.

Make sure these tools are installed before you continue.

Add the sintef-public remote conan:

conan remote add sintef-public https://gitlab.sintef.no/api/v4/projects/22218/packages/conan

Setup a conan profile:

conan profile detect --force

Open ~/.conan2/profiles/default or C:/Users/[Username]/.conan2/profiles/default with a text editor and edit the following: For all platforms: make sure these lines are present

compiler.cppstd=20

On macOS (Apple silicon), also add this line under [settings]:

llvm-openmp/*:build_type=Release

Apple clang has no OpenMP, so the libraries with parallel loops (fhsim_marine_elements, fhsim_maritime, and fhsim_fishery through them) use conancenter's llvm-openmp, whose recipe refuses Debug on armv8 ("Debug mode not supported for ARM v8"). The runtime has a C ABI, so a Debug build links the Release runtime without trouble. The apple_clang profile in conan-configs carries the same line.

Plugins and fhsim must agree on Eigen

A KalmanObject returns estimator::Matrix and estimator::Vector (dynamic Eigen types) by value. The plugin allocates the buffer and fhsim frees it, so the two sides must choose the same Eigen allocator. Eigen decides this in each translation unit, from its version and from the alignment and vectorisation flags. The rule:

Build fhsim and every plugin (every package that has a KalmanObject) with the same Eigen version (the Conan eigen reference of the workspace) and the same alignment and vectorisation flags (for example the same AVX2 setting and the same EIGEN_MAX_ALIGN_BYTES or EIGEN_MALLOC_ALREADY_ALIGNED).
Do not instrument one package with AddressSanitizer and leave the others plain. Instrument all of them, or define EIGEN_MALLOC_ALREADY_ALIGNED=1 in all of them.

A mismatch does not give a wrong number: it crashes or corrupts the heap when the Kalman filter is set up (a sanitizer reports "attempting free on address which was not malloc()-ed"). A normal Linux build with the workspace profile is consistent, so nothing fails there. Other Eigen types stay inside one library and are not affected. (FHSIM-0225.)

You will also need to acquire a license file, please contact karl..nosp@m.j.re.nosp@m.ite@s.nosp@m.inte.nosp@m.f.no or your SINTEF liaison.

For license access/support, contact your organization FhSim administrator or licensing contact.

Getting started

Suppose you are working on a project fhsim_awesome, which is a SimObject library that depends on FhSim. In case you do not have access to such a project, create one with SimObject template tool.

Typical commands to build a project with FhSim are:

cd fhsim_awesome
conan install . -s build_type=Release --build=missing --update -o fhsim/*:with_visualization=True
conan build .

Remarks: The conan install command takes an option -o fhsim/*:with_visualization= , with default value True, for building the project with or without visualization.

The install command above should have installed the FhSim executables and dependencies to the build/playpen directory. Once your project is built, its SimObject library is located in build/playpen/bin/SimObjectLibraries. When running FhSim executables, it is practical to use your playpen bin folder as working directory. The license file can either be put in this folder as license.lic, or stored elsewhere and pointed to by the environment variable SFH_LICENSE_FILE.

Suppose there exist an input file in fhsim_awesome/examples/input/Example.xml. You can run this with FhSim as follows:

cd fhsim_awesome/build/playpen/bin

FhVis ../../../examples/input/Example.xml

If this works you are ready to proceed by creating your own SimObjects, see Create a new SimObject.