Purpose

Below are some modeling methods and information for WaterGEMS beyond what is provided in the product documentation.

File Types Explained

Model Data

WTG.MDB

The model datastore in a Jet format (as used by MS Access).  It contains one model dataset and all the data for the modeling elements.  It is a self-contained file that contains all the data required to make a model run.  All other file types can be deleted without harming the datastore, and the model will still function.

WTG

A WaterGEMS Project file containing project data in an XML format.  There are many components to it, however some of the more important ones are:

• Element Symbology Manager Data:  Annotations, Color Coding, Zoom Display Levels etc.
• Project Options set in the Options->Project Tab
• Query Definitions specific to that Project

DWH

A WaterGEMS drawing file.  It's primary purpose is to speed up the opening of model files inside the Stand-alone envrionment with pre-saved drawing data.  It contains the last saved model element drawing display coordinates, symbology (eg. Color, Line Thickness Multipliers) and decorations (eg. Flow Arrows).   In this fashion, WaterGEMS does not need to refresh the drawing during the opening of a model.  Its contents are read directly into memory, and does not participate in the active session itself.

Saving a WaterGEMS file in the Stand-Alone environment triggers this file to be regenerated, and is usually the slowest part of the save process.

During a model open, if WaterGEMS detects that the DWH is out-of-sync with Project, or is not present at all, this will trigger WaterGEMS to refresh the entire drawing, and a dialog for the Synchronise Drawing process will appear during the model open.

Results

RPC

This is a results report file, which contains the information seen in the Calculation Summary Dialog.

OUT

A standard calculation output file from Hydraulic or Water Quality model simulation types.  This contains a data table that lists the corresponding results for each modelling element, for each model timestep.  The size and contents of these files are governed by the selected Calculation Options, particularly:

• The report timesteps; and
• The element selection set used for results reporting

Others

Note that simulation types other than Hydraulic or Water Quality simulation types use different file extensions.

Application Settings

XML Files

Most WaterGEMS user settings and customisations are contained in XML files. These contain things such as:

• Standard Units;
• Toolbar and Dialog positions and docked status

See WaterGEMs XML Guide

WaterGEMS File Management

Model Data

When a WaterGEMS model is opened, the following actions occur:

• The *wtg.mdb and *.wtg file are copied from the Project Directory (ie. the directory in which the model is saved), to the Working Directory, which is virtually always the default temporary file directory in Windows.   In Windows 2000/XP this is usually C:\Documents and Settings\{Profile Name}\Local Settings\Temp\Bentley\WaterGEMS.  The files are renamed to appear like "temporary" files, however they are still the same file types as in the Project Directory.
• The *.mdb is opened and read from the Working Directory
• For the stand-alone interface, the *.dwh file, if present in the Project Directory, is examined.  If it is present, and correlates with the last save time for the model datastore, its data is used as the initial drawing data for the WaterGEMS session drawing.  If not, the drawing is refreshed, which is a similar operation to the Tools->Database Utilities->Synchronize Drawing menu command.  In an active WaterGems session, drawing data is stored entirely in system memory, and no temporary files are used for it.
• For other interfaces, (ArcGIS, AutoCAD, Microstation), the corresponding "drawing" file (ESRI personal geodatabase|*.mdb, AutoCAD drawing file|*.dwg, Microstation drawing file|*.dgn) has an inspection process similar as for inspection of the *.dwh file.  The exception is that if the drawing file for those interfaces is not found in the location expected, the user will be prompted to specify a new file name so that new drawing data can be created.
• The *.wtg file is read to populate other session data, such as Project Options, Layer Symbology Definition, Query Definitions, the current active scenario, whether or not calculation results were available etc. etc.  However, if the *.dwh file was used for the initial drawing data, the *.dwh file data overrides any conflicting settings in the *.wtg file for the Element Symbology Manager.

When a WaterGEMS model is being edited:

• Changes to the Working Directory model or project files are made as and when records are updated.  However, no changes are made to the Project Directory copies are made.
• In the ArcGIS interface, the related Geodatabase Feature Classes are updated in real-time in the associated Geodatabase, as and when Feature Geometries are changed.  No temporary copy of the Geodatabase is used.

