Main module of the computational engine for Version 5 of the U.S. Environmental Protection Agency's Storm Water Management Model (SWMM). More...

#include <unistd.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <math.h>
#include <time.h>
#include <float.h>
#include "macros.h"
#include "objects.h"
#include "globals.h"
#include "funcs.h"
#include "error.h"
#include "text.h"
#include "swmm5.h"

Include dependency graph for swmm5.c:

Macros
#define	_CRT_SECURE_NO_DEPRECATE
	Define to prevent deprecation warnings from MS Visual C++ compilers.

#define	EXTERN
	Define for 'extern' in headers.h.

#define	MAX_EXCEPTIONS 100
	Maximum number of exceptions handled.

Functions
int	omp_get_max_threads (void)
	Dummy function for getting threads available for OpenMP to prevent compiler errors.

int EXPORT_SWMM_SOLVER_API	swmm_run (const char inputFile, const char reportFile, const char *outputFile)
	Run a SWMM simulation with the given input file, report file, and output file.

int EXPORT_SWMM_SOLVER_API	swmm_run_with_callback (const char inputFile, const char reportFile, const char *outputFile, progress_callback callback)
	Run a SWMM simulation with the given input file, report file, and output file with a progress callback.

int EXPORT_SWMM_SOLVER_API	swmm_open (const char inputFile, const char reportFile, const char *outputFile)
	Open a SWMM simulation with the given input file, report file, and output file.

int EXPORT_SWMM_SOLVER_API	swmm_start (int saveFlag)
	Start a SWMM simulation with the given save flag.

int EXPORT_SWMM_SOLVER_API	swmm_step (double *elapsedTime)
	End a SWMM simulation.

int EXPORT_SWMM_SOLVER_API	swmm_stride (int strideStep, double *elapsedTime)
	Perform a SWMM simulation step with a stride step and return the elapsed time.

int EXPORT_SWMM_SOLVER_API	swmm_useHotStart (const char *hotStartFile)
	Set hotstart file for SWMM simulation.

int EXPORT_SWMM_SOLVER_API	swmm_saveHotStart (const char *hotStartFile)
	Save hotstart file for SWMM simulation at current time.

int EXPORT_SWMM_SOLVER_API	swmm_end (void)
	End a SWMM simulation.

int EXPORT_SWMM_SOLVER_API	swmm_report ()
	Writes simulation results to the report file.

void EXPORT_SWMM_SOLVER_API	swmm_writeLine (const char *line)
	Write a line of text to the SWMM report file.

int EXPORT_SWMM_SOLVER_API	swmm_close ()
	Close a SWMM simulation.

int EXPORT_SWMM_SOLVER_API	swmm_getMassBalErr (float runoffErr, float flowErr, float *qualErr)
	Get the mass balance errors for a SWMM simulation.

int EXPORT_SWMM_SOLVER_API	swmm_getVersion ()
	Get the version of the SWMM engine.

int EXPORT_SWMM_SOLVER_API	swmm_getWarnings ()
	Gets the number of warnings issued during a simulation.

int EXPORT_SWMM_SOLVER_API	swmm_getError (char *errMsg, int msgLen)
	Retrieves the code number and text of the error condition that caused SWMM to abort its analysis.

int EXPORT_SWMM_SOLVER_API	swmm_getErrorFromCode (int errorCode, char *outErrMsg[1024])
	Retrieves the text of the error message that corresponds to the error code number.

int EXPORT_SWMM_SOLVER_API	swmm_getCount (int objType)
	Retrieves the number of objects of a specific type.

int EXPORT_SWMM_SOLVER_API	swmm_getName (int objType, int index, char *name, int size)
	Retrieves the ID name of an object.

int EXPORT_SWMM_SOLVER_API	swmm_getIndex (int objType, const char *name)
	Retrieves the index of a named object.

double EXPORT_SWMM_SOLVER_API	swmm_getValue (int property, int index)
	Get the value of a property for an object of a given property in the SWMM model.

double EXPORT_SWMM_SOLVER_API	swmm_getValueExpanded (int objType, int property, int index, int subIndex)
	Get the value of a property for an object given property, index, and subindex in the SWMM model.

int EXPORT_SWMM_SOLVER_API	swmm_setValue (int property, int index, double value)
	Set the value of a property for an object of a given property and index in the SWMM model.

int EXPORT_SWMM_SOLVER_API	swmm_setValueExpanded (int objType, int property, int index, int subIndex, double value)
	Set the value of a property for an object given property, index, and subindex in the SWMM model.

double EXPORT_SWMM_SOLVER_API	swmm_getSavedValue (int property, int index, int period)
	Get saved value of.

void EXPORT_SWMM_SOLVER_API	swmm_decodeDate (double date, int year, int month, int day, int hour, int minute, int second, int *dayOfWeek)
	Decode double date value into year, month, day, hour, minute, second, and day of week.

double EXPORT_SWMM_SOLVER_API	swmm_encodeDate (int year, int month, int day, int hour, int minute, int second)
	Encode date values into a double date value.

double	UCF (int u)
	Computes a conversion factor from SWMM's internal units to user's units.

size_t	sstrncpy (char dest, const char src, size_t n)
	Copies a string to a new memory location in a safe way.

size_t	sstrcat (char dest, const char src, size_t destsize)
	Safe string concatenation.

int	strcomp (const char s1, const char s2)
	Compares two strings (case insensitive).

char *	getTempFileName (char *fname)
	Creates a temporary file name with path prepended to it.

void	getElapsedTime (DateTime aDate, int days, int hrs, int *mins)
	Finds elapsed simulation time for a given calendar date.

DateTime	getDateTime (double elapsedMsec)
	Finds calendar date/time value for elapsed milliseconds of simulation time.

char *	addAbsolutePath (char *fname)
	Adds an absolute path name to a file name.

void	writecon (const char *s)
	Writes string to console.

Variables
const double	Ucf [10][2]
	Unit conversion factors for different units used in SWMM.

const double	Qcf [6]
	Flow conversion factors for different flow units used in SWMM.

Detailed Description

Main module of the computational engine for Version 5 of the U.S. Environmental Protection Agency's Storm Water Management Model (SWMM).

Author: L. Rossman

Date: Created: 2021-11-01; Last edited: 2024-12-23

Version: 5.3

This is the main module of the computational engine for Version 5 of the U.S. Environmental Protection Agency's Storm Water Management Model (SWMM). It contains functions that control the flow of computations.

This engine should be compiled into a shared object library whose API functions are listed in swmm5.h.

Update History

