SWMM (EPA) adapter

SWMM pre-adapter

Model pre-adapter for running SWMM (Storm Water Management Model) model (version 5) from Delft-FEWS.
For information about the SWMM model see https://www.epa.gov/water-research/storm-water-management-model-swmm

Usage: SWMMPreAdapter <PI XML run file pathname relative to current working directory>

Class name: nl.deltares.fews.swmm.SwmmPreAdapter

Properties

SWMM_input_file

(required)

Pathname of SWMM input file to update. This should be either an absolute path or a path relative to the workDir specified in the netcdf run file.

The input file will be updated to modify only the START_DATE, START_TIME, END_DATE, END_TIME, REPORT_START_DATE and REPORT_START_TIME fields, the rest of the file is not modified in any way.

Notes for users

For all files that are written by this adapter, if the file to be written already exists, then it will be overwritten.
This program can process timeseries input data per catchment, node or link model entity, and requires that each model entity has a unique ID, regardless of it's entity type.
This program assumes that the SWMM model configuration uses the same time zone as given in the PI XML runfile.
The working directory (workDir) defined in the PI XML run file is the ddirectory where the SWMM model will be run, the SWMM input/output files should/will be stored in this directory.
This program writes log messages to a log file called "swmm_pre_adapter_log.txt" in the workDir specified in the PI XML run file.
This program uses the information in the specified PI XML run file as input and uses this information to perform the following actions:
1. Update the start and end time for the simulation.
  The SWMM input file (*.inp) file specified in the property "SWMM_input_file" will be updated to reflect the start and end date / time for the simulation as specified in the PI XML run file. The adapter will only modify the START_DATE, START_TIME, END_DATE, END_TIME, REPORT_START_DATE and REPORT_START_TIME fields where the report start date/time will be the same as the start of the simulation.
2. Convert input PI XML timeseries files to SWMM itimeseries input file format files:
  For each of the input timeseries files listed in the PI XML run file, one or more SWMM compatible timeseries file will be written to the working directory as follows:
  - For each of the timeseries present in the PI XML input file, the location ID is looked up in the [TIMESERIES] section of the SWMM model input file (*.INP) to get the FILE name listed there.
  - A compatible timeseries file (see the SWMM5 user manual section 11.6) is written for each location in the working directory.

System requirements

This program needs Java version 11 or higher.
This program needs the following Java libraries:
- castor-0.9.5p.jar
- Delft_PI.jar
- Delft_PI_castor.jar
- Delft_Util.jar
- FastInfoset-1.2.6.jar
- log4j-1.2-api-2.11.1p.jar
- log4j-api-2.11.1.jar
- log4j-core-2.11.1.jar
- log4j-slf4j-impl-2.11.1.jar
- slf4j-api-1.7.13.jar
- xercesImpl.jar

SWMM post-adapter

Model post-adapter for running SWMM (Simulating WAves Nearshore) model from Delft-FEWS.
For information about the SWMM model see http://www.SWMM.tudelft.nl/

Usage: SWMMPostAdapter <netcdf run file pathname relative to current working directory>

Class name: nl.deltares.SWMM.SWMMPostAdapter

Properties

output_netcdf_spectra_file_to_convert	(optional)	Path to netcdf spectra file to convert. A copy of the file will be created with <name>_adapted.nc which adds "lat" "lon" coordinate variables (according to the CF conventions) and multiplies the density variable with the scale_denstity variable.
output_ascii_grid_file_to_convert	(optional)	Convert output map file from ascii (HEADER, Layout 1) to NetCDF. The path to the map ascii file should be specified in the value section. Examples are attached. overall.asc; overall.nc
output_ascii_grid_swap_north_south	(optional)	Useful when the output SWMM grid is swapped compare to the SWMM grid definition in FEWS. The swap occurs during the file conversion from Ascii to Netcdf. Usage: <bool key="output_ascii_grid_swap_north_south" value="true"/>, True: the output grid will be swapped north to south; False: no swap
TAB file conversion (not a keyword)	(hardcoded)	see description in the Notes for users. Examples are attached. overallout.nc; overallout.PNT; overallout.tab

