Creation of an empty simulator

As mentioned in the previous section (see Overview of an OpenFLUID simulator), a simulator must contain two parts :

• A signature giving information about the simulator, and used by the OpenFLUID framework to identify and couple simulators
• A C++ class defining essential methods for computational code

These two parts have to be developped in a C++ file (.cpp). They must be compiled before using it in the OpenFLUID environment.

Development environment

In order to build and develop a simulator, it is recommended to use the following tools:

• GCC as the C++/C/Fortran compiler
• CMake as the build configuration tool (see http://www.cmake.org).
  OpenFLUID provides a CMake module to ease the build of simulators.
• Eclipse as the integrated development environment (see http://www.eclipse.org).
  OpenFLUID provides an Eclipse plugin to assist the developer when creating a simulator (Available in the downloads section of the OpenFLUID web site).

Moreover, the required libraries must be installed in order to achieve the build of a simulator.

Writing the signature

The simulator signature is a set of informations about the content and behaviour of the simulator source code. With these informations, the OpenFLUID framework can evaluate the simulator, have information on what it does, on what it expects and produces, and can load it dynamically.
The informations included in the signature are :

• Identification
• Development information
• Expected variables and spatial attributes
• Produced variables and spatial attributes
• Spatial graph updates
• Time step behaviour

Usually, the signature is declared and implemented at the beginning of the .cpp file. It starts with the BEGIN_SIMULATOR_SIGNATURE macro and ends with the END_SIMULATOR_SIGNATURE macro. The minimal signature must include identification information. See part Declaration of the simulator signature for details on how to write the signature.

Writing the C++ class for the simulator

The C++ class integrates the computational code of the simulator, corresponding to successive stages of simulations. You will find a Complete example below, giving an example of source code of an empty simulator. The Development of the simulator source code part gives details about how to develop the computational code in the simulator.

Building the simulator

Any OpenFLUID simulator must be compiled using the GCC C++ compiler (g++) and must be linked to the OpenFLUID libraries and dependencies.
The recommended way to build your simulator is to use the CMake build system with the OpenFLUID CMake module, and provide CMake configuration files (CMakeLists.txt, CMake.in.config).
These operations can be performed automatically using the OpenFLUID plugin for the Eclipse IDE.

These operations can also be performed manually, with the following steps:

1. Create a build directory in your source directory (e.g. _build)
2. Go to this build directory
3. Run the cmake .. command, with the optional -DCMAKE_BUILD_TYPE=Debug option for debugging mode
4. Run the build command (e.g. make)

These steps are for Linux systems, and must be slightly adapted for other systems.

Complete example

The example below show a complete example of an empty simulator, including source code and build configuration using the OpenFLUID CMake module.

File ExampleSimulator.cpp containing the simulator source code

#include <openfluid/ware/PluggableSimulator.hpp>

DECLARE_SIMULATOR_PLUGIN


// =====================================================================
// =====================================================================


BEGIN_SIMULATOR_SIGNATURE("example.simulator")

  DECLARE_NAME("Example simulator");
  DECLARE_DESCRIPTION("This simulator is an example");
  DECLARE_VERSION("13.05");
  DECLARE_STATUS(openfluid::ware::EXPERIMENTAL);

  DECLARE_AUTHOR("John","john@foobar.org");
  DECLARE_AUTHOR("Dave","dave@foobar.org");
  DECLARE_AUTHOR("Mike","mike@foobar.org");

END_SIMULATOR_SIGNATURE


// =====================================================================
// =====================================================================


class ExampleSimulator : public openfluid::ware::PluggableSimulator
{
  private:  

  public:


    Example(): PluggableSimulator()
    {
      // Here is source code for constructor
    }


    // =====================================================================
    // =====================================================================


    ~Example()
    {
      // Here is source code for destructor
    }


    // =====================================================================
    // =====================================================================


    void initParams(const openfluid::ware::WareParams_t& /*Params*/)
    {
      // Here is source code for processing simulator parameters
    }


    // =====================================================================
    // =====================================================================


    void prepareData()
    {
      // Here is source code for data preparation
    }


    // =====================================================================
    // =====================================================================


    void checkConsistency()
    {  
      // Here is source code for specific consistency checking
    }


    // =====================================================================
    // =====================================================================


    openfluid::base::SchedulingRequest initializeRun()
    {
      // Here is source code for initialization

      return DefaultDeltaT();
    }


    // =====================================================================
    // =====================================================================


    openfluid::base::SchedulingRequest runStep()
    {
      // Here is source code for each step run

      return DefaultDeltaT();
    }


    // =====================================================================
    // =====================================================================


    void finalizeRun()
    {
      // Here is source code for finalization
    }

};


DEFINE_SIMULATOR_CLASS(ExampleSimulator);

File CMake.in.config containing the build configuration

# Simulator ID
SET(SIM_ID example.simulator)


# list of CPP files, the sim2doc tag must be contained in the first one
SET(SIM_CPP ExampleSimulator.cpp)

# list of Fortran files, if any
# ex: SET(SIM_FORTRAN Calc.f)
#SET(SIM_FORTRAN )


# set this to add include directories
# ex: SET(SIM_INCLUDE_DIRS /path/to/include/A/ /path/to/include/B/)
#SET(SIM_INCLUDE_DIRS )

# set this to add libraries directories
# ex: SET(SIM_INCLUDE_DIRS /path/to/libA/ /path/to/libB/)
#SET(SIM_LIBRARY_DIRS )

# set this to add linked libraries
# ex: SET(SIM_LINK_LIBS libA libB)
#SET(SIM_LINK_LIBS )

# set this to add definitions
# ex: SET(SIM_DEFINITIONS "-DDefinition")
#SET(SIM_DEFINITIONS )


# set this to force an install path to replace the default one
#SET(SIM_INSTALL_PATH "/my/install/path/")


# set this to 1 if you do not want automatic build of sim2doc documentation
SET(SIM_SIM2DOC_DISABLED 1)

#set to 1 to disable installation of sim2doc built documentation
#SET (SIM_SIM2DOC_INSTALL_DISABLED 1)

# set this if you want to use a specific sim2doc template
#SET(SIM_SIM2DOC_TPL "/path/to/template")


# set this if you want to add tests 
# given tests names must be datasets placed in a subdir named "tests"
# each dataset in the subdir must be names using the test name and suffixed by .IN
# ex for tests/test01.IN and tests/test02.IN: SET(SIM_TESTS_DATASETS test01 test02)
#SET(SIM_TESTS_DATASETS )

File CMakeLists.txt containing the build system using the OpenFLUID CMake module

CMAKE_MINIMUM_REQUIRED(VERSION 2.8)

INCLUDE(CMake.in.config)

FIND_PACKAGE(OpenFLUID REQUIRED core base tools ware)

OPENFLUID_ADD_SIMULATOR(SIM)