River & Flood Simulation Tools

EnSight is not just used by the typical CFD engineer at a large automotive companies. It is used across a wide variety of industries, specialties and disciplines. In this example today, EnSight is used in the Civil Engineer community for analysis and visualization of River and Flood Simulation results.

We started by taking 2 such solvers (River-FLO and FLO-2D) and created a translation Python script which would convert these formats into EnSight Case Gold files. Key benefits of this data in EnSight are the ability to take clips and graphing values along the clip; changing that clip interactively and seeing the graph update is very powerful; using the calculator to quantify the area affected by different key aspects; how much area is under more than 2 feet of water, or what the temporal max of depth to get an overall envelope of the flood, etc.

We then expanded this capability to other solvers called “MIKE21 Classic” and “MIKE21 FM”. Again, we wrote a python routine to translate these formats into EnSight Case Gold format.

The following short summary on the four different translation routines, along with two accompaning user defined tools to handle Aerial Photo projection/alignment automatically, as well as customer time annotation features.

RiverFLO-2D Translation Routine

This solver (http://www.flo-2d.com/products/riverflo-2d/) generates both a “.FED” file, and a series of “.EXP” files. The .fed file contains the geometric mesh. There is one .EXP file for each timestep, with a fixed specification of U & V velocities, water surface elevation, depth, and elevation as a per node variable. The time value is actually written as part of the .EXP filename, so the python routine parses that out and converts it into a time that EnSight can handle. Now, the time unit for the velocity is in seconds, so naturally you would want to specify time in seconds for EnSight. However, the time range for simulations is on the order of days, so reporting it as seconds is awkward. The python routine has a toggle to specify how the time is actually represented in the .case file so that graphs and integrations with time make more sense. By converting to anything other than seconds does mess up the pathline operation, but as that is not used for these models, it is okay.

Each of the translation routines take the incoming file and convert to EnSight Case Gold files. This ensures that the translation only occurs once. Each subsequent load of the model, the user can directly load in the .case file. In addition, items like changing timestep now happen very quickly, and provide the optimal operation of the model results in EnSight. To keep directories as neat and tidy as possible, I create an “ensight_files” directory, and place all of the .geo and variable files there.

The datasets are all 2D elements. They typically lie in the XY plane, with the elevation given as the Z coordinate. Timesteps are typically a few hundred, and dataset sizes are typically 200k to 500k. All of the variables are nodal, and exist for the 2D parts only. As detailed further below, models are originally prescribed in “global” coordinates. There are too many significant digits for EnSight to handle this properly, and thus this routine converts the model into “local” coordinates. The offset between local and global coordinates is referenced in the constant variables “Xref” and “Yref”.

Users will take advantage of the isosurface and isovolume tools in EnSight to restrict and create new parts. Calculator quantities including the EleSize * Water Depth will result in volume quantities like how much water volume is in each element. Querying variables over time, or creating clips and graphs on the clips over time are of significant help in analyzing the flow rates, distributions and temporal information. Use of the TempMean and TempMinMax functions allow the user to see an envelope of flood depth as a great indication of maximum depth reached over time.

To facilitate the time reporting (see below), there are constants per timestep written in the form of days, hours, minutes, seconds so that we can create the appropriate labels for time.

FLO-2D Translation Routine

This solver (http://www.flo-2d.com/products/flo-2d/) is fairly similar to the RiverFLO-2D in concept. There are a different set of files written with different (but conceptually similar) information. Here, the solver generates several files with the following suffixes: _CADPTS.DAT, _FPLAIN.DAT, and _TIMDEP.OUT. Here, the X & Y coordinates (nodal positions of the grid) are stored in the _CADPTS.DAT file, while the connectivity and elevation (Z coordinate) are stored in the _FPLAIN.DAT file. Using these two files, the python routine creates the .geo file for EnSight. The _TIMDEP.OUT files contain U and V velocity values and Water Depth. These, along with the Z coordinate as elevation are written to per node variable files.

As with the above, the python routine converts this format into EnSight Case Gold format, and saves this into a <casename>_ensight_files  directory. The routine only has to be run once per dataset, with any subsequent load of the dataset done directly as EnSight Case Gold file. As with the above format, the time unit control is provided in the Python so that the user can get the most useful unit for time. As above, reference values for the offset between global and local coordinates is kept track of via the Xref and Yref constants.

MIKE21_Classic Translation Routine

Details about the solver MIKE21_Classic (sometimes referred to as MIKE21C can be found here (http://www.mikebydhi.com/). With this solver, it writes out an ascii .asc file output. This is a structured dataset, with nodal data written to a single file for all variables and all times. Header information in the file indicates grid size, position, variable count and names. The python routine converts through this structured information, again generating EnSight Case Gold Format files for all of the information. As with the above routines, the information is placed into an “ensight_files” directory. The bulk of this python is simpler than the other translation routines, but has slightly more complex logic for strides, skipping, and structured nature of implicit information. The conversion routine here can take 15-20 minutes depending upon the amount of variables and timesteps.

One nuance with this format, is that the order of writing the static data is different to that of the time varying (dynamic) data. Therefore, a toggle has been provided in the GUI for assuming that the static data is South to Noth & East to West, rather than the order of the dynamic data (North to South; East to West).

As with the above datasets, time unit specification is important as well the references between global and local coordinates. The same convention is followed here as well to provide a similar setup of information in EnSight.


MIKE21_FM Translation Routine

Another solver in the MIKE21 family is the MIKE21_FM (sometimes called MIKE21FM or just MIKE21) (http://www.mikebydhi.com/), the “FM” here stands for Free Mesh. In this triangular unstructured grid solver configuration, information is written on out per element format (different to previous 3 formats). The files associated with this format are the .mesh and *.xyz files. What makes this format tricky is that during the run of the solver, it renumbers and reorganizes the element IDs, and when it writes the elemental result information out, it does so not by element number, but by location in 3D space. Therefore, there is no direct explicit writing of the variable with the elementID in which it exists.

Conversion of the .mesh file into an EnSight .geo file is quite straight forward. However, getting the variable information from the .xyz files back assigned to the elementID was not. I have gone around quite a bit with different methods to achieve one which was reasonably quick. In the end, some smart python loop logic allowed me to this search & find fairly quickly (takes about 40 minutes for 700k element model).

As with the other formats, data gets stored into “ensight_files” directory, and the translation only needs to happen once. Once done, users automatically get the data loaded into EnSight via Case format, and performing standard operations in EnSight from then on out. The same “Xref” and “Yref” values for local to global translations are stored as constant variables allowing users to either report true global positions or to use aerial photo alignment accurately. Time values are also extracted from the filename of the .xyz file, with the appropriate conversion to Analysis_Time information as well as a series of constants to be used for time annotation.


Global vs. Local Coordinates

Typical of this market, the model coordinates are provided in global coordinates. The model may be of a 25 square mile domain in California, but the coordinates are given relative to US reference several thousand miles away. These raw global coordinate values are too large in significant digits for EnSight to handle. So, each of the translation routines find the minimum X and Y location of the model and subtracts this off from each coordinate so that EnSight can handle the coordinates correctly (albeit as “local” coordinates). As a result, I create two model constants (Xref and Yref) which denote this difference between global and local coordinates. Users can then add this to any X or Y location to get back the global coordinates. In addition, the absolute coordinates are typically needed for Aerial Photo Alignment (see next tool). So, having these Xref and Yref constants are required for the aerial photo alignment.


Aerial Alignment Tool

Typical in this market is to utilize GIS type information within the display of the simulation information. As these are geographical simulations, having geographical information to provide context to the location are typically used. Although we can’t utilize most GIS information, we can utilize the texture map capability with aerial photos to give some sense of context. These photos pose a couple of initial “issues”, but were overcome with only a minor amount of work. Firstly, the aerial images are typically much higher resolution that EnSight can handle in the texture map. Aerial photos were typically 21k x 30k pixels. At most, EnSight can handle only 8k x 8k images, and depending upon your graphics card, a more typical limit is closer to 4k x 4k image. So, users must scale down the image to be less than 8k x 8k or 4k x 4k depending upon graphics card. The second issue is that of alignment of the image onto the geometry. Using our typical “use plane tool” to map it “by eye” is not sufficient. However, in this segment, the aerial photo image is typically accompanied by a “world coordinates” file. This word coordinate file describes how the pixels map to physical space (their width, length, orientation and position). This file is quite straight forward, and can be used to provide the appropriate S & T values in EnSight. So, I created a very small Python routine which asked the user for the Image file, World Coordinates file, and the Xref & Yref EnSight offsets (see previous). With this information, we can read the World Coordinates file and correctly create the S & T values for the image projection. The result is an immediate, exact projection of the aerial image onto the model.


Time Notation Tool

One interesting side note about this market segment is how time is best reported or annotated. In the normal CFD world, we annotate just the “Analysis_Time” field in seconds, and all is fine. Apart from having long timescales which denote using non-consistent Analysis_Time in hours or days, the user also does not want just this single string used for annotation. The annotation for time should roll up through seconds until it hits 1 minute, then the seconds reset back to zero, while the counter is bumped up on minutes. Same process for minutes to hours, hours to days, days to months, and months to years. Ideally what the user wants to see is a time annotation which looks something like :



So, there is a python tool which takes the constants written out from the above mentioned translation routines and creates the appropriate annotation string like above. This worked great for the end user to be able to see a more practical display of the current time than just “Analysis_Time”.


The current version of these River/Flood Analysis User Defined Tools can be downloaded below. This includes all four translation routines, time annotation tool, and aerial photo alignment. Should there be any questions, please do not hesitate to contact CEI.

Updated Toolset on 31-May 2012 for Command Record capability and Help Documentation

Updated Toolset on 14-Aug 2012 for TUFLOW translation routine & basic Triad tool (change triad labels from xyz to E,N,Elevation)

Updated Toolset periodically during Sept/Oct/Nov for robustness, handling of more variations of datasets and explicitly exporting out elevation variable. Latest update (04-Dec) contains updates to MIKE21_FM routine to tolerance variable locations not within element centroid (alternative search).


Click here to Download current Flood Simulation Toolset

You can view a tutorial on using these particular tools within EnSight here: