Upgrading to a new version

From OpenFLUID

This article deals with the upgrade of your code and data formats according to a specific version of the OpenFLUID API. As the API is updated, code based on previous versions may not work. Follow the instructions below to get your code to work.
As a general advice, it is strongly recommended to remove any binary objects from the previous version of the simulations functions before compiling and using them with the new version of OpenFLUID. This includes

From 1.6.2 to 1.7.x

Mandatory modifications

OPENFLUID_IsScalarVariableExist and OPENFLUID_IsVectorVariableExist methods are not available anymore. Instead you can use the following methods:

• OPENFLUID_IsVariableExist for testing the type of a value of a variable
• OPENFLUID_IsTypedVariableExist for testing the type of a variable

Recommended modifications

You should use the DoubleValue type instead of the ScalarValue type (deprecated).

You should use the getInfoAsDoubleValue method (Event class) instead of the getInfoAsScalarValue (deprecated).

In function signatures, you should use the "myvectorvariable[vector]" syntax for VectorValue variables, instead of the "myvectorvariable[]" syntax (notice the word "vector" between square brackets).

In outputs definitions (section output of .fluidX files), you should remove the brackets following the variables names.

As a general recommendation, prefer passing arguments of methods by reference instead of passing arguments by pointer, wherever it is possible. Many methods has been added or modified in the 1.7.0 API to allow passing arguments by reference.

From 1.6.x to 1.6.2

Events lists in events collections are not lists of pointers anymore. A dedicated type is available : openfluid::core::EventsList_t. openfluid::core::EventCollection now returns openfluid::core::EventsList_t instead of std::list<openfluid::core::Event*>.

example:

openfluid::core::Unit *CurrentUnit;
openfluid::core::EventsCollection EvColl;
openfluid::core::EventsList_t *EvList;
openfluid::core::DateTime BeginTime, EndTime;
 
// set BeginTime and EndTime values
 
BEGIN_UNITS_ORDERED_LOOP(1,"SU",CurrentUnit);
 
  OPENFLUID_GetEvents(CurrentUnit,BeginTime,EndTime,&EvColl);
  EvList = EvColl.getEventsList();
 
  // do domething with events lists
 
END_LOOP

From 1.5.x to 1.6.x

API

#include files

Header files to include in the main source file of the simulation function are now <openfluid/core.hpp> and <openfluid/base.hpp> (and also the optional <openfluid/tools.hpp>) instead of "openfluid-core.h" and "openfluid-base.h" (and also the optional "openfluid-tools.h")

#include <openfluid/core.hpp>
#include <openfluid/base.hpp>

OPENFLUID_xxx methods

Some OPENFLUID_XXX methods have been slighly modified, in particular for parameters passing. This affects:
 - OPENFLUID_GetUnitsCount()
See [API documentation] for details.

Run configuration in input dataset

The progressive output mode does not exist anymore, replaced by a buffering system for memory and files. See Documentation for parameterization of this buffering system.

From 1.4.2 to 1.5.0

Events in input dataset

The calendar section of input dataset must be placed into a domain section

<?xml version="1.0" standalone="yes"?>
<openfluid>
  <domain>
    <calendar>
 
      <event name="" category="test" unitclass="TestUnits" unitID="1" date="1999-12-31 23:59:59">
        <info key="when" value="before"/>
        <info key="where" value="1"/>
        <info key="numeric" value="1.13"/>
        <info key="string" value="EADGBE"/>
      </event>
      <event name="" category="test" unitclass="TestUnits" unitID="1" date="1999-12-01 12:00:00">
        <info key="when" value="before"/>
        <info key="where" value="1"/>
        <info key="numeric" value="1.13"/>
        <info key="string" value="EADG"/>
      </event>        
 
    </calendar> 
  </domain>  
</openfluid>

Input data format

TODO

From 1.4.1 to 1.4.2

No change!

From 1.4.0 to 1.4.1

Events

The name of the openfluid::core::DistributedEvent class is now openfluid::core::Event.

Signature macros

The SU, RS and GU (DECLARE_SU_PRODUCED_VAR, DECLARE_RS_REQUIRED_VAR, ...) based macros are no longer available. Use new macros (see "From 1.3.x to 1.4.0").

API

The name of some methods attached to API classes has been modified for correct spelling.

From 1.3.x to 1.4.0

Input files

The input files formats have changed:

• Spatial domain definition files are now XML
• Tags in input data files are slighly different
• New options are available in run.xml file (mainly for progressive output configuration)
• Output configuration file format has changed. See documentation.

Refer to user manual for description of these file formats

Signature

The declaration of handled data in signature has changed in order to take into account generic units features. Old declaration macros are still available but are now deprecated. You are really encouraged to use new declaration macros. The wxT macro around strings (for wxString) are no longer needed and must be removed.

As examples:

