1503 add python bindings for ABM by charlie0614 · Pull Request #1515 · SciCompMod/memilio

charlie0614 · 2026-03-24T09:41:45Z

Changes and Information

Please briefly list the changes (main added features, changed items, or corrected bugs) made:

Add python bindings for minimal ABM example

Merge Request - Guideline Checklist

Please check our git workflow. Use the draft feature if the Pull Request is not yet ready to review.

Checks by code author

Every addressed issue is linked (use the "Closes #ISSUE" keyword below).
New code adheres to coding guidelines.
No large data files have been added (files should in sum not exceed 100 KB, avoid PDFs, Word docs, etc.).
Tests are added for new functionality and a local test run was successful (with and without OpenMP).
Appropriate documentation within the code (Doxygen) for new functionality has been added in the code.
Appropriate external documentation (ReadTheDocs) for new functionality has been added to the online documentation and checked in the preview.
Proper attention to licenses, especially no new third-party software with conflicting license has been added.
(For ABM development) Checked benchmark results and ran and posted a local test above from before and after development to ensure performance is monitored.

Checks by code reviewer(s)

Corresponding issue(s) is/are linked and addressed.
Code is clean of development artifacts (no deactivated or commented code lines, no debugging printouts, etc.).
Appropriate unit tests have been added, CI passes, code coverage and performance is acceptable (did not decrease).
No large data files added in the whole history of commits(files should in sum not exceed 100 KB, avoid PDFs, Word docs, etc.).
On merge, add 2-5 lines with the changes (main added features, changed items, or corrected bugs) to the merge-commit-message. This can be taken from the briefly-list-the-changes above (best case) or the separate commit messages (worst case).

Closes #1503

codecov · 2026-03-25T12:47:08Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.38%. Comparing base (8f90ce7) to head (43cb996).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1515   +/-   ##
=======================================
  Coverage   97.38%   97.38%           
=======================================
  Files         188      188           
  Lines       16621    16621           
=======================================
  Hits        16186    16186           
  Misses        435      435

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

DavidKerkmann

There are a couple of generalized questions that we need to tackle now that we are bringing python bindings to the simulation level.

DavidKerkmann · 2026-04-13T07:48:01Z

