Releases · openmpp/main

17 Feb 02:30

amc1999

v1.16.1

d4d339a

Bug fix release 16 of February 2024

20240216 : v1.16.1

This is a minor release and you can skip it if you are not using microdata.

Changes in this release

go oms: fix a read bug of microdata entity_key database column
c++ core: new option weighted_tabulation_allow_time_based
UI: notify user if microdata is empty in the model run (zero rows)
UI: handle errors in UI if database read return with error on server for parameter, output table or microdata
UI disk use: change refresh time if changed on the server

New option weighted_tabulation_allow_time_based

When turned on, the option weighted_tabulation_allow_time_based bypasses the OpenM++ prohibition on weighted_tabulation in time-based models. Thanks to Dominic Grenier and David Pelletier for pointing out the utility of weighted tabulation to perform alignment in a time-based model with a non-interacting weighted population.

Download source code and binaries:

Download release documentation archive:

Release documentation archive

Download cluster version (MPI):

IMPORTANT:
Full version of OpenM++ source code always included into "Download" links above.
Please do NOT use "Source code (zip)" or "Source code (tar.gz)" archives from "Assets" links below.
It is auto-generated by GitHub release tools and contains only half of OpenM++ source code.

Assets 14

14 Feb 02:36

amc1999

v1.16.0

c0e23c5

Model documentation release 13 of February 2024

20240213 : v1.16.0

Main features of this release:

create model documentation as part of model build
multiple changes and fixes in c++ and UI to support bilingual models
go oms API: compare microdata
go oms: add memory resources management to model run queue
go and UI: provide storage (disk space) management UI

Other changes:

c++ core: special handling for attributes with many enumerators
c++ core bilingual: use case sensitive search for translated messages
c++ Linux and MacOS makefile: for all models included in openM++ release use Windows-1252 code page
c++ core: fix input parameters multiple copies issue (rollback previous change to check run status at digest calculation)
c++ core: add -OpenM.Sqlite option for model.exe to simplify running the database connection string
c++ core: add -OpenM.SqliteFromBin option for model.exe to simplify running the database connection string
c++ core: drop support for legacy SparseTable feature
go: re-write delete of model, model run and workset to make it more robust
go oms API: add OM_COUNT_IF to conditionally count values in output tables or microdata at calculation and comparison
go oms API: allow to use scalar model parameters in output tables or microdata at calculation and comparison
go oms: allow to limit number of CPU cores available to the user model run queue
go oms API: fix model run queue pause bug, add API call to pause model run queue fro all users
go and UI: allow to delete multiple model runs or worksets in UI
UI: correctly detect user language (browser language) in UI
Docker build: allow to build c++ part from separate git branch

Model Documentation

This release includes a beta version of Model Documentation. Model documentation is built by default and accessible through the OpenM++ UI. It consists of two components which can work synergistically:

A configurable Symbol Reference of generated cross-referenced content on parameters, tables, enumerations, etc.,
optional stand-alone cross-linked authored model documentation which can include downloadable auxiliary material.
There are two versions of Model Documentation: user-oriented or developer-oriented, selected at build time using an option.

For a complete worked example of "Developer Edition" Model Documentation which combines the two components, see RiskPaths in this release by clicking on the model information icon on the landing page, on the model bar at the top of the UI, or in any context-sensitive information window.

To build the "User Edition" of RiskPaths Model Documentation, comment one line in the file RiskPaths/code/ompp_options.ompp. The RiskPaths worked example is fully French/English bilingual.

The UI opens automatically in the current language of the user’s browser but can be switched in the UI using the drop-down menu at the top right of the UI.

For more information on Model Documentation from the model dev and content dev perspective, please see the main topic in our wiki at
Model Documentation · openmpp/openmpp.github.io Wiki · GitHub.

Please note that the Model Documentation topic on the wiki is under extensive revision and may not reflect this new functionality at the time of this release.

A big shout-out to Claude Nadeau for very helpful feedback and suggested enhancements based on his review of an early alpha version of Model Documentation.

Multiple changes and fixes in c++ and in UI to support bilingual models

Special thanks to Daniel Blanchette who found many missing translations in UI and identified major issue with detecting user default language.

There are still known issues with switching UI language through the top right corner menu, we will be fixing it in the next releases.

Microdata run comparison

It is possible to compare microdata values between different model runs using command line tools and oms API (oms is openM++ web-service).

For example we can:

get CSV microdata values calculated as max( Income[variant] - Income[base] ) grouped by Person.Province, Person.AgeGroup
get CSV microdata values count_if ( Income[variant] - Income[base] > Parameter.Threshold ) grouped by Person.Gender

UI for microdata comparison will be implemented soon.

Enchantments elastic resource management (model run queue)

If you are using ERM (elastic resource management) for your cloud resources then now it is also possible:

specify model memory requirements to select servers for your model run
limit max number of CPU cores allowed for user(s)
assign storage quota (disk space limit) to users and to entire cluster
user can see and cleanup storage space in UI
user can delete multiple model runs or input scenario, delete all download or upload files through UI

More enchantments to ERM will be included into the next release.

More convenient options to specify model SQLite database path

