![]() |
OpenSWMM Engine
6.0.0-alpha.4
Data-oriented, plugin-extensible SWMM Engine (6.0.0-alpha.4)
|
Prototypes for SWMM5 API functions. More...
#include "openswmm_legacy_solver_export.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. | |
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. | |
Prototypes for SWMM5 API functions.
This file contains the prototypes for SWMM5 API functions.
| #define OPENSWMM_JUNCTION_STORAGE 1 |
| #define SWMM_MAX_FLOW_CLASSES 7 |
Maximum number of flow classification classes for link statistics.
| 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.
| [in] | progress | NewRoutingTime/TotalDuration fraction supplied after an attempted step; caller should handle completion/error callbacks and does not own engine state. |
| 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.
| [in] | message | Borrowed null-terminated warning text valid only during this synchronous callback; copy it to retain. |
| [in] | userData | Opaque pointer supplied to swmm_setWarningCallback; ownership remains with the registering caller. |
| enum swmm_API_Errors |
Enumeration of API errors used in SWMM5.
| enum 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.
| enum swmm_GageProperty |
| enum 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.
| enum swmm_LinkProperty |
Enumeration of link properties used in SWMM5.
| enum swmm_LinkType |
| enum swmm_NodeProperty |
Enumeration of node properties used in SWMM5.
| enum swmm_NodeType |
| enum swmm_Object |
Enumeration of object types used in SWMM5.
| enum 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).
| enum 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.
Enumeration of subcatchment properties used in SWMM5.
| enum swmm_SystemProperty |
Enumeration of system properties used in SWMM5.
| 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.
| [in] | nodeIndex | Zero-based node index. |
| [in] | pollutantIndex | Zero-based pollutant index. |
| 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.
| 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.
| [in] | date | Encoded date/time in decimal days relative to the legacy epoch 1899-12-30. |
| [out] | year | Non-null writable year. |
| [out] | month | Non-null writable month 1..12 for a valid date. |
| [out] | day | Non-null writable calendar day. |
| [out] | hour | Non-null writable hour. |
| [out] | minute | Non-null writable minute. |
| [out] | second | Non-null writable whole second. |
| [out] | dayOfWeek | Non-null writable weekday: Sunday=1 through Saturday=7, as returned by datetime_dayOfWeek. |
| 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.
| [in] | year | Calendar year accepted by datetime_encodeDate. |
| [in] | month | Month 1..12. |
| [in] | day | Valid calendar day for the month/year. |
| [in] | hour | Clock hour 0..23. |
| [in] | minute | Minute 0..59. |
| [in] | second | Whole second 0..59. |
| 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.
| int EXPORT_OPENSWMMCORE_SOLVER_API swmm_getCount | ( | int | objType | ) |
Get the number of objects in a legacy category.
| [in] | objType | Legacy object category from swmm_GAGE up to but excluding swmm_SYSTEM. |
| 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.
| [out] | errMsg | Non-null writable character buffer of at least msgLen + 1 bytes; sstrncpy can copy msgLen payload characters and append a terminator. |
| [in] | msgLen | Nonnegative maximum number of payload characters, not total buffer capacity; zero still writes a terminator. |
| 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.
| [in] | errorCode | Legacy internal error enum passed to error_getMsg, independent of global ErrorCode. |
| [out] | outErrMsg | Required pointer-array argument; only *outErrMsg is used and must reference writable storage for the bounded MAXMSG copy plus its terminator (reserve 1025 bytes). |
| int EXPORT_OPENSWMMCORE_SOLVER_API swmm_getIndex | ( | int | objType, |
| const char * | name ) |
Find a named object in the opened global model.
| [in] | objType | Supported category in [swmm_GAGE,swmm_SYSTEM). |
| [in] | name | Non-null null-terminated lookup name; borrowed only during the call. |
| 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.
| [in] | index | Zero-based global link index; subtype must match link. |
| [out] | stats | Non-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. |
| 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.
| [out] | runoffErr | Non-null writable percent-error slot. |
| [out] | flowErr | Non-null writable routing percent-error slot. |
| [out] | qualErr | Non-null writable quality percent-error slot. |
| int EXPORT_OPENSWMMCORE_SOLVER_API swmm_getName | ( | int | objType, |
| int | index, | ||
| char * | name, | ||
| int | size ) |
Copy the ID of one named legacy object.
| [in] | objType | Named category: gage, subcatchment, node, link, pollutant, landuse, time pattern, curve, time series, transect, aquifer or unit hydrograph/snowmelt where supported. |
| [in] | index | Zero-based object index strictly below the category count. |
| [out] | name | Non-null writable buffer, initially cleared; reserve at least size + 1 bytes for the legacy bounded copy. |
| [in] | size | Nonnegative maximum payload characters, excluding the final terminator. |
| 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.
| [in] | index | Zero-based global node index; subtype must match node. |
| [out] | stats | Non-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. |
| 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.
| [in] | index | Zero-based global node index; subtype must match outfall node. |
| [in,out] | stats | Non-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. |
| 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.
| [in] | index | Zero-based global link index; subtype must match pump link. |
| [out] | stats | Non-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. |
| 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.
| [out] | runoffErr | Non-null writable runoff percent-error slot. |
| [out] | flowErr | Non-null writable routing percent-error slot. |
| 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.
| [in] | property | swmm_CURRENTDATE or a supported subcatch/node/link result property. |
| [in] | index | Zero-based object index, ignored for the saved date. |
| [in] | period | One-based saved reporting period in [1,Nperiods], unlike the separate output-reader zero-based API. |
| 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.
| [in] | index | Zero-based global node index; subtype must match storage node. |
| [out] | stats | Non-null caller-owned destination, borrowed only during the call. Volumes ft3, maxFlow cfs and maxVolDate absolute SWMM days; avgVol is an accumulated sample sum. |
| 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.
| [in] | index | Zero-based global subcatchment index; subtype must match subcatchment. |
| [out] | stats | Non-null caller-owned destination, borrowed only during the call. Volumes ft3, peak flow cfs. |
| 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.
| [out] | totals | Non-null caller-owned destination. routing volume categories are ft3; pctError is percent, with no model display conversion. |
| 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.
| [out] | totals | Non-null caller-owned destination. runoff water categories including rainfall and snow stores are ft3; pctError is percent, with no model display conversion. |
| 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.
| [in] | property | Property enum for the selected object family; system/date/step, gage, subcatchment, node and link values follow the public property enums. |
| [in] | index | Zero-based object index; ignored by system properties. Other families validate against their object count. |
| 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.
| [in] | objType | swmm_SYSTEM, GAGE, SUBCATCH, NODE, LINK, POLLUTANT, TIME_PATTERN, LANDUSE or AQUIFER; selects the property implementation. |
| [in] | property | Property enum for the selected object family; system/date/step, gage, subcatchment, node and link values follow the public property enums. |
| [in] | index | Zero-based object index; ignored by system properties. Other families validate against their object count. |
| [in] | subIndex | Property-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] | pollutantIndex | Zero-based pollutant index for pollutant-dependent node/link/subcatchment properties; unused by other properties. |
| int EXPORT_OPENSWMMCORE_SOLVER_API swmm_getVersion | ( | void | ) |
Return the compiled legacy engine version integer.
| int EXPORT_OPENSWMMCORE_SOLVER_API swmm_getWarnings | ( | void | ) |
Return the current project warning counter.
| 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.
| [in] | inputFile | Non-null null-terminated input-deck path, borrowed for the call. |
| [in] | reportFile | Non-null null-terminated report path; the engine opens/overwrites the report. |
| [in] | outputFile | Non-null null-terminated binary output path; an empty string selects a scratch output file. |
| 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.
| 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.
| [in] | inputFile | Non-null null-terminated input-deck path, borrowed for the call. |
| [in] | reportFile | Non-null null-terminated report path; the engine opens/overwrites the report. |
| [in] | outputFile | Non-null null-terminated binary output path; an empty string selects a scratch output file. |
| 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.
| [in] | inputFile | Non-null null-terminated input-deck path, borrowed for the call. |
| [in] | reportFile | Non-null null-terminated report path; the engine opens/overwrites the report. |
| [in] | outputFile | Non-null null-terminated binary output path; an empty string selects a scratch output file. |
| [in] | callback | Optional borrowed function pointer called after each attempted step, including completion/error; null disables progress. Return type is void, so it cannot cancel. |
| 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.
| [in] | hotStartFile | Non-null null-terminated destination passed to the hotstart writer; borrowed only during the call. |
| 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.
| [in] | lidIndex | Zero-based LID process index. |
| [in] | coeff | Nonnegative coefficient in authored rain-rate units (in/hr or mm/hr) for the configured head exponent. |
| [in] | expon | Nonnegative dimensionless head exponent. |
| [in] | offset | Nonnegative drain offset in in or mm, converted internally to ft. |
| 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.
| [in] | nodeIndex | Zero-based node index within the opened model. |
| [in] | pollutantIndex | Zero-based pollutant index. |
| [in] | expression | Non-null nonempty null-terminated input-form equation, e.g. R = 0.5 or C = BOD * 0.2; copied into a bounded MAXLINE working buffer. |
| 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.
| [in] | property | Property enum for the selected object family; system/date/step, gage, subcatchment, node and link values follow the public property enums. |
| [in] | index | Zero-based object index; ignored by system properties. Other families validate against their object count. |
| [in] | value | New 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. |
| 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.
| [in] | objType | swmm_SYSTEM, GAGE, SUBCATCH, NODE, LINK, POLLUTANT, TIME_PATTERN, LANDUSE or AQUIFER; selects the property implementation. |
| [in] | property | Property enum for the selected object family; system/date/step, gage, subcatchment, node and link values follow the public property enums. |
| [in] | index | Zero-based object index; ignored by system properties. Other families validate against their object count. |
| [in] | subIndex | Property-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] | pollutantIndex | Zero-based pollutant index for pollutant-dependent node/link/subcatchment properties; unused by other properties. |
| [in] | value | New 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. |
| 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.
| [in] | cb | Callback pointer to retain, or null to disable. Its code must remain valid until replaced/disabled. |
| [in] | userData | Opaque pointer retained and supplied unchanged; caller owns its lifetime until replacement/disable. |
| 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.
| [in] | saveFlag | Zero suppresses periodic binary-result saving; nonzero enables it. |
| 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.
| [out] | elapsedTime | Non-null writable double, set to elapsed days since simulation start, or zero at completion; initialized to zero before lifecycle validation. |
| 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.
| [in] | strideStep | Requested stride in seconds; <= 0 delegates to one swmm_step. A positive stride temporarily caps RouteStep if smaller and stops at model end. |
| [out] | elapsedTime | Non-null writable elapsed-days slot; positive when more model time remains, zero at final completion or before validation. |
| 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.
| [in] | hotStartFile | Non-null null-terminated filename, copied up to MAXFNAME characters and resolved through the legacy input-directory path rules. |
| 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.
| [in] | line | Non-null null-terminated report text; borrowed during the call. |