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.44%. Comparing base (8f90ce7) to head (ee1ecc4).
⚠️ Report is 10 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1515      +/-   ##
==========================================
+ Coverage   97.38%   97.44%   +0.06%     
==========================================
  Files         188      190       +2     
  Lines       16621    15963     -658     
==========================================
- Hits        16186    15555     -631     
+ Misses        435      408      -27

☔ 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.

true, removed also from the cpp version

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.

In the cpp version this is divided into the abm_minimal and the abm_vaccination example. Agree that we should probably stay close, so either merge them in the cpp version or split it here. Do you have a favorite solution?

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.

added the bindings for the prng and infections. Maybe we can discuss if we want to provide simplified functionality for python at a later time.

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).

Added some functionality. Let's discuss if that is our prefereable solution

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).

Copilot

Pull request overview

Adds/extends pybind11 bindings to enable running a minimal ABM workflow from Python, including additional utility bindings needed by the ABM parameterization and logging.

Changes:

Expose additional core utility types to Python (e.g., RNG/distributions, time-series functor, abstract parameter distributions, lognormal distribution).
Extend ABM bindings to support richer parameter arrays, histories/loggers, and additional model/simulation helpers.
Add a Python minimal ABM example script demonstrating the new bindings.

Reviewed changes

Copilot reviewed 14 out of 15 changed files in this pull request and generated 19 comments.

Show a summary per file

File	Description
pycode/memilio-simulation/memilio/simulation/bindings/utils/time_series.cpp	Adds a Python constructor for `TimeSeries` from a table.
pycode/memilio-simulation/memilio/simulation/bindings/utils/random_number_generator.h	Introduces RNG + discrete distribution bindings.
pycode/memilio-simulation/memilio/simulation/bindings/utils/parameter_distributions.h	Declares lognormal distribution binding entry point.
pycode/memilio-simulation/memilio/simulation/bindings/utils/parameter_distributions.cpp	Implements `ParameterDistributionLogNormal` binding.
pycode/memilio-simulation/memilio/simulation/bindings/utils/index.h	Exposes `Index.get()` to Python.
pycode/memilio-simulation/memilio/simulation/bindings/utils/custom_index_array.h	Minor comment formatting fix.
pycode/memilio-simulation/memilio/simulation/bindings/utils/abstract_parameter_distribution.h	Adds binding for `AbstractParameterDistribution`.
pycode/memilio-simulation/memilio/simulation/bindings/simulation.cpp	Wires new utility bindings into the main `_simulation` module.
pycode/memilio-simulation/memilio/simulation/bindings/pybind_util.h	Fixes `Range.__iter__` to return an iterator object.
pycode/memilio-simulation/memilio/simulation/bindings/models/abm.cpp	Extends ABM bindings (parameters, histories, model/simulation helpers).
pycode/memilio-simulation/memilio/simulation/bindings/math/time_series_functor.h	Adds `TimeSeriesFunctor` Python binding.
pycode/memilio-simulation/memilio/simulation/bindings/geography/geolocation.cpp	Adds `GeographicalLocation` binding (currently included from `.cpp`).
pycode/examples/simulation/abm_minimal_example.py	New Python example using the new ABM bindings.
cpp/memilio/utils/abstract_parameter_distribution.h	Introduces a C++20 concept constraint for distribution implementations.
cpp/examples/abm_minimal.cpp	Small tweak to the C++ minimal ABM example.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

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

apply suggestions from review and enhance bindings of histories

10607ae

charlie0614 requested a review from DavidKerkmann April 16, 2026 13:13

rename histories

d442c86

kilianvolmer requested a review from Copilot April 16, 2026 13:29

Copilot started reviewing on behalf of kilianvolmer April 16, 2026 13:30 View session

Copilot AI reviewed Apr 16, 2026

View reviewed changes

reneSchm and others added 8 commits April 30, 2026 13:56

add details::AbstractHistory

1b364cf

improve binding of advance function

8f6a2fb

Apply suggestions from code review

7cfe952

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

apply suggestions from review

c30c597

Apply suggestions from code review

0521f44

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

add some tests

cc1171d

add eol

b8fdc58

generalize abstract parameter distribution binding

ee1ecc4

		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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

charlie0614 commented Mar 24, 2026 •

edited

Loading

codecov Bot commented Mar 25, 2026 •

edited

Loading