By default model opens SQLIte database file ModelName.sqlite in current working directory. If it is not a default case then user must specify database connection string as model command line option (or ini-file option) and that connection string may be unnecessary complicated.

Thanks to Dominic Grenier who provide us multiple suggestions, we have now a simplified options for typical use cases. For example:

RiskPaths.exe  -db path/to/any-file-name.sqlite
my/models/RiskPaths/ompp/bin/RiskPathsD.exe -OpenM.SqliteFromBin

second option above allow to keep SQLite database file next to model.exe and not in the current directory.

Attributes with many enumerators

Attributes publishable as microdata are now filtered by configurable maximum enumerators (option microdata_max_enumerators, default 1000).

Microdata Output · openmpp/openmpp.github.io Wiki · GitHub

Download source code and binaries:

Download release documentation archive:

Release documentation archive

Download cluster version (MPI):

Assets 14

16 Nov 01:34

amc1999

v1.15.6

c8f4a08

Minor release 15 of November 2023

20231115 : v1.15.6

This is a minor release and it is recommended for all model developers.

Changes in that release:

c++ core: early error detection of unmatched comment, brace, parenthesis, bracket, or syntactic island
c++ core: new Model Metrics Report
c++ core: disable model build steps for speedier model code syntax checking
c++ core: new options which emit warnings for missing model symbol documentation
c++ core: new options which emit warnings for missing explicit names
c++ core: explicit short names can be used in //LABEL and /*NOTE
c++ core: event Trace can display table increments
c++ core: detect unrecognized option and raise error
c++ core: disable population scaling for a case-based model
dbcopy: suppress zero and/or null in csv output
go oms: use ini-file for run description to fix -Description bug
go oms API: in run comparison csv allow to use multiple variant runs, comma separated.
R: use openM++ models in cloud from local computer RStudio
UI: prevent user to leave parameter page if notes edited and not saved

Early error detection of unmatched comment, brace, parenthesis, bracket, or syntactic island

In this release, the OpenM++ compiler (omc) detects and emits an error message if it encounters an unmatched

C-style comment /* */
brace { }
parenthesis ( )
bracket [ ]
syntactic island, e.g. a syntactic island which is missing its trailing ‘;’

This error detection occurs for both ompp syntactic islands and for C++ code in model code.

The error will stop the build early in the ompp compilation phase before code generation and DB publishing, and before C++ compilation.

If the mismatch occurs at the end-of-file (EOF) of a code module, the error message indicates the line where the construct started, e.g. the opening /* of a C-style comment which had no finishing */.

For example, if a module HostCore.mpp contained an unterminated NOTE which started at line 364

   /* NOTE(Person.myfunc,EN)

the OpenM++ compiler would detect the error at the EOF of HostCore.mpp, but would emit the error message

1>../code/HostCore.mpp(364): error : unexpected EOF due to unmatched /* */.

to indicate line 364 where the comment started, rather than the last line of the module where the error was detected.

If a mismatch is detected before EOF due to a supernumerary closing brace/parenthesis/bracket, the error message gives the line where the error was detected followed by a note giving the line of the innermost preceding matching construct, e.g.

1>../code/HostCore.mpp(370): error : '}' without opening '{'.
1>../code/HostCore.mpp(364) : note: Location of innermost previous '{'.

The brace-matching capabilities of your IDE may help locate missing matching constructs, e.g. Ctrl-] in Visual Studio with the cursor after a brace, parenthesis, or bracket will navigate to the matching brace. Note that if there is no matching brace, Ctrl-] does nothing (but a red squiggly indicates the brace has no match).

Note: The OpenM++ compiler does not grammatically parse C++ code located outside of OpenM++ syntactic islands. This error condition is detected at a lower pre-grammatical level in the parsing process.

New Model Metrics Report

A Model Metrics Report is now produced by the OpenM++ compiler.
It summarizes code inputs, code outputs, model inputs, model outputs, model symbols, visibility to end users, and maintained dependencies.
For more information including an example using RiskPaths, please see

Model Metrics Report · openmpp/openmpp.github.io Wiki

Disable model build steps for speedier model code syntax checking

In Visual Studio, two Yes/No options have been added to Model Property Pages > Configuration Properties > OpenM++.

They are in the “Build Options” section of the dialog, with labels “Disable metadata publishing” and “Disable C++ build” (see screenshot below).

Turning both options on can significantly improve build speed for a big model when a syntax check of code changes is all that’s needed.

Evidently, turning on either of these options does not produce a functional model.

In a test of a large model, build time was reduced by ~8x (from ~2m to ~15s).

When changing these options, it’s probably better to Rebuild, rather than Build.

Thanks to Chantal for suggesting this enhancement.

New options which emit warnings for missing model symbol documentation

This enhancement implements a family of 15 options to help model developers identify and address missing label and note documentation in model code.

The 15 options target specific kinds of symbols and documentation. For example, one of the options targets missing translations of notes of published symbols.

When turned on, each option causes the OpenM++ compiler to issue a warning for each symbol which meets the option conditions.

The warnings contain file and line number and can be used to navigate directly to the relevant model code in an IDE.

For more, see: https://github.com/openmpp/openmpp.github.io/wiki/model-documentation#identifying-missing-symbol-documentation

