Tools to convert, debug and - FEFlow

FEFLOW Data Tools –
Tools to convert, debug and modify FEFLOW import and export files
1. General information
Scripts for everyday data preparation work...
This collection of utilities had been created at WASY GmbH to help in the everyday work with
FEFLOW solving problems in the fields of
• data debugging
• data conversion
• data statistics
• data selection and extraction
Operations that would typically be done on a PC with standard spreadsheet software packages
can be performed with these tools without limitations of line numbers.
The tools are UNIX shell scripts. They are using the ‘awk’ and ‘nawk’ or ‘gawk’ command. ‘awk’
and ‘nawk’ come with the UNIX operating system. For ‘gawk’, please refer to the GNU software
distributions and consider the public GNU license. These tools offer universal possibilities of file
data operations.
Running on UNIX systems:
The FEFLOW Data Tools are directly executable on all UNIX systems with installed ‘awk’ and
‘nawk’ commands.
Running on WINDOWS systems:
Start the tools under an UNIX shell emulation program like the ‘bash’ in the CYGWIN package.
CYGWIN can be installed from the win32/cygwin directory of the FEFLOW DVD. No compilation
is necessary. The programs are the same for all hardware platforms. The FEFLOW Data Tools
are plain ASCII files. The user can read it to understand the functionality. You are invited to
adapt the tools to your specific needs. Hints for ‘awk’ programming finds in the ‘awk’, ‘nawk’ and
‘gawk’ manual pages.
Copyright and warranty
There is no kind of copyright on the FEFLOW Data Tools. WASY provides no software support
for these tools. There is absolutely no warranty on the correct function of the tools! If you use
third party software like UNIX shell emulation software you have to respect the licensing
conditions of this software.
UNIX and MSDOS files
It’s possible to read MSDOS files as well as UNIX files. The default program output comes on
UNIX machines with UNIX linefeed and on a PC with MS-DOS line feed. Using the ‘-msdos’
parameter on UNIX machines or the ‘-unix’ parameter on a PC you can change the output file

format. So you can use the tools to convert your files between the different platforms.
Help messages
about program usage and function come by typing the pure program name or the name with the
parameter ‘-h’. If you are using wrong parameters the program usage occurs.
Program usage basics
The UNIX typical syntax for program parameters will be used:
value :A simple value (e.g., file name) has to be enclosed with blanks. Write the
value without quotes.
-a :Parameter without values: You have to type it without a blank between the minus
sign and the parameter name.
[-a] :Parameters between brackets are optional.
-a | -b | -c :Vertical lines differ between alternative parameters. Only one of the
parameters ‘-a’, ‘-b’ or ‘-c’ can be used.
-a value :Parameters with a numerical value: You have to type it without a blank
between the minus-sign and the name but with a blank between the name and the
value. Write the value without quotes.
-a ‘string’ :Parameters with a string value: You have to type without a blank between
the minus sign and the name but with a blank between the name and the string. Write
the string with quotes.
value ... :List of values. The number of values is arbitrary. Between the values has to
be a blank.
The program output...
comes to stdout (into the calling window). So you have the possibility to observe the program
results.
The input files will never be changed. To write the output into a file you have to use the UNIXlike
redirections.
For example, a ‘bash’ or ‘sh’ user can write:
trp2pnt -f 0.01 test1_head.trp
Write to stdout (= output into the calling window).
trp2pnt -f 0.01 test1_head.trp > test1.pnt
Create and write a file ‘test1.pnt’. If the file already exists, the program overwrites the
file.
trp2pnt -f 0.01 test1_head.trp >> test1.pnt
Create a file ‘test1.pnt’ or append to the file if it already exists.

Further development of the FEFLOW data tools
WASY is collecting FEFLOW data tools, also user-developed tools. This pool will be published
on the following FEFLOW DVD’s. That’s why we are interested in your modifications and
developments. You are also invited to send us your critical remarks as well as your problems.
Please contact support@wasy.de.

