openswmm_xsect.h

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_XSECT_H
#define OPENSWMM_XSECT_H
 
#include "openswmm_engine.h"
#include "openswmm_links.h"
 
#ifdef __cplusplus
extern "C" {
#endif

typedef void* SWMM_XSect;

typedef enum SWMM_UnitSystem {
    SWMM_UNITS_US = 0, 
    SWMM_UNITS_SI = 1  
} SWMM_UnitSystem;
 
/* =========================================================================
 * Construction / destruction
 * ========================================================================= */

SWMM_ENGINE_API int swmm_xsect_create(int shape, double geom1, double geom2,
                                      double geom3, double geom4,
                                      int unit_system, SWMM_XSect* out);

SWMM_ENGINE_API int swmm_xsect_create_irregular(
    const double* stations, const double* elevations, int n_pts,
    double x_left_bank, double x_right_bank,
    double n_left, double n_channel, double n_right, double length_factor,
    int unit_system, SWMM_XSect* out);

SWMM_ENGINE_API int swmm_xsect_create_custom(
    double y_full, const double* curve_depths, const double* curve_widths,
    int n_pts, int unit_system, SWMM_XSect* out);

SWMM_ENGINE_API int swmm_xsect_create_street(
    double width, double curb_height, double slope, double roughness,
    double gutter_depression, double gutter_width, int sides,
    double back_width, double back_slope, double back_roughness,
    int unit_system, SWMM_XSect* out);

SWMM_ENGINE_API int swmm_link_create_xsect(SWMM_Engine engine, int link_idx,
                                           SWMM_XSect* out);

SWMM_ENGINE_API int swmm_xsect_free(SWMM_XSect xsect);
 
/* =========================================================================
 * Identity
 * ========================================================================= */

SWMM_ENGINE_API int swmm_xsect_get_shape(SWMM_XSect xsect, int* shape);

SWMM_ENGINE_API int swmm_xsect_get_units(SWMM_XSect xsect, int* unit_system,
                                         int* flow_units);

SWMM_ENGINE_API const char* swmm_xsect_shape_name(int shape);
 
/* =========================================================================
 * Queries — scalar
 * ========================================================================= */

SWMM_ENGINE_API int swmm_xsect_area_of_depth(SWMM_XSect xsect, double depth,
                                             double* area);

SWMM_ENGINE_API int swmm_xsect_width_of_depth(SWMM_XSect xsect, double depth,
                                              double* width);

SWMM_ENGINE_API int swmm_xsect_hydrad_of_depth(SWMM_XSect xsect, double depth,
                                               double* hydrad);

SWMM_ENGINE_API int swmm_xsect_depth_of_area(SWMM_XSect xsect, double area,
                                             double* depth);

SWMM_ENGINE_API int swmm_xsect_hydrad_of_area(SWMM_XSect xsect, double area,
                                              double* hydrad);

SWMM_ENGINE_API int swmm_xsect_sectfactor_of_area(SWMM_XSect xsect, double area,
                                                  double* sf);

SWMM_ENGINE_API int swmm_xsect_area_of_sectfactor(SWMM_XSect xsect, double sf,
                                                  double* area);

SWMM_ENGINE_API int swmm_xsect_dsda(SWMM_XSect xsect, double area, double* dsda);

SWMM_ENGINE_API int swmm_xsect_critical_depth(SWMM_XSect xsect, double flow,
                                              double* ycrit);

SWMM_ENGINE_API int swmm_xsect_full_properties(SWMM_XSect xsect, double* y_full,
                                               double* a_full, double* r_full,
                                               double* w_max, double* s_full,
                                               double* a_max);

SWMM_ENGINE_API int swmm_xsect_is_open(SWMM_XSect xsect, int* is_open);
 
/* =========================================================================
 * Queries — array
 * ========================================================================= */
/*
 * Each scalar query above has an `_array` counterpart evaluating `n` inputs in
 * one call. `in` and `out` must each hold `n` elements and may alias. `n` == 0
 * is a no-op returning SWMM_OK. A single out-of-domain input fails the whole
 * call with SWMM_ERR_BADPARAM, leaving `out` unspecified.
 */

SWMM_ENGINE_API int swmm_xsect_area_of_depth_array(SWMM_XSect xsect,
                                                   const double* depth, int n,
                                                   double* area);
SWMM_ENGINE_API int swmm_xsect_width_of_depth_array(SWMM_XSect xsect,
                                                    const double* depth, int n,
                                                    double* width);
SWMM_ENGINE_API int swmm_xsect_hydrad_of_depth_array(SWMM_XSect xsect,
                                                     const double* depth, int n,
                                                     double* hydrad);
SWMM_ENGINE_API int swmm_xsect_depth_of_area_array(SWMM_XSect xsect,
                                                   const double* area, int n,
                                                   double* depth);
SWMM_ENGINE_API int swmm_xsect_hydrad_of_area_array(SWMM_XSect xsect,
                                                    const double* area, int n,
                                                    double* hydrad);
SWMM_ENGINE_API int swmm_xsect_sectfactor_of_area_array(SWMM_XSect xsect,
                                                        const double* area,
                                                        int n, double* sf);
SWMM_ENGINE_API int swmm_xsect_area_of_sectfactor_array(SWMM_XSect xsect,
                                                        const double* sf, int n,
                                                        double* area);
SWMM_ENGINE_API int swmm_xsect_dsda_array(SWMM_XSect xsect, const double* area,
                                          int n, double* dsda);
SWMM_ENGINE_API int swmm_xsect_critical_depth_array(SWMM_XSect xsect,
                                                    const double* flow, int n,
                                                    double* ycrit);
 
#ifdef __cplusplus
}
#endif
 
#endif /* OPENSWMM_XSECT_H */