Getting started with IWFM TRACK

In the following paragraphs we will show the minimum steps to run the particle tracking algorithm.

First, there is a rather time consuming preprocessing step to prepare the required files. 

Then, for each particle tracking run two additional input files are needed.

Preprocessing

Preprocessing involves two steps.

Run the IWFM

First we have to run IWFM to generate the groundwater flow field that particle tracking is using.
At the moment there is only one (but very important if you live in California) IWFM model the C2Vsim. There are few different versions of C2Vsim. IWFM TRACK is based on the newest fine grid version which is based on IWFM version 2015 code. You can  obtain a beta version from here.
Guidelines on how to run C2Vsim are beyond the scope of this tutorial, yet running it is trivial. Depending on the workstation this may take up to 6 hours. It is important to make sure that the groundwater flow field is printed as hdf output.

Gather data

The second step is to gather the required data and write out the input files for IWFM TRACK. For this task we use R.

This step involves the following R command

 source("Preproc.R")

In the first 16 lines of the Preproc.R script the user has to define 3 paths. There are explanations in the script. Once those paths are set, simply run the script to generate the PartTrackData.h5 file. This script takes few minutes to run.

Prepare standard input files

The following sequence of R commands prepare the input files that have to be generated only once per model run.

setwd("Path/of/Rwrkspc") # Sets the directory where all the R scripts and required files are 
source("iwfm_funct.R") # loads R functions that are related to iwfm 
D <- iwfm.loadData("PartTrackData.h5") # Loads the hdf5 file that was generated in the previous step 
iwfm.writeData("XYfile.dat",D$XY[,]) # Write the xy coordinates 
iwfm.writeData("MSHfile.dat",D$MSH[,]) # Write the element indices 
iwfm.writeData("STRATfile.dat",D$STRAT[,]) # Writes the Z coordinates for the xy nodes 
iwfm.writeData("NRMLfile.dat",D$NRML[,]) # Writes the xy and normal direction of the xy flow field 
iwfm.writeData("FACEZfile.dat",D$FACEZ[,]) # Writes the z coordinates of the points where the horizontal flow field is defined
iwfm.writeData("BCfile.dat",D$BC[,]) # Writes the coordinates of the xy locations where the vertical flow field is defined
iwfm.writeData("BCZfile.dat",D$BCZ[,]) # Writes the coordinates of the Z location where the vertical flow is defined

The current version of particle tracking operates on a steady state field (at least the c++ implementation).

Therefore we have to average the flows. To calculate average flows we can use the following R function:

simTime <- iwfm.SimTime()
D <- iwfm.AverageVelField(ISOdate(2005,10,31), ISOdate(2015,9,30), D, simTime)

The above command averages the flow field from 10/2005 to 9/2015. The variable D was loaded in the previous set of commands. Note that the above line overwrites D. Therefore to calculate an average field for another period we have to reload the entire D variable. One could assign the output of iwfm.AverageVelField to a different variable. However D containts a huge amount of data ~1.5GB and its not recommended to keep unnecessary copies of this variable.

Another possibility is to use selected months instead of a range. 
First examine the output of the iwfm.SimTime() and decide which ids you should use.

For example, to average the values of all April months from 2005 to 2015 do the following:

IDS <- seq(from=379, to=499, by=12)
D <- iwfm.AverageVelField_IDS(IDS, D)

 Similarly to the previous inputs we print the magnitudes of horizontal and vertical velocities as

iwfm.writeData("HFLOWfile.dat",D$HFLOW[,])
iwfm.writeData("VFLOWfile.dat",D$VFLOW[,])

These two files have to be generated every time we wish to use a different averaged velocity field.

Prepare input files

The following files are required for each particle tracking run.

Well file

The well input is an ascii file with the following format:

Nwells

X Y Depth ScreenLength Year Month Day

Where Nwells is the number of wells to be simulated. Then repeat at least Nwells times the next line which includes

X and Y coordinates, Depth, which is the distance between the ground surface and the top of the screen and ScreenLength is the screen length. The units are are in meters

For example:

4
554756 4497000 20 50 2015 8 1
566343 4414078 10 35 2015 8 1
697362 4156498 5 30 2015 8 1
752641 4024654 10 40 2015 8 1

Configuration file

Last the program requires a configuration input file. The configuration file contains variable names and values

A short list of some of the variables is the following:

XY=path\to\XYfile.dat
MSH=path\to\MSHfile.dat
STRAT=path\to\STRATfile.dat
NORMALS=path\to\NRMLfile.dat
FACEZ=path\to\FACEZfile.dat
HFLOW=path\to\HFLOWfile.dat
VFLOW=path\to\VFLOWfile.dat
BC=path\to\BCfile.dat
BCZ=path\to\BCZfile.dat
WELLS=path\to\welldataVS.dat
OUTFILE=path\to\streamlines.dat

The variable names must be exact as shown and they are case sensitive. To see a full list of the variables that can be set at run time, execute the code as

.\iwfmTrack.exe

You can also execute with the option -h to get a short help or -v to get information about the version.

Run the code

Finally, once the inputs are all set you can start the particle tracking by executing the following command under windows powershell

.\iwfmTrack.exe -c config.dat 

where config.dat is the configuration file.

Output

There are four options associated with the output of the code. The most important is the OUTFILE variable which is the file where the output of the code will be printed.

• ENDPNTS if set to 1 the output will print only the exit points of the streamlines. This is useful if one wants to delineate the source area of a well.
• PNTPRECISION sets the number of digits after decimal point for the coordinates and the age.
• VELPRECISION sets the number of digits after decimal point for the velocity.

The format of the output file when ENDPNTS=0, which is the default value, is the following:

The first line is a single number with the number of printed streamlines, which is a function of the number of wells and the number of streamlines per well.

Nstreamlines

Eid Sid exitflag Nsteps

X Y Z VX VY VZ AGE (Repeat Nsteps times)

Where Eid is the id of the well, Sid is the id of the streamline. The pair Eid, Sid defines a unique streamline. exitflag is an integer that determines the reason why the Eid, Sid streamline stopped, and Nsteps in the number of steps for this streamline, which varies for each streamline.

The next line is repeated Nsteps times and containts the following info

X,Y,Z are the point coordinates, VX, VY, VZ are the velocities on that point. AGE is the time since the start of the particle and shows the age of water at that point.

Post processing

The post processing is not a standard procedure. Nevertheless visualizing the velocity field is not only interesting but fun also.

At the moment of writing we provide a digital asset that can be used for visualization with Houdini

Under the hou folder of the repository there are two files. The file *.hdanc is the digital asset definition, while the *.hipnc is the file that can be opened with houdini.