2. Overview of the FEFLOW Data Tools
dar2pow
[-p ‘H’| ‘C’| ‘T’] [-id start_id] dar_file observation_point_id [observation_point_id ...]
dar2trp
[-p ‘H’| ‘C’| ‘T’] [-s stepnumber] dar_file
debug_pow
[-discard] [-ci ‘ID_condition_string’] [-cp ‘Point_condition_string’] [-o operation_string’] pow_file
debug_trp
[-discard] [-comment] [-c ‘condition_string’] [-o ‘operation_string’] trp_file
describe_pow
[-ci ‘ID_condition_string’] [-cp ‘Point_condition_string’] pow_file
describe_trp
trp_file
grid2trp
grid_file
mix_pnt+trp
[-s snap_distance] ascii_point_file trp_file
mix_pow
[-comment] [-discard | -merge] [-o ‘operation_string’] pow_file1 pow_file2
mix_pow_id
pow_file id_file
mix_pow_tab
pow_file tab_file
mix_trp
[-discard | -merge] [-comment] [-s snap_distance] [-o ‘operation_string’] trp_file1 trp_file2
opera_trp
[-o ‘operation_string’] trp_file1 trp_file2
ply_deldouble
[-comment] [-s snap_distance] trp_file
pnt2trp
[-sort] [-f factor] ascii_point_file
set_lin_id
[-id ID-value] ascii_line_file
tin2trp
[-sort] [-f factor] ascii_tin_file
trp2pow
[-id start_id] [-o ‘operation_string’] [-s snap_distance] definition_file trp_file
trp2pow_acc
[-t start_time] [-id start_id] [-o ‘operation_string’] definition_file trp_file

trp2pnt
[-f factor] trp_file
trp2grid
[-min | -max | -average | -sum ] [-x grid_x_origin] [-y grid_y_origin] [-w grid_width] trp_file
trp_deldouble
[-comment] [-min | -max | -average | -sum ] [-s snap_distance] trp_file

‘pnt2trp’ and ‘trp2pnt’
usage: pnt2trp [-sort] [-f factor] ascii_point_file
usage: trp2pnt [-f factor] trp_file
The data conversion programs ‘pnt2trp’ and ‘trp2pnt’ enable the ‘mis’-use of the ID in ASCII
POINT files (compatible to the ARCINFOÒ defined ASCII-Format) for point data exchange
between ArcInfo and FEFLOW. The function values of the triplet files can be scaled into the
integer ID and vice versa. In pnt2trp the option -sort activates the data point sorting and deletion
of multiple points with identical coordinate strings.
‘debug_trp’
usage: debug_trp [-discard] [-comment] [-c ‘condition_string’] [-o ‘operation_string’] trp_file
‘debug_trp’ provides basic spreadsheet functionality on triplet files. Operations will be performed
on all points or - if a condition_string parameter is used - on the selected points.

‘mix_trp’
usage: mix_trp [-discard | -merge] [-comment] [-s snap_distance] [-o ‘operation_string’]
trp_file1 trp_file2
‘mix_trp’ provides basic spreadsheet functionality on triplet files. Operations will be performed on
the points that are contained in two triplet files.
‘mix_trp’ is running a foreward loop along the data points in trp_file1 (reference points). At every
reference points the trp_file2 will be scanned in a foreward loop if a point lies in a circle with the
radius snap_distance around the reference point (corresponding point). The scanning of trp_file2
will be finished if one corrsponding point had been found. All operations to calculate the function
value of the output according the -o ‘operation_string’ refer only to a pair of reference and
corresponding point.
Using the -discard-Option all the reference points from trp_file1 without a corresponding point in
trp_file2 do not appear in the program output. The points from trp_file2 that are not a
corresponding point to the trp_file1 data do also not come to the program output.
Using the -merge-Option all points from trp_file1 and trp_file2 that are not in a reference point -
corresponding point pair will be written to the program output without any changes.
Using the –comment option the program appends a short comment to the output data line that
comes from a found pair of reference point - corresponding point. This comment output may not
be in a FEFLOW import data file. So you should use this option only to check the program
output.

‘dar2pow’
usage: dar2pow [-p ‘H’| ‘C’| ‘T’] [-id start_id] dar_file observation_point_id
[observation_point_id ...]
dar2pow extracts from the results file the timesteps and values of the defined Parameter (H or C
or T) for the defined obeservation points and writem them into a powerfunction file. The start_id
determines the first powerfunction ID written in the output file. This ID will be increased
automatically. The default ID is -999. If FEFLOW finds a negative ID-value then the following
power function will be placed at the next free FEFLOW-time function-ID. If FEFLOW finds a
positive ID in the imported powerfunction file, this ID will be used also in FEFLOW.
‘dar2trp’
usage: dar2trp [-p ‘H’| ‘C’| ‘T’] [-s time_step_number] dar_file
Using dar2trp you can generate triplet files for a specific time step. That’s usefull to analyze
differences between the FEFLOW results and measured values at the observation points. If no
-s time_step_number is defined the last timestep will be used as default.

