![]() |
OpenSWMM Engine
6.0.0-alpha.1
Data-oriented, plugin-extensible SWMM Engine (6.0.0-alpha.1)
|
C API implementation — transects, streets, inlets, LID controls, LID usage. More...
#include "openswmm_api_common.hpp"#include "../../../include/openswmm/engine/openswmm_infrastructure.h"#include <cctype>#include <string>Functions | |
| SWMM_ENGINE_API int | swmm_transect_add (SWMM_Engine engine, const char *id) |
| Add a new transect for irregular cross-sections. | |
| SWMM_ENGINE_API int | swmm_transect_set_roughness (SWMM_Engine engine, int idx, double n_left, double n_right, double n_channel) |
| Set Manning's roughness for left overbank, right overbank, and channel. | |
| SWMM_ENGINE_API int | swmm_transect_add_station (SWMM_Engine engine, int idx, double station, double elevation) |
| Add a station–elevation data point to a transect. | |
| SWMM_ENGINE_API int | swmm_transect_count (SWMM_Engine engine) |
| Get the total number of transects in the model. | |
| SWMM_ENGINE_API int | swmm_transect_index (SWMM_Engine engine, const char *id) |
| Look up a transect's zero-based index by its string identifier. | |
| SWMM_ENGINE_API const char * | swmm_transect_id (SWMM_Engine engine, int idx) |
| Get the string identifier of a transect by index. | |
| SWMM_ENGINE_API int | swmm_transect_get_roughness (SWMM_Engine engine, int idx, double *n_left, double *n_right, double *n_channel) |
| Get the Manning's roughness values for a transect. | |
| SWMM_ENGINE_API int | swmm_transect_set_bank_stations (SWMM_Engine engine, int idx, double x_left, double x_right) |
| Set the left and right bank stations for a transect. | |
| SWMM_ENGINE_API int | swmm_transect_get_bank_stations (SWMM_Engine engine, int idx, double *x_left, double *x_right) |
| Get the left and right bank stations for a transect. | |
| SWMM_ENGINE_API int | swmm_transect_set_encroachment_stations (SWMM_Engine engine, int idx, double x_left, double x_right) |
| Set the left and right encroachment stations for a transect (BQ-TR-02). | |
| SWMM_ENGINE_API int | swmm_transect_get_encroachment_stations (SWMM_Engine engine, int idx, double *x_left, double *x_right) |
| Get the left and right encroachment stations for a transect (BQ-TR-02). | |
| SWMM_ENGINE_API int | swmm_transect_set_modifiers (SWMM_Engine engine, int idx, double x_factor, double y_factor, double length_factor) |
| Set the station, elevation, and meander modifiers for a transect. | |
| SWMM_ENGINE_API int | swmm_transect_get_modifiers (SWMM_Engine engine, int idx, double *x_factor, double *y_factor, double *length_factor) |
| Get the station, elevation, and meander modifiers for a transect. | |
| SWMM_ENGINE_API int | swmm_transect_set_comments (SWMM_Engine engine, int idx, const char *text) |
| Set the free-form comments / description for a transect. | |
| SWMM_ENGINE_API int | swmm_transect_get_comments (SWMM_Engine engine, int idx, char *buf, int buflen) |
| Get the free-form comments / description for a transect. | |
| SWMM_ENGINE_API int | swmm_transect_get_station_count (SWMM_Engine engine, int idx) |
| Get the number of station–elevation points stored for a transect. | |
| SWMM_ENGINE_API int | swmm_transect_get_station (SWMM_Engine engine, int idx, int station_idx, double *station, double *elevation) |
| Get a single station–elevation pair from a transect. | |
| SWMM_ENGINE_API int | swmm_transect_clear_stations (SWMM_Engine engine, int idx) |
| Remove all station–elevation pairs from a transect. | |
| SWMM_ENGINE_API int | swmm_transect_rename (SWMM_Engine engine, int idx, const char *new_id) |
| Rename an existing transect. | |
| SWMM_ENGINE_API int | swmm_transect_remove (SWMM_Engine engine, int idx) |
| Remove a transect by index. | |
| SWMM_ENGINE_API int | swmm_street_add (SWMM_Engine engine, const char *id) |
| Add a new street cross-section definition. | |
| SWMM_ENGINE_API int | swmm_street_set_params (SWMM_Engine engine, int idx, double t_crown, double h_curb, double sx, double n_road, double gutter_depres, double gutter_width, int sides, double back_width, double back_slope, double back_n) |
| Set the geometric parameters for a street cross-section. | |
| SWMM_ENGINE_API int | swmm_street_count (SWMM_Engine engine) |
| Get the total number of street definitions in the model. | |
| SWMM_ENGINE_API int | swmm_street_index (SWMM_Engine engine, const char *id) |
| Look up a street's zero-based index by its string identifier. | |
| SWMM_ENGINE_API const char * | swmm_street_id (SWMM_Engine engine, int idx) |
| Get the string identifier of a street by index. | |
| SWMM_ENGINE_API int | swmm_inlet_add (SWMM_Engine engine, const char *id, const char *type) |
| Add a new inlet definition. | |
| SWMM_ENGINE_API int | swmm_inlet_set_params (SWMM_Engine engine, int idx, double length, double width, const char *grate_type, double open_area, double splash_veloc) |
| Set the geometric parameters for an inlet. | |
| SWMM_ENGINE_API int | swmm_inlet_count (SWMM_Engine engine) |
| Get the total number of inlet definitions in the model. | |
| SWMM_ENGINE_API int | swmm_inlet_index (SWMM_Engine engine, const char *id) |
| Look up an inlet's zero-based index by its string identifier. | |
| SWMM_ENGINE_API const char * | swmm_inlet_id (SWMM_Engine engine, int idx) |
| Get the string identifier of an inlet by index. | |
| SWMM_ENGINE_API int | swmm_lid_add (SWMM_Engine engine, const char *id, int type) |
| Add a new LID (Low Impact Development) control. | |
| SWMM_ENGINE_API int | swmm_lid_set_surface (SWMM_Engine engine, int idx, double storage, double roughness, double slope) |
| Set the surface layer properties for a LID control. | |
| SWMM_ENGINE_API int | swmm_lid_set_soil (SWMM_Engine engine, int idx, double thick, double porosity, double fc, double wp, double ksat, double kslope) |
| Set the soil layer properties for a LID control. | |
| SWMM_ENGINE_API int | swmm_lid_set_storage (SWMM_Engine engine, int idx, double thick, double void_frac, double ksat) |
| Set the storage layer properties for a LID control. | |
| SWMM_ENGINE_API int | swmm_lid_set_drain (SWMM_Engine engine, int idx, double coeff, double expon, double offset) |
| Set the underdrain properties for a LID control. | |
| SWMM_ENGINE_API int | swmm_lid_count (SWMM_Engine engine) |
| Get the total number of LID controls in the model. | |
| SWMM_ENGINE_API int | swmm_lid_index (SWMM_Engine engine, const char *id) |
| Look up a LID control's zero-based index by its string identifier. | |
| SWMM_ENGINE_API const char * | swmm_lid_id (SWMM_Engine engine, int idx) |
| Get the string identifier of a LID control by index. | |
| SWMM_ENGINE_API int | swmm_lid_usage_add (SWMM_Engine engine, int subcatch_idx, int lid_idx, int number, double area, double width, double init_sat, double from_imperv) |
| Assign a LID control to a subcatchment. | |
C API implementation — transects, streets, inlets, LID controls, LID usage.
| SWMM_ENGINE_API int swmm_inlet_add | ( | SWMM_Engine | engine, |
| const char * | id, | ||
| const char * | type | ||
| ) |
Add a new inlet definition.
| engine | Engine handle (SWMM_STATE_BUILDING). |
| id | Unique null-terminated identifier. |
| type | Inlet type string (e.g., "GRATE", "CURB", "SLOTTED", "CUSTOM"). |
| SWMM_ENGINE_API int swmm_inlet_count | ( | SWMM_Engine | engine | ) |
Get the total number of inlet definitions in the model.
| engine | Engine handle. |
| SWMM_ENGINE_API const char * swmm_inlet_id | ( | SWMM_Engine | engine, |
| int | idx | ||
| ) |
Get the string identifier of an inlet by index.
| engine | Engine handle. |
| idx | Zero-based inlet index. |
| SWMM_ENGINE_API int swmm_inlet_index | ( | SWMM_Engine | engine, |
| const char * | id | ||
| ) |
Look up an inlet's zero-based index by its string identifier.
| engine | Engine handle. |
| id | Null-terminated inlet identifier. |
| SWMM_ENGINE_API int swmm_inlet_set_params | ( | SWMM_Engine | engine, |
| int | idx, | ||
| double | length, | ||
| double | width, | ||
| const char * | grate_type, | ||
| double | open_area, | ||
| double | splash_veloc | ||
| ) |
Set the geometric parameters for an inlet.
| engine | Engine handle. |
| idx | Zero-based inlet index. |
| length | Inlet length. |
| width | Inlet width. |
| grate_type | Grate type string (e.g., "P-50", "GENERIC"). |
| open_area | Open area fraction (0–1). |
| splash_veloc | Splash-over velocity threshold. |
| SWMM_ENGINE_API int swmm_lid_add | ( | SWMM_Engine | engine, |
| const char * | id, | ||
| int | type | ||
| ) |
Add a new LID (Low Impact Development) control.
LID types: 0=BIO_CELL, 1=RAIN_GARDEN, 2=GREEN_ROOF, 3=INFIL_TRENCH, 4=PERM_PAVEMENT, 5=RAIN_BARREL, 6=ROOFTOP_DISCONN, 7=VEGETATIVE_SWALE.
| engine | Engine handle (SWMM_STATE_BUILDING). |
| id | Unique null-terminated identifier. |
| type | LID type code. |
| SWMM_ENGINE_API int swmm_lid_count | ( | SWMM_Engine | engine | ) |
Get the total number of LID controls in the model.
| engine | Engine handle. |
| SWMM_ENGINE_API const char * swmm_lid_id | ( | SWMM_Engine | engine, |
| int | idx | ||
| ) |
Get the string identifier of a LID control by index.
| engine | Engine handle. |
| idx | Zero-based LID index. |
| SWMM_ENGINE_API int swmm_lid_index | ( | SWMM_Engine | engine, |
| const char * | id | ||
| ) |
Look up a LID control's zero-based index by its string identifier.
| engine | Engine handle. |
| id | Null-terminated LID identifier. |
| SWMM_ENGINE_API int swmm_lid_set_drain | ( | SWMM_Engine | engine, |
| int | idx, | ||
| double | coeff, | ||
| double | expon, | ||
| double | offset | ||
| ) |
Set the underdrain properties for a LID control.
| engine | Engine handle. |
| idx | Zero-based LID index. |
| coeff | Drain coefficient. |
| expon | Drain exponent. |
| offset | Drain offset height above the storage layer bottom. |
| SWMM_ENGINE_API int swmm_lid_set_soil | ( | SWMM_Engine | engine, |
| int | idx, | ||
| double | thick, | ||
| double | porosity, | ||
| double | fc, | ||
| double | wp, | ||
| double | ksat, | ||
| double | kslope | ||
| ) |
Set the soil layer properties for a LID control.
| engine | Engine handle. |
| idx | Zero-based LID index. |
| thick | Soil thickness. |
| porosity | Soil porosity (fraction). |
| fc | Field capacity (fraction). |
| wp | Wilting point (fraction). |
| ksat | Saturated hydraulic conductivity. |
| kslope | Slope of the conductivity–moisture curve. |
| SWMM_ENGINE_API int swmm_lid_set_storage | ( | SWMM_Engine | engine, |
| int | idx, | ||
| double | thick, | ||
| double | void_frac, | ||
| double | ksat | ||
| ) |
Set the storage layer properties for a LID control.
| engine | Engine handle. |
| idx | Zero-based LID index. |
| thick | Storage layer thickness. |
| void_frac | Void fraction (porosity of gravel/aggregate). |
| ksat | Seepage rate through the storage layer bottom. |
| SWMM_ENGINE_API int swmm_lid_set_surface | ( | SWMM_Engine | engine, |
| int | idx, | ||
| double | storage, | ||
| double | roughness, | ||
| double | slope | ||
| ) |
Set the surface layer properties for a LID control.
| engine | Engine handle. |
| idx | Zero-based LID index. |
| storage | Surface storage depth. |
| roughness | Surface Manning's n. |
| slope | Surface slope (fraction). |
| SWMM_ENGINE_API int swmm_lid_usage_add | ( | SWMM_Engine | engine, |
| int | subcatch_idx, | ||
| int | lid_idx, | ||
| int | number, | ||
| double | area, | ||
| double | width, | ||
| double | init_sat, | ||
| double | from_imperv | ||
| ) |
Assign a LID control to a subcatchment.
Multiple LID units of the same or different types can be assigned to a single subcatchment.
| engine | Engine handle. |
| subcatch_idx | Zero-based subcatchment index. |
| lid_idx | Zero-based LID control index. |
| number | Number of replicate LID units. |
| area | Area of each LID unit in project area units. |
| width | Top width of the overland flow surface per unit. |
| init_sat | Initial saturation of the soil layer (0–1). |
| from_imperv | Fraction of impervious area runoff treated by this LID (0–1). |
| SWMM_ENGINE_API int swmm_street_add | ( | SWMM_Engine | engine, |
| const char * | id | ||
| ) |
Add a new street cross-section definition.
| engine | Engine handle (SWMM_STATE_BUILDING). |
| id | Unique null-terminated identifier. |
| SWMM_ENGINE_API int swmm_street_count | ( | SWMM_Engine | engine | ) |
Get the total number of street definitions in the model.
| engine | Engine handle. |
| SWMM_ENGINE_API const char * swmm_street_id | ( | SWMM_Engine | engine, |
| int | idx | ||
| ) |
Get the string identifier of a street by index.
| engine | Engine handle. |
| idx | Zero-based street index. |
| SWMM_ENGINE_API int swmm_street_index | ( | SWMM_Engine | engine, |
| const char * | id | ||
| ) |
Look up a street's zero-based index by its string identifier.
| engine | Engine handle. |
| id | Null-terminated street identifier. |
| SWMM_ENGINE_API int swmm_street_set_params | ( | SWMM_Engine | engine, |
| int | idx, | ||
| double | t_crown, | ||
| double | h_curb, | ||
| double | sx, | ||
| double | n_road, | ||
| double | gutter_depres, | ||
| double | gutter_width, | ||
| int | sides, | ||
| double | back_width, | ||
| double | back_slope, | ||
| double | back_n | ||
| ) |
Set the geometric parameters for a street cross-section.
| engine | Engine handle. |
| idx | Zero-based street index. |
| t_crown | Crown thickness (rise of the crown above the gutter). |
| h_curb | Curb height. |
| sx | Cross slope of the roadway. |
| n_road | Manning's n for the road surface. |
| gutter_depres | Gutter depression depth. |
| gutter_width | Gutter width. |
| sides | Number of sides (1 or 2). |
| back_width | Backing (sidewalk) width. |
| back_slope | Backing slope. |
| back_n | Manning's n for the backing area. |
| SWMM_ENGINE_API int swmm_transect_add | ( | SWMM_Engine | engine, |
| const char * | id | ||
| ) |
Add a new transect for irregular cross-sections.
| engine | Engine handle (SWMM_STATE_BUILDING). |
| id | Unique null-terminated identifier. |
| SWMM_ENGINE_API int swmm_transect_add_station | ( | SWMM_Engine | engine, |
| int | idx, | ||
| double | station, | ||
| double | elevation | ||
| ) |
Add a station–elevation data point to a transect.
Stations must be added in order from left to right across the cross-section.
| engine | Engine handle. |
| idx | Zero-based transect index. |
| station | Horizontal distance (station) from a reference. |
| elevation | Elevation at this station. |
| SWMM_ENGINE_API int swmm_transect_clear_stations | ( | SWMM_Engine | engine, |
| int | idx | ||
| ) |
Remove all station–elevation pairs from a transect.
Used by the GUI's snapshot-and-rewrite path: clear then re-add the full station list in one shot.
| engine | Engine handle. |
| idx | Zero-based transect index. |
| SWMM_ENGINE_API int swmm_transect_count | ( | SWMM_Engine | engine | ) |
Get the total number of transects in the model.
| engine | Engine handle. |
| SWMM_ENGINE_API int swmm_transect_get_bank_stations | ( | SWMM_Engine | engine, |
| int | idx, | ||
| double * | x_left, | ||
| double * | x_right | ||
| ) |
Get the left and right bank stations for a transect.
| engine | Engine handle. |
| idx | Zero-based transect index. |
| x_left | [out] Station of the left bank. May be NULL. |
| x_right | [out] Station of the right bank. May be NULL. |
| SWMM_ENGINE_API int swmm_transect_get_comments | ( | SWMM_Engine | engine, |
| int | idx, | ||
| char * | buf, | ||
| int | buflen | ||
| ) |
Get the free-form comments / description for a transect.
Writes the comment into buf with NUL termination; truncates if the buffer is smaller than the comment. Always returns SWMM_OK (an empty comment results in buf[0] == '\0').
| engine | Engine handle. |
| idx | Zero-based transect index. |
| buf | Destination buffer. |
| buflen | Size of buf in bytes (must be > 0). |
| SWMM_ENGINE_API int swmm_transect_get_encroachment_stations | ( | SWMM_Engine | engine, |
| int | idx, | ||
| double * | x_left, | ||
| double * | x_right | ||
| ) |
Get the left and right encroachment stations for a transect (BQ-TR-02).
| engine | Engine handle. |
| idx | Zero-based transect index. |
| x_left | [out] Station of the left encroachment limit. May be NULL. |
| x_right | [out] Station of the right encroachment limit. May be NULL. |
| SWMM_ENGINE_API int swmm_transect_get_modifiers | ( | SWMM_Engine | engine, |
| int | idx, | ||
| double * | x_factor, | ||
| double * | y_factor, | ||
| double * | length_factor | ||
| ) |
Get the station, elevation, and meander modifiers for a transect.
| engine | Engine handle. |
| idx | Zero-based transect index. |
| x_factor | [out] Station spacing multiplier. May be NULL. |
| y_factor | [out] Elevation offset. May be NULL. |
| length_factor | [out] Meander factor. May be NULL. |
| SWMM_ENGINE_API int swmm_transect_get_roughness | ( | SWMM_Engine | engine, |
| int | idx, | ||
| double * | n_left, | ||
| double * | n_right, | ||
| double * | n_channel | ||
| ) |
Get the Manning's roughness values for a transect.
| engine | Engine handle. |
| idx | Zero-based transect index. |
| n_left | [out] Manning's n for the left overbank. May be NULL. |
| n_right | [out] Manning's n for the right overbank. May be NULL. |
| n_channel | [out] Manning's n for the main channel. May be NULL. |
| SWMM_ENGINE_API int swmm_transect_get_station | ( | SWMM_Engine | engine, |
| int | idx, | ||
| int | station_idx, | ||
| double * | station, | ||
| double * | elevation | ||
| ) |
Get a single station–elevation pair from a transect.
| engine | Engine handle. |
| idx | Zero-based transect index. |
| station_idx | Zero-based station-pair index. |
| station | [out] Horizontal distance. May be NULL. |
| elevation | [out] Elevation at this station. May be NULL. |
| SWMM_ENGINE_API int swmm_transect_get_station_count | ( | SWMM_Engine | engine, |
| int | idx | ||
| ) |
Get the number of station–elevation points stored for a transect.
| engine | Engine handle. |
| idx | Zero-based transect index. |
| SWMM_ENGINE_API const char * swmm_transect_id | ( | SWMM_Engine | engine, |
| int | idx | ||
| ) |
Get the string identifier of a transect by index.
| engine | Engine handle. |
| idx | Zero-based transect index. |
| SWMM_ENGINE_API int swmm_transect_index | ( | SWMM_Engine | engine, |
| const char * | id | ||
| ) |
Look up a transect's zero-based index by its string identifier.
| engine | Engine handle. |
| id | Null-terminated transect identifier. |
| SWMM_ENGINE_API int swmm_transect_remove | ( | SWMM_Engine | engine, |
| int | idx | ||
| ) |
Remove a transect by index.
Out-of-range indices are a SWMM_OK no-op (mirrors the pattern mutation API — see test_pattern_mutation_api.cpp). Remaining transects preserve their relative order; their indices shift down by one.
| engine | Engine handle. |
| idx | Zero-based transect index. |
| SWMM_ENGINE_API int swmm_transect_rename | ( | SWMM_Engine | engine, |
| int | idx, | ||
| const char * | new_id | ||
| ) |
Rename an existing transect.
Refuses on collision with another existing transect name (case insensitive); same-name is a no-op SWMM_OK.
| engine | Engine handle. |
| idx | Zero-based transect index. |
| new_id | New null-terminated identifier. |
| SWMM_ENGINE_API int swmm_transect_set_bank_stations | ( | SWMM_Engine | engine, |
| int | idx, | ||
| double | x_left, | ||
| double | x_right | ||
| ) |
Set the left and right bank stations for a transect.
Bank stations delimit the main channel from the overbanks; they are independent of the encroachment stations (BQ-TR-02).
| engine | Engine handle. |
| idx | Zero-based transect index. |
| x_left | Station of the left bank. |
| x_right | Station of the right bank. |
| SWMM_ENGINE_API int swmm_transect_set_comments | ( | SWMM_Engine | engine, |
| int | idx, | ||
| const char * | text | ||
| ) |
Set the free-form comments / description for a transect.
| engine | Engine handle. |
| idx | Zero-based transect index. |
| text | Null-terminated comment string. NULL clears the comment. |
| SWMM_ENGINE_API int swmm_transect_set_encroachment_stations | ( | SWMM_Engine | engine, |
| int | idx, | ||
| double | x_left, | ||
| double | x_right | ||
| ) |
Set the left and right encroachment stations for a transect (BQ-TR-02).
Encroachment stations are distinct from bank stations and identify floodplain encroachment limits (HEC-RAS convention). On legacy [TRANSECTS] X1 records that omit the trailing encroachment columns, the INP parser may default these to the bank stations to preserve backward compatibility; callers writing programmatic values via this API are setting them explicitly.
| engine | Engine handle. |
| idx | Zero-based transect index. |
| x_left | Station of the left encroachment limit. |
| x_right | Station of the right encroachment limit. |
| SWMM_ENGINE_API int swmm_transect_set_modifiers | ( | SWMM_Engine | engine, |
| int | idx, | ||
| double | x_factor, | ||
| double | y_factor, | ||
| double | length_factor | ||
| ) |
Set the station, elevation, and meander modifiers for a transect.
Maps to the xFactor, yFactor, and lengthFactor parameters on the [TRANSECTS] X1 record:
x_factor = station-spacing multiplier (default 1.0).y_factor = elevation offset added to every station elevation (default 0.0 — engine stores 1.0 as a no-op marker at swmm_transect_add time).length_factor = meander factor = channel / floodplain length ratio (default 1.0).| engine | Engine handle. |
| idx | Zero-based transect index. |
| x_factor | Station spacing multiplier. |
| y_factor | Elevation offset. |
| length_factor | Meander factor (channel/floodplain length ratio). |
| SWMM_ENGINE_API int swmm_transect_set_roughness | ( | SWMM_Engine | engine, |
| int | idx, | ||
| double | n_left, | ||
| double | n_right, | ||
| double | n_channel | ||
| ) |
Set Manning's roughness for left overbank, right overbank, and channel.
| engine | Engine handle. |
| idx | Zero-based transect index. |
| n_left | Manning's n for the left overbank. |
| n_right | Manning's n for the right overbank. |
| n_channel | Manning's n for the main channel. |