[santiagomarquezd]

Hi all, I spent some hours overnight to understand how turbulence models are selected by the run time selection mechanism, the best commentary I've read was by marupio:

"4.3.5 When does this all happen?

The "virtual constructor" table is fully built and loaded into memory when the include list is fully read, and before the first line of code is executed. This is achieved using the static keyword. All static members of a class exist prior to any instance of that class."

OpenFOAM guide/runTimeSelection mechanism

For example en turbulenceModel.C

   75 
   76 autoPtr<turbulenceModel> turbulenceModel::New
   77 (
   78     const volVectorField& U,
   79     const surfaceScalarField& phi,
   80     transportModel& transport,
   81     const word& turbulenceModelName
   82 )
   83 {
   84     // get model name, but do not register the dictionary
   85     // otherwise it is registered in the database twice
   86     const word modelType
   87     (
   88         IOdictionary
   89         (
   90             IOobject
   91             (
   92                 "turbulenceProperties",
   93                 U.time().constant(),
   94                 U.db(),
   95                 IOobject::MUST_READ_IF_MODIFIED,
   96                 IOobject::NO_WRITE,
   97                 false
   98             )
   99         ).lookup("simulationType")
  100     );
  101 
  102     Info<< "Selecting turbulence model type " << modelType << endl;
  103 
  104     turbulenceModelConstructorTable::iterator cstrIter =
  105         turbulenceModelConstructorTablePtr_->find(modelType);
  106 
  107     if (cstrIter == turbulenceModelConstructorTablePtr_->end())
  108     {
  109         FatalErrorIn
  110         (
  111             "turbulenceModel::New(const volVectorField&, "
  112             "const surfaceScalarField&, transportModel&, const word&)"
  113         )   << "Unknown turbulenceModel type "
  114             << modelType << nl << nl
  115             << "Valid turbulenceModel types:" << endl
  116             << turbulenceModelConstructorTablePtr_->sortedToc()
  117             << exit(FatalError);
  118     }
  119 
  120     return autoPtr<turbulenceModel>
  121     (
  122         cstrIter()(U, phi, transport, turbulenceModelName)
  123     );

The general turbulence model indicated in constant/turbulenceProperties, for example "RASModel", is searched in the turbulenceModelConstructorTable (lines 104-105). Next if it is found the proper constructor is called, if not, an error is presented in stdout. I've walked through the code using gdb until these lines and checked the Hash Table. I wasn't be able to see the contents of the table entries, but they are three, I guess they're RASModel, LESModel and laminar. Clearly this table was created and filled before any turbulence model is instantiated. I found the macros which define the method to create the table and add the entries but I couldn't find the very moment when they're are called such as marupio wrote. They are static so they are available before the objects are instantiated, but they need to be invoked in some code line. This was also a question of Jaswinder,

http://www.cfd-online.com/Forums/ope...nderstand.html

I've read other material about this topic, such as:

Run-time type selection in OpenFOAM – the type name system

but the point of when these tables are created and how isn't completely clear for me yet.

All commentaries are appreciated!

Santiago.

[wyldckat]

Greetings Santiago,

OK, this is a bit strenuous to detail every single step with showing the actual code (and it's already done in the other pages), so I'll have to describe this in a more conceptual way.

First of all, let's approach a few initialization programming paradigms in a not very technical way, while keeping in mind that the technical terms and examples can be found here: http://www.cplusplus.com/doc/tutorial/

1. Classes have constructors, which can initialize internal variables in two major ways:
   1. Define it in the initialization section, for example:
      

      Rectangle::Rectangle (int a, int b) :
        width(a),
        height(b)
      {
        //Nothing else needed here, at least not in this case
      }

   2. Define it in the method's code section,
      

      Rectangle::Rectangle (int a, int b)
      {
        width = a;
        height = b;
      }

2. The difference between the two is that:
   1. The first way does the initialization in the first stages when the memory is being allocated for an instance of this class, e.g.:
      

      Rectangle box(1,2);

   2. The second way does the initialization as if it were calling a method. For example, it would be as if you did this:
      

      Rectangle box;
      box.set(1,2);

3. Now, if you define the variable with the initial values in the global memory area of the program, e.g.:
   

   Rectangle box(1,2);
   
   int main()
   {
     cout << box;
     return 0;
   }

   This means that the variable "box" is initialized even before the "main" function is called for execution.
4. When libraries are involved, it's almost the same thing, if you define variables in the global memory region. Worse even is that it's very hard to have control over which is loaded first into memory... but that's a topic for a whole other discussion.

Now, with these concepts in mind, we can easily describe how the "RunTimeSelectionTable" mechanism works in OpenFOAM:

1. If we look at the file "src/turbulenceModels/incompressible/turbulenceModel/turbulenceModel.C", we can find this line:
   

   defineRunTimeSelectionTable(turbulenceModel, turbulenceModel);

   • This is the equivalent to the other example:
     

     Rectangle box(1,2);

     albeit with a lot more macro-voodoo-magic in the middle.
2. This line will essentially create a new global variable "turbulenceModelConstructorTablePtr_", which can later be used by the method "turbulenceModel::New()" a few lines below in the same file. Keep in mind that at first this variable is not populated with the whole list of turbulence models, because that's the next step.
3. Since "turbulenceModelConstructorTablePtr_" is a global+shared variable, this means that it can be populated by any other class or library. That's where this line:
   

   addToRunTimeSelectionTable(turbulenceModel, laminar, turbulenceModel);

   comes into play. This is in the file "src/turbulenceModels/incompressible/turbulenceModel/laminar/laminar.C".
4. The line "addToRunTimeSelectionTable" will create a new global variable, but which isn't directly used. Weird, isn't it?
   But the trick is that this line:
   

   addToRunTimeSelectionTable(turbulenceModel, laminar, turbulenceModel);

   does something similar to this example:
   

   ElementRect cube(1);

   where the class "ElementRect" has this constructor:
   

   ElementRect::ElementRect(int edgeLength)
   {
     box.set(edgeLength, edgeLength);
   }

5. Therefore, the example will roll out to something like this:
   

   Rectangle box(1,2);
   ElementRect cube(1);
   
   int main()
   {
     cout << box;
     return 0;
   }

   where the "box" is first defined to have dimensions of "1x2", but then the "cube" variable overrides the dimensions of the initial "box" settings.
6. For our turbulence code, it conceptually becomes something like this:
   

   //global pointer in "turbulenceModel.C" variable which will have the table
   static turbulenceModelConstructorTable* turbulenceModelConstructorTablePtr_;
   
   //laminar model adds itself to the global table, in "laminar.C"
   turbulenceModel::addlaminarConstructorToTable<turbulenceModel>        addlaminarConstructorToturbulenceModelTable_();

   Confusing? Well, the actual step of creating the instance of the object for "turbulenceModelConstructorTablePtr_" to point to, is done from within the constructor of the variable "addlaminarConstructorToturbulenceModelTable_" .
7. In our example, it would be something like this:
   

   ElementRect::ElementRect(int edgeLength)
   {
     box = new Rectangle(edgeLength, edgeLength);
   }
   
   //snip snip...
   
   Rectangle* box;
   ElementRect cube(1);

So, to answer your question, have a look at the file "src/OpenFOAM/db/runTimeSelection/construction/runTimeSelectionTables.H":

1. This block of code:
   

       void baseType::construct##argNames##ConstructorTables()                   \
       {                                                                         \
           static bool constructed = false;                                      \
           if (!constructed)                                                     \
           {                                                                     \
               constructed = true;                                               \
               baseType::argNames##ConstructorTablePtr_                          \
                   = new baseType::argNames##ConstructorTable;                   \
           }                                                                     \
       }

   Does the same as our example:
   

   box = new Rectangle(edgeLength, edgeLength);

2. This block of code:
   

           add##argNames##ConstructorToTable                                     \
           (                                                                     \
               const word& lookup = baseType##Type::typeName                     \
           )                                                                     \
           {                                                                     \
               construct##argNames##ConstructorTables();                         \
               if (!argNames##ConstructorTablePtr_->insert(lookup, New))         \
               {                                                                 \
                   std::cerr<< "Duplicate entry " << lookup                      \
                       << " in runtime selection table " << #baseType            \
                       << std::endl;                                             \
                   error::safePrintStack(std::cerr);                             \
               }                                                                 \
           }                                                                     \

   1. Uses this line:
      

      construct##argNames##ConstructorTables();

      to call the function defined on the previous point.
   2. Then uses this code:
      

      argNames##ConstructorTablePtr_->insert(lookup, New)

      to add itself to the list. Therefore, this is where the global table is populated.

As to when: it's done while the libraries are still being loaded up and initialized into the application's memory regions, even before the "main" method is called for the application itself. This means that it's considerably hard to use any debugger to pinpoint this moment of construction and population, since it occurs before the application starts processing the "main" function. I say this because AFAIK, few debuggers support this feature... worse even if libraries are involved.

Best regards,
Bruno

[tomislav_maric]

Hi Santiago,

have you seen my blog post on the RTS implementation? If you go through the steps described there very carefully, you'll see that the table initialization is encapsulated in the nested class template generated by the macro.

" That is it, the initialization of the addAlgorithmBaseWordConstructorToAlgorithmBaseTabl e_ object takes care of adding the “constructor” of the class to the run-time type selection table."

This constructor calls the class static function that creates the table, in case it has not yet been created:

addWordConstructorToTable ( const word& lookup = AlgorithmBaseType::typeName )
{
    constructWordConstructorTables();

So, to see when the tables are created, you have to see when the object of the type addWordConstructorToTable is initialized. It is a global object...

The constructor of this object calls the static function responsible for creating the table. The function is static, because the table is a class-static object: there are as many tables as there are RTS enabled classes in OpenFOAM. If the RTS tables would be initialized as objects, the order of their initialization would be undefined, because that's just how C++ works. Therfore, the creation is packed in the static class function. Having them initialized in an undefined order might result in the attempt of the derived RTS class to add its constructor to the yet uninitialized RTS table of the base class. Boom.


I had a lot of difficulties in writing that post, because the system is a bit complex: it uses nested class templates, static as well as global objects, etc...

I hope this helps somewhat..

[santiagomarquezd]

Thanks Bruno for the complete explanation! Respect to the Tomislav question, yes I've read your material but still couldn't find the moment when tables are created. I've prepared some slides explaining the RTS with the macros and the calling sequence for a real case (extracted by debugging). The topic of when the tables are created is not explained but the mechanisms are shown. I've took some concepts and paragraphs of you and the credits are added,

https://drive.google.com/file/d/0B2l...it?usp=sharing

I hope more people got involved and add their knowledge here!.

Regards.

[wyldckat]

Greetings to all!

@Santiago: Many thanks for compiling+sharing that document!
I gave a quick read to it and didn't find anything wrong with it, but I didn't double-check every single detail either .


Honestly, there is already tons of knowledge here on the forums, on the conferences/workshops, open+public+online courses and so on.
The problem is that there are very few people that are compiling this information into more convenient/consolidated formats/locations. The best couple of places where I know this can be consolidated is at http://openfoamwiki.net and at the Cocoons Project, but people are usually more keen on using the formats/locations they're more familiar with ... hence information gets dispersed and only those who know what to look for will find the answers... oh well.

Best regards,
Bruno

[tomislav_maric]

Originally Posted by santiagomarquezd

Thanks Bruno for the complete explanation! Respect to the Tomislav question, yes I've read your material but still couldn't find the moment when tables are created. I've prepared some slides explaining the RTS with the macros and the calling sequence for a real case (extracted by debugging). The topic of when the tables are created is not explained but the mechanisms are shown. I've took some concepts and paragraphs of you and the credits are added,

https://drive.google.com/file/d/0B2l...it?usp=sharing

I hope more people got involved and add their knowledge here!.

Regards.

Cool that you assembled the document! I find that describing things like this often leads to new ways of understanding the problem. Also, thanks for adding credits, it would be great if you would add a link to that blog post in the future because cross-linking is what keeps the documentation alive and searchable...

As for the RTS table initialization, if you still don't understand when this happens, I would propose you try something out.

1. Get the application that selects objects either from the blog post, or from bitbucket.org/sourceflux.
2. Expand all the macros in that file using the macro expansion script.
3. Insert Info statements in interesting places: inside RTS table constructor functions, nested class template constructors, etc.
4. Save this file as the application C file.
5. Compile the application and run it.

Now you will be able to read the execution semantics of the RTS system in the console standard output. This should help you see that the object initialization (last line in the expanded macro) calls the creation static class function, which generates the class static HashTable object.

Hope this helps...

Tomislav

[tomislav_maric]

Originally Posted by wyldckat

Greetings to all!

Honestly, there is already tons of knowledge here on the forums, on the conferences/workshops, open+public+online courses and so on.
The problem is that there are very few people that are compiling this information into more convenient/consolidated formats/locations. The best couple of places where I know this can be consolidated is at http://openfoamwiki.net and at the Cocoons Project, but people are usually more keen on using the formats/locations they're more familiar with ... hence information gets dispersed and only those who know what to look for will find the answers... oh well.

Best regards,
Bruno

I believe that any kind of documentation that is searchable on the internet is a benefit to the community. I personally really love the blog form of documenting things for many reasons. Others may like PDF presentations like santiagomarquezd, some will edit the Wiki, some will contribute their part to the CocoonsProject. In the end, it's about taking spare time to provide help to others. Of course people will do that in the form that they like most - it's their time...

Yes I perfectly agree that the information is dispersed, but better to have people actually contributing to the community and having fun while doing so, then forcing people to just use wiki, or just use CocoonsProject, or just post on the forum, or to use any other "established" system(s)...

Variety is a sign evolution....

[zordiack]

I feel like this is totally related to my problem with duplicate entry errors. Can someone help me how to implement own turbulence model properly in -dev or 3.0.x? I'm guessing the use of makeRASModel(kOmegaSSTSASnew), which uses makeTurbulenceModel.H, also creates entries for base classes laminar, RASModel and LESModel in the custom library. Solvers then complain about those duplicate entries.

More details here:

http://www.cfd-online.com/Forums/ope...tml#post578060

[alexeym]

@zordiack,

Do you have test case? On my laptop all I have got is sigSEGV if I try to use the library.

[zordiack]

Here is one, modified pitzDaily.

Compile the new libs (kOmegaSSTSASnew) from the github link, run blockMesh, run simpleFoam.

[alexeym]

Hi,

When you do

makeBaseTurbulenceModel
(
    geometricOneField,
    volScalarField,
    compressibleTurbulenceModel,
    CompressibleTurbulenceModel,
    ThermalDiffusivity,
    fluidThermo
);

in myturbulentFluidThermoModels.C (the same thing with incompressible models) you readd lots of things runtime selection table (laminar, RAS, and LES in particular, yet you can check makeBaseTurbulenceModel macro for more details).

See pull request on Github with "corrected" variant. I am not sure that it is canonical way of defining new models, yet it compiles and solver does not complain about duplicate entries.

[zordiack]

Originally Posted by alexeym

Hi,

When you do

makeBaseTurbulenceModel
(
    geometricOneField,
    volScalarField,
    compressibleTurbulenceModel,
    CompressibleTurbulenceModel,
    ThermalDiffusivity,
    fluidThermo
);

in myturbulentFluidThermoModels.C (the same thing with incompressible models) you readd lots of things runtime selection table (laminar, RAS, and LES in particular, yet you can check makeBaseTurbulenceModel macro for more details).

See pull request on Github with "corrected" variant. I am not sure that it is canonical way of defining new models, yet it compiles and solver does not complain about duplicate entries.

This is great, the code is much cleaner now and it works Thank you so much for your help. The current implementation is something I tried to do, but I just went kind of one level too high.