• DECLARE_SU_PRODUCED_VAR("water.atm-surf.H.rain","rainfall height on each SU by time step","m") becomes DECLARE_PRODUCED_VAR("water.atm-surf.H.rain","SU","rainfall height on each SU by time step","m")
• DECLARE_RS_REQUIRED_PROPERTY("nmanning","Manning roughness coefficient","s/m^(-1/3)") becomes DECLARE_REQUIRED_INPUTDATA("nmanning","RS","Manning roughness coefficient","s/m^(-1/3)")
• DECLARE_USED_SU_EVENTS becomes DECLARE_USED_EVENTS("SU")

Refer to API reference guide for available and deprecated signature declarations

Type of domain units

The types for domain units openfluid::core::SurfaceUnit, openfluid::core::ReachSegment, openfluid::core::GroundwaterUnit does not exist anymore. Now all units are openfluid::core::Unit.

example:

openfluid::core::Unit *RS;
openfluid::core::Unit *SU;

Access to input data

Former "properties", "initial conditions", and "physical descriptions" are now gathered as "input data".
In order to access to these input data, use the OPENFLUID_GetInputData primitive instead of former OPENFLUID_GetProperty, OPENFLUID_GetIniCondition, or method of units for physical description (SU->getUsrSlope(), RS->getUsrLength(), ...)

Primitive OPENFLUID_SetProperty is no longer available.

example:

openfluid::core::ScalarValue ThetaS, ThetaI, Slope;
 
OPENFLUID_GetInputData(SU,"slope",&Slope);
OPENFLUID_GetInputData(SU,"thetasat",&ThetaS);
OPENFLUID_GetInputData(SU,"thetaisurf",&ThetaI);

Access to connected units

To access to connected units, linked using the defined oriented topology, use the getToUnits(UnitClass_t aClass) and getFromUnits(UnitClass_t aClass) methods of the processed unit.

example:

openfluid::core::UnitsPtrList_t* UpSUsList;
openfluid::core::UnitsPtrList_t* DownRSsList;
 
UpSUsList = SU->getFromUnits("SU");
DownRSsList = SU->getToUnits("RS");

initParams() method

The type of the initParams method parameter named "Params" has changed. The new correct type is openfluid::core::FuncParamsMap_t.

example:

bool ExFunc::initParams(openfluid::core::FuncParamsMap_t Params)
{
  // do params process here
  return true;
}

Loops on units

The loops on units have changed in order to take into account generic units features. Old loops on units are still available but are now deprecated. You are really encouraged to use new loops on units.

example:

openfluid::core::Unit TU;
DECLARE_UNITS_ORDERED_LOOP(1)
 
// loop on the TestUnits class
BEGIN_UNITS_ORDERED_LOOP(1,"TestUnits",TU)
  // do some stuff here
END_LOOP

From 1.2 to 1.3.x

Data files format

The changes in data files format is the replacement of the <mhydas> tag by the <openfluid> tag in XML files.

Names and identifiers

The following table presents the corresponding names from the 1.2 version (left) to 1.3 version (right). You have to do the modifications in your source code to match the new names.

To use the OPENFLUID_GetRunEnvironment with the correct parameters, please read the simulation function developer (see documentation).

Vector values

Because of lack of performance, the management class for vectors has been modified. The std::vector class has been abandonned and has been replaced by the openfluid::core::Array class. All necessary information about the openfluid::core::Array class is available through the simulation function development documentation.

Date and time management

Due to a daylight saving time bug, the use of wxDateTime for time representation and management has been abandonned.

Date and time are now managed and available through openfluid::core::DateTime objects.

Makefiles

The name of the config tool used to give the correct compilation options has changed. It is now called ofelib-config. Modify you makefiles to use the new name. If you have generated your makefiles through the eclipse plug-in, the modification have to be done in the top part of the makefile.

From 1.1 to 1.2

Model and run configuration

• The simulation period is now defined with begin and end dates. This period has to be given in the run.xml file. The time step is also given through this file.

<?xml version="1.0" standalone="yes"?>
<mhydas>
  <run>
    <deltat>60</deltat>
    <period begin="1997-06-05 04:00:00" end="1997-06-05 16:23:00" />
  </run>
</mhydas>

• The runparams section has to be removed from the model.xml file

Removing explicit rain access

Access to rain using the MHYDAS_GetDistributedRainValue(...) primitives is not allowed anymore. You have to remove calls to this primitive from your source code.

Get access to rain through simulation variables

To get rain values on SU and RS as forcing data, you can use two simulation functions : water.atm-surf.rain-su.files and water.atm-surf.rain-rs.files. These functions use rainfall files and spatial distribution files for prodution of rain values on units. Note that the rain values are now given in m by timestep, instead of former m/s by timestep. You may adapt your simulation functions to take into account the new values unit.

