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(dt_output_remaining, dt_cfl, dt_controls, dt_rdii)

Key design decision (R18)

The legacy SWMM engine (src/solver/routing.c, routing_execute()) uses a fixed routing step and then interpolates simulation state to hit output time boundaries. This means the output values are not computed at exact output times — they are interpolated.

The new engine instead:

1. Computes dt_next so the simulation clock lands exactly on the next output boundary.
2. Takes the computed step (no interpolation needed).
3. Posts the exact-time snapshot to the IO thread.

This is more physically correct (no interpolation artifacts) and also simplifies the output writing code (no interpolation logic needed).

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 HydroCouple. All rights reserved.

License\n MIT License