‘mix_pnt+trp’
usage: mix_pnt+trp [-s snap_distance] ascii_point_file trp_file
This program is usefull if FEFLOW results or modell property data are to be exported into
ArcInfo. ArcInfo tables can read the resulting file using the ‘add’-command.
‘describe_trp’
usage: describe_trp [-c ‘condition_string’] trp_file
describe_trp offers the simplest statistical analysis on triplet files.

‘set_lin_id’
usage: set_lin_id [-id ID-value] ascii_line_file
The color of line background maps in FEFLOW will be computed from the LINE-ID. 4 colors are
used. They are defined using the ‘modulo’-operator on the ID: color=Line-ID % 4. Use set_lin_id
to change the background map color.
‘tin2trp’
usage: tin2trp [-sort] [-f factor] ascii_tin_file
Data from the ArcInfo TIN module can be exported using the ASCII TIN format. tin2trp converts
these data into the FEFLOW supported format. The Z-coordinate can be scaled to compute the
function value in the program output. This is a good basis for FEFLOW’s regionalization tools to
compute slice elevations or other parameter distribitions.

‘trp2grid’
usage: trp2grid [-min | -max | -average | -sum ] [-x grid_x_origin] [-y grid_y_origin] [-w
grid_width] trp_file
If triplets are to be converted into a quadratic raster grid you can use trp2grid. Further
conversions on the grid file may also be performed using the debug_trp program (e.g. from
Row/Column coordinates into the real world coordinates of the cell-center point).

‘trp_deldouble’
usage: trp_deldouble [-comment] [-min | -max | -average | -sum ] [-s snap_distance] trp_file
FEFLOW’s regionalization tools need input data without multiple values at the same location.
This can be achieved using trp_deldouble. Using different snap_distance values you can use the
tool also for data reduction purposes.
‘ply_deldouble’
usage: ply_deldouble [-comment] [-s snap_distance] trp_file
Multiple points in polygons are possible in the ASCII format but FEFLOW tools like the
supermesh filter or the JOIN method await no multiple points. There may occure different errors
and effects using multiple points. You should check your polygons using this tools before you
they are used in FEFLOW. Using the -comment-option and different snap_distance values you
can get an overview on the point densities in the input file.

‘debug_pow’
usage: debug_pow [-discard] [-ci ‘ID_condition_string’] [-cp ‘Point_condition_string’] [-o
‘operation_string’] pow_file
debug_pow provides basic spreadsheet functionality on FEFLOW powerfunction files.
Operations will be performed on:
- all selected points (selected by -cp ‘Point_condition_string’ , default: all points selected)
within
- all selected functions (selected by -ci ‘ID_condition_string’ , default: all functions selected)
Unselected points or functions will comes to output without any changes or - if the -discard
parameter is defined - they will be hidden in the output.
‘describe_pow’
usage: describe_pow [-ci ‘ID_condition_string’] [-cp ‘Point_condition_string’] pow_file
describe_pow analyses the seleted powerfunctions and powerfunction points and write out some
descripting and statistical information.
The ID_condition_string serves to select complete powerfunctions from the file. The
Point_condition_string serves to select a number of powerfunction points from the
powerfunctions selected by the ID_condition_string.
For all selected powerfunctions and their selected powerfunction points the analysis will be
applied.
A powerfunction in the pow_file is accesible by it’s ‘ID’. If no ID will be selected in the
ID_condition_string, all ID’s (resp. all powerfunctions) will be selected. The columns of the
powerfunction are accesible as ‘T’ and ‘F’. If no points will be selected using the T and F