These functions use a rainsources.xml file (see below), defining the rain sources. The rain distribution file for SU has to be named SUraindistri.dat. The rain distribution file for RS has to be named RSraindistri.dat. The formats of these files are the same as the previous version of MHYDAS-engine (when rain was managed by the kernel and not by simulation functions).

<?xml version="1.0" standalone="yes"?>
<mhydas>
  <datasources>
    <filesource ID="3" file="rainfile3.txt" />
    <filesource ID="4" file="rainfile4.txt" />
    <filesource ID="5" file="rainfile5.txt" />
  </datasources>
</mhydas>

Date and time management

Dates and times are now managed by the wxDateTime class. Remove all references and calls to the deprecated mhydasdk::core::DateTime class.

From 1.0 to 1.1

Plugin hooks

The plugin hooks have been modified. The signature has been detached from the simulation function for better versions handling. the declaration have to be done in the .h file, the definitions of the signature hook and the simulation function hook have to be done in the .cpp file.

• The declaration have to be placed in the end of the .h file. This is done using the DECLARE_PLUGIN_HOOKS macro.

DECLARE_PLUGIN_HOOKS;

• The following code has to be removed, as it is replaced by the previous code.

extern "C" 
{ 
  DLLIMPORT mhydasdk::base::PluggableFunction* GetMHYDASPluggableFunction(); 
};

Signature

• The signature has to be declared outside the simulation function class

BEGIN_SIGNATURE_HOOK
  DECLARE_SIGNATURE_ID(wxT("example")); 
  DECLARE_SIGNATURE_NAME(wxT("Example simulation function"));
  DECLARE_SIGNATURE_DOMAIN(wxT("dummy"));
  DECLARE_SIGNATURE_STATUS(mhydasdk::base::BETA);
 
  // here the rest of the signature using classic macros
 
END_SIGNATURE_HOOK

• Every macro used to define the signature has to be removed from the simulation function class constructor

Simulation function

• The simulation function hook is defined in the .cpp file, using the DEFINE_FUNCTION_HOOK macro with the name of the class as argument.

DEFINE_FUNCTION_HOOK(MyFunc);

• The following code has to be removed, as it is replaced by the previous code.

mhydasdk::base::PluggableFunction* GetMHYDASPluggableFunction() 
{ 
  return new MyFunc(); 
}

Input data files

Rain

• The file containing the rain data references has to be renamed from rainevent.xml to rainsources.xml.
• The format of the file rainsources.xml has been changed. The new format must look like this

<?xml version="1.0" standalone="yes"?>
<mhydas>
  <rainsources>
    <raindata ID="4" file="pluvio4.dat" />
    <raindata ID="5" file="pluvio5.dat" />
    <raindata ID="3" file="pluvio3.dat" />
  </rainsources>
</mhydas>

Distributed data

Initial conditions and properties files are now considered distributed data files.

• These files have to be renamed with the whatyouwant.ddata.xml file name pattern, where whatyouwant is a name which means something for you. Example: SUini.xml could be renamed as SUini.ddata.xml

• The format has changed too. The file for distributed initial conditions on SU should look like this:

<?xml version="1.0" standalone="yes"?>
<mhydas>
  <distridata unitclass="SU" datacat="ini">
    <columns order="thetaisurf;thetains" />
    <data>
 
1	0.3	0.2
2	0.3	0.2
3	0.3	0.2
4	0.3	0.2
5	0.3	0.2
6	0.3	0.2
7	0.3	0.2
 
    </data>
  </distridata>
</mhydas>

The unitclass attribute could be "SU", "RS", or "GU" (I really don't know why ...:-))

The datacat attribute could be "ini" for initial conditions, or "param" for parameters (aka properties)

MHYDAS data types

• For scalar data, MHYDASValue has been renamed to MHYDASScalarValue
• For vector data, VectorizedMHYDASvalue has been renamed to MHYDASVectorValue

These two types are defined into the namespace mhydasdk::core

example:

mhydasdk::core::MHYDASScalarValue TmpScalarValue;
mhydasdk::core::MHYDASVectorValue TmpVectorValue;

Simulation infos and status

• Simulation informations and status are now passed to the simulation functions as const pointers. This avoids modification of simulation infos and status from inside simulation functions

• initializeRun(mhydasdk::base::SimulationInfo* SimInfo) has to be replaced by initializeRun(const mhydasdk::base::SimulationInfo* SimInfo), runStep(mhydasdk::base::SimulationStatus* SimStatus) by runStep(const mhydasdk::base::SimulationStatus* SimStatus), and finalizeRun(mhydasdk::base::SimulationInfo* SimInfo) by initializeRun(const mhydasdk::base::SimulationInfo* SimInfo). Note the const keyword added.

• Those replacements have to be done in both header and implementation files (.h and .cpp).