Thanks to Claude Nadeau for pointing out the need for this enhancement and contributing to the design.

New options which emit warnings for missing explicit names

Explicit names replace default names like Dim2 in downloads with meaningful names like age_group.

This enhancement implements a family of 6 options to help model developers identify and address missing explicit names in model code.

When turned on, each option causes the OpenM++ compiler to issue a warning which meets the option conditions.

The warnings contain file and line number and can be used to navigate directly to the relevant model code in an IDE.

For more, see: https://github.com/openmpp/openmpp.github.io/wiki/external-names#identifying-missing-explicit-names

Explicit short names can be used in //LABEL and /*NOTE

In this release, the two-part name in a //LABEL or /*NOTE model documentation comment can use the explicit short name for the second part of name as an alternative to the Modgen naming scheme, e.g. MyTable.region instead of MyTable.Dim3.

For more on explicit short names, see:
https://github.com/openmpp/openmpp.github.io/wiki/external-names#explicit-name

For more on two-part names in model documentation, see:
https://github.com/openmpp/openmpp.github.io/wiki/model-documentation#symbol-labels-label-with-two-part-name-explicit-short-name

Event Trace can display table increments

An entity table is updated ‘on the fly’ during a run, in response to changes in entity attributes.

Event Trace now includes options to see these table increments in the context of the entity’s timeline.

For a worked example, see: https://github.com/openmpp/openmpp.github.io/wiki/Event-Trace#worked-example-4

Detect unrecognized option and raise error

In this version, the OpenM++ compiler will detect an unrecognized option and issue an error.

For example, the following statement

options autofix_model_logic = on;

will produce an error message like

1>../code/ompp_framework.ompp(45): error : unrecognized option 'autofix_model_logic'

Disable population scaling for a case-based model

A new use module which disables population scaling is included in this release.

This module (case_based/case_based_scaling_disable.ompp) scales each sub upwards by the number of subs in the run, which causes overall (average) run results to become the sums of the original (unscaled) subs. This can be helpful for microdata-based models which partition the starting microdata among subs to gain computational speed through parallel execution of subs.

Thanks to Dominic for working with us on the underlying issue.

For more, see: Population Size and Scaling · openmpp/openmpp.github.io Wiki

Dbcopy: suppress zero and / or null in CSV output

Some output tables may contain large amount of zero values or missing values (NULLs). You can suppress zero values and / or NULL (missing) values in output tables or microdata CSV files:

dbcopy -m modelOne -dbcopy.To csv -dbcopy.NoZeroCsv
dbcopy -m modelOne -dbcopy.To csv -dbcopy.NoZeroCsv=true
dbcopy -m modelOne -dbcopy.To csv -dbcopy.NoNullCsv
dbcopy -m modelOne -dbcopy.To csv -dbcopy.NoNullCsv=true
dbcopy -m modelOne -dbcopy.To csv -dbcopy.NoZeroCsv -dbcopy.NoNullCsv

Thanks to Dominic Grenier for suggestion.

Oms API: in run comparison CSV allow to use multiple variant runs, comma separated

There is an oms API method which allow to compare run output tables with arbitrary expressions and get results as CSV text file. Before it was possible to compare only two model runs, now you can supply multiple runs to compare. It can be a list of comma separated run digests (recommended) or run names or run stamps.

UI backend (oms): use ini-file for run description to fix -Description bug

There were a bug in UI and oms back-end which prevented user to supply model run description started with -dash. It fixed now.

UI: prevent user to leave parameter page if notes edited and not saved

If user were editing parameter notes and did not save it before clicking on other tab in UI then message box appears now prompting user to save the notes.

R: use openM++ models in cloud from local computer RStudio

It was a long standing request from many cloud R users to have an ability to use RStudio on their own Window...

Assets 14

06 Oct 01:18

amc1999

v1.15.5

c7ded36

Model runs comparison, first version: 10 of October 2023

20231005 : v1.15.5

There are multiple improvements and bug fixes in that release.
It is recommended for model developers and for model users who may want to model run comparison.

Changes in that release:

c++ core: implement suppress/retain of derived parameters exported as tables
c++ core: new EventTrace filter SelectedEntityKinds
c++ core: implement order by attribute in entity sets
c++ core: revised event dependency report
c++ core: experimental option for alternate attribute dependency implementation
c++ core: fix model run error if database contain multiple models (error introduced in May 2023)
c++ core: use only completed or in progress runs as base run
UI and oms API: output table run comparison
go oms API: allow to calculate arbitrary comparison or ad hoc measure
UI: bug fix : long dimension truncated in UI
UI and oms API: Fix data loss during run delete
UI and oms API: do not use failed runs as base run
UI: automatically lock-unlock input scenario on parameter edit and note edit
UI: automatically lock-unlock input scenario on parameter upload
UI: do not allow to open note editor and edit parameter values at the same time
UI: microdata: use boolean attributes as dimensions
Docker: use git version tag to build release
multiple bug fixes

Implement suppress/retain of derived parameters exported as tables

Derived parameters exported as tables using parameters_to_tables can now be used in tables_suppress / tables_retain statements.

New EventTrace filter SelectedEntityKinds