Build 5.1.008:
- Support added for the MinGW compiler.
- Reporting of project options moved to swmm_start.
- Hot start file now read before routing system opened.
- Final routing step adjusted so that total duration not exceeded.
Build 5.1.011:
- Made sure that MS exception handling only used with MS C compiler.
- Added name of module handling an exception to error report.
- Elapsed simulation time now saved to new global variable ElaspedTime.
- Added swmm_getError() function that retrieves error code and message.
- Changed WarningCode to Warnings (# warnings issued).
- Added swmm_getWarnings() function to retrieve value of Warnings.
- Fixed error code returned on swmm_xxx functions.
Build 5.1.012:
- #include <direct.h> only used when compiled for Windows.
Build 5.1.013:
- Support added for saving average results within a reporting period.
- SWMM engine now always compiled to a shared object library.
Build 5.1.015:
- Fixes bug in summary statistics when Report Start date > Start Date.
Build 5.2.0:
- Added additional API functions.
- Set max. number of open files to 8192.
- Changed getElapsedTime function to use report start as base date/time.
- Prevented possible infinite loop if swmm_step() called when ErrorCode > 0.
- Prevented early exit from swmm_end() when ErrorCode > 0.
- Support added for relative file names.
Build 5.3.0:
- Added support for saving hot start files at specific times.
- Expanded SWMM api to save and use prescribed hotstart files.
- Expansions to the SWMM API to include attributes of more objects and water quality.

Macro Definition Documentation

◆ _CRT_SECURE_NO_DEPRECATE

#define _CRT_SECURE_NO_DEPRECATE

Define to prevent deprecation warnings from MS Visual C++ compilers.

◆ EXTERN

#define EXTERN

Define for 'extern' in headers.h.

◆ MAX_EXCEPTIONS

#define MAX_EXCEPTIONS 100

Maximum number of exceptions handled.

Function Documentation

◆ omp_get_max_threads()

int omp_get_max_threads ( void )

Dummy function for getting threads available for OpenMP to prevent compiler errors.

Returns: 1

◆ swmm_close()

int EXPORT_SWMM_SOLVER_API swmm_close ( void )

Close a SWMM simulation.

Returns: Error code

Close a SWMM simulation.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ swmm_decodeDate()

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

Decode double date value into year, month, day, hour, minute, second, and day of week.

Parameters

[in]	date	Date value
[out]	year	Year
[out]	month	Month
[out]	day	Day
[out]	hour	Hour
[out]	minute	Minute
[out]	second	Second
[out]	dayOfWeek	Day of week (0=Sunday, 1=Monday, ..., 6=Saturday)

Decode double date value into year, month, day, hour, minute, second, and day of week.

Here is the call graph for this function:

◆ swmm_encodeDate()

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

Encode date values into a double date value.

Parameters

[in]	year	Year
[in]	month	Month
[in]	day	Day
[in]	hour	Hour
[in]	minute	Minute
[in]	second	Second

Returns: Date value

Encode date values into a double date value.

Here is the call graph for this function:

◆ swmm_end()

int EXPORT_SWMM_SOLVER_API swmm_end ( void )

End a SWMM simulation.

Returns: Error code

End a SWMM simulation.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ swmm_getCount()

int EXPORT_SWMM_SOLVER_API swmm_getCount ( int objType )

Retrieves the number of objects of a specific type.

Parameters

[in] objType Type of SWMM object

Returns: Number of objects or error code

Retrieves the number of objects of a specific type.

◆ swmm_getError()

int EXPORT_SWMM_SOLVER_API swmm_getError	(	char *	errMsg,
		int	msgLen
	)

Retrieves the code number and text of the error condition that caused SWMM to abort its analysis.

Parameters

[out]	errMsg	Error message text
[in]	msgLen	Maximum size of errMsg

Returns: Error message code number

Retrieves the code number and text of the error condition that caused SWMM to abort its analysis.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ swmm_getErrorFromCode()

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

Retrieves the text of the error message that corresponds to the error code number.

Parameters

[in]	errorCode	Error code number
[out]	outErrMsg	Error message text

Returns: Error code

Retrieves the text of the error message that corresponds to the error code number.

Here is the call graph for this function:

◆ swmm_getIndex()

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

Retrieves the index of a named object.

Parameters

[in]	objType	Type of SWMM object
[in]	name	Object name

Returns: Object index or error code

Retrieves the index of a named object.

Here is the call graph for this function:

◆ swmm_getMassBalErr()

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

Get the mass balance errors for a SWMM simulation.

Parameters

[out]	runoffErr	Runoff error (percent)
[out]	flowErr	Flow error (percent)
[out]	qualErr	Quality error (percent)

Returns: Error code

Get the mass balance errors for a SWMM simulation.

◆ swmm_getName()

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

Retrieves the ID name of an object.

Parameters

[in]	objType	Type of SWMM object
[in]	index	Object index
[out]	name	Object name
[in]	size	Size of the name array

Returns: Error code

Retrieves the ID name of an object.

Here is the call graph for this function:

◆ swmm_getSavedValue()

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

Get saved value of.

Parameters

[in]	property	Property type
[in]	index	Object index
[in]	period	Time period index

Returns: Property value

Get saved value of.

◆ swmm_getValue()

double EXPORT_SWMM_SOLVER_API swmm_getValue	(	int	property,
		int	index
	)

Get the value of a property for an object of a given property in the SWMM model.

Parameters

[in]	property	Property type
[in]	index	Object index

Returns: Property value

Deprecated:: Use swmm_getValueExpanded instead. Function will be changed to swmm_getValueExpanded in future versions.

Get the value of a property for an object of a given property in the SWMM model.

Here is the call graph for this function:

◆ swmm_getValueExpanded()

double EXPORT_SWMM_SOLVER_API swmm_getValueExpanded	(	int	objType,
		int	property,
		int	index,
		int	subIndex
	)

Get the value of a property for an object given property, index, and subindex in the SWMM model.

Parameters

[in]	objType	Object type
[in]	property	Property type
[in]	index	Object index
[in]	subIndex	Optional Subindex for the property

Returns: Property value

Get the value of a property for an object given property, index, and subindex in the SWMM model.

Here is the call graph for this function:

◆ swmm_getVersion()

int EXPORT_SWMM_SOLVER_API swmm_getVersion ( void )

Get the version of the SWMM engine.

Returns: Version number

Get the version of the SWMM engine.

Here is the caller graph for this function:

◆ swmm_getWarnings()

int EXPORT_SWMM_SOLVER_API swmm_getWarnings ( void )

Gets the number of warnings issued during a simulation.

Returns: Number of warning messages issued

Gets the number of warnings issued during a simulation.

Here is the caller graph for this function:

◆ swmm_open()

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

Open a SWMM simulation with the given input file, report file, and output file.

Parameters

[in]	inputFile	Path to the input file
[in]	reportFile	Path to the report file
[in]	outputFile	Path to the output file

Returns: Error code

Open a SWMM simulation with the given input file, report file, and output file.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ swmm_report()

int EXPORT_SWMM_SOLVER_API swmm_report ( void )

Writes simulation results to the report file.

Returns: Error code

Writes simulation results to the report file.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ swmm_run()

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

Run a SWMM simulation with the given input file, report file, and output file.

Parameters

[in]	inputFile	Path to the input file
[in]	reportFile	Path to the report file
[in]	outputFile	Path to the output file

Returns: Error code

Run a SWMM simulation with the given input file, report file, and output file.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ swmm_run_with_callback()

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

Run a SWMM simulation with the given input file, report file, and output file with a progress callback.

Parameters

[in]	inputFile	Path to the input file
[in]	reportFile	Path to the report file
[in]	outputFile	Path to the output file
[in]	callback	Progress callback function

Returns: Error code

Run a SWMM simulation with the given input file, report file, and output file with a progress callback.

Here is the call graph for this function:

◆ swmm_saveHotStart()

int EXPORT_SWMM_SOLVER_API swmm_saveHotStart ( const char * hotStartFile )

Save hotstart file for SWMM simulation at current time.

Parameters

[in] hotStartFile Path to the hotstart file

Returns: Error code

Save hotstart file for SWMM simulation at current time.

Here is the call graph for this function:

◆ swmm_setValue()

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

Set the value of a property for an object of a given property and index in the SWMM model.

Parameters

[in]	property	Property type
[in]	index	Object index
[in]	value	Property value

Returns: Error code

Deprecated:: Use swmm_setValueExpanded instead. Function will be changed to swmm_setValueExpanded in future versions.

Set the value of a property for an object of a given property and index in the SWMM model.

◆ swmm_setValueExpanded()

int EXPORT_SWMM_SOLVER_API swmm_setValueExpanded	(	int	objType,
		int	property,
		int	index,
		int	subIndex,
		double	value
	)

Set the value of a property for an object given property, index, and subindex in the SWMM model.

Parameters

[in]	objType	Object type
[in]	property	Property type
[in]	index	Object index
[in]	subIndex	Optional Subindex for the property
[in]	value	Property value

Returns: Error code

Set the value of a property for an object given property, index, and subindex in the SWMM model.

◆ swmm_start()

int EXPORT_SWMM_SOLVER_API swmm_start ( int saveFlag )

Start a SWMM simulation with the given save flag.

Parameters

[in] saveFlag Flag to save simulation

Returns: Error code

Start a SWMM simulation with the given save flag.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ swmm_step()

int EXPORT_SWMM_SOLVER_API swmm_step ( double * elapsedTime )

End a SWMM simulation.

Perform a SWMM simulation step and return the elapsed time.

Returns: Error code

End a SWMM simulation.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ swmm_stride()

int EXPORT_SWMM_SOLVER_API swmm_stride	(	int	strideStep,
		double *	elapsedTime
	)

Perform a SWMM simulation step with a stride step and return the elapsed time.

Parameters

[in]	strideStep	Stride step
[out]	elapsedTime	Elapsed time

Returns: Error code

Perform a SWMM simulation step with a stride step and return the elapsed time.

Here is the call graph for this function:

◆ swmm_useHotStart()

int EXPORT_SWMM_SOLVER_API swmm_useHotStart ( const char * hotStartFile )

Set hotstart file for SWMM simulation.

Sets the hotstart file to use for simulation. Errors does not terminate simulation unless there is a prior terminating error.

Parameters

[in] hotStartFile Path to the hotstart file

Returns: Error code

Set hotstart file for SWMM simulation.

Here is the call graph for this function:

◆ swmm_writeLine()

void EXPORT_SWMM_SOLVER_API swmm_writeLine ( const char * line )

Write a line of text to the SWMM report file.

Parameters

[in] line Line of text

Write a line of text to the SWMM report file.

Here is the call graph for this function:

Macros

Functions

Variables

Detailed Description

Update History

Macro Definition Documentation

◆ _CRT_SECURE_NO_DEPRECATE

◆ EXTERN

◆ MAX_EXCEPTIONS

Function Documentation

◆ omp_get_max_threads()

◆ swmm_close()

◆ swmm_decodeDate()

◆ swmm_encodeDate()

◆ swmm_end()

◆ swmm_getCount()

◆ swmm_getError()

◆ swmm_getErrorFromCode()

◆ swmm_getIndex()

◆ swmm_getMassBalErr()

◆ swmm_getName()

◆ swmm_getSavedValue()

◆ swmm_getValue()

◆ swmm_getValueExpanded()

◆ swmm_getVersion()

◆ swmm_getWarnings()

◆ swmm_open()

◆ swmm_report()

◆ swmm_run()

◆ swmm_run_with_callback()

◆ swmm_saveHotStart()

◆ swmm_setValue()

◆ swmm_setValueExpanded()

◆ swmm_start()

◆ swmm_step()

◆ swmm_stride()

◆ swmm_useHotStart()

◆ swmm_writeLine()