Adding DiffRoute benchmark/ integration and tests with SANDBOX.md

[taddyb]

Issue Addressed

Adds testing infrastructure for DiffRoute integration, validated against RAPID2 reference outputs using the Sandbox test network.

Description

New Test Infrastructure (tests/benchmarks/)

Core Tests (test_diffroute.py):

• Network Construction: Verifies DiffRoute can build RivTree and LTIRouter from RAPID Sandbox network topology
• Basic Routing: Tests forward pass produces valid discharge (correct shape, no NaN, non-negative)
• Gradient Flow: Confirms gradients propagate through the differentiable routing for ML training
• Multiple IRF Models: Tests Muskingum, linear storage, and pure lag impulse response functions

Physical Validation Tests:

• RAPID2 Reference Comparison: Compares DiffRoute output against RAPID2 reference data after spin-up period (correlation > 0.8)
• Downstream Accumulation: Verifies discharge increases at confluences (Q50 >= Q30, Q30 >= Q10, etc.)
• Mass Balance: Checks total input Qext ≈ total outlet discharge within 15% tolerance
• Steady-State Convergence: Verifies constant Qext produces expected steady-state discharge matching analytical solution

Visualization:

• test_generate_hydrograph_plot: Creates 4-panel comparison plot (Qext vs routed, outlet comparison, confluence comparison, all
  reaches)
• NOTE: this plot will be written to a tmp/ dir unless the user uncomments a line. This is what the plot should look like:

DiffRoute Adapter (benchmarks/src/ddr_benchmarks/diffroute_adapter.py)

Utilities to convert DDR Engine COO adjacency matrices to DiffRoute-compatible NetworkX graphs:

• zarr_group_to_networkx(): Direct zarr Group conversion
• coo_to_networkx(): SciPy COO matrix conversion
• zarr_to_networkx(): Path-based loading
• create_muskingum_params(): Generate parameter DataFrames with k/x values

Test Data

RAPID Sandbox network (5 reaches, 10-day simulation):

• Network topology: reaches 10, 20 → 30; reaches 30, 40 → 50 (outlet)
• Input: Qext_Sandbox_19700101_19700110.nc4 (lateral inflow)
• Reference: Qout_Sandbox_19700101_19700110.nc4 (RAPID2 discharge)
• Initial conditions: Qinit_Sandbox_19700101_19700110.nc4

Test Organization Improvements

• Reorganized test directory structure (moved integration tests under tests/engine/)
• Shared fixtures in tests/conftest.py
• CUDA-aware test skipping via @requires_cuda marker

Type of Change

• New feature (non-breaking change which adds functionality)
• Code cleanup/refactor

Checklist

• Branch is up to date with master
• Updated tests or added new tests
• Tests & pre-commit hooks pass
• Code follows established style and conventions