UnitConversion.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_UNIT_CONVERSION_HPP
#define OPENSWMM_UNIT_CONVERSION_HPP
 
#include <array>
 
namespace openswmm {
 
struct SimulationOptions;
 
namespace ucf {
 
// ============================================================================
// Quantity codes — matching legacy enums.h
// ============================================================================
 
enum Quantity {
    RAINFALL = 0,    
    RAINDEPTH = 1,   
    EVAPRATE = 2,    
    LENGTH = 3,      
    LANDAREA = 4,    
    VOLUME = 5,      
    WINDSPEED = 6,   
    TEMPERATURE = 7, 
    MASS = 8,        
    GWFLOW = 9,      
    FLOW = 10        
};
 
// ============================================================================
// Conversion factor tables — identical to legacy Ucf[10][2] and Qcf[6]
// ============================================================================

static constexpr double Ucf[10][2] = {
    //  US           SI
    {43200.0, 1097280.0},    // RAINFALL: in/hr, mm/hr → ft/sec
    {12.0, 304.8},           // RAINDEPTH: in, mm → ft
    {1036800.0, 26334720.0}, // EVAPRATE: in/day, mm/day → ft/sec
    {1.0, 0.3048},           // LENGTH: ft, m → ft
    {2.2956e-5, 0.92903e-5}, // LANDAREA: ac, ha → ft²
    {1.0, 0.02832},          // VOLUME: ft³, m³ → ft³
    {1.0, 1.608},            // WINDSPEED: mph, km/hr → mph
    {1.0, 1.8},              // TEMPERATURE: °F, °C → °F
    {2.203e-6, 1.0e-6},      // MASS: lb, kg → mg
    {43560.0, 3048.0}        // GWFLOW: cfs/ac, cms/ha → ft/sec
};

static constexpr double Qcf[6] = {
    1.0,     // CFS → cfs
    448.831, // GPM → cfs
    0.64632, // MGD → cfs
    0.02832, // CMS → cfs
    28.317,  // LPS → cfs
    2.4466   // MLD → cfs
};
 
// ============================================================================
// Precomputed reciprocal tables — multiply instead of divide
// ============================================================================
//
// Display → internal conversion is `internal = display / Ucf` everywhere. To
// let hot/peripheral conversion sites multiply by a hoisted loop-invariant
// instead of dividing, expose the compile-time reciprocals. These are derived
// from Ucf/Qcf so they can never drift out of sync.
//
// Convention:  internal = display * Ucf_inv[q][us]   (display → internal)
//              display  = internal * Ucf[q][us]       (internal → display)
 
namespace detail {
inline constexpr std::array<std::array<double, 2>, 10> makeUcfInv() {
    std::array<std::array<double, 2>, 10> r{};
    for (int q = 0; q < 10; ++q)
        for (int u = 0; u < 2; ++u)
            r[static_cast<std::size_t>(q)][static_cast<std::size_t>(u)] = 1.0 / Ucf[q][u];
    return r;
}

inline constexpr std::array<double, 6> makeQcfInv() {
    std::array<double, 6> r{};
    for (int f = 0; f < 6; ++f)
        r[static_cast<std::size_t>(f)] = 1.0 / Qcf[f];
    return r;
}
} // namespace detail

inline constexpr std::array<std::array<double, 2>, 10> Ucf_inv = detail::makeUcfInv();

inline constexpr std::array<double, 6> Qcf_inv = detail::makeQcfInv();
 
// ============================================================================
// Convenience constants — common fixed conversions not unit-system dependent
// ============================================================================
 
static constexpr double ACRES_TO_FT2 = 43560.0;   
static constexpr double FT3_TO_MGAL = 7.48052e-6; 
static constexpr double SEC_PER_DAY = 86400.0;    
 
// ============================================================================
// UCF function — matching legacy UCF()
// ============================================================================

double UCF(int quantity, const SimulationOptions& opts);

double UCF_inv(int quantity, const SimulationOptions& opts);

int getUnitSystem(int flow_units);

inline constexpr const char* FlowUnitWords[6] = {"CFS", "GPM", "MGD", "CMS", "LPS", "MLD"};
 
// ============================================================================
// DisplayUnits — single source of truth for internal → display conversion
// ============================================================================
//
// Built once from SimulationOptions via DisplayUnits::from(). Carries the
// internal→display multipliers (display = internal * factor) plus the matching
// unit-label words, so every output / report consumer shares one definition
// instead of re-deriving Ucf / Qcf inline. Mirrors legacy statsrpt.c / report.c
// UCF()-based output and the VolUnitsWords / PondingUnitsWords tables.
struct DisplayUnits {
    int unit_system = 0; 
    int flow_units = 0;  
 
    // --- internal → display multipliers (display = internal * factor) ---
    double flow = 1.0;      
    double length = 1.0;    
    double volume = 1.0;    
    double rainfall = 1.0;  
    double raindepth = 1.0; 
    double evaprate = 1.0;  
    double landarea = 1.0;  
    double mvol = 1.0;      
    double landvol = 1.0;   
 
    // --- unit-label words (legacy statsrpt.c / report.c) ---
    const char* flow_word = "CFS";             
    const char* length_word = "Feet";          
    const char* depth_word = "in";             
    const char* vel_word = "ft/sec";           
    const char* mvol_word = "10^6 gal";        
    const char* landvol_word = "acre-feet";    
    const char* storage_vol_word = "1000 ft3"; 

    static DisplayUnits from(const SimulationOptions& opts);

    double temperature(double tF) const {
        return unit_system == 0 ? tF : (5.0 / 9.0) * (tF - 32.0);
    }
};
 
} // namespace ucf
} // namespace openswmm
 
#endif // OPENSWMM_UNIT_CONVERSION_HPP