OpenSWMM Engine  6.0.0-alpha.4
Data-oriented, plugin-extensible SWMM Engine (6.0.0-alpha.4)
Loading...
Searching...
No Matches
openswmm_solver.h File Reference

Prototypes for SWMM5 API functions. More...

Include dependency graph for openswmm_solver.h:

Go to the source code of this file.

Classes

struct  swmm_SubcatchStats
 Cumulative subcatchment statistics. More...
 
struct  swmm_NodeStats
 Cumulative node statistics. More...
 
struct  swmm_StorageStats
 Cumulative storage node statistics. More...
 
struct  swmm_OutfallStats
 Cumulative outfall node statistics. More...
 
struct  swmm_LinkStats
 Cumulative link statistics. More...
 
struct  swmm_PumpStats
 Cumulative pump statistics. More...
 
struct  swmm_RoutingTotals
 System-level flow routing mass balance totals (raw ft3; pctError is percent). More...
 
struct  swmm_RunoffTotals
 System-level surface runoff mass balance totals. More...
 

Macros

#define OPENSWMM_JUNCTION_STORAGE   1
 
#define SWMM_MAX_FLOW_CLASSES   7
 Maximum number of flow classification classes for link statistics.
 

Typedefs

typedef void(* progress_callback) (double progress)
 Receive synchronous legacy simulation progress.
 
typedef void(* swmm_LegacyWarningCallback) (const char *message, void *userData)
 Receive one process-global legacy engine warning.
 

Enumerations

enum  swmm_Object {
  swmm_GAGE ,
  swmm_SUBCATCH ,
  swmm_NODE ,
  swmm_LINK ,
  swmm_POLLUTANT ,
  swmm_LANDUSE ,
  swmm_TIME_PATTERN ,
  swmm_CURVE ,
  swmm_TIMESERIES ,
  swmm_CONTROL_RULE ,
  swmm_TRANSECT ,
  swmm_AQUIFER ,
  swmm_UNIT_HYDROGRAPH ,
  swmm_SNOWPACK ,
  smmm_XSECTION_SHAPE ,
  swmm_LID ,
  swmm_STREET ,
  swmm_INLET ,
  swmm_SYSTEM = 100
}
 Enumeration of object types used in SWMM5. More...
 
enum  swmm_NodeType {
  swmm_JUNCTION = 0 ,
  swmm_OUTFALL = 1 ,
  swmm_STORAGE = 2 ,
  swmm_DIVIDER = 3
}
 Enumeration of node types used in SWMM5. More...
 
enum  swmm_LinkType {
  swmm_CONDUIT = 0 ,
  swmm_PUMP = 1 ,
  swmm_ORIFICE = 2 ,
  swmm_WEIR = 3 ,
  swmm_OUTLET = 4
}
 Enumeration of link types used in SWMM5. More...
 
enum  swmm_GageProperty {
  swmm_GAGE_TOTAL_PRECIPITATION = 100 ,
  swmm_GAGE_RAINFALL ,
  swmm_GAGE_SNOWFALL ,
  swmm_GAGE_SCALEFACTOR
}
 Enumeration of gage properties used in SWMM5. More...
 
enum  swmm_SubcatchProperty {
  swmm_SUBCATCH_AREA = 200 ,
  swmm_SUBCATCH_RAINGAGE ,
  swmm_SUBCATCH_RAINFALL ,
  swmm_SUBCATCH_EVAP ,
  swmm_SUBCATCH_INFIL ,
  swmm_SUBCATCH_RUNOFF ,
  swmm_SUBCATCH_RPTFLAG ,
  swmm_SUBCATCH_WIDTH ,
  swmm_SUBCATCH_SLOPE ,
  swmm_SUBCATCH_OUTLET_TYPE ,
  swmm_SUBCATCH_OUTLET_INDEX ,
  swmm_SUBCATCH_INFILTRATION_MODEL ,
  swmm_SUBCATCH_FRACTION_IMPERVIOUS ,
  swmm_SUBCATCH_SUB_AREA_ROUTE_TO ,
  swmm_SUBCATCH_SUB_AREA_FRACTION_OUTLET ,
  swmm_SUBCATCH_SUB_AREA_MANNINGS_N ,
  swmm_SUBCATCH_SUB_AREA_FRACTION_AREA ,
  swmm_SUBCATCH_SUB_AREA_DEPRESSION_STORAGE ,
  swmm_SUBCATCH_SUB_AREA_INFLOW ,
  swmm_SUBCATCH_SUB_AREA_RUNOFF ,
  swmm_SUBCATCH_SUB_AREA_DEPTH ,
  swmm_SUBCATCH_LID_UNITS_COUNT ,
  swmm_SUBCATCH_LID_UNITS_PERV_AREA ,
  swmm_SUBCATCH_LID_UNITS_FLOW_TO_PERV_AREA ,
  swmm_SUBCATCH_LID_UNITS_DRAIN_FLOW ,
  swmm_SUBCATCH_LID_UNIT_REPLICATES ,
  swmm_SUBCATCH_LID_UNIT_AREA ,
  swmm_SUBCATCH_LID_UNIT_FULL_WIDTH ,
  swmm_SUBCATCH_LID_UNIT_BOTTOM_WIDTH ,
  swmm_SUBCATCH_LID_UNIT_INIT_SATURATION ,
  swmm_SUBCATCH_LID_UNIT_FROM_IMPERVIOUS ,
  swmm_SUBCATCH_LID_UNIT_FROM_PERVIOUS ,
  swmm_SUBCATCH_LID_UNIT_TO_PERVIOUS ,
  swmm_SUBCATCH_LID_UNIT_RECEIVING_OUTLET_TYPE ,
  swmm_SUBCATCH_LID_UNIT_RECEIVING_OUTLET_INDEX ,
  swmm_SUBCATCH_LID_UNIT_SURFACE_DEPTH ,
  swmm_SUBCATCH_LID_UNIT_SOIL_MOISTURE ,
  swmm_SUBCATCH_LID_UNIT_GREEN_AMPT_CAPILLARY_SUCTION ,
  swmm_SUBCATCH_LID_UNIT_GREEN_AMPT_SATURATED_CONDUCTIVITY ,
  swmm_SUBCATCH_LID_UNIT_GREEN_AMPT_MAXIMUM_SOIL_MOISTURE_DEFICIT ,
  swmm_SUBCATCH_CURB_LENGTH ,
  swmm_SUBCATCH_API_RAINFALL ,
  swmm_SUBCATCH_API_SNOWFALL ,
  swmm_SUBCATCH_POLLUTANT_BUILDUP ,
  swmm_SUBCATCH_EXTERNAL_POLLUTANT_BUILDUP ,
  swmm_SUBCATCH_POLLUTANT_RUNOFF_CONCENTRATION ,
  swmm_SUBCATCH_POLLUTANT_PONDED_CONCENTRATION ,
  swmm_SUBCATCH_POLLUTANT_TOTAL_LOAD ,
  swmm_SUBCATCH_API_PET ,
  swmm_SUBCATCH_GW_MOISTURE ,
  swmm_SUBCATCH_GW_LOWER_DEPTH ,
  swmm_SUBCATCH_SNOW_SWE ,
  swmm_SUBCATCH_SNOW_FW ,
  swmm_SUBCATCH_SNOW_ATI ,
  swmm_SUBCATCH_SNOW_COLDC ,
  swmm_SUBCATCH_RAIN_SCALE_FACTOR ,
  swmm_SUBCATCH_SNOW_SCALE_FACTOR
}
 Enumeration of subcatchment properties used in SWMM5. More...
 
enum  swmm_NodeProperty {
  swmm_NODE_TYPE = 300 ,
  swmm_NODE_ELEV ,
  swmm_NODE_MAXDEPTH ,
  swmm_NODE_DEPTH ,
  swmm_NODE_HEAD ,
  swmm_NODE_VOLUME ,
  swmm_NODE_LATFLOW ,
  swmm_NODE_INFLOW ,
  swmm_NODE_OVERFLOW ,
  swmm_NODE_RPTFLAG ,
  swmm_NODE_SURCHARGE_DEPTH ,
  swmm_NODE_PONDED_AREA ,
  swmm_NODE_INITIAL_DEPTH ,
  swmm_NODE_POLLUTANT_CONCENTRATION ,
  swmm_NODE_POLLUTANT_LATMASS_FLUX ,
  swmm_NODE_OUTFLOW ,
  swmm_NODE_STORAGE_AREA
}
 Enumeration of node properties used in SWMM5. More...
 
enum  swmm_LinkProperty {
  swmm_LINK_TYPE = 400 ,
  swmm_LINK_NODE1 = 401 ,
  swmm_LINK_NODE2 = 402 ,
  swmm_LINK_LENGTH = 403 ,
  swmm_LINK_SLOPE = 404 ,
  swmm_LINK_FULLDEPTH = 405 ,
  swmm_LINK_FULLFLOW = 406 ,
  swmm_LINK_SETTING = 407 ,
  swmm_LINK_TIMEOPEN = 408 ,
  swmm_LINK_TIMECLOSED = 409 ,
  swmm_LINK_FLOW = 410 ,
  swmm_LINK_DEPTH = 411 ,
  swmm_LINK_VELOCITY = 412 ,
  swmm_LINK_TOPWIDTH = 413 ,
  swmm_LINK_VOLUME = 414 ,
  swmm_LINK_CAPACITY = 415 ,
  swmm_LINK_RPTFLAG = 416 ,
  swmm_LINK_OFFSET1 = 417 ,
  swmm_LINK_OFFSET2 = 418 ,
  swmm_LINK_INITIAL_FLOW = 419 ,
  swmm_LINK_FLOW_LIMIT = 420 ,
  swmm_LINK_INLET_LOSS = 421 ,
  swmm_LINK_OUTLET_LOSS = 422 ,
  swmm_LINK_AVERAGE_LOSS = 423 ,
  swmm_LINK_SEEPAGE_RATE = 424 ,
  swmm_LINK_HAS_FLAPGATE = 425 ,
  swmm_LINK_POLLUTANT_CONCENTRATION = 426 ,
  swmm_LINK_POLLUTANT_LOAD = 427 ,
  swmm_LINK_POLLUTANT_LATMASS_FLUX = 428
}
 Enumeration of link properties used in SWMM5. More...
 