+template <class T>
+concept HasSampleFunction = requires(T t) {
+    { t.get_sample(std::declval<RandomNumberGenerator&>()) } -> std::convertible_to<ScalarType>;
+    { t.get_sample(std::declval<abm::PersonalRandomNumberGenerator&>()) } -> std::convertible_to<ScalarType>;


The abstract parameter disctribution is in utils/ and should remain model-independent. An abm::PersonalRandomNumberGenerator is only known when there is knowledge about the ABM..
Is this required at this point? Requiring an abm::PRNG makes this unusable for other models.

DavidKerkmann · 2026-04-13T07:50:22Z

+    model.parameters.AgeGroupGotoSchool[AgeGroup(age_group)] = False
+    model.parameters.AgeGroupGotoWork[AgeGroup(age_group)] = False


As the default is false, these line could be removed, unless you have an intention to explicitly write them down.

DavidKerkmann · 2026-04-13T07:52:05Z

+for age in range(num_age_groups):
+    model.parameters.InfectionProtectionFactor[abm.ProtectionType.GenericVaccine, AgeGroup(
+        age), abm.VirusVariant.Wildtype] = mio.TimeSeriesFunctor(
+        [[0, 0.0], [14, 0.67], [180, 0.4]])
+
+    model.parameters.SeverityProtectionFactor[abm.ProtectionType.GenericVaccine, AgeGroup(
+        age), abm.VirusVariant.Wildtype] = mio.TimeSeriesFunctor(
+        [[0, 0.0], [14, 0.85], [180, 0.7]])


This part is not in the .cpp file. We should probably stay as close as possible to the .cpp example. If we want to add this, then we should also add it in the .cpp example.

DavidKerkmann · 2026-04-13T08:01:11Z

+# Seed infections
+
+infection_distribution = [0.5, 0.3, 0.05, 0.05, 0.05, 0.05, 0.0, 0.0]
+rng = np.random.default_rng()


With the availability of the MEmilio RNG / Personal RNG we should use that one here instead of the numpy rng. The discrete distribution would be suitable.

DavidKerkmann · 2026-04-13T10:59:23Z

-        .def_property_readonly("is_in_quarantine", &mio::abm::Person::is_in_quarantine);
+        .def_property_readonly("is_in_quarantine", &mio::abm::Person::is_in_quarantine)
+        .def_property_readonly("id", &mio::abm::Person::get_id)
+        .def("add_new_infection",


I see that this looked different at some point. Normally, as far as I can tell, we always bind the functions 1:1, meaning that we use the same arguments as in the cpp code. Here, the model is passed instead of the rng, and then the function itself creates the PRNG. However, then we could go a step further and also remove the age for example, as it could also be inferred directly from the person.

In general, we should decide how we want to go about these things. In a way, we lose flexibility if the user intends to use a different rng for some reason here. However, I think it also simplifies the use and perhaps we could bind functions for easier use in general.

DavidKerkmann · 2026-04-13T11:07:27Z

+        .def(
+            "advance",
+            [](mio::abm::Simulation<>& sim, mio::abm::TimePoint tmax) {
+                sim.advance(tmax);
+            },
+            py::arg("tmax"))
+        .def(
+            "advance",
+            [](mio::abm::Simulation<>& sim, mio::abm::TimePoint tmax,
+               mio::History<mio::abm::TimeSeriesWriter, mio::abm::LogInfectionState>& history) {
+                sim.advance(tmax, history);
+            },
+            py::arg("tmax"), py::arg("history"))


This only allows for two specific advance calls. A general functionality with any history object would be preferred (in conjuction with the binding of the History).

DavidKerkmann · 2026-04-13T11:39:42Z

+{
+    bind_class<mio::AbstractParameterDistribution, EnablePickling::Never>(m, name.c_str())
+        .def(py::init<>())
+        .def(py::init<mio::ParameterDistributionLogNormal>(), py::arg("dist"))


This should be generic for any distribution (see templated definition).

charlie0614 added 4 commits March 16, 2026 08:26

add python bindings for households and abstractparameterdistributions

52163a8

exchange contact rates by contact matrix

4f49e04

add python bindings for minimal example

e18e5b2

change to ContactMatrix

cc3ddb2

charlie0614 linked an issue Mar 24, 2026 that may be closed by this pull request

Add python bindings for ABM #1503

Open

2 tasks

charlie0614 added 2 commits March 25, 2026 11:06

Merge branch 'main' into 1503-add-python-bindings-for-abm

efd5e65

fix bug

5851eec

charlie0614 added 2 commits March 26, 2026 10:59

rename History

7e352b1

add bindings for vaccinations

9e7c6aa

charlie0614 requested a review from DavidKerkmann April 2, 2026 12:33

charlie0614 added 3 commits April 9, 2026 15:38

remove debug artifacts

ef29c59

Merge branch 'main' into 1503-add-python-bindings-for-abm

cf15f80

remove personalrng from bindings

43cb996

DavidKerkmann requested changes Apr 13, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

1503 add python bindings for ABM#1515

1503 add python bindings for ABM#1515
charlie0614 wants to merge 11 commits intomainfrom
1503-add-python-bindings-for-abm

charlie0614 commented Mar 24, 2026 •

edited

Loading

Uh oh!

codecov bot commented Mar 25, 2026 •

edited

Loading

Uh oh!

DavidKerkmann left a comment

Uh oh!

DavidKerkmann Apr 13, 2026

Uh oh!

DavidKerkmann Apr 13, 2026

Uh oh!

DavidKerkmann Apr 13, 2026

Uh oh!

DavidKerkmann Apr 13, 2026

Uh oh!

DavidKerkmann Apr 13, 2026

Uh oh!

DavidKerkmann Apr 13, 2026

Uh oh!

DavidKerkmann Apr 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		model.parameters.AgeGroupGotoSchool[AgeGroup(age_group)] = False
		model.parameters.AgeGroupGotoWork[AgeGroup(age_group)] = False

Conversation

charlie0614 commented Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes and Information

Merge Request - Guideline Checklist

Checks by code author

Checks by code reviewer(s)

Uh oh!

codecov bot commented Mar 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

DavidKerkmann left a comment

Choose a reason for hiding this comment

Uh oh!

DavidKerkmann Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

DavidKerkmann Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

DavidKerkmann Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

DavidKerkmann Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

DavidKerkmann Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

DavidKerkmann Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

DavidKerkmann Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

charlie0614 commented Mar 24, 2026 •

edited

Loading

codecov bot commented Mar 25, 2026 •

edited

Loading