1419 Add SECIRVVS optimal control example

[julianlitz]

Pull Request Description

Changes and Information

Briefly list the changes:

We add a new optimal control toolbox for solving epidemiological intervention optimization problems.
Here we focus on the optimization of weekly interventions based on the SECIRVVS model used in ESID.

• Control Parameters: Damping control parameters for interventions (school closure, face masks, remote work, etc.)
• Constraint System: Path constraints and terminal constraints on infection states (Infected, Severe, Critical, Dead)
• Utility Functions:
  • Infection state query system for constraint evaluation
  • Time grid generation helpers
  • Integrator selector (Euler, RK methods)
  • Feasibility checking tools

Key files added:

• constraints/ - Constraint definitions and updates
• control_parameters/ - Definition of damping controls
• ipopt_solver/ - IPOPT integration (objective, constraints, solution saving)
• optimization_model/ - Graph model management with caching
• optimization_settings/ - Manage configuration settings
• helpers/ - Utility functions (integrators, time grids, AD type support)

run.sh:

#!/bin/bash
cd ../../ 

CURRENT_PATH=$(pwd)

"$CURRENT_PATH/cpp/build/bin/optimal_control_ESID" \
    "$CURRENT_PATH/data" \
    "$CURRENT_PATH/cpp/tools/optimal_control/secirvvs_damping/optimal_control_settings"

Reviewer Notes

• Dependencies: Requires MEMILIO_ENABLE_IPOPT=ON to build
• Model caching: Thread-safe caching mechanism in OptimizationModel to handle expensive graph model creation
• Integration validation: Check constraint feasibility before running optimization

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
• 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 0% with 1026 lines in your changes missing coverage. Please review.
✅ Project coverage is 91.26%. Comparing base (47f4820) to head (cde11a4).

Files with missing lines	Patch %	Lines
...rvvs_ESID_dampings/ipopt_solver/secirvvs_ipopt.cpp	0.00%	208 Missing ⚠️
...D_dampings/optimization_model/optimization_model.h	0.00%	164 Missing ⚠️
...ol/secirvvs_ESID_dampings/optimal_control_ESID.cpp	0.00%	67 Missing ⚠️
...gs/optimization_settings/optimization_settings.cpp	0.00%	66 Missing ⚠️
...dampings/control_parameters/control_parameters.cpp	0.00%	63 Missing ⚠️
..._ESID_dampings/constraints/infection_state_utils.h	0.00%	61 Missing ⚠️
...control/secirvvs_ESID_dampings/check_feasibility.h	0.00%	59 Missing ⚠️
...cirvvs_ESID_dampings/helpers/integrator_selector.h	0.00%	48 Missing ⚠️
...vvs_ESID_dampings/constraints/update_constraints.h	0.00%	44 Missing ⚠️
...l/secirvvs_ESID_dampings/create_constraints_ESID.h	0.00%	39 Missing ⚠️
... and 10 more

❗ There is a different number of reports uploaded between BASE (47f4820) and HEAD (cde11a4). Click for more details.

HEAD has 2 uploads less than BASE

Flag	BASE (47f4820)	HEAD (cde11a4)
	3	1

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1421      +/-   ##
==========================================
- Coverage   97.29%   91.26%   -6.04%     
==========================================
  Files         180      200      +20     
  Lines       15646    16678    +1032     
==========================================
- Hits        15223    15221       -2     
- Misses        423     1457    +1034     

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

[julianlitz]

I'm not sure why the ABM test is failing in the test-cpp-gcc-openmp CI job. The ABM code itself hasn’t been modified.
@jubicker, do you have any insights into what might be causing this issue?

The error is located in the CI at line 7335.

Rerunning the job resolved the error. I opened a new issue to report this bug.

TEST_F(TestMobilityRules, hospital)
{
    mio::abm::Location home(mio::abm::LocationType::Home, 0, num_age_groups);
    auto t  = mio::abm::TimePoint(12346);
    auto dt = mio::abm::hours(1);
    auto p_inf =
        make_test_person(this->get_rng(), home, age_group_15_to_34, mio::abm::InfectionState::InfectedSevere, t);
    auto rng_inf = mio::abm::PersonalRandomNumberGenerator(p_inf);

    // Ensure person goes to the hospital when severely infected
    EXPECT_EQ(mio::abm::go_to_hospital(rng_inf, p_inf, t, dt, mio::abm::Parameters(num_age_groups)),
              mio::abm::LocationType::Hospital);

    auto p_car =
        make_test_person(this->get_rng(), home, age_group_15_to_34, mio::abm::InfectionState::InfectedSymptoms);
    auto rng_car = mio::abm::PersonalRandomNumberGenerator(p_car);
    // Ensure person has infection symptoms still stay at home
    EXPECT_EQ(mio::abm::go_to_hospital(rng_car, p_car, t, dt, mio::abm::Parameters(num_age_groups)),
              mio::abm::LocationType::Home);
}

Error message:

 [ RUN      ] TestMobilityRules.quarantine
[warning] Using RNG with seeds: 330212194, 2389258055, 1174281593, 2854787471, 2770270862, 15005904.
 [       OK ] TestMobilityRules.quarantine (0 ms)
 [ RUN      ] TestMobilityRules.hospital
[warning] Using RNG with seeds: 2224242119, 3829650121, 3420097603, 3118483604, 4246163161, 2108093968.
 /home/runner/work/memilio/memilio/cpp/tests/test_abm_mobility_rules.cpp:496: Failure
 Expected equality of these values:
 mio::abm::go_to_hospital(rng_car, p_car, t, dt, mio::abm::Parameters(num_age_groups))
    Which is: 4-byte object <05-00 00-00>
  mio::abm::LocationType::Home
     Which is: 4-byte object <00-00 00-00>
 [  FAILED  ] TestMobilityRules.hospital (0 ms)
 [ RUN      ] TestMobilityRules.go_shopping
 [warning] Using RNG with seeds: 3947717808, 3534382770, 2573329571, 4165076476, 3807877626, 2814792865.
 [       OK ] TestMobilityRules.go_shopping (0 ms)
 [ RUN      ] TestMobilityRules.shop_return
 [warning] Using RNG with seeds: 4253064542, 3408089865, 677807438, 3476096263, 2330537639, 1014114783.
 [       OK ] TestMobilityRules.shop_return (0 ms)