enum  swmm_PollutProperty {
  swmm_POLLUT_RAIN_CONCEN = 500 ,
  swmm_POLLUT_GW_CONCEN ,
  swmm_POLLUT_RDII_CONCEN ,
  swmm_POLLUT_DWF_CONCEN ,
  swmm_POLLUT_KDECAY ,
  swmm_POLLUT_CO_POLLUTANT ,
  swmm_POLLUT_CO_FRACTION ,
  swmm_POLLUT_SNOW_ONLY ,
  swmm_POLLUT_INIT_CONCEN
}
 Enumeration of pollutant properties used in SWMM5. More...
 
enum  swmm_PatternProperty {
  swmm_PATTERN_FACTOR = 600 ,
  swmm_PATTERN_COUNT ,
  swmm_PATTERN_TYPE
}
 Enumeration of time-pattern properties used in SWMM5. More...
 
enum  swmm_LanduseProperty {
  swmm_LANDUSE_SWEEP_INTERVAL = 700 ,
  swmm_LANDUSE_SWEEP_REMOVAL ,
  swmm_LANDUSE_BUILDUP_FUNC ,
  swmm_LANDUSE_BUILDUP_COEFF1 ,
  swmm_LANDUSE_BUILDUP_COEFF2 ,
  swmm_LANDUSE_BUILDUP_COEFF3 ,
  swmm_LANDUSE_BUILDUP_NORMALIZER ,
  swmm_LANDUSE_WASHOFF_FUNC ,
  swmm_LANDUSE_WASHOFF_COEFF ,
  swmm_LANDUSE_WASHOFF_EXPON ,
  swmm_LANDUSE_WASHOFF_SWEEP_EFFIC ,
  swmm_LANDUSE_WASHOFF_BMP_EFFIC
}
 Enumeration of land-use properties used in SWMM5. More...
 
enum  swmm_AquiferProperty {
  swmm_AQUIFER_POROSITY = 800 ,
  swmm_AQUIFER_WILTING_POINT ,
  swmm_AQUIFER_FIELD_CAPACITY ,
  swmm_AQUIFER_CONDUCTIVITY ,
  swmm_AQUIFER_CONDUCT_SLOPE ,
  swmm_AQUIFER_TENSION_SLOPE ,
  swmm_AQUIFER_UPPER_EVAP_FRAC ,
  swmm_AQUIFER_LOWER_EVAP_DEPTH ,
  swmm_AQUIFER_LOWER_LOSS_COEFF ,
  swmm_AQUIFER_BOTTOM_ELEV ,
  swmm_AQUIFER_WATER_TABLE_ELEV ,
  swmm_AQUIFER_UPPER_MOISTURE
}
 Enumeration of aquifer properties used in SWMM5. More...
 
enum  swmm_SystemProperty {
  swmm_STARTDATE = 0 ,
  swmm_CURRENTDATE = 1 ,
  swmm_ELAPSEDTIME = 2 ,
  swmm_ROUTESTEP = 3 ,
  swmm_MAXROUTESTEP = 4 ,
  swmm_REPORTSTEP = 5 ,
  swmm_TOTALSTEPS = 6 ,
  swmm_NOREPORT = 7 ,
  swmm_FLOWUNITS = 8 ,
  swmm_ENDDATE = 9 ,
  swmm_REPORTSTART = 10 ,
  swmm_UNITSYSTEM = 11 ,
  swmm_SURCHARGEMETHOD = 12 ,
  swmm_ALLOWPONDING = 13 ,
  swmm_INERTIADAMPING = 14 ,
  swmm_NORMALFLOWLTD = 15 ,
  swmm_SKIPSTEADYSTATE = 16 ,
  swmm_IGNORERAINFALL = 17 ,
  swmm_IGNORERDII = 18 ,
  swmm_IGNORESNOWMELT = 19 ,
  swmm_IGNOREGROUNDWATER = 20 ,
  swmm_IGNOREROUTING = 21 ,
  swmm_IGNOREQUALITY = 22 ,
  swmm_ERROR_CODE = 23 ,
  swmm_RULESTEP = 24 ,
  swmm_SWEEPSTART = 25 ,
  swmm_SWEEPEND = 26 ,
  swmm_MAXTRIALS = 27 ,
  swmm_NUMTHREADS = 28 ,
  swmm_MINROUTESTEP = 29 ,
  swmm_LENGTHENINGSTEP = 30 ,
  swmm_STARTDRYDAYS = 31 ,
  swmm_COURANTFACTOR = 32 ,
  swmm_MINSURFAREA = 33 ,
  swmm_MINSLOPE = 34 ,
  swmm_RUNOFFERROR = 35 ,
  swmm_FLOWERROR = 36 ,
  swmm_QUALERROR = 37 ,
  swmm_HEADTOL = 38 ,
  swmm_SYSFLOWTOL = 39 ,
  swmm_LATFLOWTOL = 40 ,
  swmm_EVAPRATE = 41 ,
  swmm_TEMPERATURE = 42 ,
  swmm_API_TEMPERATURE = 43 ,
  swmm_WINDSPEED = 44 ,
  swmm_API_WINDSPEED = 45 ,
  swmm_API_EVAP = 46 ,
  swmm_EVAP_DRY_ONLY = 47
}
 Enumeration of system properties used in SWMM5. More...
 
enum  swmm_FlowUnitsProperty {
  swmm_CFS = 0 ,
  swmm_GPM = 1 ,
  swmm_MGD = 2 ,
  swmm_CMS = 3 ,
  swmm_LPS = 4 ,
  swmm_MLD = 5
}
 Enumeration of flow units used in SWMM5. More...
 
enum  swmm_API_Errors {
  ERR_API_NOT_OPEN = -999901 ,
  ERR_API_NOT_STARTED = -999902 ,
  ERR_API_NOT_ENDED = -999903 ,
  ERR_API_OBJECT_TYPE = -999904 ,
  ERR_API_OBJECT_INDEX = -999905 ,
  ERR_API_OBJECT_NAME = -999906 ,
  ERR_API_PROPERTY_TYPE = -999907 ,
  ERR_API_PROPERTY_VALUE = -999908 ,
  ERR_API_TIME_PERIOD = -999909 ,
  ERR_API_HOTSTART_FILE_OPEN = -999910 ,
  ERR_API_HOTSTART_FILE_FORMAT = -999911 ,
  ERR_API_IS_RUNNING = -999912
}
 Enumeration of API errors used in SWMM5. More...
 

Functions

int EXPORT_OPENSWMMCORE_SOLVER_API swmm_run (const char *inputFile, const char *reportFile, const char *outputFile)
 Run the global legacy engine through open/start/step/end/report/close.
 
int EXPORT_OPENSWMMCORE_SOLVER_API swmm_run_with_callback (const char *inputFile, const char *reportFile, const char *outputFile, progress_callback callback)
 Run the global legacy engine and report synchronous step progress.
 
int EXPORT_OPENSWMMCORE_SOLVER_API swmm_open (const char *inputFile, const char *reportFile, const char *outputFile)
 Open, parse and validate a single process-global legacy model.
 
int EXPORT_OPENSWMMCORE_SOLVER_API swmm_start (int saveFlag)
 Initialize the opened model and its computing systems.
 
int EXPORT_OPENSWMMCORE_SOLVER_API swmm_step (double *elapsedTime)
 Advance one routing step and save any scheduled results.
 
int EXPORT_OPENSWMMCORE_SOLVER_API swmm_stride (int strideStep, double *elapsedTime)
 Advance routing up to a requested interval while retaining the configured step afterward.
 
int EXPORT_OPENSWMMCORE_SOLVER_API swmm_useHotStart (const char *hotStartFile)
 Select a validated hotstart input for the next start.
 
int EXPORT_OPENSWMMCORE_SOLVER_API swmm_saveHotStart (const char *hotStartFile)
 Write current running state to a named hotstart file.
 
int EXPORT_OPENSWMMCORE_SOLVER_API swmm_end (void)
 Finalize output/continuity and close computing systems while retaining model/statistics.
 
int EXPORT_OPENSWMMCORE_SOLVER_API swmm_report (void)
 Write the full results report from the current legacy project.
 
int EXPORT_OPENSWMMCORE_SOLVER_API swmm_close (void)
 Release global statistics/model/output resources and close project files.
 
int EXPORT_OPENSWMMCORE_SOLVER_API swmm_getMassBalErr (float *runoffErr, float *flowErr, float *qualErr)
 Read finalized runoff, routing and quality continuity errors.
 
int EXPORT_OPENSWMMCORE_SOLVER_API swmm_getRunningMassBalErr (float *runoffErr, float *flowErr)
 Recompute current runoff and routing continuity errors during a run.
 
