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. All inputs are validated before any result is written; invalid input
 * returns SWMM_ERR_BADPARAM and preserves the output array.
 */

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 */