openswmm_api_common.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_API_COMMON_HPP
#define OPENSWMM_API_COMMON_HPP
 
#include "SWMMEngine.hpp"
#include "UnitConversion.hpp"
#include "../../../include/openswmm/engine/openswmm_engine.h"
 
#include <cstring>
#include <algorithm>
#include <cmath>

static inline openswmm::SWMMEngine* to_engine(SWMM_Engine e) noexcept {
    return static_cast<openswmm::SWMMEngine*>(e);
}
 
// ============================================================================
// Unit conversion at the C API boundary
// ============================================================================
//
// The engine stores all state in internal SWMM units (ft, cfs, ft³, ft/s, sec).
// The public C API, like legacy swmm5.c, exposes values in the project's
// configured *display* units (selected by [OPTIONS] FLOW_UNITS): getters return
// display units, setters accept display units.
//
//   getter:  display  = internal * UCF(q)        -> to_display()
//   setter:  internal = display  * UCF_inv(q)    -> to_internal()
//
// Setters multiply by the precomputed reciprocal (UCF_inv / Qcf_inv) rather than
// dividing by UCF — no runtime division at any boundary site. The two roundings
// can leave a written value an ulp or two off when it is read back (98 m →
// 97.99999999999999). Setters pick the internal value whose display reads back
// unchanged where one exists (exact_inverse); for the rest, getters snap the
// result to the nearest 15-significant-digit decimal within two ulps
// (snap_display), so a value written with up to 15 significant digits always
// reads back exactly. `q` is a
// openswmm::ucf::Quantity code (LENGTH, FLOW, VOLUME, LANDAREA, RAINFALL,
// EVAPRATE, RAINDEPTH, ...). Templated on the context type so the include of the
// full SimulationContext definition is deferred to the impl translation units.

static inline double snap_display(double v) noexcept {
    static constexpr double kPow10[23] = {1e0,  1e1,  1e2,  1e3,  1e4,  1e5,  1e6,  1e7,
                                          1e8,  1e9,  1e10, 1e11, 1e12, 1e13, 1e14, 1e15,
                                          1e16, 1e17, 1e18, 1e19, 1e20, 1e21, 1e22};
    const double a = std::fabs(v);
    if (!(a >= 1e-8 && a < 1e15))
        return v;
    // Scale to a 15-digit integer; correct log10 when it lands on the wrong side of a power of ten.
    int k = 14 - static_cast<int>(std::floor(std::log10(a)));
    double m = std::nearbyint(a * kPow10[k]);
    if (m >= 1e15 && k > 0)
        m = std::nearbyint(a * kPow10[--k]);
    else if (m < 1e14 && k < 22)
        m = std::nearbyint(a * kPow10[++k]);
    const double r = std::copysign(m / kPow10[k], v); // powers up to 1e22 are exact
    const double two_ulps = 2.0 * (std::nextafter(a, HUGE_VAL) - a);
    return std::fabs(r - v) <= two_ulps ? r : v;
}

template <class Ctx> static inline double to_display(const Ctx& ctx, int q, double v) noexcept {
    const double f = openswmm::ucf::UCF(q, ctx.options);
    return f == 1.0 ? v : snap_display(v * f);
}

static inline double exact_inverse(double internal, double factor, double display) noexcept {
    if (internal * factor == display || !std::isfinite(internal))
        return internal;
    const double up = std::nextafter(internal, HUGE_VAL);
    if (up * factor == display)
        return up;
    const double down = std::nextafter(internal, -HUGE_VAL);
    return down * factor == display ? down : internal;
}

template <class Ctx> static inline double to_internal(const Ctx& ctx, int q, double v) noexcept {
    return exact_inverse(v * openswmm::ucf::UCF_inv(q, ctx.options),
                         openswmm::ucf::UCF(q, ctx.options), v);
}
 
#define CHECK_HANDLE(e)                                                                            \
    do {                                                                                           \
        if (!(e))                                                                                  \
            return SWMM_ERR_BADHANDLE;                                                             \
    } while (0)
#define CHECK_INDEX(cond)                                                                          \
    do {                                                                                           \
        if (!(cond))                                                                               \
            return SWMM_ERR_BADINDEX;                                                              \
    } while (0)
 
// ============================================================================
// Lifecycle state guards
// ============================================================================

#define CHECK_GEOMETRY(ctx)                                                                        \
    do {                                                                                           \
        if ((ctx).state != openswmm::EngineState::BUILDING &&                                      \
            (ctx).state != openswmm::EngineState::OPENED)                                          \
            return SWMM_ERR_LIFECYCLE;                                                             \
    } while (0)

#define CHECK_EDITABLE(ctx)                                                                        \
    do {                                                                                           \
        if ((ctx).state != openswmm::EngineState::BUILDING &&                                      \
            (ctx).state != openswmm::EngineState::OPENED)                                          \
            return SWMM_ERR_LIFECYCLE;                                                             \
    } while (0)

#define CHECK_INITIAL_COND(ctx)                                                                    \
    do {                                                                                           \
        if ((ctx).state != openswmm::EngineState::BUILDING &&                                      \
            (ctx).state != openswmm::EngineState::OPENED &&                                        \
            (ctx).state != openswmm::EngineState::INITIALIZED)                                     \
            return SWMM_ERR_LIFECYCLE;                                                             \
    } while (0)

#define CHECK_RUNNING(ctx)                                                                         \
    do {                                                                                           \
        if ((ctx).state != openswmm::EngineState::RUNNING)                                         \
            return SWMM_ERR_LIFECYCLE;                                                             \
    } while (0)

#define CHECK_READABLE(ctx)                                                                        \
    do {                                                                                           \
        if ((ctx).state == openswmm::EngineState::CREATED ||                                       \
            (ctx).state == openswmm::EngineState::CLOSED ||                                        \
            (ctx).state == openswmm::EngineState::ERROR_STATE)                                     \
            return SWMM_ERR_LIFECYCLE;                                                             \
    } while (0)
 
#endif /* OPENSWMM_API_COMMON_HPP */