int EXPORT_OPENSWMMCORE_SOLVER_API swmm_getVersion (void)
 Return the compiled legacy engine version integer.
 
int EXPORT_OPENSWMMCORE_SOLVER_API swmm_getError (char *errMsg, int msgLen)
 Copy the current terminating error text into caller-owned storage.
 
int EXPORT_OPENSWMMCORE_SOLVER_API swmm_getErrorFromCode (int errorCode, char *outErrMsg[1024])
 Copy the text for an explicit internal legacy error enum.
 
int EXPORT_OPENSWMMCORE_SOLVER_API swmm_getWarnings (void)
 Return the current project warning counter.
 
int EXPORT_OPENSWMMCORE_SOLVER_API swmm_setWarningCallback (swmm_LegacyWarningCallback cb, void *userData)
 Retain a process-global callback for each emitted warning.
 
int EXPORT_OPENSWMMCORE_SOLVER_API swmm_getCount (int objType)
 Get the number of objects in a legacy category.
 
int EXPORT_OPENSWMMCORE_SOLVER_API swmm_getName (int objType, int index, char *name, int size)
 Copy the ID of one named legacy object.
 
int EXPORT_OPENSWMMCORE_SOLVER_API swmm_getIndex (int objType, const char *name)
 Find a named object in the opened global model.
 
double EXPORT_OPENSWMMCORE_SOLVER_API swmm_getValue (int property, int index)
 Read one legacy numeric-family property.
 
double EXPORT_OPENSWMMCORE_SOLVER_API swmm_getValueExpanded (int objType, int property, int index, int subIndex, int pollutantIndex)
 Read one explicitly typed property.
 
int EXPORT_OPENSWMMCORE_SOLVER_API swmm_setValue (int property, int index, double value)
 Set one legacy numeric-family property.
 
int EXPORT_OPENSWMMCORE_SOLVER_API swmm_setValueExpanded (int objType, int property, int index, int subIndex, int pollutantIndex, double value)
 Set one explicitly typed property.
 
int EXPORT_OPENSWMMCORE_SOLVER_API swmm_setTreatment (int nodeIndex, int pollutantIndex, const char *expression)
 Replace a node/pollutant treatment expression for subsequent routing steps.
 
int EXPORT_OPENSWMMCORE_SOLVER_API swmm_clearTreatment (int nodeIndex, int pollutantIndex)
 Remove a node/pollutant treatment equation.
 
int EXPORT_OPENSWMMCORE_SOLVER_API swmm_setLidDrain (int lidIndex, double coeff, double expon, double offset)
 Replace live underdrain parameters of a legacy LID process.
 
double EXPORT_OPENSWMMCORE_SOLVER_API swmm_getSavedValue (int property, int index, int period)
 Read a saved output value after the run has ended.
 
void EXPORT_OPENSWMMCORE_SOLVER_API swmm_writeLine (const char *line)
 Append a caller line to the open report.
 
void EXPORT_OPENSWMMCORE_SOLVER_API swmm_decodeDate (double date, int *year, int *month, int *day, int *hour, int *minute, int *second, int *dayOfWeek)
 Decode an absolute legacy SWMM date/time into calendar fields.
 
double EXPORT_OPENSWMMCORE_SOLVER_API swmm_encodeDate (int year, int month, int day, int hour, int minute, int second)
 Encode calendar date and clock fields using the legacy date utilities.
 
int EXPORT_OPENSWMMCORE_SOLVER_API swmm_getSubcatchStats (int index, swmm_SubcatchStats *stats)
 Copy raw internal subcatchment statistics.
 
int EXPORT_OPENSWMMCORE_SOLVER_API swmm_getNodeStats (int index, swmm_NodeStats *stats)
 Copy raw internal node statistics.
 
int EXPORT_OPENSWMMCORE_SOLVER_API swmm_getStorageStats (int index, swmm_StorageStats *stats)
 Copy raw internal storage node statistics.
 
int EXPORT_OPENSWMMCORE_SOLVER_API swmm_getOutfallStats (int index, swmm_OutfallStats *stats)
 Copy raw internal outfall node statistics.
 
int EXPORT_OPENSWMMCORE_SOLVER_API swmm_getLinkStats (int index, swmm_LinkStats *stats)
 Copy raw internal link statistics.
 
int EXPORT_OPENSWMMCORE_SOLVER_API swmm_getPumpStats (int index, swmm_PumpStats *stats)
 Copy raw internal pump link statistics.
 
int EXPORT_OPENSWMMCORE_SOLVER_API swmm_getSystemRoutingTotals (swmm_RoutingTotals *totals)
 Copy raw global routing continuity totals.
 
int EXPORT_OPENSWMMCORE_SOLVER_API swmm_getSystemRunoffTotals (swmm_RunoffTotals *totals)
 Copy raw global runoff continuity totals.
 

Detailed Description

Prototypes for SWMM5 API functions.

Author
L. Rossman
Date
Created on: 2021-11-01
Last edited on: 2024-12-23 (Build 5.3.0)

This file contains the prototypes for SWMM5 API functions.

Update History

  • Build 5.3.0:
    • Added new functions to support saving hotstart files at specific times.
    • Expansions to the SWMM API to include attributes of more objects and water quality.
Author
Caleb Buahin caleb.nosp@m..bua.nosp@m.hin@g.nosp@m.mail.nosp@m..com (OpenSWMM maintenance and extensions)
License
Apache-2.0 for OpenSWMM contributions; original EPA SWMM provenance is retained.

Macro Definition Documentation

◆ OPENSWMM_JUNCTION_STORAGE

#define OPENSWMM_JUNCTION_STORAGE   1

◆ SWMM_MAX_FLOW_CLASSES

#define SWMM_MAX_FLOW_CLASSES   7

Maximum number of flow classification classes for link statistics.

Typedef Documentation

◆ progress_callback

typedef void(* progress_callback) (double progress)

Receive synchronous legacy simulation progress.

Borrowed function pointer used during swmm_run_with_callback; no return value/cancellation channel. Do not reenter or concurrently use the process-global legacy engine.

Parameters
[in]progressNewRoutingTime/TotalDuration fraction supplied after an attempted step; caller should handle completion/error callbacks and does not own engine state.

◆ swmm_LegacyWarningCallback

typedef void(* swmm_LegacyWarningCallback) (const char *message, void *userData)

Receive one process-global legacy engine warning.

Runs on the engine thread. Avoid reentrant lifecycle/model edits and keep callback code/userData alive until replacement or disabling.

Parameters
[in]messageBorrowed null-terminated warning text valid only during this synchronous callback; copy it to retain.
[in]userDataOpaque pointer supplied to swmm_setWarningCallback; ownership remains with the registering caller.

Enumeration Type Documentation

◆ swmm_API_Errors

Enumeration of API errors used in SWMM5.

Enumerator
ERR_API_NOT_OPEN 

API error for file not opened.

ERR_API_NOT_STARTED 

API error for API not started.

ERR_API_NOT_ENDED 

API error for API not ended.

ERR_API_OBJECT_TYPE 

API error for errorneous object type.

ERR_API_OBJECT_INDEX 

API error for errorneous object index.

ERR_API_OBJECT_NAME 

API error for errorneous object name.

ERR_API_PROPERTY_TYPE 

API error for errorneous property type.

ERR_API_PROPERTY_VALUE 

API error for errorneous property value.

ERR_API_TIME_PERIOD 

API error for errorneous time period.

ERR_API_HOTSTART_FILE_OPEN 

API error for errorneous hotstart file open.

ERR_API_HOTSTART_FILE_FORMAT 

API error for errorneous hotstart file format.

ERR_API_IS_RUNNING 

API error for API already running.

◆ swmm_AquiferProperty

Enumeration of aquifer properties used in SWMM5.

Values use input-file units (the [AQUIFERS] line columns). The flux-coefficient properties (conductivity, slopes, evap/loss coefficients) are read live each step, so they are settable both before the simulation starts and while it is running; the structural / initial-condition properties (porosity, wilting point, field capacity, bottom elevation, water table elevation, upper moisture) bound or seed the groundwater state and return ERR_API_IS_RUNNING while the simulation is running.

Enumerator
swmm_AQUIFER_POROSITY 

Porosity (volumetric fraction, pre-start-only)

swmm_AQUIFER_WILTING_POINT 

Wilting point (volumetric fraction, pre-start-only)

swmm_AQUIFER_FIELD_CAPACITY 

Field capacity (volumetric fraction, pre-start-only)

swmm_AQUIFER_CONDUCTIVITY 

Saturated hydraulic conductivity (in/hr or mm/hr)

swmm_AQUIFER_CONDUCT_SLOPE 

Conductivity slope (unitless)

swmm_AQUIFER_TENSION_SLOPE 

Tension slope (ft or m)

swmm_AQUIFER_UPPER_EVAP_FRAC 

Upper-zone evaporation fraction (0-1)

swmm_AQUIFER_LOWER_EVAP_DEPTH 

Lower-zone evaporation depth (ft or m)

swmm_AQUIFER_LOWER_LOSS_COEFF 

Lower-zone seepage-loss coefficient (in/hr or mm/hr)

swmm_AQUIFER_BOTTOM_ELEV 

Aquifer bottom elevation (ft or m, pre-start-only)

swmm_AQUIFER_WATER_TABLE_ELEV 

Initial water table elevation (ft or m, pre-start-only)

swmm_AQUIFER_UPPER_MOISTURE 

