385 Travel-time-aware mobility scheme

[HenrZu]

Changes and Information

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

• Implement Travel-time-aware metapopulation scheme from doi.org/10.1371/journal.pcbi.1012630
• New GraphSimulationTravelTime with explicit transit of travelers

If need be, add additional information and what the reviewer should look out for in particular:

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

[codecov]

Codecov Report

❌ Patch coverage is 93.11475% with 21 lines in your changes missing coverage. Please review.
✅ Project coverage is 97.29%. Comparing base (cd10687) to head (a6df67e).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
...ilio/mobility/metapopulation_mobility_traveltime.h	88.88%	21 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1511      +/-   ##
==========================================
- Coverage   97.38%   97.29%   -0.09%     
==========================================
  Files         188      190       +2     
  Lines       16536    16846     +310     
==========================================
+ Hits        16103    16390     +287     
- Misses        433      456      +23     

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

[reneSchm]

Thank you for this addition!
This is not yet a full review, as I have not checked most of the algorithms, but I do have a couple of (high-level?) comments.

[reneSchm]

I have a couple of thoughts on this:

• While using "day" as a unit is not bad, I would prefer being more generic, e.g. use "time period mapped to [0, 1)", as there technically is nothing day-specific here.
• I think this can be a class in its own file. Between the struct and compute_traveltime_schedule there already are 150 lines used for this.
• Using a class, you can make the members private, and use functions for read-only access. You can also move the explanation of what the vectors do there, and the functions would help showing how the vectors should be used.
• Also allows adding size asserts etc.
• compute_traveltime_schedule can be used as or by a constructor.
• Two performance considerations: Would it make sense to some vectors 1-dimensional, for better locality? Do you need the step index, or can you store the step value (i.e. 1/index) to avoid division?

[HenrZu]

• Day -> normalized time period
• Scheduler is now a class in an own file (using your ideas incl. asserts etc.)
• Tried to use 1d vectors
• PRecompute the first_depature time instead of the step, so one division less per edge

[reneSchm]

This looks very model specific. It would break from switching the order of age group and compartment. You could perhaps use the Population (or just CustomIndexArray) for taking the correct slice of the population and "correct" these?

It also does not seem like a safe or fast algorithm. What if more than max_iter negative entries exist? Why do up to max_iter searches for max/minCeoff? Consider using map_to_nonnegative on the population slices*.

*We may want to refactor Slices to use Eigen::seq for this.

[HenrZu]

yes, thats true. Reimplemented it with the slice and then use map_to_nonnegative.

however, this would still fail if we decide to switch the order of age groups and compartments.

[reneSchm]

This output contains a lot of hard-coded numbers, I think these should either be configurable, or used as explanations for the setup above instead of being printed.

[HenrZu]

Removed the hardcoded sub-step numbers (n_steps=100, sub-steps 51-53, ...) from the output