Experienced Modgen Developer - openmpp/openmpp.github.io GitHub Wiki

Home > Model Development Topics > Experienced Modgen Developer

This topic contains a grab bag of subtopics of possible interest to model developers who are experienced in using Modgen.

• Model Code

• The End of Start
• Simplified iteration of range, classification, partition
• Parameter and table groups can be populated by module names
• hook to self-scheduling or trigger attribute

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.

[back to topic contents]

OpenM++ implements enhancements which can simplify model code which iterates ranges, classifications, or partitions. As the title of this post suggests, this was implemented some time ago, when ranges, classifications, and partitions were originally implemented in OpenM++ circa 2015.

The enhancement is not Modgen-compatible, so was of limited interest at the time. But it’s of greater interest now, with Modgen in the rear-view mirror.

It is not currently documented in the wiki but should be, in a dedicated topic on enumerations (ranges, classifications, partitions). There was no wiki back then, and documentation of ompp-exclusive features was typically communicated via email.

Here’s a sketch and some examples:

In OpenM++, any range, classification, or partition has a special member function indices(), which is designed to be used in a C++ “range-based for” statement. Here’s an example from GMM, where RISK_FACTOR is a classification:

// Verify that SimulateRiskFactor is true if the risk factor is passed to Boadicea in RA_BoadiceaUseRiskFactor.
for (auto j : RISK_FACTOR::indices()) {
    if (RA_BoadiceaUseRiskFactor[j] && !SimulateRiskFactor[j]) {
        ModelExit("Risk factors passed to Boadicea in RA_BoadiceaUseRiskFactor must be simulated in SimulateRiskFactor");
        break; // not reached
    }
}

The auto keyword is not required, one could use int (or size_t for the illuminati). I tend to use auto wherever it works, for code simplicity and generality. auto is a message from the coder to the C++ compiler which says: “You know what I mean, figure it out yourself”.

Here’s another example, where ONCOGENESIS_AGE_GROUP is a partition, and ONCOGENESIS_LAG is a range:

for (auto j : ONCOGENESIS_AGE_GROUP::indices()) {
    for (auto k : ONCOGENESIS_LAG::indices()) {
        double dValue = OncogenesisLags[j][k];
        SetTableValue("IM_OncogenesisLags.VALUE", dValue, j, k);
    }
}

For ranges, OpenM++ also includes the member function values(), which iterates the values of the range rather than the indices. Here’s an example where YEAR is a range:

for (auto year : YEAR::values()) {
    if (year == 1970) {
        theLog->logMsg("begin peak disco decade");
    }
}

A possible enhancement might be a member function for ranges which iterates indices and values as a std::pair, allowing one to access either inside the same range-based for, something like:

for (auto pr : YEAR::indices_values()) {
    auto j = pr.first();
    auto year = pr.second();
    …
}

[back to topic contents]

In Modgen models, parameter and table groups often duplicate the organization of modules. Creating and maintaining these groups can be tedious and clutter model code. It can also be error-prone because it's easy to forget to include a newly added parameter or table into its group, with the forgotten symbol becoming a top-level 'orphan' symbol in the UI.

There's a better way to group parameters and tables by module in OpenM++.

You can specify that all declarations in a module become elements of a named group. For example, the following code fragment in RiskPaths specifies that all tables declared in the Tables.mpp module are elements of the table group TG0_AllTables:

table_group TG0_AllTables //EN All tables in Tables.mpp
{
    "Tables.mpp"
};

The double quotes around the module name are required.

Group declarations can contain multiple module names and mixtures of module names, other groups, and symbols. A module name is expanded into a list of the symbols declared in the module in lexicographical order, exactly as if they had been typed in manually. The elements of groups containing module names will automatically track the current declarations of parameters and tables in the modules of your model. For example, if you re-organize the table declarations in your model to move validation tables to new distinctly-named modules to split them from release tables, you can create a group for them by using the new module name. At the same time, when you move the declaration of a validation table to the new module, it will automatically be removed from the release group of tables, if the module syntax is used.

For more on groups, please see this wiki topic.

[back to topic contents]

Self-scheduling and trigger derived attributes can be very convenient in model code. For example, self_scheduling_int(time) implicitly creates a hidden event which implements an annual calendar clock which updates the attribute.

OpenmM++ takes self-scheduling and trigger attributes to another level by allowing hooks to them.

So, for example, one can do

entity Person {
   hook NewYear, self_scheduling_int(time);
};

to call the model-specific entity function Person::NewYear() when time crosses an integer boundary, without having to explicitly code a clock-like event in model code.

Here's another example which outputs microdata at age 65 using the built-in entity function write_microdata.

entity Person {
   int integer_age = self_scheduling_int(age);
   hook write_microdata, trigger_entrances(integer_age, 65);
};

For a bit more on this, see the Entity Function Hooks wiki topic.

[back to topic contents]