Creation of an empty simulator

Table of Contents

• Required tools for development environment
• Writing the signature
• Writing the C++ class for the simulator
• Building the simulator
• Complete example
  • File ExampleSimulator.cpp containing the simulator source code
  • File CMake.in.config containing the build configuration
  • File CMakeLists.txt defining the build process

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

Required tools for development environment

In order to build and develop a simulator, the following tools are required:

• GCC as the C++/C/Fortran compiler (version 4.8 or later for C++11 compatibility)
• CMake as the build configuration tool (version 2.8.12 or later).
  OpenFLUID provides a CMake module to ease the build of simulators.

These tools are also required when using the OpenFLUID-DevStudio application. Detailed instructions for installation of these tools are available on the OpenFLUID Community web site (http://www.openfluid-project.org/community).

The OpenFLUID-DevStudio is the recommended environment for simulators development, and is the only one which is officially supported for OpenFLUID wares development.

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 parameters
• 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 overview of the 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-DevStudio application.

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 directive 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>


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


BEGIN_SIMULATOR_SIGNATURE("example.simulator")

  DECLARE_NAME("Example simulator");
  DECLARE_DESCRIPTION("This simulator is an example");
  DECLARE_VERSION("14.07");
  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
# ex: SET(SIM_ID "my.simulator.id")
SET(SIM_ID "example.simulator")

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

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


# list of extra OpenFLUID libraries required
# ex: SET(SIM_OPENFLUID_COMPONENTS tools)
SET(SIM_OPENFLUID_COMPONENTS )

# 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 "-DDebug")
#SET(SIM_DEFINITIONS )


# unique ID for linking parameterization UI extension (if any)
#SET(WARE_LINK_UID "{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}")

# set this to ON to enable parameterization widget
# ex: SET(SIM_PARAMSUI_ENABLED ON)
SET(SIM_PARAMSUI_ENABLED OFF)

# list of CPP files for parameterization widget, if any
# ex: SET(SIM_PARAMSUI_CPP MyWidget.cpp)
SET(SIM_PARAMSUI_CPP )

# list of UI files for parameterization widget, if any
# ex: SET(SIM_PARAMSUI_UI MyWidget.ui)
SET(SIM_PARAMSUI_UI )

# list of RC files for parameterization widget, if any
# ex: SET(SIM_PARAMSUI_RC MyWidget.rc)
SET(SIM_PARAMSUI_RC )


# set this to ON to enable translations
#SET(SIM_TRANSLATIONS_ENABLED ON)

# set this to list the languages for translations
#SET(SIM_TRANSLATIONS_LANGS fr_FR)

# set this to list the extra files or directories to scan for strings to translate
#SET(SIM_TRANSLATIONS_EXTRASCANS )


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


# set this to ON or AUTO for build of simulator documentation using sim2doc
SET(SIM_SIM2DOC_MODE ON)

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

# 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 defining the build process

CMAKE_MINIMUM_REQUIRED(VERSION 2.8)

INCLUDE(CMake.in.config)

FIND_PACKAGE(OpenFLUIDHelpers REQUIRED)

OPENFLUID_ADD_SIMULATOR(SIM)