Old Language Feature: The End of Start

[esseff]

Yes, that Start. Person::Start(a,b,c,d,e,f,…)

Modgen required that each entity had a single entity function named Start and a single entity function named Finish. In a complex model, that required a single Start with all possible arguments to handle the various ways to start an entity, most of which were unused in a given call. It also led to a monolithic Start function to handle all possible ways of starting an entity, in a ‘catch-all’ module. And it sometimes led to the creation of a special argument whose only purpose was to distinguish the different ways of starting an entity.

By design OpenM++ has no such requirement. An OpenM++ foundational design principle is to let the C++ language do its thing, as a powerful stand-alone language which is also fully integrated and understood by the IDE used by the model developer.

In ompp, there is nothing special about the name Start (or Finish). In fact, the ompp compiler omc contains no references whatsoever to Start or Finish. Instead, three entity member functions generated by the ompp compiler are called by model code to handle the lifecycle of an entity: initialize_attributes(), enter_simulation(), and exit_simulation().

This design freedom allows you to code a model without being limited to a single Start function, like Modgen was.
One way is to declare overloaded versions of Start, each specialized to start an entity in a different way. For example, to start a Person entity using a microdata Observation, one could declare (in an entity Person {...}; syntactic island) and define (in C++ code) the member function

void Person::Start(Microdata_ptr microdata_record);

and to start a Person entity as a newborn during the simulation, declare and define the member function

void Person::Start(Person_ptr mother);

and to clone a Person entity as an immigrant

void Person::Start(Person_ptr donor, int year_of_immigration);

These examples use a C++ language feature called “function overloading”, where different versions of the same named function are distinguished by the number, order, and types of arguments (aka the 'function signature').

Alternatively, different function names can be used, either if necessary to distinguish Start variants sharing the same 'function signature' or as a coding style choice, e.g.

void Person::Start_microdata(Microdata_ptr microdata_record);
void Person::Start_newborn(Person_ptr mother);
void Person::Start_immigrant(Person_ptr donor, int year_of_immigration);

Either way, the C++ implementation code for these functions can be located in its appropriate substantive module, e.g. StartPop.mpp, Fertility.mpp, Immigration.mpp.

[DominicGrenier]

That's quite interesting, thanks so much for sharing this.
Demosim's Start() function has become pretty busy and crowded and I see right away how our code could be simplified. But there's a few things i'm not 100% sure i understand...

When i look at the Start function in Demosim, I notice that the first statement is initialize_attributes() and the last statement is enter_simulation(). Is that all it takes to make it a "Start function" ?

So when i want to create a new entity (Observation in my example), I just need to create it (new) and call my custom Start function, Start_Obs. The presence of initialize_attributes() and enter_simulation() in the function will do the trick. Correct?

Also, obviously there are a few things that will be common to all Start functions (we'd have 4!). I assume this can be put in a Start_Common function which could be called from inside each of the custom Start_BlaBla functions... Correct?

Lastly, this might not be the best place to ask but I never really took the time to understand what you meant when you talked about syntactic islands. Can you point me to a short but comprehensive document that would explain this concept, what it is, when and how to use it, etc.

many thanks in advance

[esseff]

You wrote "Is that all it takes to make it a "Start function" ?".
Yes. If you use hooks to the function, you also need to insert a function call to control where the hook happens.

You wrote "The presence of initialize_attributes() and enter_simulation() in the function will do the trick. Correct?".
Exact!

You wrote " I assume this can be put in a Start_Common function which could be called from inside each of the custom Start_BlaBla functions... Correct?".
Should be fine. Haven't tried it, though. Let me know if you encounter issues. By design, OpenM++ does not look deeply into what you do in C++ (or care). The only exception is the C++ code in event time functions, which it looks at to figure out event dependencies.

You wrote "understand what you meant when you talked about syntactic islands".
I coined the term while writing documentation to explain how model code is structured. :-)
Yes, see this subtopic.
Quick version: A syntactic island is everything between a top-level ompp/modgen language keyword (like parameters or table) and the matching ; which terminates it. Everything else in a module is C++ and is passed on to the C++ compiler.

To be clear, the Start function, or multiple Start functions, are unique to each kind of entity. So, a Person entity and an Observation entity would each have their own. Different kinds of entity cannot share a common 'member' function.