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 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.
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
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
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.
The well input is an ascii file with the following format:
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
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
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
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.
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.
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.
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.