Event trace output can now be optionally filtered by the kind of entity, e.g. Person. This can be helpful in models with more than one kind of entity.
For more on Event Trace, please see the wiki topic:
Event Trace · openmpp/openmpp.github.io Wiki · GitHub

Revised event dependency report

The file name and content of the event dependency report has been revised.
For more information, see the wiki topic:
Events · openmpp/openmpp.github.io Wiki · GitHub

Implement order by attribute in entity sets

The order clause of an entity_set (aka actor_set) with an attribute argument is now implemented in OpenM++.
It is documented in the Modgen Developer’s Guide.

Experimental option for alternate attribute dependency implementation

An experimental option alternate_attribute_dependency_implementation is included in this release.

It is off by default.

This option activates an alternate ordering of computation which may produce more consistent results for simultaneous changes of interdependent self-scheduling attributes.

This appears to be an obscure condition absent from most model code.

Please contact us if you notice unexplainable differences in model results when probing model results with this option activated.

Output table run comparison

Users can select multiple model runs to compare results.

Model run summary dialog would provide a list of different parameters, output tables and microdata entities, it would also include a list of suppressed (missing) output tables and microdata entities.

In the output table viewer users can see the difference, ratio or percentage ratio of output values. It is also possible to download run comparison results as CSV file.

Through API, for example form R, users can invoke an arbitrary calculation to compare model runs, e.g.: 100 * ( (Pension[variant] - Pension[base]) - (Tax[variant] - Tax[base]) )

Bug fix: long dimension truncated in UI

Thank you to John Than for finding a UI bug when long dimension truncated in UI. The bug was introduced in May and fixed now.

Also UI hot fix released and Steven Kong with active help of John Than demonstrated an ability to instantly build UI hotfixes inside of secure perimeter and deploy it to the end users PCs.

UI and oms API: Fix data loss during run delete

Thank you to Roxanne Garaszczuk who discovered a rare case scenario when deletion of model run in UI can lead to data loss in the database.

Multiple fixes applied to back-end Go web-service (oms) to prevent this situation. Minor changes also applied to UI and c++ model core to prevent race conditions when user delete model run.

UI: automatically lock-unlock input scenario on parameter edit and note edit
UI: automatically lock-unlock input scenario on parameter upload
UI: do not allow to open note editor and edit parameter values at the same time

Based on user experience and UI discussion meetings we simplified model parameter editing process. Before the user has to click on input scenario "unlock" before editing parameter, editing notes or uploading parameter CSV. Now it is done automatically upon clicking on Edit or Upload button. Also an input scenario would be automatically "locked" and ready to run after the user saved all parameters editing.

UI: microdata: use boolean attributes as dimensions

In microdata viewer boolean attributes are now treated as dimensions which allow the user to filter by such attributes, for example to see only microdata where Retired = true.

Docker: use git version tag to build release

Docker build scripts are now properly using git version tag for the build.

Download source code and binaries:

Download release documentation archive:

Release documentation archive

Download cluster version (MPI):

Assets 15

03 Aug 17:01

amc1999

v1.15.4

d5d04b9

Microdata viewer UI and output tables ad-hoc measures: 03 of August 2023

Microdata viewer UI and output tables ad hoc measures: 03 of August 2023

20230803 : v1.15.4

There are multiple improvements and bug fixes in that release.
It is recommended for model developers and for model users who wants to view microdata in UI.

Changes in that release:

c++ core: transforming derived (model-generated) parameters to output tables
c++ core: raise runtime error on non-numeric table increment
c++ core: use Markdown rendering of symbol documentation in UI
c++ core: omc compiler warnings on re-used or missing random streams
c++ core: allow a linked attribute in a derived attribute
c++ core: support for linked attributes in event time functions
c++ core: fix model error reading CSV files with heuristic dimension names
UI: first version of microdata viewer
UI and go: calculate and download table with ad hoc measures: AVG SUM COUNT MIN MAX VAR SD SE CV

Transforming derived (model-generated) parameters to output tables with parameters_to_tables

The model code statement parameters_to_tables creates and populates new output tables for a list of derived (model-generated) parameters. Because these derived parameters are treated as output tables by OpenM++, they can be organized into table groups in the UI, visualized in the UI just like multi-dimensional tables, and downloaded as csv’s for use downstream. For more information, please see the wiki sub-topic

https://github.com/openmpp/openmpp.github.io/wiki/Parameter-and-Table-Display-and-Content#derived-parameters-as-tables

Raise runtime error on non-numeric table increment

If non-numeric values such as infinity or NaN (not a number) occur in an entity during a run, and are used in a table, cells of the table could become empty. This enhancement identifies this condition and causes a run-time error which halts the run. For more information including a worked example, please see the wiki section

https://github.com/openmpp/openmpp.github.io/wiki/Entity-Tables#invalid-table-increments

Rendering of symbol documentation in UI

Model symbols like parameters and tables can be documented using NOTE comments in model code. By default, NOTE comments are assumed to follow Modgen markup conventions and are converted to equivalent markdown notation, which is what OpenM++ uses to display structured textual content. This conversion was not working correctly and has been fixed in this release.

OpenM++ compiler warnings on re-used or missing random streams