Initial upper-zone moisture (volumetric fraction, pre-start-only)

◆ swmm_FlowUnitsProperty

Enumeration of flow units used in SWMM5.

Enumerator
swmm_CFS 

Cubic feet per second.

swmm_GPM 

Gallons per minute.

swmm_MGD 

Million gallons per day.

swmm_CMS 

Cubic meters per second.

swmm_LPS 

Liters per second.

swmm_MLD 

Million liters per day.

◆ swmm_GageProperty

Enumeration of gage properties used in SWMM5.

Enumerator
swmm_GAGE_TOTAL_PRECIPITATION 

Total precipitation.

swmm_GAGE_RAINFALL 

Rainfall.

swmm_GAGE_SNOWFALL 

Snowfall.

swmm_GAGE_SCALEFACTOR 

Rainfall scaling factor (dimensionless, > 0).

◆ swmm_LanduseProperty

Enumeration of land-use properties used in SWMM5.

Street-sweeping parameters are settable both before the simulation starts and while it is running; they are read per step when sweeping is evaluated, so a mid-run edit takes effect on the next step.

Enumerator
swmm_LANDUSE_SWEEP_INTERVAL 

Street-sweeping interval (days)

swmm_LANDUSE_SWEEP_REMOVAL 

Fraction of buildup available for sweeping (0-1)

swmm_LANDUSE_BUILDUP_FUNC 

Buildup function type code (subIndex = pollutant index)

swmm_LANDUSE_BUILDUP_COEFF1 

Buildup coefficient c0 / max buildup (subIndex = pollutant)

swmm_LANDUSE_BUILDUP_COEFF2 

Buildup coefficient c1 / rate (subIndex = pollutant)

swmm_LANDUSE_BUILDUP_COEFF3 

Buildup coefficient c2 / exponent (subIndex = pollutant)

swmm_LANDUSE_BUILDUP_NORMALIZER 

Buildup normalizer code: 0 area, 1 curb length (subIndex = pollutant)

swmm_LANDUSE_WASHOFF_FUNC 

Washoff function type code (subIndex = pollutant)

swmm_LANDUSE_WASHOFF_COEFF 

Washoff coefficient (subIndex = pollutant)

swmm_LANDUSE_WASHOFF_EXPON 

Washoff exponent (subIndex = pollutant)

swmm_LANDUSE_WASHOFF_SWEEP_EFFIC 

Washoff street-sweeping removal efficiency 0-1 (subIndex = pollutant)

swmm_LANDUSE_WASHOFF_BMP_EFFIC 

Washoff BMP removal efficiency 0-1 (subIndex = pollutant)

◆ swmm_LinkProperty

Enumeration of link properties used in SWMM5.

Enumerator
swmm_LINK_TYPE 

Link type.

swmm_LINK_NODE1 

Upstream node.

swmm_LINK_NODE2 

Downstream node.

swmm_LINK_LENGTH 

Length.

swmm_LINK_SLOPE 

Slope.

swmm_LINK_FULLDEPTH 

Full depth.

swmm_LINK_FULLFLOW 

Full flow.

swmm_LINK_SETTING 

Setting.

swmm_LINK_TIMEOPEN 

Time open.

swmm_LINK_TIMECLOSED 

Time closed.

swmm_LINK_FLOW 

Flow.

swmm_LINK_DEPTH 

Depth.

swmm_LINK_VELOCITY 

Velocity.

swmm_LINK_TOPWIDTH 

Top width.

swmm_LINK_VOLUME 

Volume.

swmm_LINK_CAPACITY 

Capacity.

swmm_LINK_RPTFLAG 

Report flag.

swmm_LINK_OFFSET1 

Upstream invert offset.

swmm_LINK_OFFSET2 

Downstream invert offset.

swmm_LINK_INITIAL_FLOW 

Initial flow.

swmm_LINK_FLOW_LIMIT 

Flow limit.

swmm_LINK_INLET_LOSS 

Inlet loss.

swmm_LINK_OUTLET_LOSS 

Outlet loss.

swmm_LINK_AVERAGE_LOSS 

Average loss.

swmm_LINK_SEEPAGE_RATE 

Seepage rate.

swmm_LINK_HAS_FLAPGATE 

Flap gate.

swmm_LINK_POLLUTANT_CONCENTRATION 

Pollutant concentration.

swmm_LINK_POLLUTANT_LOAD 

Pollutant load.

swmm_LINK_POLLUTANT_LATMASS_FLUX 

Pollutant lateral mass flux.

◆ swmm_LinkType

Enumeration of link types used in SWMM5.

Enumerator
swmm_CONDUIT 

Conduit link.

swmm_PUMP 

Pump link.

swmm_ORIFICE 

Orifice link.

swmm_WEIR 

Weir link.

swmm_OUTLET 

Outlet link.

◆ swmm_NodeProperty

Enumeration of node properties used in SWMM5.

Enumerator
swmm_NODE_TYPE 

Node type.

swmm_NODE_ELEV 

Elevation.

swmm_NODE_MAXDEPTH 

Maximum depth.

swmm_NODE_DEPTH 

Depth.

swmm_NODE_HEAD 

Hydraulic head.

swmm_NODE_VOLUME 

Volume.

swmm_NODE_LATFLOW 

Lateral inflow.

swmm_NODE_INFLOW 

Inflow.

swmm_NODE_OVERFLOW 

Overflow.

swmm_NODE_RPTFLAG 

Report flag.

swmm_NODE_SURCHARGE_DEPTH 

Surcharge depth.

swmm_NODE_PONDED_AREA 

Ponded area.

swmm_NODE_INITIAL_DEPTH 

Initial depth.

swmm_NODE_POLLUTANT_CONCENTRATION 

Pollutant concentration.

swmm_NODE_POLLUTANT_LATMASS_FLUX 

Pollutant lateral mass flux inflow.

swmm_NODE_OUTFLOW 

Total outflow.

swmm_NODE_STORAGE_AREA 

Physical junction chamber area in project ft2/m2

◆ swmm_NodeType

Enumeration of node types used in SWMM5.

Enumerator
swmm_JUNCTION 

Junction node.

swmm_OUTFALL 

Outfall node.

swmm_STORAGE 

Storage node.

swmm_DIVIDER 

Divider node.

◆ swmm_Object

Enumeration of object types used in SWMM5.

Enumerator
swmm_GAGE 

Rain gages.

swmm_SUBCATCH 

Subcatchments.

swmm_NODE 

Nodes.

swmm_LINK 

Links.

swmm_POLLUTANT 

Pollutants.

swmm_LANDUSE 

Land uses.

swmm_TIME_PATTERN 

Time patterns.

swmm_CURVE 

Curve functions.

swmm_TIMESERIES 

Time series.

swmm_CONTROL_RULE 

Control rules.

swmm_TRANSECT 

Transects.

swmm_AQUIFER 

Aquifers.

swmm_UNIT_HYDROGRAPH 

Unit hydrographs.

swmm_SNOWPACK 

Snow packs.

smmm_XSECTION_SHAPE 

Cross section shape.

swmm_LID 

Low impact development units.

swmm_STREET 

Street.

swmm_INLET 

Inlet.

swmm_SYSTEM 

System.

◆ swmm_PatternProperty

Enumeration of time-pattern properties used in SWMM5.

Pattern multiplier factors are settable both before the simulation starts and while it is running. They are looked up afresh on every step (DWF/GW/inflow scaling), so a mid-run edit takes effect on the next step. The factor index is passed as the subIndex argument of swmm_setValueExpanded / swmm_getValueExpanded (0-based position within the pattern: 0-11 monthly, 0-6 daily, 0-23 hourly/weekend).

Enumerator
swmm_PATTERN_FACTOR 

One multiplier factor (subIndex = factor position)

swmm_PATTERN_COUNT 

Number of factors in the pattern (read-only)

swmm_PATTERN_TYPE 

Pattern type code (read-only): 0 monthly, 1 daily, 2 hourly, 3 weekend.

◆ swmm_PollutProperty

Enumeration of pollutant properties used in SWMM5.

The source concentrations are settable while the simulation is running, enabling dynamic wet-deposition, groundwater, RDII, and dry weather quality forcing. Values are in the pollutant's concentration units (e.g. mg/L) as defined in the input file.

Enumerator
swmm_POLLUT_RAIN_CONCEN 

Rain (wet deposition) concentration.

swmm_POLLUT_GW_CONCEN 

Groundwater inflow concentration.

swmm_POLLUT_RDII_CONCEN 

RDII inflow concentration.

swmm_POLLUT_DWF_CONCEN 

Dry weather sanitary flow concentration.

swmm_POLLUT_KDECAY 

First-order decay constant (1/day); read live each step.

swmm_POLLUT_CO_POLLUTANT 

Co-pollutant index (-1 = none)

swmm_POLLUT_CO_FRACTION 

Co-pollutant fraction (0-1)

swmm_POLLUT_SNOW_ONLY 

Buildup-only-under-snow flag (0/1)

swmm_POLLUT_INIT_CONCEN 

Initial conveyance-network concentration (pre-start only)

◆ swmm_SubcatchProperty

Enumeration of subcatchment properties used in SWMM5.

Todo
Add LID properties to this enum
Enumerator
swmm_SUBCATCH_AREA 

Area.

swmm_SUBCATCH_RAINGAGE 

Rain gage.

swmm_SUBCATCH_RAINFALL 

Rainfall.

swmm_SUBCATCH_EVAP 

Evaporation.

