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_time  = 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);

double gageUnitsFactor(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, double current_time);

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);
 
} // namespace gage
} // namespace openswmm
 
#endif // OPENSWMM_GAGE_HPP