A random stream is the integer argument in a call to one of the random number generators. For example, the call RandUniform(23) in model code specifies that random stream 23 will be used to produce random numbers in that model code location. Different random streams are independent - a call using one stream has no effect on a call using a different stream. This independence reduces spurious differences at the micro level between model runs and improves the statistical power of run differences for a given run size.

In this release, the OpenM++ compiler will emit a warning if a random stream is reused. That can occur if model code is copied, pasted, and modified during model development. The warning includes a suggested unused random stream to use instead. If a call has no random stream argument, like RandUniform(), the OpenM++ compiler will emit an error instead of a warning, as well as a suggested unused random stream to use. In newly added model code, it is generally best to omit random stream arguments throughout the new code and let the OpenM++ compiler suggest unused random stream(s) in the resulting error message(s). After the build, use the error messages to navigate to each line of new model code with a missing random stream and edit the line to use the suggested random stream in the error message for that line. Using new random streams for new code maximizes run similarity between the previous and modified versions of a model by keeping existing stream usage in the model unchanged.

Allow a linked attribute in a derived attribute

Due to an implementation oversight, the OpenM++ compiler did not accept a linked attribute in the declaration of a derived attribute.
For example, a derived attribute like

  split(spawner->curtate_age,P_AGE_GROUP5)

caused a syntax error. This has been remedied in this release.
Thanks to Dominic for bringing this issue to our attention.

Support for linked attributes in event time functions

In previous openM++ releases, a linked attribute like A->B could be used in an event time function, but event dependency on changes to A->B was not implemented. This issue has been addressed in this release. For more, including an example, please see the following wiki subtopic:

https://github.com/openmpp/openmpp.github.io/wiki/Events#attributes-affecting-event-time

Fix model error reading CSV files with heuristic dimension names

In previous versions of openM++ models were not able to read parameter values from CSV file if parameter has heuristic dimension names. For example, attempt to read following file would produce model run error:

sub_id,ANNES,param_value
0, 2000, 0
0, 2001, 0
0, 2002, 0
0, 2003, 0

This issue is fixed now.
Many thanks to Dominic and Jean-Dominique for discovering this issue and testing bug fix.

Known Issue (Windows only): It is not possible to read model parameters from CSV files if path contains caractères accentués

On Windows, the model is unable to read parameter(s) from CSV if path contains Any/Caractères/Accentués. That issue will be fixed in the future release. Thanks to Dominic and his colleague discovering and testing the problem.

UI microdata viewer

First version of microdata viewer UI is available now. It allows a user to browse microdata, filter it by classification attributes, download to CSV or copy to clipboard. Because it is a typical situation to have a huge amount of microdata output rows, the UI displays only a small "page" of rows and supports next, previous, first, last page navigation.

We planning to improve microdata UI in the future releases.

UI and backend API to calculate and download table with ad hoc measures

Backend API allows now to calculate ad hoc measures for the output tables. Calculation can include arithmetic operations (e.g. ratio or difference), SQRT, ABS and use sub-values (sub-samples) aggregation functions: AVG, SUM, COUNT, MAX, MIN, VAR, SD, SE, CV.

In the UI user can select additional measure for the output table: MEAN, SUM, COUNT, MAX, MIN, VAR, SD, SE, CV. Result view will include existing table measure and ad hoc measure calculated as aggregation over sub-values (sub-samples).

Download source code and binaries:

Download release documentation archive:

Release documentation archive

Download cluster version (MPI):

Assets 13

14 Jun 07:46

amc1999

v1.15.3

b174240

Minor release 14 of June 2023

20230614 : v1.15.3

This is a minor release and you can skip it, unless any changes below are important for your model development.

Changes in that release:

c++ core: new option ascii_infinity to improve utf-8 support
c++ core: in Windows model projects always use BOM in CSV files to improve utf-8 support
c++ core: emit build error on attribute redeclaration
c++ core: improve range type and fix microdata issues by using non-zero based enum id
database: update Modgen compatibility views for range types
dbcopy: add model list option to display list of the models in database
UI and oms: allow to read single sub-value to improve UI performance
UI and oms: significant performance improvements, especially for model run delete
UI and oms: add page support display large amount of microdata
UI: implement page support output tables, parameters and microdata viewer
UI: initial version of microdata viewer
RedHat 7 special release version

New option ascii_infinity

OpenM++ uses Unicode ∞ in the enumerators of the lower and upper intervals of partitions. Unicode ∞ is written as a UTF-8 multibyte character in files exported from a model. This can interfere with ASCII-only downstream processing of model results. The new option

 options ascii_infinity = on | off;

can be used to tell the openM++ compiler to use ‘inf’ instead of Unicode ‘∞’ for partition endpoints.

This option is off by default.

Please note that existing parameter input csv files (used in model build or model run) may need to be modified if this option is turned on.

Thanks to Claude Nadeau for describing this issue and suggesting the remedy.

UI changes and microdata viewer

It is a typical situation to have a huge amount of microdata output rows. To avoid potential performance issues microdata UI viewer displays only a small "page" of rows and supports next, previous, first, last page navigation. Also similar UI changes applied to large parameters and output tables.