swmm_SUBCATCH_INFIL 

Infiltration.

swmm_SUBCATCH_RUNOFF 

Runoff.

swmm_SUBCATCH_RPTFLAG 

Report flag.

swmm_SUBCATCH_WIDTH 

Width.

swmm_SUBCATCH_SLOPE 

Slope.

swmm_SUBCATCH_OUTLET_TYPE 

Outlet type.

swmm_SUBCATCH_OUTLET_INDEX 

Outlet index.

swmm_SUBCATCH_INFILTRATION_MODEL 

Infiltration model.

swmm_SUBCATCH_FRACTION_IMPERVIOUS 

Fraction impervious.

swmm_SUBCATCH_SUB_AREA_ROUTE_TO 

Subarea routing to.

swmm_SUBCATCH_SUB_AREA_FRACTION_OUTLET 

Fraction subarea routed to outlet.

swmm_SUBCATCH_SUB_AREA_MANNINGS_N 

Subarea's Manning's n.

swmm_SUBCATCH_SUB_AREA_FRACTION_AREA 

Subarea's depression storage.

swmm_SUBCATCH_SUB_AREA_DEPRESSION_STORAGE 

Subarea's depression storage.

swmm_SUBCATCH_SUB_AREA_INFLOW 

Subarea's inflow.

swmm_SUBCATCH_SUB_AREA_RUNOFF 

Subarea's runoff.

swmm_SUBCATCH_SUB_AREA_DEPTH 

Subarea's depth.

swmm_SUBCATCH_LID_UNITS_COUNT 

Subcatch's LID unit count.

swmm_SUBCATCH_LID_UNITS_PERV_AREA 

Subcatch's LID pervious area.

swmm_SUBCATCH_LID_UNITS_FLOW_TO_PERV_AREA 

Subcatch's LID flow to pervious area.

swmm_SUBCATCH_LID_UNITS_DRAIN_FLOW 

Subcatch's LID drain flow.

swmm_SUBCATCH_LID_UNIT_REPLICATES 

Number of Subcatch's LID replicates.

swmm_SUBCATCH_LID_UNIT_AREA 

Subcatch's LID unit area.

swmm_SUBCATCH_LID_UNIT_FULL_WIDTH 

Subcatch's LID unit full top width.

swmm_SUBCATCH_LID_UNIT_BOTTOM_WIDTH 

Subcatch's LID unit bottom width.

swmm_SUBCATCH_LID_UNIT_INIT_SATURATION 

Subcatch's LID unit initial saturation of soil and storage layers.

swmm_SUBCATCH_LID_UNIT_FROM_IMPERVIOUS 

Subcatch's LID unit fraction of impervious area runoff treated.

swmm_SUBCATCH_LID_UNIT_FROM_PERVIOUS 

Subcatch's LID unit fraction of pervious area runoff treated.

swmm_SUBCATCH_LID_UNIT_TO_PERVIOUS 

Whether Subcatch's LID unit's flow is sent to the pervious area.

swmm_SUBCATCH_LID_UNIT_RECEIVING_OUTLET_TYPE 

The object type of the receiving drain flow.

swmm_SUBCATCH_LID_UNIT_RECEIVING_OUTLET_INDEX 

The index of the object receiving drain flow.

swmm_SUBCATCH_LID_UNIT_SURFACE_DEPTH 

Subcatch's LID unit surface depth.

swmm_SUBCATCH_LID_UNIT_SOIL_MOISTURE 

Subcatch's LID unit soil moisture content of biocell soil layer.

swmm_SUBCATCH_LID_UNIT_GREEN_AMPT_CAPILLARY_SUCTION 

Subcatch's LID unit green and ampt soil capillary suction.

swmm_SUBCATCH_LID_UNIT_GREEN_AMPT_SATURATED_CONDUCTIVITY 

Subcatch's LID unit green and ampt saturated conductivity.

swmm_SUBCATCH_LID_UNIT_GREEN_AMPT_MAXIMUM_SOIL_MOISTURE_DEFICIT 

Subcatch's LID unit green and ampt maximum soil moisture deficit.

swmm_SUBCATCH_CURB_LENGTH 

Curb length.

swmm_SUBCATCH_API_RAINFALL 

API provided rainfall.

swmm_SUBCATCH_API_SNOWFALL 

API provided snowfall.

swmm_SUBCATCH_POLLUTANT_BUILDUP 

Pollutant buildup.

swmm_SUBCATCH_EXTERNAL_POLLUTANT_BUILDUP 

External pollutant buildup.

swmm_SUBCATCH_POLLUTANT_RUNOFF_CONCENTRATION 

Runoff concentration.

swmm_SUBCATCH_POLLUTANT_PONDED_CONCENTRATION 

Ponded concentration.

swmm_SUBCATCH_POLLUTANT_TOTAL_LOAD 

Total pollutant load.

swmm_SUBCATCH_API_PET 

API prescribed potential evapotranspiration rate (in/day or mm/day). Settable while the simulation is running; overrides the climate-derived evaporation rate for the subcatchment's surface, LID, and groundwater evaporation. Set a negative value to clear and revert to climate-derived evaporation.

swmm_SUBCATCH_GW_MOISTURE 

Groundwater upper zone moisture content (volume fraction, 0..porosity). Settable while the simulation is running (state injection / data assimilation).

swmm_SUBCATCH_GW_LOWER_DEPTH 

Groundwater saturated (lower) zone depth above the aquifer bottom (ft or m). Settable while the simulation is running.

swmm_SUBCATCH_SNOW_SWE 

Snow pack snow water equivalent on a snow subarea (in or mm; sub_index = 0 plowable, 1 impervious, 2 pervious). Settable while the simulation is running.

swmm_SUBCATCH_SNOW_FW 

Snow pack free water on a snow subarea (in or mm; sub_index as for swmm_SUBCATCH_SNOW_SWE). Settable while the simulation is running.

swmm_SUBCATCH_SNOW_ATI 

Snow pack antecedent temperature index on a snow subarea (deg F or deg C). Settable while the simulation is running.

swmm_SUBCATCH_SNOW_COLDC 

Snow pack cold content on a snow subarea (in or mm of melt equivalent). Settable while the simulation is running.

swmm_SUBCATCH_RAIN_SCALE_FACTOR 

Subcatchment rainfall scale factor (optional token 9 of [SUBCATCHMENTS]; default 1.0 = no scaling). Multiplies the gage-derived rainfall for this subcatchment only, composing multiplicatively with the gage's own scale factor. API-prescribed rainfall is NOT scaled by it. Must be > 0. Settable while the simulation is running.

swmm_SUBCATCH_SNOW_SCALE_FACTOR 

Subcatchment snowfall scale factor (optional token 10 of [SUBCATCHMENTS]; default 1.0 = no scaling). Composes multiplicatively with the gage snow catch factor (SCF): SCF corrects the physical gage's snow-catch deficiency, while this represents spatial variation across the catchment. Must be > 0. Settable while the simulation is running.

◆ swmm_SystemProperty

Enumeration of system properties used in SWMM5.

Enumerator
swmm_STARTDATE 

Start date.

swmm_CURRENTDATE 

Current date.

swmm_ELAPSEDTIME 

Elapsed time.

swmm_ROUTESTEP 

Routing step.

swmm_MAXROUTESTEP 

Maximum routing step.

swmm_REPORTSTEP 

Reporting step.

swmm_TOTALSTEPS 

Total steps.

swmm_NOREPORT 

No report flag.

swmm_FLOWUNITS 

Flow units.

swmm_ENDDATE 

End date.

swmm_REPORTSTART 

Report start.

swmm_UNITSYSTEM 

Unit system.

swmm_SURCHARGEMETHOD 

Surcharge method.

swmm_ALLOWPONDING 

Allow ponding.

swmm_INERTIADAMPING 

Inertia damping.

swmm_NORMALFLOWLTD 

Normal flow limited.

swmm_SKIPSTEADYSTATE 

Skip steady state.

swmm_IGNORERAINFALL 

Ignore rainfall.

swmm_IGNORERDII 

Ignore RDII.

swmm_IGNORESNOWMELT 

Ignore snowmelt.

swmm_IGNOREGROUNDWATER 

Ignore groundwater.

swmm_IGNOREROUTING 

Ignore routing.

swmm_IGNOREQUALITY 

Ignore quality.

swmm_ERROR_CODE 

Error code.

swmm_RULESTEP 

Rule step.

swmm_SWEEPSTART 

Sweep start.

swmm_SWEEPEND 

Sweep end.

swmm_MAXTRIALS 

Maximum trials.

swmm_NUMTHREADS 

Number of threads.

swmm_MINROUTESTEP 

Minimum routing step.

swmm_LENGTHENINGSTEP 

Lengthening step.

swmm_STARTDRYDAYS 

Start dry days.

swmm_COURANTFACTOR 

Courant factor.

swmm_MINSURFAREA 

Minimum surface area.

swmm_MINSLOPE 

Minimum slope.

swmm_RUNOFFERROR 

Runoff error.

swmm_FLOWERROR 

Flow error.

swmm_QUALERROR 

Quality error.

swmm_HEADTOL 

Head tolerance.

swmm_SYSFLOWTOL 

System flow tolerance.

swmm_LATFLOWTOL 

Lateral flow tolerance.

swmm_EVAPRATE 

Current climate-derived evaporation rate (in/day or mm/day), including any monthly adjustments (read-only)

swmm_TEMPERATURE 

Current air temperature (deg F or deg C; read-only)

