Basic modelling concepts

Basic modelling concepts

The SimObject

A simulation is usually comprised of multiple sub-models which are connected through input and output ports. These sub.models are a fundamental part of FhSim and is referred to as SimObjects. A SimObject has the following properties:

  • Input ports: Each input port is defined by a name and a width (number of elements). The data type is always double. All input ports must be connected.
  • Output ports: Each output port is defined by a name and a width. The data type is always double. It is allowed to have output ports which are not connected. The values of output ports are calculated for every time step if any other SimObject is requesting it, and if it is not cached.
  • Parameters: Parameters are static values which are set before the simulation starts. They are defined by a name and a width.
  • States: Each state is defined by a name and a width.

The most fundamental methods which a SimObject must implement are:

  • 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
  • OdeFcn: This function is responsible for calculating the time derivative of the states of the SimObject. For a point mass object, this would be done by setting the derivatives of the position equal to the velocity, and by setting the derivative of the velocity equal to the acceleration as 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.

For efficiency, the port values are never copied, only pointers to the different port values are distributed. This is also the case with the states and the state derivatives.

Shared objects

In some cases, it is beneficial to have access to perform identical calculations, coordinated tasks across SimObjects or calculations not fitting within the usual time integration paradigm. A typical example would be when one wants to calculate the environmental forces on multiple structures operating in the same sea, and especially if these interact. In FhSim, this is typically solved by defining an environment object, and giving all relevant SimObjects access to this.

CommonComputation

Computations that are shared between different functions (OdeFcn, PortFunctions, different SimObjects) may be registered as a CommonComputation. The system will ensure it is called only once per time step. The typical use case is if several output ports depends on the same calculation. Imagine a spring which outputs force in each end in two separate output ports. Each port function could then start by calling the same CommonComputation, calculating the tension and orientation of the spring only once per time step.

Initial condition

The time integration must have a starting point in the form of an initial state vector. This starting point can be defined in multiple ways:

  • A full state vector read from a file (typically written from a previous simulation).
  • Defined for the individual SimObjects in the input file.
  • Calculated by the function InitialConditionSetup of the individual SimObjects.

The latter allows for example SimObjects to calculate their initial state based on parameters and input ports. In some cases multiple SimObjects use input ports for determining their states, and output ports depend on input ports and/or states. This can lead to mutual dependencies. FhSim tries to solve this by iteration. If this doesn’t succeed within a predefined number of iterations, the simulation will be aborted with an error message.