Please keep in mind microdata UI still under active development and current version published only as initial preview.

RedHat 7 release

There is a special release published for RedHat 7 Linux. Please use it on your own risk, openM++ team no longer support RedHat 7, it may not work as expected.

Download source code and binaries:

Download release documentation archive:

Release documentation archive

Download cluster version (MPI):

Assets 14

03 May 05:39

amc1999

v1.15.2

45a1835

Minor release 2 of May 2023

20230502 : v1.15.2

This is a minor release and it is recommended for time-based model development.

Changes in that release:

c++: Windows debug model disabling Microsoft iterator debug
c++: simulate only one member in a time-based model if specified in combined seed
c++: time-like attributes forbidden in entity set filter or dimension
c++: get model memory usage from Windows, Linux and MacOS
c++: enhancement to allow predicting run-time memory requirements
c++: new model run-time options to specify memory usage requirements
c++: MPI microdata database writing: fix memory leak
UI and web-service back-end API: collect and display storage management status for model data
Windows: removing PowerShell scripts from openM++

Option to build Windows Debug model disabling Microsoft iterator debug functionality

The Windows Debug version of a time-based model can be unusably slow even for relatively small populations due to normal Microsoft functionality which verifies the integrity of iterators in the Debug version of a C++ application. The issue typically manifests at the end of a simulation of a Debug time-based model with the model slowing down so much it appears to hang, perhaps for hours. This release includes a new model build property which disables this Microsoft functionality for a Debug model. The property can be accessed in Visual Studio in

    Model > Properties > OpenM++ > Build Options > Disable Microsoft iterator debug functionality

This option is off by default.

A Debug model with this option activated will write the following line to the run log:

Note : this Debug model was built with Microsoft iterator debug disabled

Thanks to François for bringing this issue to our attention.

Simulate only one member in a time-based model if specified in combined seed

Case-based models can reproduce a single case in a run using a ‘combined seed’ (aka as the case seed). A combined seed encodes the simulation member and the SimulationSeed into a single integer. This functionality can be useful to reproduce a single case which causes a run-time error in a large run with many cases, or to reproduce an extreme case identified using the case seed. This enhancement adds an analogous capability for time-based models with multiple members (aka replicates, subs). Thanks to Yann for bringing this need to our attention.

When a run-time error occurs in a time-based model with multiple members, it can be helpful to reproduce the error in a run which simulates only the member in which the error occurred. For example, the full run might have 40 members which is executed on a large server or back-end server grid, but the model developer may wish to reproduce the error on a development workstation by simulating just the member in which the error occurred, for speed. To do so, set the SimulationSeed parameter to the ‘combined seed’ given in the run-time error message. For example, if the run-time error is

Simulation error: attempt to assign -1 to range REPORT_TIME which has limits [0,200] when current time is 26.00000000000000 in entity_id 58 in or after event TickEvent in simulation member 18 with combined seed 38654705665

then setting the SimulationSeed parameter to 38654705665 and re-running will simulate only the member in which the error occurred (member 18 in this example).

If a member is not the member encoded in the combined seed, the run log will contain a message like the following:

member=7 Suppress simulation for single-member run specified in combined seed

Note that table values for other members will be empty.

If the error happened to occur in member 0 in a run with multiple members, there is no need to use this mechanism because a run with a single member/replicate/sub will reproduce member 0.

Time-like attributes forbidden in entity set filter or dimension

A time-like attribute is forbidden in an entity table filter, dimension, or event time function.
This prohibition has now been extended to entity set filters and dimensions.
For more on time-like and event-like attributes, see Time Like and Event like Attributes · openmpp/openmpp.github.io Wiki · GitHub

New wiki content on test_models and dbcopy

The test_models utility builds and runs a model and compares outputs with a previous version and cross-platform.

New content on test_models has been added to the existing model development topic at Test Models · openmpp/openmpp.github.io Wiki

The dbcopy utility handles input and output from a model database.

A new model development wiki topic on dbcopy has been added at Using dbcopy · openmpp/openmpp.github.io Wiki

MPI microdata database writing: fix memory leak

MPI version of models (cluster and cloud version, not desktop) suffering from excessive memory consumption if microdata are written into database. This issue now fixed.

Cross-platform function to get model memory usage from Windows, Linux and MacOS

Now model reports peak memory usage at the end of simulation. Model developer also can measure memory usage at any given moment by:

auto [nMem, nMax] = openm::getProcessMemorySize();

// if (nMem > 0) then it is current model memory usage in bytes
// if (nMax > 0) then it is peak model memory usage in bytes

Collect and display storage management status for model data

If enabled by oms web-service run options or if enabled by your cloud admin then user can see outdated model runs and input scenarios in UI. This feature is a first step towards cost-effective storage management in cloud. We are planning to implement automated backups and storage cleanup in subsequent releases.

Windows: removing PowerShell scripts from openM++

There were multiple PowerShell .ps1 scripts used by openM++ on Windows to start and stop UI during model build. Unfortunately PowerShell scripts may not be allowed by organization security policy. We removed almost all .ps1 scripts except the last one related to Modgen 11 legacy issue.

Download source code and binaries:

Download release documentation archive:

Release documentation archive