variables in the Point_condition_string, than all points of the selected powerfunctions are
selected points (default). The condition may be defined by Boolean combinations (!, ||, &&) of
relational expressions build with ==, !=, , =, e.g.:’ID 200.0’
Example output of describe_pow gaug_curves.pow:
‘mix_pow’
usage: mix_pow [-comment] [-discard | -merge] [-o ‘operation_string’]
pow_file1 pow_file2
mix_pow looks for each powerfunction in pow_file1 if there is a corresponding powerfunction
with identical ID in pow_file2. For these common powerfunctions all data points from pow_file1
and pow_file2 will be merged and written out sorted by time. On the time levels and function
values operations can be defined in the operation_string that will be performed before sorting.
In the operation_string the user can access the time level values as variables named T1 and T2.
Function values can be accessed by variables F1 and F2.
Examples:
‘T2 = T2 + 12000.00’ : Time shift of powerfunction from pow_file2.
‘F1 = log (F1); F2 = log (F2)’ : Write logarithmized values.
Operations can use functions (e.g.: atan2, cos, exp, int, log, rand, sin, sqrt, ...see manual pages
for ‘nawk’). If no operation_string is defined no operation will be done.
If the -comment option is used, for every mixed powerfunction a second comment line will be
inserted.
If the -discard option is used, only the powerfunctions common in pow_file1 and pow_file2 will be
written to standard output. Otherwise also powerfunctions from pow_file1 without a
corresponding powerfunction in pow_file2 will be written to standard output without any changes.
The-merge option writes all powerfunctions from pow_file1 AND pow_file2. Only for
corresponding powerfunctions operation_string will be applied.

‘mix_pow_id’
usage: mix_pow_id pow_file id_file
mix_pow_id is a usefull tool to derive powerfunctions with different offsets from one given
powerfunction. For example you have the time-dependency of a floodwave as input
powerfunction and you wish to create powerfunctions of this floodwave adapted to different
positions of a river with different medium elevations (offsets): Then you put the elevations into
the id_file and the powerfunction into the pow_file - and as a result you get the shifted
powerfunctions for your different offset values.
mix_pow_id generates for each entry in id_file an power function with the ID from the id_file, with
time values from the pow_file and function values computed as the sum of the value in the id_file
and the values in the pow_file.
The pow_file must contain only 1 powerfunction. Comment lines at the header of the pow_file
can begin with ‘!’ or ‘#’.
In the id_file all lines with two entries will be used as a data line. Comment lines, empty lines or
the END-line are allowed if they have less or more than 2 entries.
Example:

‘mix_pow_tab’
usage: mix_pow_tab pow_file tab_file
Using mix_pow_tab you can convert your time-dependent data from database format (with
different columns for different timestages) into FEFLOW powerfunction file format with data pairs
.
mix_pow_tab generates for each data line in tab_file an power function with the ID from the 1 st
column in tab_file, with time values from the pow_file and function values from the columns 2 pp.
in the tab_file.
The pow_file must contain only 1 column with timelevel values. Comment lines at the header of
the pow_file can begin with ‘!’ or ‘#’.
In the tab_file the first line contains columns names. It will be skipped. The columns are: 1 st
column: ID column. Following columns: Data values for the timelevels defined in the pow_file.
Example:
‘trp2pow’
usage: trp2pow [-id start_id] [-o ‘operation_string’] [-s snap_distance]
definition_file trp_file
This program is usefull to generate output in FEFLOW’s powerfunction file format from point
measurement data files at different measure times. The definition_file defines in a list the used
time values and for every time value the appropriate triplet file in the following format:
! Comment lines beginning with ‘!’ are possible.
time1 trp_file_at_time1
time2 trp_file_at_time2
timeX trp_file_at_timeX
END
trp2pow works on all points that are contained in the trp_file. This file serves to select points
where further power function generation will be performed.

This program produces powerfunction output. For every data point that occures in the input
trp_file a powerfunction will be created. Therefore for every point runs a loop over all the triplet
files that are defined in the definition_file. If the point finds in such a time data file then a output
line of the format will be generated. T is the time value according to column 1 in the
definition_file. F is a function value that will be computed according the operation_string.
The operation_string defines the function value in the program output. It can define a
computation using the function value from the input trp_file that is represented as the characters
‘FR’ –reference value- in the operation_string. The function value of the current time data triplet
file will be represented as the characters ‘FT’ -time value- in the operation_string. The resulting
value for the program output will be represented as the character ‘F’ in the operation_string.
Example1: Resulting value is the reference value plus the time dependend values: ‘F = FR + FT’
The reference data will be used as offset for the time dependent data.
Example2: Resulting value is the time dependent value shifted and scaled: ‘F = (FT + 0.36) *
1000.0’
The default value of operation_string is ‘F = FT’. So the reference data will not be used and the
time dependent data will be used without any changes.
The -id start_id option defines the first power function ID. The default value is -999. The power
function ID will be increased automatically. The -s snap_distance option defines the radius
around reference points to identify ‘identical’ points in the time dependent triplet files. The default
value is 1.e-6.
Example:
‘trp2pow_acc’
usage: trp2pow_acc [-t start_time] [-id start_id] [-o ‘operation_string’] definition_file trp_file
trp2pow_acc is very similar to trp2pow. The difference consistes of two points:
The time levels in the definition file and the function values defined in the files
trp_file_at_time_xxx will be interpreted as time step lenght and as value change at this
timestep. (In trp2acc these data will treated as absolute time levels and absolute physical
values at the time.)
The initial time comes from the input parameter -t start_time and the initial value comes from
the input trp_file.
The resulting powerfunction data will be computed in the following way:

T is the accumulated time value. It will computed starting from the start_time and will be
increased by every time value in the definition_file:
T = start_time + time1 + time2 + ... + timeQ (for Q-th power function entry)
F is a accumulated function value. It starts with the reference value from the input trp_file. For
every timestep it will be increased (plus-operation) by the current timestepvalue that will be
compzted according the operation_string:
F = reference_value + F1 + F2 + ... + FQ (for Q-th power function entry)
Example:
‘opera_trp’
Usage: opera_trp [-o ‘operation_string’] trp_file1 trp_file2
opera_trp is usefull to perform operations (e.g. difference computation) on point data exported
from the FEFLOW mesh. These data will be written always in the same order (the internal
indexing, visible in the mesh inspector).
opera_trp works on 2 trp-files with the same points (identical coordinates but arbitrary function
values) in the same order. It takes two data lines from file 1 and 2 and writes out the coordinates
from file 1 together with the value F computed by the operation string.
The operation_string can define a computation using the function value from trp_file1
represented as ‘F1’) or from the first corresponding point in trp_file2, (represented as the
character ‘F2’.)
- Operation examples with a constant value, e.g.:
‘F = F1+10.0’ ‘F = (F1+F2)/2.0’ ‘F = 2.0*F1 + F2’
- Operation examples with functions (atan2, cos, exp, int, log, rand, sin, sqrt,
...see manual pages for ‘nawk’), e.g.:
‘F = log (F1-F2)’ ‘F = 2.0 * sin (F1 - 3.1415)’ ‘F = sqrt(F1*F2)’
The default value of operation_string is ‘F = F1’, which is identical with no change of the value of
the reference point.

‘grid2trp’
usage: grid2trp grid_file
grid2trp converts an grid file in the ESRI grid file format (ASCII) into FEFLOW triplet formatted
output [x y f]. The ‘nodata-points’ will be hidden in the output. All other data points in the grid will
the written out with point coordinates at the centerpoints of the grid cells. The program is easy to
adapt to other grid file formats.
Example:

Data Conversion Tools
Tools to convert data between ASCII-files and ESRI-shape files + AUTOCAD DXF
files
1. Introduction
The Data Conversion Tools are programs written in C reading a file without changing it. If you
don’t specify a output filename using the ‘-o’-option the output filename will be generated
automatically from the input filename or the output is directed to stdout. The data conversion
tools can be found in the /bin directory. Typing the name of the conversion tool
without a specified input file, a help text is displayed explaining the usage of the tool.
2. Converting ASCII-files and ESRI-Shapefiles
Source Tool Destination
ESRI shape file (polygon) shptoasc ASCII polygon file (*.ply)
ESRI shape file (line) shptoasc ASCII line file (*.lin)
ESRI shape file (point) shptoasc ASCII point file (*.pnt)
ESRI shape file (point) shptotrp Triplet file (*.trp)
ASCII polygon file (*.ply) plytoshp ESRI shape file (polygon)
ASCII line file (*.lin) lintoshp ESRI shape file (line)
ASCII point file (*.pnt) pnttoshp ESRI shape file (point)
Triplet file (*.trp) trptoshp ESRI shape file (point)
AutoCAD exchange file (*.dxf)
(NOTE: not compliant with recent
*.dxf file format)
dxftoasc ASCII polygon file (*.ply)
ASCII line file (*.lin)
ASCII point file (*.pnt)
ASCII text file (*.ano)
ASCII file (*.plx, *.lin, *.pnt, *.ano) asctodxf AutoCAD exchange file (*.dxf)