WaterSimDCDC Version 5.0 Model and Application Interface (Draft 8/15/11)

Model Description | API Description | Documentation and Source Code

Introduction

WaterSim is a regional water supply and demand budget model for the Maricopa Active Management Area (AMA) that that simulates the dynamics of watersupply management at both the regional and local water provider level. Version 5.0 of WaterSim results from over 5 years of research on the dynamics of water mamangement within the region. Each new vresion has added more complexity to what is an extremely complex system of regional water management and policy development. Though this version of the model expands the number of systems and management options for the region, there are still systems for which the model does not address or only address in a fairly simple fashion.

This site provides access to the Version 5.0 WaterSim model and a .Net Application Interface to the model. Documentation for this version of the model is provided through this site. Links to articles that describe various aspects of this model are included. A diagram of the provider level urban systems model is provided. Also a reference for the API is also provided. For questions about the Model itself contact David Sampson [dasamps1asu.edu], for questions about the interface or current research using WaterSim contact Ray Quay [ray.quayasu.edu]

Model Description

WaterSim is a regional water supply and demand budget model for the Maricopa Active Management Area (AMA) that runs at a annual interval and is able to simulate water supply and demand for the AMA for up to a 75 year period. The model consists of several sub models which work together to annually 1) simulate River Flows and reservoir management for the Colorado and Salt Verde River systems, 2) allocate available surface water to each of the AMA’s water providers based on their surface water rights and estimate groundwater pumping, 3) account for flow of water through each providers water supply deliver and wastewater collection systems as well as reclaimed and effluent reuse, 4) and account for groundwater pumping and recharge for each provider. Version 5 of the WaterSim model is implemented in a Fortran based COM based unmanaged code module, WaterSimDCDC_model.dll. This model is designed for speed and encompasses a high level of complexity that represents the dynamics of water supply and demand within the AMA.

The Model relies on a large number of data files. These files must be located in a subdirectory titled App_Data, which can be located in any directory (see the App_Data.zip file). At this time we are not supporting any modification of these data files. The format of these files is very rigid and any modification will cause the model to fail to start. In the future access to these files will be provided through the interface.

API Description

The API is a .Net C# managed module that provides access to the WaterSIm Fotrran model (WaterSImDCDC.model.dll) through several input / output parameters and model control routines. The primary classes for creating and instance of the model are WaterSim and WaterSim_DB. The API also provides a set of routines to facilitate data retrieval from the model , and database storage and retrieval of model input and output data. There are two main types of parameters, base parameters and provider parameters. Input base parameters are read / write integer parameters that control the initial state of the model before it runs and primarily affect regional state factors. Once the model has started a simulation, these parameters cannot be set until the simulation is complete or a new simulation is initialized. Output parameters read only integer variables that report that state of regional factors after the model has executed a one year simulation. Provider input parameters are read write routines that send or receive an array of integer values to or from the model with each array representing a state factor for the water providers and each value in the array representing a different provider. Provider output parameters are read routines that represent state factors for each provider after the model has run a one year simulation. A structure, ProviderIntArray, is used to facilitate creation and passing this array data to and from the model.

The model control routines are used to setup and execute simulations using the input parameters to set the state of the mode and the output parameters to report results. There are three basic types of control routines, those the initialize a simulation, those that execute a annual or multi year simulation, and those that close the simulation. A typical simulation would consists of the following:

One of the purposes of the API is to insure that input into the model is within the allowed range for each parameter and in the correct format. Each input and output parameter has its owned declared property. These can be used to send and receive model data. All the input parameters perform range checks on all data passed to the model, and will throw an exception if values are outside the allowed range. Try/Catch structures can be used to trap these exceptions and retrieve error messages.

The API model also provides a dynamic method for sending and receiving parameter data and performing range checks before sending data. All input and output parameters are managed by an instance of a ModelParameterClass. This class manages the flow of data in and out of the model, as well as the range checking of this data. Output from the model is designed to be as fast as possible (no range or error checking) while input to the model is designed to insure only valid data is sent to the model. The ModelParameterClass provides rangecheck routines that can be used to check if values are within a parameters range before trying to actually send the value to the model.

The ModelParameterClass object for all parameters are in turn managed by a ParameterManagerClass object created by the WaterSim class, which provides a means to more dynamically access model parameters. For examples the ParameterManager provides access to ModelParameterClass object using enum values (a different one for each parameter) and provides iterators that allow access to parameters using a foreach() loop structure.

Documentation and Source Code

Tester Project - Source files are provided for an example program, WaterSim Tester. All the files needed to compile and run this project can be found in the Project Zip file, including the model and API .dll files and all the data files.

API Source - Source files for the API source can be found in the WaterSIM_API source zip file.

Version 5.0 Paramters ver 3.xlsx - This spreadsheet provides a description for each of the Model Paramters accessible throught the API. Information includes the API property name and eModelParam, units, and range. This spreadheet also provides some basic information on the model input files. Thsi file can be found in the Documentation zip file.

Visio-CityModel_NewLabels.pdf - This file provides a diagram of the provider urban systems model including the Model Parameters available through the API. This file can be found in the Documentation zip file and is available for viewing through the online documentation

Documentation.chm - This is a windows help file that provides the same API documentation that can be found in the online reference. This can be found in the Documentation zip file.

Articles - Several articles can be viewed and downloaded through the online documentation. These provide further documentation of WaterSim as well as examples of its use.


 

Note: The WaterSim Fortran model has been developed over a period of time to serve a number of research purposes. The current model API only exposes a small number of the model functions, with a focus on water supply and demand policy.