Download cluster version (MPI):

Assets 13

11 Mar 00:44

amc1999

v1.15.0

49a45db

New output table viewer in UI: 10 of March 2023

20230310 : v1.15.0

This release include two important features: reduced memory size in time-based models and new output table viewer in UI.

Changes in that release:

c++: reduced memory size in time-based models
c++: improved display of entity attributes in debugger
UI: replace output table viewer
UI: implement output table decimals support from model metadata
fix path with spaces issues in Visual Studio projects, oms and dbcopy
multiple small improvements and bug fixes

Reduced memory use in time-based models

This release reduces the memory requirements of entity members used to implement events and table increments.

This enhancement is unimportant for case-based models but may be helpful for time-based models with large populations experiencing memory stress on the target hardware.

The reduction in memory use related to events only occurs if time_type is float in the model.

In tests of two large time-based models, the memory savings were 11% in one model, 18% in the other.

Improved display of entity attributes in Visual Studio debugger

The value of an entity attribute now displays directly in Visual Studio debugger windows and mouse hover.

Previously, the internal structure of an attribute needed to be expanded manually to see the value.

UI: replace output table viewer

Output table viewer in UI replaced with a new version to address multiple issues with existing component:

it does not show misleading "Total" columns and rows
it handles slicing view correctly (previous version could lead to incorrect numbers in table body)
it allow user to save default table view
it displays measure decimals according to model metadata
it has better performance on large tables

This is a first of multiple releases with output table viewer enchantments, more functionality would be delivered in subsequent releases.

UI enhancements and fixes

There are multiple enchantments and fixes in UI:

properly highlight selected model run or input scenario (thank you to Kevin for design ideas)
explicitly display currently selected model run (base run) and input scenario
fix output table viewer title which was not showing before

Fix path with spaces issues

There were multiple issues in Visual Studio model projects and openM++ utilities (dbcopy amd oms) if openM++ path contained spaces. Thanks to our users (to Chantal and Daniel) for discovering and testing the issue. Please let us know if there are outstanding problems in that area.

Known Issues

MPI version of models (cluster and cloud version, not desktop) suffering from heap fragmentation and excessive memory consumption if microdata are written into database. We are planning to fix this problem in subsequent releases.

Download source code and binaries:

Download release documentation archive:

Release documentation archive

Download cluster version (MPI):

Assets 13

01 Feb 10:54

amc1999

v1.14.0

7539be9

Microdata output UI release: 01 of February 2023

20230201 : v1.14.0

This release include initial version UI to support model microdata. Please skip this release unless microdata is an important part of your model, use 23 of September 2022 release v1.11.1

Changes in that release:

BREAKING change in db schema: add microdata row count column;
c++ core: model_streams no longer required in model code;
c++ core: Local Random Streams;
c++ core: multilink size run-time warning;
c++ core: fix microdata value digest calculation;
UI: initial version of microdata UI;
oms: microdata must be enabled on the server to improve data security;
oms API: add microdata to model run request;
dbcopy: clean output folder by default, add new run option to keep it if required.

BREAKING change in db schema

There is a small, but breaking change in database schema in this release.

It does NOT affect you if all your models are in development:

remove existing model.sqlite files;
rebuild your model;
done.

It is applied to you only if openM++ models already deployed in production and you want to keep existing database(s).

If your production model version is 2022-09-23 (v1.11.1) or older then use upgrade scripts and instruction from current release, located in sql/upgrade_to_20230201/ folder.

If you are using model version 2022-12-10 (v1.12.0) or 2023-01-17 (v1.13.0) and do want to upgrade your database(s) then please contact us for further instructions.

model_streams no longer required in model code

In previous releases, models specified the maximum number of random number streams used in the model using code like the following in in ompp_framework.ompp:

namespace fmk {
 /**
 * Maximum number of random streams in the model (increase if insufficient)
 */
 const int model_streams = 400;
}

In this release, this code is no longer required and can be removed. If this code is retained, it will have no effect in this and subsequent OpenM++ releases. However, this code is required to build and run a model using previous OpenM++ releases.

The OpenM++ compiler now detects the maximum random stream used in model code. During build, an informational message like the following is written to the log:

Maximum random stream = 393

Local Random Streams

Model code can now optionally specify that the state of random number streams be maintained locally for each entity rather than shared among entities.

This can significantly reduce variance in run comparisons of models which simulate multiple instances of entities together, such as time-based models or case-based models with multiple entities in a case. It can also make run comparisons at the microdata level feasible for such models.

To see charts comparing the effect with and without local random streams in a highly interacting time-based model, see https://github.com/openmpp/openmpp.github.io/wiki/Local-Random-Streams#base-variant-coherence.

For more information on local random streams, see the wiki topic: https://github.com/openmpp/openmpp.github.io/wiki/Local-Random-Streams

Multilink size run-time warning

A run-time warning such as the following will be issued if a multilink exceeds 1,000 in size:

warning : A multilink has grown larger than 1000 - possible performance impact

A multilink holds the 'many' side of a one-to-many or a many-to-many link.
It is designed to be economical in memory but consequently some operations scale poorly if the size becomes large.
The resource_use option can be used to see the maximize size of each multilink in a model run.