Notes for users

For all files that are written by this adapter, if the file to be written already exists, then it will be overwritten.
This program assumes that the model always runs in time zone GMT.
This program writes log messages to a log file called SWMM_post_adapter_log.txt in the workDir specified in the netcdf run file.
This program uses the information in the specified netcdf run file as input and uses this information to do the following actions:
1. Convert output scalar time series:
  All .TAB files in the workDir specified in the netcdf run file will be converted to files in netcdf format with the same path and name but different extension (.nc). For this conversion the mapping between coordinates and locationIds from the corresponding .PNT files is used. This program assumes that for a given .TAB file the corresponding .PNT file has the same path and name as the .TAB file, only a different extension. This program assumes that the locations in the .TAB file and in the corresponding .PNT file are in the same order. This program assumes that the last part between double quotes on a given line in a .PNT file is the locationId. This program assumes that the coordinates in a given .TAB file are in degrees in the WGS 1984 coordinate system. If no .TAB files are present in the specified workDir, then this step does nothing.

System requirements

This program needs Java version 8 or higher.
This program needs the following Java libraries:
- commons-httpclient-3.0.1.jar
- Delft_FEWS.jar
- Delft_Util.jar
- log4j-1.2.14.jar
- netcdf-4.2.jar
- slf4j-api-1.5.6.jar
- slf4j-log4j12-1.5.6.jar
- TimeSeriesImport.jar

GeneralAdapterRun Example Configuration

The following gives an example of how to set up the GeneralAdapterRun file for SWMM in FEWS using the SWMM model pre and post-adapters. The GeneralAdapterRun file follows the general structure as described here.

General

In this section general information regarding the module such as version number, file directories, missing values, and time zone information can be specified.

general

<general>
	<description>SWMM model run</description>
	<piVersion>1.8</piVersion>
	<rootDir>%REGION_HOME%/Modules/SWMM/$MODEL$</rootDir>
	<workDir>%ROOT_DIR%/workDir</workDir>
	<exportDir>%ROOT_DIR%/input</exportDir>
	<exportDataSetDir>%ROOT_DIR%/</exportDataSetDir>
	<exportIdMap>IdExport_$MODEL$</exportIdMap>
	<importDir>%ROOT_DIR%/workDir</importDir>
	<importIdMap>IdImport_$MODEL$</importIdMap>
	<importUnitConversionsId>ImportUnitConversions</importUnitConversionsId>
	<dumpFileDir>$GA_DUMPFILEDIR$</dumpFileDir>
	<dumpDir>%ROOT_DIR%/diagnostics/</dumpDir>
	<diagnosticFile>%ROOT_DIR%/diagnostics/diagnostics.xml</diagnosticFile>
	<missVal>-999</missVal>
	<timeZone>
		<timeZoneName>GMT+0:00</timeZoneName>
	</timeZone>
</general>

Start-up activities

It may be useful to clear the model working directory of any previous runs before starting a new run.

