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