Microdata must be enabled on the server to improve data security

By default model microdata are not visible in UI and not available through oms web-service API. In order to use it oms must be started with -oms.AllowMicrodata argument. For example:

oms -l localhost:4040 -oms.AllowMicrodata

dbcopy do clean output folder by default

Previous version of dbcopy utility did not clean existing output directory, For example:

dbcopy -m RiskPaths
dbcopy -m RiskPaths -dbcopy.To csv

Results of both commands above would be stored in the same output directory RiskPaths.

Current release of dbcopy does delete existing output directory by default to avoid mixing results of multiple commands. If you want to keep existing output directory then use -dbcopy.KeepOutputDir run option:

dbcopy -m RiskPaths -dbcopy.KeepOutputDir
dbcopy -m RiskPaths -dbcopy.KeepOutputDir -dbcopy.To csv

Known Issues

MPI version of models (cluster and cloud version, not desktop) suffering from heap fragmentation and excessive memory consumption if microdata are written into database. We are planning to fix this problem in subsequent releases.
There is no switch to English language button in UI, only to French. That issue would be fixed soon.

Download source code and binaries:

Download release documentation archive:

Release documentation archive

Download cluster version (MPI):

Assets 13

17 Jan 11:22

amc1999

v1.13.0

b046cc9

Microdata output core release: 17 of January 2023

20230117 : v1.13.0

This release include core functionality to support model microdata. Please skip this release unless microdata is an important part of your model, use 23 of September 2022 release v1.11.1

Changes in that release:

scripts and instructions how to upgrade production databases
c++ core: multiple bug fixes in microdata code
wiki: updated developer topic Microdata Output
Go back-end: add microdata support into dbcopy and oms
dbcopy: store parameters, output tables and microdata in separate sub-folders
oms: additional filters to select microdata more precisely

Upgrade models SQLite database files to the new schema

If you are using openM++ models in production then it is necessary to existing databases before using new release.
Please follow the readme.txt instructions and run upgrade scripts suitable for your OS which are located in sql/upgrade_to_20221210/ folder.

Important: Always do a database backup before running any upgrade scripts.

Windows:
Assuming existing database files are in:

C:\openmpp_win_20220923\
                       bin\
                       models\

and current release unpacked into:

C:\openmpp_win_20221210\
                       bin\
                       sql\upgrade_to_20221210\
                                              upgrade_win.bat

Option 1:

copy directory \upgrade_to_20221210\ into old openM++ folder: C:\openmpp_win_20220923\
double click on C:\openmpp_win_20220923\upgrade_to_20221210\upgrade_win.bat

Option 2:

open command prompt (not PowerShell) and type:

    cd /D C:\openmpp_win_20221210\sql\upgrade_to_20221210
    upgrade_win.bat C:\openmpp_win_20220923

Linux or MacOS
Assuming existing database files are in:

~/openmpp_debian_20220923/
                       bin/
                       models/

and current release unpacked into:

~/openmpp_debian_20221210/
                       bin/
                       sql/upgrade_to_20221210/
                                              upgrade_linux.sh

Option 1:

cp -r ~/openmpp_debian_20221210/sql/upgrade_to_20221210/ ~/openmpp_debian_20220923/
cd ~/openmpp_debian_20220923
./upgrade_to_20221210/upgrade_linux.sh

Option 2.

cd ~/openmpp_debian_20221210/sql/upgrade_to_20221210/
./upgrade_to_20221210/upgrade_linux.sh ~/openmpp_debian_20220923

Updated model developer topic Microdata Output on wiki

The model developer wiki topic Microdata Output has been revised to improve and expand previous content. It now also includes new material with worked examples on event context, event filtering, and database output, including use of dbcopy to extract microdata for downstream use. The Microdata Output developer topic is at https://github.com/openmpp/openmpp.github.io/wiki/Microdata-Output

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Bug fix release 16 of February 2024

Model documentation release 13 of February 2024

Minor release 15 of November 2023

Model runs comparison, first version: 10 of October 2023

Microdata viewer UI and output tables ad hoc measures: 03 of August 2023

Minor release 14 of June 2023

Minor release 2 of May 2023

New output table viewer in UI: 10 of March 2023

Microdata output UI release: 01 of February 2023

Microdata output core release: 17 of January 2023

Releases: openmpp/main

Bug fix release 16 of February 2024

Bug fix release 16 of February 2024

Model documentation release 13 of February 2024

Model documentation release 13 of February 2024

Minor release 15 of November 2023

Minor release 15 of November 2023

Model runs comparison, first version: 10 of October 2023

Model runs comparison, first version: 10 of October 2023

Microdata viewer UI and output tables ad-hoc measures: 03 of August 2023

Microdata viewer UI and output tables ad hoc measures: 03 of August 2023

Minor release 14 of June 2023

Minor release 14 of June 2023

Minor release 2 of May 2023

Minor release 2 of May 2023

New output table viewer in UI: 10 of March 2023

New output table viewer in UI: 10 of March 2023

Microdata output UI release: 01 of February 2023

Microdata output UI release: 01 of February 2023

Microdata output core release: 17 of January 2023

Microdata output core release: 17 of January 2023