TimestepController.hpp File Reference

Explicit next-timestep computation for the new engine. More...

#include <algorithm>
#include <cmath>

Include dependency graph for TimestepController.hpp:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
class	openswmm::hydraulics::TimestepController
	Static utility class for explicit timestep computation. More...

Namespaces
namespace	openswmm
namespace	openswmm::hydraulics

Detailed Description

Explicit next-timestep computation for the new engine.

The TimestepController implements the explicit timestep formula:

dt_next = min(time_to_next_report, dt_cfl, dt_controls, dt_rdii)

Report clock (legacy parity)

Report scheduling runs on the legacy-parity millisecond clock: ctx.elapsed_ms mirrors legacy NewRoutingTime (accumulated as += 1000.0 * dt, routing.c:309) and ctx.next_report_ms mirrors legacy ReportTime (seeded 1000*ReportStep, advanced by 1000*ReportStep per period, swmm5.c:721/1044). A report period is due when elapsed_ms >= next_report_ms (swmm5.c:1019). Periods dated before REPORT_START are skipped by the writer but the grid still advances (output.c:481).

Key design decision (R18) — resolved for parity

The original refactored design shortened dt so the clock lands exactly on report boundaries (no interpolation). Legacy instead free-steps and interpolates results to the report instant (output.c:650/682). That clamp was REMOVED by the A2 reporting-parity work: compute_next never aligns to the report grid, and postOutputSnapshot performs the legacy-identical interpolation. The only step alignments that remain are legacy-real: the total-duration clamp (swmm5.c:975-980, 1 ms floor) and the RULE_STEP control grid (routing.c:196-204, via ctx.dt_controls_remaining set by SWMMEngine::step from the absolute rule clock).

Integration with IO thread (Phase 5)

The main simulation loop uses TimestepController as follows:

while (!done) {
    double dt_cfl = dynwave.compute_cfl_step(ctx);
    double dt_next = TimestepController::compute_next(ctx, dt_cfl);
 
    hydrology::step(ctx, dt_next);
    hydraulics::step(ctx, dt_next);
    quality::step(ctx, dt_next);
 
    TimestepController::advance(ctx, dt_next);
 
    if (TimestepController::output_due(ctx)) {
        io_thread.post(SimulationSnapshot(ctx));
        TimestepController::reset_output_timer(ctx);
    }
}

See also

Legacy reference: src/solver/routing.c — routing_execute()

tests/unit/test_timestep_controller.cpp

Author

Caleb Buahin caleb.nosp@m..bua.nosp@m.hin@g.nosp@m.mail.nosp@m..com

Copyright

Copyright (c) 2026 Caleb Buahin. All rights reserved.

License\n Apache-2.0