When a WaterGEMS model is saved, the following actions occur:

• Backup copies are made of the Project Directory files.
• The Working Directory *.wtg.mdb and *.wtg files are copy and pasted into the Project Directory, replacing any previous versions.
• The *.dwh file is created from scratch, based on the current drawing displayed in the active WaterGEMS session.

Results

Result files are treated similarly to model data files, but with some subtle differences:

• During model open, result files are moved, instead of copied, from the Project Directory to the Working Directory.  The exception is for projects which have a Custom Results Directory specified.  In this instance, an attempt is made to move the model's corresponding result files from this location, if they exist,
• The Working Directory result files are updated as and when model calculation engines are run.
• During a model save, results files are not copied or moved back to the Project Directory.  This action only happens on model close.

Common Problems and Work-arounds

Failure to Save

Sometimes a runtime error will occur during the model save process, and the model will "appear" to not have saved, with no apparent way of saving the model.  Generally these errors occur during the generation of the *.dwh file in the Project Directory.  However, the copy and paste operation of the *.wtg.mdb and *.wtg files from the Working Directory to the Project Directory generally always completes, which is the only thing important in these instances.

Solution

The important files, the *.wtg.mdb, and *.wtg files have saved, although the *.dwh file is often corrupted in these instances.  After a "failed" save, the user can simply close the model (choosing not to save in the 2nd instance), delete the *.dwh file from the Project Directory, and reopen the model.

For added assurance, a user can compare the timestamps between the Working Directory and Project Directory copies of the *.wtg.mdb and *.wtg files to ensure they are the same.  If they are not, the user can manually copy, paste and rename the files from the Working Directory to the Project Directory.

Application Crash / Abnormal Termination

There are two problems in these instances, one obvious, and one not obvious:

1. Model edits were not saved; and
2. The Working Directory copy of the model was not cleared.

Solution

The solution can treat both symptoms.  Model edits are recoverable because the Working Directory copies of the model files are updated as and when edits are made.  The user can go into the Working Directory and manually copy, paste and rename the files into the Project Directory to retrieve his/her model edits.

"Out of Memory" on Model Open

This error indicates a lack of space of the volume (usually C:) that contains the WaterGEMS Working Directory.  Often, this is caused by an accumulation of WaterGEMS abnormal application terminations.  This progressively accumulates copies of models in the Working Directory, eventually causing a lack of free space.

Solution

Close any open WaterGEMS session, and go into the Working Directory (not the Project Directory).  Clean all files out of this directory.

No Element Data Showing in Properties Dialog

In this case, it is likely that the element is still present in the Drawing, and the user can still do a Find for the element ID/Label, but there is no corresponding record for the element in the model data store.  In this case, the model will not be able display data for an element that does not exist in the model data store.

Solution

Run the Tools->Database Utilities->Synchronise Drawing menu command to update the drawing to show elements in the model data store.

Color Coding/Symbology different from Properties Dialog values

This is another variation on the WaterGEMS Drawing being out-of-sync with other model files.  Usually this occurs with results files.  Either:

1. The results files were not found during model open.  However, the application will still load the previously saved DWH file that may have been showing the symbology for the last model run.  Further evidence of this is the lack of results in the Properties Dialog for model elements.
2. Drawing Auto-Refresh did not occur for either a model rerun, or the Active Scenario changed to another scenario.

Solution

The corresponding solutions are:

1. Either re-run the model, or close the model, locate the results files and place in the location that the WaterGEMS project expects to find them during model open.
2. Activate the View->Auto-Refresh menu option.  The user can also manually refresh the drawing using View->Refresh Drawing (F5).

Element Results show in the Properties Dialog, but not in the Calculation Summary

In this case, although the *.out file is present, the *.rpc file is missing.

Solution

The safest solution is to close the model, and delete *.out files that have no corresponding *.rpc files, re-open and re-run the model.  In addition, this problem is more prevalent when older copies of the model are still present in the Working directory, and the user should delete these copies.