swmm_API_TEMPERATURE 

API prescribed air temperature (deg F or deg C). Settable while the simulation is running; overrides the climate data-source value (and bypasses monthly adjustments) for snowmelt and evaporation. Set a value <= -999 to clear and revert to climate-derived temperature. Getter returns -999 when no prescription is active.

swmm_WINDSPEED 

Current wind speed (mph or km/hr; read-only)

swmm_API_WINDSPEED 

API prescribed wind speed (mph or km/hr). Settable while the simulation is running; overrides the monthly/file value used in snowmelt. Set a negative value to clear. Getter returns -1 when no prescription is active.

swmm_API_EVAP 

API prescribed system-wide evaporation rate (in/day or mm/day). Settable while the simulation is running; replaces the climate-derived Evap.rate (after monthly adjustments) for every consumer — subcatchments, LID units, groundwater, conduits and storage nodes. Per-subcatchment swmm_SUBCATCH_API_PET still takes precedence. Set a negative value to clear. Getter returns -1 when not prescribed.

swmm_EVAP_DRY_ONLY 

Evaporation DRY_ONLY option (0/1). Settable while the simulation is running.

Function Documentation

◆ swmm_clearTreatment()

int EXPORT_OPENSWMMCORE_SOLVER_API swmm_clearTreatment ( int nodeIndex,
int pollutantIndex )

Remove a node/pollutant treatment equation.

Requires an open model, before or during a run. Frees the owned equation and leaves the pair without treatment removal.

Parameters
[in]nodeIndexZero-based node index.
[in]pollutantIndexZero-based pollutant index.
Returns
Zero on success (including an already absent equation), or ERR_API_NOT_OPEN / ERR_API_OBJECT_INDEX.

◆ swmm_close()

int EXPORT_OPENSWMMCORE_SOLVER_API swmm_close ( void )

Release global statistics/model/output resources and close project files.

Clears open/started flags and each closed file pointer; repeated explicit closes avoid double fclose. Deletes scratch output where applicable. Does not itself run swmm_end, so finish an active simulation first to produce final output and accounting. Previously borrowed model storage becomes invalid.

Returns
Always zero.

◆ swmm_decodeDate()

void EXPORT_OPENSWMMCORE_SOLVER_API swmm_decodeDate ( double date,
int * year,
int * month,
int * day,
int * hour,
int * minute,
int * second,
int * dayOfWeek )

Decode an absolute legacy SWMM date/time into calendar fields.

No model lifecycle is required; valid encodable dates and non-null outputs are caller preconditions. Uses the legacy floor/whole-second conventions and does not retain pointers.

Parameters
[in]dateEncoded date/time in decimal days relative to the legacy epoch 1899-12-30.
[out]yearNon-null writable year.
[out]monthNon-null writable month 1..12 for a valid date.
[out]dayNon-null writable calendar day.
[out]hourNon-null writable hour.
[out]minuteNon-null writable minute.
[out]secondNon-null writable whole second.
[out]dayOfWeekNon-null writable weekday: Sunday=1 through Saturday=7, as returned by datetime_dayOfWeek.

◆ swmm_encodeDate()

double EXPORT_OPENSWMMCORE_SOLVER_API swmm_encodeDate ( int year,
int month,
int day,
int hour,
int minute,
int second )

Encode calendar date and clock fields using the legacy date utilities.

Parameters
[in]yearCalendar year accepted by datetime_encodeDate.
[in]monthMonth 1..12.
[in]dayValid calendar day for the month/year.
[in]hourClock hour 0..23.
[in]minuteMinute 0..59.
[in]secondWhole second 0..59.
Returns
datetime_encodeDate + datetime_encodeTime, in absolute SWMM decimal days. Invalid component sentinel behavior is inherited from those helpers; this wrapper does not validate the combined result.

◆ swmm_end()

int EXPORT_OPENSWMMCORE_SOLVER_API swmm_end ( void )

Finalize output/continuity and close computing systems while retaining model/statistics.

Requires an open project. If started, writes final binary records, finalizes mass-balance/statistics reports when no error and reporting enabled, closes computing systems and clears the started flag. Calling again on an open ended model performs no additional finalization. Statistics remain allocated until swmm_close.

Returns
Zero on success or the legacy engine error enum. Lifecycle errors can also set the process-global ErrorCode.

◆ swmm_getCount()

int EXPORT_OPENSWMMCORE_SOLVER_API swmm_getCount ( int objType)

Get the number of objects in a legacy category.

Parameters
[in]objTypeLegacy object category from swmm_GAGE up to but excluding swmm_SYSTEM.
Returns
Object count, zero when no project is open, or ERR_API_OBJECT_TYPE for an unsupported category. Errors share the integer result space with counts.

◆ swmm_getError()

int EXPORT_OPENSWMMCORE_SOLVER_API swmm_getError ( char * errMsg,
int msgLen )

Copy the current terminating error text into caller-owned storage.

Lazily populates ErrorMsg from ErrorCode when necessary, then changes a leading newline in the copy to a space. A negative length converts to an unsigned copy bound and is invalid. The buffer is used synchronously only.

Parameters
[out]errMsgNon-null writable character buffer of at least msgLen + 1 bytes; sstrncpy can copy msgLen payload characters and append a terminator.
[in]msgLenNonnegative maximum number of payload characters, not total buffer capacity; zero still writes a terminator.
Returns
Current global ErrorCode; does not clear it.

◆ swmm_getErrorFromCode()

int EXPORT_OPENSWMMCORE_SOLVER_API swmm_getErrorFromCode ( int errorCode,
char * outErrMsg[1024] )

Copy the text for an explicit internal legacy error enum.

The unusual declaration is an array of character pointers, not a character buffer. No null/capacity checks are performed and no storage is retained; unknown-code behavior follows error_getMsg.

Parameters
[in]errorCodeLegacy internal error enum passed to error_getMsg, independent of global ErrorCode.
[out]outErrMsgRequired pointer-array argument; only *outErrMsg is used and must reference writable storage for the bounded MAXMSG copy plus its terminator (reserve 1025 bytes).
Returns
Always zero after lookup/copy.

◆ swmm_getIndex()

int EXPORT_OPENSWMMCORE_SOLVER_API swmm_getIndex ( int objType,
const char * name )

Find a named object in the opened global model.

Parameters
[in]objTypeSupported category in [swmm_GAGE,swmm_SYSTEM).
[in]nameNon-null null-terminated lookup name; borrowed only during the call.
Returns
Zero-based index or -1 when project_findObject cannot find the name; ERR_API_NOT_OPEN / ERR_API_OBJECT_TYPE on validation failure.

◆ swmm_getLinkStats()

int EXPORT_OPENSWMMCORE_SOLVER_API swmm_getLinkStats ( int index,
swmm_LinkStats * stats )

Copy raw internal link statistics.

Call after swmm_end and before swmm_close for final data. Checks array presence, not explicit lifecycle flags. No display-unit conversion or averaging normalization is performed.

Parameters
[in]indexZero-based global link index; subtype must match link.
[out]statsNon-null caller-owned destination, borrowed only during the call. Depths ft, velocity ft/s, flows cfs, duration fields seconds, maxFlowDate absolute SWMM days; timeCourantCritical counts events.
Returns
Zero on success, ERR_API_NOT_ENDED if the statistics array is absent, ERR_API_OBJECT_INDEX for an invalid index.

◆ swmm_getMassBalErr()

int EXPORT_OPENSWMMCORE_SOLVER_API swmm_getMassBalErr ( float * runoffErr,
float * flowErr,
float * qualErr )

Read finalized runoff, routing and quality continuity errors.

Call after swmm_end and before swmm_close for final values. These are percentages (0.1 means 0.1 percent), unlike the worker JSON fractions. Outputs are copied, not retained.

Parameters
[out]runoffErrNon-null writable percent-error slot.
[out]flowErrNon-null writable routing percent-error slot.
[out]qualErrNon-null writable quality percent-error slot.
Returns
Always zero; outputs are zero unless the model is open and not started.

◆ swmm_getName()

int EXPORT_OPENSWMMCORE_SOLVER_API swmm_getName ( int objType,
int index,
char * name,
int size )

Copy the ID of one named legacy object.

Parameters
[in]objTypeNamed category: gage, subcatchment, node, link, pollutant, landuse, time pattern, curve, time series, transect, aquifer or unit hydrograph/snowmelt where supported.
[in]indexZero-based object index strictly below the category count.
[out]nameNon-null writable buffer, initially cleared; reserve at least size + 1 bytes for the legacy bounded copy.
[in]sizeNonnegative maximum payload characters, excluding the final terminator.
Returns
Zero on success, or ERR_API_NOT_OPEN / ERR_API_OBJECT_TYPE / ERR_API_OBJECT_INDEX. Output remains empty on validation failure.

◆ swmm_getNodeStats()

int EXPORT_OPENSWMMCORE_SOLVER_API swmm_getNodeStats ( int index,
swmm_NodeStats * stats )

Copy raw internal node statistics.

Call after swmm_end and before swmm_close for final data. Checks array presence, not explicit lifecycle flags. No display-unit conversion or averaging normalization is performed.

Parameters
[in]indexZero-based global node index; subtype must match node.
[out]statsNon-null caller-owned destination, borrowed only during the call. Depths ft, volumes ft3, flows cfs, duration fields seconds and max dates absolute SWMM days. avgDepth is an accumulated sample sum; timeCourantCritical counts events.
Returns
Zero on success, ERR_API_NOT_ENDED if the statistics array is absent, ERR_API_OBJECT_INDEX for an invalid index.

