Marine systems simulation
SimObject methods

Table of Contents

A SimObject can implement a range of methods. Some of these are optional, some are required. Their calling sequence is given in the figure below.

The FhSim call sequence.

Constructor

 SimObject(const string& simObjectName);
Parameters
[in]simObjectName-> The name of the simobject

The constructor performs all initial setup for a SimObject. It 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 It should also perform any additional 'one time only' resource setup.

A list of methods used in the constructor is found here

InitialConditionSetup

 void InitialConditionSetup(const double T, const double* const currentIC, double* const updatedIC, ISimObjectCreator* const creator);
Parameters
[in]TThe time at the beginning of the simulation. Usually but not necessarily zero
[in]currentICArray of initial conditions. If the value is QNAN, the value is not set yet and can be set by the SimObject, otherwise the value is set, and can not be changed. Trying to change an already set value will trigger an error
[out]updatedICArray of ONAN. Any initial condition that are ready to be set, should be written to this array.
[in]creatorPointer to creator class

Method for SimObjects that wants to set it's own initial conditions based on the value of it's input ports. SimObjects that wants to use this feature overrides the method, and it will be called if the SimObject has unspecified initial conditions after the values from the SimObject constructor, and the input file are set.

The following service contract applies to SimObjects that wishes to override this method:

  • All or some of the input ports may not be ready yet, for instance if other SimObjects also has unfinished states. In the case where a port is not yet ready, it will return an array of QNAN. In the case where a state is not ready it will contain a QNAN. The method should detect this and act appropriately. See also the is_qNaN function in SimObject
  • The method are expected to set as many states as it can based on which input port are ready or not.
  • If due to unfinished states, the SimObject itself has output ports that are not yet ready to return a legal value, these ports must be reported as unfinished. Note that if an output port is dependent on an unfinished input port, this in itself does not warrant a report. Only dependence on unfinished states are grounds for report.
  • If, after the method returns, the SimObject were unable to set all of it's states, the method will be called again until all states are set.
  • The solution is always growing. This entails that states that are once set, cannot be unset or changed. Input ports that were once ready, will continue to be ready. Output ports that during previous calls were not reported as unfinished are assumed ready and cannot be reported as unfinished later.
  • In all these matters the SimObject are expected to tell the truth, the whole truth, and nothing but the truth.
  • Some or all states that were suggested by the SimObject in the constructor, may have been overwritten by values from input files or other.
  • The SimObject may assume that multi element states and input ports are either set completely, or not at all. This means that if one element is QNAN the rest of the elements will be QNAN, and if one element is set all elements will be set. The exceptions from this rule are when the SimObject itself, either in the constructor or the InitialConditionSetup- method, specified the state with incomplete elements. In this case the SimObject are expected to know about it and take the proper precautions.

FinalSetup

 virtual void FinalSetup(double T, const double* X, ISimObjectCreator* creator);
Parameters
[in]T-> Current simulation time
[in]X-> Current simulation state
[in]creator-> Retrieve shared resources

Make final preparations before simulation starts. Mainly for retrieving shared resources registered during construction phase. Note: Called before RenderInit. Simobjects that wish to exchange shared resources through GetSharedResource/SetSharedResource may not retrieve said resources inside the constructor due to unpredictable order of construction.

RenderInit

 void RenderInit(Ogre::Root* ogreRoot, ISimObjectCreator* creator);
Parameters
[in]ogreRoot-> Register visualization resources
[in]creator-> Retrieve parameters.

Sets up visualization resources.

PreOdeFcn

 void PreOdeFcn(double T, const double* X, IStateUpdater* updater);
Parameters
[in]T-> Current simulation time
[in]X-> Current simulation state
[in]updater-> Callback class for updating states

Pre ode-function pass for handling discontinuous/discrete states. Called once before the start of every major timestep.

OdeFcn

 void OdeFcn(double T, const double* X, double* XDot, bool IsMajorTimeStep) = 0;
Parameters
[in]T-> Current simulation time
[in]X-> Current simulation state
[out]XDot-> State derivatives
[in]IsMajorTimeStep-> Is this a major time step?

This method is responsible for calculating the derivative of the states of the SimObject as a function of time, states and input ports.

RenderUpdate

 void RenderUpdate(double T, const double* X);
Parameters
[in]T-> Current simulation time
[in]X-> Current simulation state

Updates visualization resources to reflect current state