Gage.hpp

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
//
// Copyright 2026 Caleb Buahin
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

 
#ifndef OPENSWMM_GAGE_HPP
#define OPENSWMM_GAGE_HPP
 
#include "../data/SubcatchData.hpp"
#include <cstddef>
#include <vector>
 
namespace openswmm {
 
struct SimulationContext;
struct Table;

namespace gage {
 
// ============================================================================
// Constants
// ============================================================================
 
constexpr double ONE_SECOND = 1.1574074e-5; 
constexpr int MAXPASTRAIN = 48;             
 
// ============================================================================
// Rain type codes
// ============================================================================
 
enum class RainType : int { INTENSITY = 0, VOLUME = 1, CUMULATIVE = 2 };
 
// ============================================================================
// Per-gage state
// ============================================================================
 
struct GageState {
    double rainfall = 0.0;      
    double snowfall = 0.0;      
    double total_precip = 0.0;  
    double rain_accum = 0.0;    
    double api_rainfall = -1.0; 
    double snow_factor = 1.0;   
    double scale_factor = 1.0;  
    double units_factor = 1.0;  
    double adjust_factor = 1.0; 
    double rain_interval = 0.0; 
    RainType rain_type = RainType::INTENSITY;
 
    double past_rain[MAXPASTRAIN] = {}; 
    double past_rain_accum = 0.0;       
    double past_rain_interval = 0.0;    
};
 
// ============================================================================
// Functions
// ============================================================================

double convertRainfall(double raw_value, GageState& state);
 
// ---------------------------------------------------------------------------
// Shared rainfall resolution
// ---------------------------------------------------------------------------
//
// The sequence "pick the gage's series -> apply the rain-type transform ->
// apply units factor -> apply scale factor" is needed by the routing update,
// by report rainfall, and by the swmm_gage_get_rainfall_series C API. Three
// private copies would drift, so the pieces that are genuinely common live
// here. (getReportRainfall deliberately does NOT apply the CUMULATIVE delta —
// see its comment — so it composes these itself rather than calling
// convertGageValue.)

const Table* gageRainSeries(const SimulationContext& ctx, int gage_idx);

bool gageIsUsed(const SimulationContext& ctx, int gage_idx);

double gageNextRainDate(const SimulationContext& ctx, int gage_idx, double t);
 
// Read-only forecast for held surface-process forcing. Adjacent records
// with the same converted rate are one interval; gaps still end rainfall.
// Unlike the legacy runoff clock this uses the exact interval start.
double gageNextRateChange(const SimulationContext& ctx, int gage_idx, double date, double limit);

double gageUnitsFactor(const SimulationContext& ctx, int gage_idx);

int gageSeriesRainType(const SimulationContext& ctx, int gage_idx);

double convertGageValue(double raw, int rain_type, double interval_sec, double& cumul_accum,
                        double units_factor, double scale_factor);

struct PrecipSplit {
    double rainfall = 0.0; 
    double snowfall = 0.0; 
};

PrecipSplit splitPrecip(const SimulationContext& ctx, std::size_t sub);

void updatePastRain(GageState& state, int time_step);

void updatePastRain(SimulationContext& ctx, int time_step);

double getPastRain(const GageState& state, int hours);

void updateAllGages(SimulationContext& ctx, double current_time);

double getReportRainfall(const SimulationContext& ctx, int gage_idx, double report_date);

double getReportRainfallFromSeries(const SimulationContext& ctx, int gage_idx, double report_date);
 
} // namespace gage
} // namespace openswmm
 
#endif // OPENSWMM_GAGE_HPP