◆ swmm_getOutfallStats()

int EXPORT_OPENSWMMCORE_SOLVER_API swmm_getOutfallStats ( int index,
swmm_OutfallStats * stats )

Copy raw internal outfall node statistics.

Call after swmm_end and before swmm_close for final data. Checks array presence, not explicit lifecycle flags. Flows cfs; avgFlow is a sample sum, totalPeriods its count. Loads retain internal concentration-volume accounting units. No display-unit conversion or averaging normalization is performed.

Parameters
[in]indexZero-based global node index; subtype must match outfall node.
[in,out]statsNon-null caller-owned destination, borrowed only during the call. Initialize totalLoad to null to skip loads or to writable storage for Npollut doubles; the API never allocates that storage.
Returns
Zero on success, ERR_API_NOT_ENDED if the statistics array is absent, ERR_API_OBJECT_INDEX for an invalid index, or ERR_API_OBJECT_TYPE for a wrong subtype.

◆ swmm_getPumpStats()

int EXPORT_OPENSWMMCORE_SOLVER_API swmm_getPumpStats ( int index,
swmm_PumpStats * stats )

Copy raw internal pump link statistics.

Call after swmm_end and before swmm_close for final data. Checks array presence, not explicit lifecycle flags. No display-unit conversion or averaging normalization is performed.

Parameters
[in]indexZero-based global link index; subtype must match pump link.
[out]statsNon-null caller-owned destination, borrowed only during the call. Flows cfs, volume ft3, energy kWh; utilized/off-curve fields are seconds and avgFlow remains a sample sum.
Returns
Zero on success, ERR_API_NOT_ENDED if the statistics array is absent, ERR_API_OBJECT_INDEX for an invalid index, or ERR_API_OBJECT_TYPE for a wrong subtype.

◆ swmm_getRunningMassBalErr()

int EXPORT_OPENSWMMCORE_SOLVER_API swmm_getRunningMassBalErr ( float * runoffErr,
float * flowErr )

Recompute current runoff and routing continuity errors during a run.

Uses live water accumulators/current storage between steps and does not change the eventual finalized errors. Values are percentages; caller storage is not retained.

Parameters
[out]runoffErrNon-null writable runoff percent-error slot.
[out]flowErrNon-null writable routing percent-error slot.
Returns
Always zero; both outputs are zero unless the model is open and started.

◆ swmm_getSavedValue()

double EXPORT_OPENSWMMCORE_SOLVER_API swmm_getSavedValue ( int property,
int index,
int period )

Read a saved output value after the run has ended.

Requires an open ended model with readable saved output. Numeric zero is ambiguous with unavailable data. Does not retain caller storage.

Parameters
[in]propertyswmm_CURRENTDATE or a supported subcatch/node/link result property.
[in]indexZero-based object index, ignored for the saved date.
[in]periodOne-based saved reporting period in [1,Nperiods], unlike the separate output-reader zero-based API.
Returns
Saved value in model display units (date in absolute SWMM days), or zero if closed, still started, invalid period/property, or an unsupported/missing value.

◆ swmm_getStorageStats()

int EXPORT_OPENSWMMCORE_SOLVER_API swmm_getStorageStats ( int index,
swmm_StorageStats * stats )

Copy raw internal storage node statistics.

Call after swmm_end and before swmm_close for final data. Checks array presence, not explicit lifecycle flags. No display-unit conversion or averaging normalization is performed.

Parameters
[in]indexZero-based global node index; subtype must match storage node.
[out]statsNon-null caller-owned destination, borrowed only during the call. Volumes ft3, maxFlow cfs and maxVolDate absolute SWMM days; avgVol is an accumulated sample sum.
Returns
Zero on success, ERR_API_NOT_ENDED if the statistics array is absent, ERR_API_OBJECT_INDEX for an invalid index, or ERR_API_OBJECT_TYPE for a wrong subtype.

◆ swmm_getSubcatchStats()

int EXPORT_OPENSWMMCORE_SOLVER_API swmm_getSubcatchStats ( int index,
swmm_SubcatchStats * stats )

Copy raw internal subcatchment statistics.

Call after swmm_end and before swmm_close for final data. Checks array presence, not explicit lifecycle flags. No display-unit conversion or averaging normalization is performed.

Parameters
[in]indexZero-based global subcatchment index; subtype must match subcatchment.
[out]statsNon-null caller-owned destination, borrowed only during the call. Volumes ft3, peak flow cfs.
Returns
Zero on success, ERR_API_NOT_ENDED if the statistics array is absent, ERR_API_OBJECT_INDEX for an invalid index.

◆ swmm_getSystemRoutingTotals()

int EXPORT_OPENSWMMCORE_SOLVER_API swmm_getSystemRoutingTotals ( swmm_RoutingTotals * totals)

Copy raw global routing continuity totals.

Use after swmm_end and before swmm_close for finalized totals. Does not recompute accounting, retain storage or normalize units.

Parameters
[out]totalsNon-null caller-owned destination. routing volume categories are ft3; pctError is percent, with no model display conversion.
Returns
Always zero; no lifecycle or null checks.

◆ swmm_getSystemRunoffTotals()

int EXPORT_OPENSWMMCORE_SOLVER_API swmm_getSystemRunoffTotals ( swmm_RunoffTotals * totals)

Copy raw global runoff continuity totals.

Use after swmm_end and before swmm_close for finalized totals. Does not recompute accounting, retain storage or normalize units.

Parameters
[out]totalsNon-null caller-owned destination. runoff water categories including rainfall and snow stores are ft3; pctError is percent, with no model display conversion.
Returns
Always zero; no lifecycle or null checks.

◆ swmm_getValue()

double EXPORT_OPENSWMMCORE_SOLVER_API swmm_getValue ( int property,
int index )

Read one legacy numeric-family property.

Requires an open model. Dispatches by numeric property band: <100 system, <200 gage, <300 subcatchment, <400 node, <500 link; passes -1 for sub/pollutant indices. Prefer the Expanded interface for explicit type/subobject selection.

Parameters
[in]propertyProperty enum for the selected object family; system/date/step, gage, subcatchment, node and link values follow the public property enums.
[in]indexZero-based object index; ignored by system properties. Other families validate against their object count.
Returns
Property value in its declared/model units, or a legacy API error enum encoded as double. Numeric values and errors share the same return channel.

◆ swmm_getValueExpanded()

double EXPORT_OPENSWMMCORE_SOLVER_API swmm_getValueExpanded ( int objType,
int property,
int index,
int subIndex,
int pollutantIndex )

Read one explicitly typed property.

Requires an open model. Dispatches to the matching property implementation; no uniform validation or transaction applies across properties. Buffers/strings are not involved.

Parameters
[in]objTypeswmm_SYSTEM, GAGE, SUBCATCH, NODE, LINK, POLLUTANT, TIME_PATTERN, LANDUSE or AQUIFER; selects the property implementation.
[in]propertyProperty enum for the selected object family; system/date/step, gage, subcatchment, node and link values follow the public property enums.
[in]indexZero-based object index; ignored by system properties. Other families validate against their object count.
[in]subIndexProperty-specific subobject (e.g. subarea 0..2, pattern factor or landuse entry); use the relevant property range, as it is not a universal optional index.
[in]pollutantIndexZero-based pollutant index for pollutant-dependent node/link/subcatchment properties; unused by other properties.
Returns
Property value in its declared/model units, or a legacy API error enum encoded as double. Numeric values and errors share the same return channel.

◆ swmm_getVersion()

int EXPORT_OPENSWMMCORE_SOLVER_API swmm_getVersion ( void )

Return the compiled legacy engine version integer.

Returns
VERSION, without requiring an open model.

◆ swmm_getWarnings()

int EXPORT_OPENSWMMCORE_SOLVER_API swmm_getWarnings ( void )

Return the current project warning counter.

Returns
Global number of warnings, reset at swmm_open; no lifecycle validation is performed.

◆ swmm_open()

int EXPORT_OPENSWMMCORE_SOLVER_API swmm_open ( const char * inputFile,
const char * reportFile,
const char * outputFile )

Open, parse and validate a single process-global legacy model.

Resets global error/warning/lifecycle state, opens files, reads the deck and validates it. On a failure after files/project allocation, call swmm_close to release partial resources. Requires the previous project to have been closed; this function resets flags rather than safely disposing an already-open model.

Parameters
[in]inputFileNon-null null-terminated input-deck path, borrowed for the call.
[in]reportFileNon-null null-terminated report path; the engine opens/overwrites the report.
[in]outputFileNon-null null-terminated binary output path; an empty string selects a scratch output file.
Returns
Zero on success or the legacy engine error enum. Lifecycle errors can also set the process-global ErrorCode.

◆ swmm_report()

int EXPORT_OPENSWMMCORE_SOLVER_API swmm_report ( void )

Write the full results report from the current legacy project.

Caller must provide an opened model with appropriate completed output/report state. This wrapper checks only ErrorCode; it does not enforce a separate lifecycle condition. Normally call after swmm_end and before swmm_close.

Returns
Current ErrorCode after report_writeReport, or the existing error without writing.

◆ swmm_run()

int EXPORT_OPENSWMMCORE_SOLVER_API swmm_run ( const char * inputFile,
const char * reportFile,
const char * outputFile )

Run the global legacy engine through open/start/step/end/report/close.