startUpActivities

		<startUpActivities>
			<purgeActivity>
				<filter>%ROOT_DIR%/workDir/*</filter>
			</purgeActivity>
		</startUpActivities>

Export activities

In this section the data to be exported from FEWS as input to the module is specified. Data to export to SWMM generally includes:

Model state
Model data set
Input data (i.e. wind, water levels, wave spectra)
Run file

The run file contains information regarding the input file names, start and stop times, and time step. Additional properties can be passed using the run file as listed above under Properties.

exportActivities

<exportActivities>
			<exportStateActivity>
				<moduleInstanceId>$MODULE_INSTANCE_ID$</moduleInstanceId>
				<stateExportDir>%ROOT_DIR%/stateInput</stateExportDir>
				<stateSelection>
					<warmState>
						<stateSearchPeriod unit="hour" start="-1" end="0"/>
					</warmState>
				</stateSelection>
			</exportStateActivity>
			<exportDataSetActivity>
				<moduleInstanceId>SWMM_$MODEL$_$METEO$</moduleInstanceId>
			</exportDataSetActivity>
			<exportNetcdfActivity>
				<exportFile>waterlevel.nc</exportFile>
				<timeSeriesSets>
					<timeSeriesSet>
						<moduleInstanceId>D3D_flow_dcsm5_hirlam72_hc</moduleInstanceId>
						<valueType>grid</valueType>
						<parameterId>H.simulated</parameterId>
						<locationId>dcsm5</locationId>
						<timeSeriesType>simulated historical</timeSeriesType>
						<timeStep unit="hour"/>
						<relativeViewPeriod unit="hour" start="-1" startOverrulable="true" end="0"/>
						<readWriteMode>read only</readWriteMode>
						<synchLevel>2</synchLevel>
					</timeSeriesSet>
				</timeSeriesSets>
			</exportNetcdfActivity>
			<exportNetcdfActivity>
				<exportFile>$METEO$.nc</exportFile>
				<timeSeriesSets>
					<timeSeriesSet>
						<moduleInstanceId>Import_$METEO$</moduleInstanceId>
						<valueType>grid</valueType>
						<parameterId>Wind.u.simulated</parameterId>
						<locationId>$METEO$_regular</locationId>
						<timeSeriesType>external historical</timeSeriesType>
						<timeStep unit="hour" multiplier="1"/>
						<relativeViewPeriod unit="hour" start="-1" startOverrulable="true" end="0"/>
						<readWriteMode>read only</readWriteMode>
					</timeSeriesSet>
					<timeSeriesSet>
						<moduleInstanceId>Import_$METEO$</moduleInstanceId>
						<valueType>grid</valueType>
						<parameterId>Wind.v.simulated</parameterId>
						<locationId>$METEO$_regular</locationId>
						<timeSeriesType>external historical</timeSeriesType>
						<timeStep unit="hour" multiplier="1"/>
						<relativeViewPeriod unit="hour" start="-1" startOverrulable="true" end="0"/>
						<readWriteMode>read only</readWriteMode>
					</timeSeriesSet>
				</timeSeriesSets>
			</exportNetcdfActivity>
			<exportNetcdfActivity>
				<exportFile>ecmwf_spectra.nc</exportFile>
				<timeSeriesSets>
					<timeSeriesSet>
						<moduleInstanceId>Import_ecmwf_spectra</moduleInstanceId>
						<valueType>scalar</valueType>
						<parameterId>Wave.variancedensity2D.simulated</parameterId>
						<domainParameterId>f</domainParameterId>
						<domainParameterId>dir</domainParameterId>
						<locationSetId>ecmwf_spectra.locations</locationSetId>
						<timeSeriesType>external historical</timeSeriesType>
						<timeStep unit="hour" multiplier="6"/>
						<relativeViewPeriod unit="hour" end="0"/>
						<readWriteMode>read only</readWriteMode>
					</timeSeriesSet>
				</timeSeriesSets>
			</exportNetcdfActivity>
			<exportNetcdfRunFileActivity>
				<description>This run file is passed as argument to SWMMPreAdapter</description>
				<exportFile>%WORK_DIR%\run_info.nc</exportFile>
				<properties>
					<string key="input_spectra_file_to_convert" value="..\input\ecmwf_spectra.nc"/>
					<string key="template_SWMM_input_file" value="..\template\template.swn"/>
					<string key="SWMM_input_file" value="INPUT"/>
				</properties>
			</exportNetcdfRunFileActivity>
		</exportActivities>

Execute activities

This section calls the SWMM pre and post-adapters as well as the SWMM executable. Note: the run file must be passed as an argument to the SWMM pre and post-adapters.

executeActivities

<executeActivities>
			<executeActivity>
				<command>
					<className>nl.deltares.SWMM.SWMMPreAdapter</className>
					<binDir>..\..\..\bin\SWMM_adapter\bin</binDir>
				</command>
				<arguments>
					<argument>%WORK_DIR%\run_info.nc</argument>
				</arguments>
				<timeOut>99999999</timeOut>
				<ignoreDiagnostics>true</ignoreDiagnostics>
			</executeActivity>
			<executeActivity>
				<command>
					<executable>..\..\..\bin\SWMM\SWMM_4091AB_3_del_win_vs2010.exe</executable>
				</command>
				<arguments>
					<argument>%WORK_DIR%\INPUT</argument>
				</arguments>
				<timeOut>99999999</timeOut>
				<ignoreDiagnostics>true</ignoreDiagnostics>
			</executeActivity>
			<executeActivity>
				<command>
					<className>nl.deltares.SWMM.SWMMPostAdapter</className>
					<binDir>..\..\..\bin\SWMM_adapter\bin</binDir>
				</command>
				<arguments>
					<argument>%WORK_DIR%\run_info.nc</argument>
				</arguments>
				<timeOut>99999999</timeOut>
				<ignoreDiagnostics>true</ignoreDiagnostics>
			</executeActivity>
		</executeActivities>

Import activities

In this section the data to be imported into FEWS as output from the module is specified. Data to import from SWMM generally includes:

Model state
Output data (i.e. wind, water levels, wave spectra)

importActivities

<importActivities>
			<importStateActivity>
				<stateFile>
					<importFile>%ROOT_DIR%/workDir/SWMM-state.nc</importFile>
					<relativeExportFile>SWMM-restart.nc</relativeExportFile>
				</stateFile>
				<expiryTime unit="day" multiplier="3"/>
			</importStateActivity>
			<importPiNetcdfActivity>
				<importFile>..\output\SPEC2D_P1.nc</importFile>
				<timeSeriesSets>
					<timeSeriesSet>
						<moduleInstanceId>$MODULE_INSTANCE_ID$</moduleInstanceId>
						<valueType>spectrum</valueType>
						<parameterId>Wave.variancedensity2D.simulated</parameterId>
						<domainParameterId>f</domainParameterId>
						<domainParameterId>dir</domainParameterId>
						<locationSetId>$MODEL$.locations</locationSetId>
						<timeSeriesType>simulated historical</timeSeriesType>
						<timeStep unit="hour"/>
						<readWriteMode>add originals</readWriteMode>
						<synchLevel>2</synchLevel>
						<expiryTime unit="week" multiplier="1"/>
					</timeSeriesSet>
				</timeSeriesSets>
			</importPiNetcdfActivity>
			<importPiNetcdfActivity>
				<importFile>POINTS.nc</importFile>
				<timeSeriesSets>
					<timeSeriesSet>
						<moduleInstanceId>$MODULE_INSTANCE_ID$</moduleInstanceId>
						<valueType>scalar</valueType>
						<parameterId>Wave.hm0.simulated</parameterId>
						<locationSetId>$MODEL$.locations</locationSetId>
						<timeSeriesType>simulated historical</timeSeriesType>
						<timeStep unit="minute" multiplier="60"/>
						<readWriteMode>add originals</readWriteMode>
						<synchLevel>0</synchLevel>
						<expiryTime unit="week" multiplier="1"/>
					</timeSeriesSet>
					<timeSeriesSet>
						<moduleInstanceId>$MODULE_INSTANCE_ID$</moduleInstanceId>
						<valueType>scalar</valueType>
						<parameterId>Wave.he10.simulated</parameterId>
						<locationSetId>$MODEL$.locations</locationSetId>
						<timeSeriesType>simulated historical</timeSeriesType>
						<timeStep unit="minute" multiplier="60"/>
						<readWriteMode>add originals</readWriteMode>
						<synchLevel>0</synchLevel>
						<expiryTime unit="week" multiplier="1"/>
					</timeSeriesSet>
					<timeSeriesSet>
						<moduleInstanceId>$MODULE_INSTANCE_ID$</moduleInstanceId>
						<valueType>scalar</valueType>
						<parameterId>Wave.period.Tm-1.0.simulated</parameterId>
						<locationSetId>$MODEL$.locations</locationSetId>
						<timeSeriesType>simulated historical</timeSeriesType>
						<timeStep unit="minute" multiplier="60"/>
						<readWriteMode>add originals</readWriteMode>
						<synchLevel>0</synchLevel>
						<expiryTime unit="week" multiplier="1"/>
					</timeSeriesSet>
					<timeSeriesSet>
						<moduleInstanceId>$MODULE_INSTANCE_ID$</moduleInstanceId>
						<valueType>scalar</valueType>
						<parameterId>Wave.dir.E10.simulated</parameterId>
						<locationSetId>$MODEL$.locations</locationSetId>
						<timeSeriesType>simulated historical</timeSeriesType>
						<timeStep unit="minute" multiplier="60"/>
						<readWriteMode>add originals</readWriteMode>
						<synchLevel>0</synchLevel>
						<expiryTime unit="week" multiplier="1"/>
					</timeSeriesSet>
					<timeSeriesSet>
						<moduleInstanceId>$MODULE_INSTANCE_ID$</moduleInstanceId>
						<valueType>scalar</valueType>
						<parameterId>Wave.s0bh.simulated</parameterId>
						<locationSetId>$MODEL$.locations</locationSetId>
						<timeSeriesType>simulated historical</timeSeriesType>
						<timeStep unit="minute" multiplier="60"/>
						<readWriteMode>add originals</readWriteMode>
						<synchLevel>0</synchLevel>
						<expiryTime unit="week" multiplier="1"/>
					</timeSeriesSet>
					<timeSeriesSet>
						<moduleInstanceId>$MODULE_INSTANCE_ID$</moduleInstanceId>
						<valueType>scalar</valueType>
						<parameterId>Wave.period.Tps.simulated</parameterId>
						<locationSetId>$MODEL$.locations</locationSetId>
						<timeSeriesType>simulated historical</timeSeriesType>
						<timeStep unit="minute" multiplier="60"/>
						<readWriteMode>add originals</readWriteMode>
						<synchLevel>0</synchLevel>
						<expiryTime unit="week" multiplier="1"/>
					</timeSeriesSet>
					<timeSeriesSet>
						<moduleInstanceId>$MODULE_INSTANCE_ID$</moduleInstanceId>
						<valueType>scalar</valueType>
						<parameterId>H.simulated</parameterId>
						<locationSetId>$MODEL$.locations</locationSetId>
						<timeSeriesType>simulated historical</timeSeriesType>
						<timeStep unit="minute" multiplier="60"/>
						<readWriteMode>add originals</readWriteMode>
						<synchLevel>0</synchLevel>
						<expiryTime unit="week" multiplier="1"/>
					</timeSeriesSet>
				</timeSeriesSets>
			</importPiNetcdfActivity>
			<importPiNetcdfActivity>
				<importFile>..\output\SWMM2D.nc</importFile>
				<timeSeriesSets>
					<timeSeriesSet>
						<moduleInstanceId>$MODULE_INSTANCE_ID$</moduleInstanceId>
						<valueType>grid</valueType>
						<parameterId>Wave.hm0.simulated</parameterId>
						<locationId>$MODEL$</locationId>
						<timeSeriesType>simulated historical</timeSeriesType>
						<timeStep unit="minute" multiplier="60"/>
						<readWriteMode>add originals</readWriteMode>
						<synchLevel>2</synchLevel>
						<expiryTime unit="hour" multiplier="24"/>
					</timeSeriesSet>
					<timeSeriesSet>
						<moduleInstanceId>$MODULE_INSTANCE_ID$</moduleInstanceId>
						<valueType>grid</valueType>
						<parameterId>Wave.he10.simulated</parameterId>
						<locationId>$MODEL$</locationId>
						<timeSeriesType>simulated historical</timeSeriesType>
						<timeStep unit="minute" multiplier="60"/>
						<readWriteMode>add originals</readWriteMode>
						<synchLevel>2</synchLevel>
						<expiryTime unit="hour" multiplier="24"/>
					</timeSeriesSet>
					<timeSeriesSet>
						<moduleInstanceId>$MODULE_INSTANCE_ID$</moduleInstanceId>
						<valueType>grid</valueType>
						<parameterId>Wave.period.Tm-1.0.simulated</parameterId>
						<locationId>$MODEL$</locationId>
						<timeSeriesType>simulated historical</timeSeriesType>
						<timeStep unit="minute" multiplier="60"/>
						<readWriteMode>add originals</readWriteMode>
						<synchLevel>2</synchLevel>
						<expiryTime unit="hour" multiplier="24"/>
					</timeSeriesSet>
					<timeSeriesSet>
						<moduleInstanceId>$MODULE_INSTANCE_ID$</moduleInstanceId>
						<valueType>grid</valueType>
						<parameterId>Wave.period.Tps.simulated</parameterId>
						<locationId>$MODEL$</locationId>
						<timeSeriesType>simulated historical</timeSeriesType>
						<timeStep unit="minute" multiplier="60"/>
						<readWriteMode>add originals</readWriteMode>
						<synchLevel>2</synchLevel>
						<expiryTime unit="hour" multiplier="24"/>
					</timeSeriesSet>
					<timeSeriesSet>
						<moduleInstanceId>$MODULE_INSTANCE_ID$</moduleInstanceId>
						<valueType>grid</valueType>
						<parameterId>Wave.th0.simulated</parameterId>
						<locationId>$MODEL$</locationId>
						<timeSeriesType>simulated historical</timeSeriesType>
						<timeStep unit="minute" multiplier="60"/>
						<readWriteMode>add originals</readWriteMode>
						<synchLevel>2</synchLevel>
						<expiryTime unit="hour" multiplier="24"/>
					</timeSeriesSet>
					<timeSeriesSet>
						<moduleInstanceId>$MODULE_INSTANCE_ID$</moduleInstanceId>
						<valueType>grid</valueType>
						<parameterId>Wave.s0bh.simulated</parameterId>
						<locationId>$MODEL$</locationId>
						<timeSeriesType>simulated historical</timeSeriesType>
						<timeStep unit="minute" multiplier="60"/>
						<readWriteMode>add originals</readWriteMode>
						<synchLevel>2</synchLevel>
						<expiryTime unit="hour" multiplier="24"/>
					</timeSeriesSet>
					<timeSeriesSet>
						<moduleInstanceId>$MODULE_INSTANCE_ID$</moduleInstanceId>
						<valueType>grid</valueType>
						<parameterId>H.simulated</parameterId>
						<locationId>$MODEL$</locationId>
						<timeSeriesType>simulated historical</timeSeriesType>
						<timeStep unit="minute" multiplier="60"/>
						<readWriteMode>add originals</readWriteMode>
						<synchLevel>2</synchLevel>
						<expiryTime unit="hour" multiplier="24"/>
					</timeSeriesSet>
				</timeSeriesSets>
			</importPiNetcdfActivity>
		</importActivities>

Page tree

SWMM (EPA) adapter

SWMM pre-adapter

Properties

Notes for users

System requirements

SWMM post-adapter

Properties

Notes for users

System requirements

GeneralAdapterRun Example Configuration

General

Start-up activities

Export activities

Execute activities

Import activities