Resets global open/start flags and errors, saves binary results, writes console progress and closes resources before returning. Writes the full text report only for scratch output when no error occurred. Operates on one process-global project; do not overlap another legacy simulation.

Parameters
[in]inputFileNon-null null-terminated input-deck path, borrowed for the call.
[in]reportFileNon-null null-terminated report path; the engine opens/overwrites the report.
[in]outputFileNon-null null-terminated binary output path; an empty string selects a scratch output file.
Returns
Final process-global ErrorCode, zero for a successful run.

◆ swmm_run_with_callback()

int EXPORT_OPENSWMMCORE_SOLVER_API swmm_run_with_callback ( const char * inputFile,
const char * reportFile,
const char * outputFile,
progress_callback callback )

Run the global legacy engine and report synchronous step progress.

Uses the same lifecycle and scratch-report behavior as swmm_run. Progress is NewRoutingTime/TotalDuration; this entry point adds no clamp or zero-duration guard. Callback execution occurs on the simulation thread and must not reenter or concurrently mutate the global engine.

Parameters
[in]inputFileNon-null null-terminated input-deck path, borrowed for the call.
[in]reportFileNon-null null-terminated report path; the engine opens/overwrites the report.
[in]outputFileNon-null null-terminated binary output path; an empty string selects a scratch output file.
[in]callbackOptional borrowed function pointer called after each attempted step, including completion/error; null disables progress. Return type is void, so it cannot cancel.
Returns
Final process-global ErrorCode.

◆ swmm_saveHotStart()

int EXPORT_OPENSWMMCORE_SOLVER_API swmm_saveHotStart ( const char * hotStartFile)

Write current running state to a named hotstart file.

Requires an open started model and no prior global error. The writer may create/overwrite the destination; writer errors are returned directly.

Parameters
[in]hotStartFileNon-null null-terminated destination passed to the hotstart writer; borrowed only during the call.
Returns
Zero on success or the legacy engine error enum. Lifecycle errors can also set the process-global ErrorCode.

◆ swmm_setLidDrain()

int EXPORT_OPENSWMMCORE_SOLVER_API swmm_setLidDrain ( int lidIndex,
double coeff,
double expon,
double offset )

Replace live underdrain parameters of a legacy LID process.

Edits take effect on the next kernel evaluation. The validator tests negativity without an explicit finite-value check; callers should supply finite physical parameters.

Parameters
[in]lidIndexZero-based LID process index.
[in]coeffNonnegative coefficient in authored rain-rate units (in/hr or mm/hr) for the configured head exponent.
[in]exponNonnegative dimensionless head exponent.
[in]offsetNonnegative drain offset in in or mm, converted internally to ft.
Returns
Zero, ERR_API_NOT_OPEN, ERR_API_OBJECT_INDEX, or ERR_API_PROPERTY_VALUE for a negative parameter.

◆ swmm_setTreatment()

int EXPORT_OPENSWMMCORE_SOLVER_API swmm_setTreatment ( int nodeIndex,
int pollutantIndex,
const char * expression )

Replace a node/pollutant treatment expression for subsequent routing steps.

May be called before or during a run. The old equation is freed before parsing its replacement; parse failure leaves no equation for the pair. No rollback restores the old expression and the caller string is not retained.

Parameters
[in]nodeIndexZero-based node index within the opened model.
[in]pollutantIndexZero-based pollutant index.
[in]expressionNon-null nonempty null-terminated input-form equation, e.g. R = 0.5 or C = BOD * 0.2; copied into a bounded MAXLINE working buffer.
Returns
Zero on success; ERR_API_NOT_OPEN, ERR_API_OBJECT_INDEX or ERR_API_PROPERTY_VALUE on rejected lifecycle/index/expression.

◆ swmm_setValue()

int EXPORT_OPENSWMMCORE_SOLVER_API swmm_setValue ( int property,
int index,
double value )

Set one legacy numeric-family property.

Requires an open model. The compatibility setter supports rainfall/scale, reporting flags, node lateral flow/outfall stage, link setting and route/report controls. Reporting edits generally require not started. Prefer the Expanded interface for explicit type/subobject selection.

Parameters
[in]propertyProperty enum for the selected object family; system/date/step, gage, subcatchment, node and link values follow the public property enums.
[in]indexZero-based object index; ignored by system properties. Other families validate against their object count.
[in]valueNew value in the selected property units; hydraulic lengths/flows and rainfall generally use model display units, dates absolute SWMM days, step sizes seconds, and fractions dimensionless. Property-specific range/lifecycle checks apply.
Returns
Zero or a legacy API object/property/value/state error. Some unsupported indices/lifecycle edits are silently ignored with zero, so zero does not guarantee mutation.

◆ swmm_setValueExpanded()

int EXPORT_OPENSWMMCORE_SOLVER_API swmm_setValueExpanded ( int objType,
int property,
int index,
int subIndex,
int pollutantIndex,
double value )

Set one explicitly typed property.

Requires an open model. Dispatches to the matching property implementation; no uniform validation or transaction applies across properties. Buffers/strings are not involved.

Parameters
[in]objTypeswmm_SYSTEM, GAGE, SUBCATCH, NODE, LINK, POLLUTANT, TIME_PATTERN, LANDUSE or AQUIFER; selects the property implementation.
[in]propertyProperty enum for the selected object family; system/date/step, gage, subcatchment, node and link values follow the public property enums.
[in]indexZero-based object index; ignored by system properties. Other families validate against their object count.
[in]subIndexProperty-specific subobject (e.g. subarea 0..2, pattern factor or landuse entry); use the relevant property range, as it is not a universal optional index.
[in]pollutantIndexZero-based pollutant index for pollutant-dependent node/link/subcatchment properties; unused by other properties.
[in]valueNew value in the selected property units; hydraulic lengths/flows and rainfall generally use model display units, dates absolute SWMM days, step sizes seconds, and fractions dimensionless. Property-specific range/lifecycle checks apply.
Returns
Zero or a legacy API object/property/value/state error. Some unsupported indices/lifecycle edits are silently ignored with zero, so zero does not guarantee mutation.

◆ swmm_setWarningCallback()

int EXPORT_OPENSWMMCORE_SOLVER_API swmm_setWarningCallback ( swmm_LegacyWarningCallback cb,
void * userData )

Retain a process-global callback for each emitted warning.

Register before swmm_open to capture parse warnings. Invocations are synchronous on the legacy engine thread; avoid reentrancy and concurrent access to global engine state.

Parameters
[in]cbCallback pointer to retain, or null to disable. Its code must remain valid until replaced/disabled.
[in]userDataOpaque pointer retained and supplied unchanged; caller owns its lifetime until replacement/disable.
Returns
Always zero.

◆ swmm_start()

int EXPORT_OPENSWMMCORE_SOLVER_API swmm_start ( int saveFlag)

Initialize the opened model and its computing systems.

Requires successful swmm_open and no active run. Resets clocks, initializes runoff/routing/quality, opens output and rainfall/hotstart interfaces, mass balance and statistics. A failed start may already have marked the model started and allocated systems; finalize/close through the lifecycle before reuse.

Parameters
[in]saveFlagZero suppresses periodic binary-result saving; nonzero enables it.
Returns
Zero on success or the legacy engine error enum. Lifecycle errors can also set the process-global ErrorCode.

◆ swmm_step()

int EXPORT_OPENSWMMCORE_SOLVER_API swmm_step ( double * elapsedTime)

Advance one routing step and save any scheduled results.

Requires a successfully started open model. Advances associated runoff/quality processors as needed. The pointer is used only during the call; no wall-clock duration or callback scheduling is implied.

Parameters
[out]elapsedTimeNon-null writable double, set to elapsed days since simulation start, or zero at completion; initialized to zero before lifecycle validation.
Returns
Zero on success or the legacy engine error enum. Lifecycle errors can also set the process-global ErrorCode.

◆ swmm_stride()

int EXPORT_OPENSWMMCORE_SOLVER_API swmm_stride ( int strideStep,
double * elapsedTime )

Advance routing up to a requested interval while retaining the configured step afterward.

Requires open/started state. Repeatedly steps until the temporary end, then restores original RouteStep and full RoutingDuration, and exposes the actual elapsed time. Existing global errors are returned without advancing.

Parameters
[in]strideStepRequested stride in seconds; <= 0 delegates to one swmm_step. A positive stride temporarily caps RouteStep if smaller and stops at model end.
[out]elapsedTimeNon-null writable elapsed-days slot; positive when more model time remains, zero at final completion or before validation.
Returns
Zero on success or the legacy engine error enum. Lifecycle errors can also set the process-global ErrorCode.

◆ swmm_useHotStart()

int EXPORT_OPENSWMMCORE_SOLVER_API swmm_useHotStart ( const char * hotStartFile)

Select a validated hotstart input for the next start.

Requires an open model before swmm_start. Validation errors are returned locally without storing them as a new terminating global ErrorCode; a preexisting global error still blocks the call. Success stores the path/mode; actual state loading occurs at start.

Parameters
[in]hotStartFileNon-null null-terminated filename, copied up to MAXFNAME characters and resolved through the legacy input-directory path rules.
Returns
Zero on success or the legacy engine error enum. Lifecycle errors can also set the process-global ErrorCode.

◆ swmm_writeLine()

void EXPORT_OPENSWMMCORE_SOLVER_API swmm_writeLine ( const char * line)

Append a caller line to the open report.

Does nothing if no project is open. Report-write failures are not separately returned by this void wrapper.

Parameters
[in]lineNon-null null-terminated report text; borrowed during the call.