RES to RES

From Tuflow
Revision as of 10:57, 14 January 2021 by Pavlina Monhartova (talk | contribs)
Jump to navigation Jump to search

    Introduction

    This utility performs a variety of operations on the TUFLOW 2D outputs. Valid formats are .xmdf (as of utility version 2012-10-AC) and .dat files. This page is split into two section, utility operations (e.g. maximum, difference etc.) and general options. The general options can be used regardless of operation being performed. The table of contents can be used to jump to a desired operation.

    Operations

    The section below contains a list of the operations that the utility can perform. One of these operations must be specified or the utility will generate an error.

    Max

    Input Switch: -max
    Description
    This can be used to extract the maximum from a number of input datasets. Any number of input files can be specified. If a maximum folder exists in an .xmdf file for the type specified, this dataset will be used, for dat files use -t99999 to use the maximum data in the .dat file.
    Examples

  1. res_to_res.exe -max -t99999 results_1_h.dat results_2_h.dat results_3_h.dat
  2. Extracts the maximum water level from the three .dat files, where the maximum water level over all timesteps (tracked and output to t99999) is available for each of the .dat files.
  3. res_to_res.exe -max -typeH results_1.xmdf results_2.xmdf results_3.xmdf
  4. As above but for results stored in xmdf file format.
  5. res_to_res.exe -max results_h.dat
  6. Extracts the maximum water level of all available output times for a .dat file. Note this does not provide the true, tracked maximum over all timesteps.

    Min

    Input Switch: -min
    Notes
    This option was added in the 2015-02-AA version of the utility. If using an earlier version this command will not be recognised as valid.
    Description
    This can be used to extract the minimums from a number of input datasets. Any number of input files can be specified. If a minimum folder exists in an .xmdf file for the type specified, this dataset will be used.
    Examples

  7. res_to_res.exe -min results_1_h.dat results_2_h.dat results_3_h.dat
  8. Extracts the minimum water level from the three .dat files.
  9. res_to_res.exe -min -typeH -out Minimums.xmdf results_1.xmdf results_2.xmdf results_3.xmdf
  10. As above but for results stored in xmdf file format in "Minimums.xmdf".

    Difference

    Input Switch: -dif
    Description
    This can be used to compare two datasets. If a third file is specified, the third file is used as the output file. The output filename can also be specified with the -out option. The output is the first result minus the second result file.
    A special wet/dry algorithm is used. If water level results are not specified (_h.dat or -typeH), the algorithm opens these files, as well as opens the .2dm file associated with the results files, and uses the water levels and ZH Zpt values (for 2D cells) and elevations at the WLL triangle corners to determine whether a node (corner of a mesh element) is wet or dry. This allows two special values to be output in the event that a node is dry in one results file and wet in the other or vice versa. A value of -99 is used to indicate that a node is dry in the first results file, but is flooded in the second results file, while +99 indicates that the node was wet in the first results file but is dry in the second results file. Specifying -nowetdry does not carry out a wet/dry check using the water level results.
    The -t option can be used to carry out the difference at a particular time (rather than all times). The most common time is to take the difference at the flood peak, ie. specify -t99999.
    Examples

  11. res_to_res.exe -dif results_developed_h.dat results_existing_h.dat
  12. Extracts the difference in water level, the output is results_developed_h - results_existing_h for all timesteps.
  13. res_to_res.exe -dif -typeH -t99999 -nowetdry results_developed.xmdf results_existing.xmdf
  14. Extracts the difference in water level for the maximum water level and suppresses the wet/dry check described above.

    Duration

    Input Switch: -dur<cut of value>
    Description
    Determines the duration in hours that the the results exceed the cut off value.
    Note: A preferable approach is to use the .tcf file command: Time Output Cutoff Depths == <cut off value or values>. With this command specified TUFLOW tracks this on a timestep by timestep basis rather than post processing this at the map output interval.
    Examples

  15. res_to_res.exe -dur0.1 -typeD results.xmdf
  16. Extracts the duration in flooding above 0.1m deep.

    Keep

    Input Switch: -k<output time>
    Description
    Can be used to extract a single timestep from a results file. This is useful to extract the maximums to a separate file making it easier to transfer electronically. To keep a range of output times see the -range option below.
    Examples

  17. res_to_res.exe -k99999 results_h.dat
  18. Creates a new results file containing just the maximum from the water level results.
  19. res_to_res.exe -k2.5 -typeV results.xmdf
  20. Creates a new results file containing just velocity results for the 2.5 hour output.

    Range

    Input Switch: -rangeA<start time> -rangeB<end time>
    Description
    Extracts all timestep between start time and end time (inclusive) into a separate results file.
    Examples

  21. res_to_res.exe -rangeA1 -rangeB2.5 results_d.dat
  22. Creates a new results file containing the outputs between 1.0 and 2.5 hours. Both 1 and 2.5 hour outputs are included.
  23. res_to_res.exe -rangeA1 -rangeB2.5 -typeD results.xmdf
  24. As above but for xmdf input files.

    Remove

    Input Switch: -r<output time>
    Description
    Creates a new output file and removes the output time from this.
    Examples

  25. res_to_res.exe -r3 results_d.dat
  26. Creates a new output file which does not include the output at 3.

    Trim Values

    Input Switch: -trim<value>
    Description
    Creates a new output file which has any values above <value> set to <value>. If the input is a vector data, the vector magnitude is used to trim the value (direction is unchanged).
    Examples

  27. res_to_res.exe -trim5 -typeV results.xmdf
  28. Creates a new output of velocity with any outputs greater than 5.0 set to 5.0.

    Times

    Input Switch: -times
    Description
    Creates a text file which contains the output times in the .dat or xmdf file. If no output filename is specified with the -out option the output file will be called "times.txt". For xmdf files see also the -xnfo option below.
    Examples

  29. res_to_res.exe -times results_h.dat
  30. Creates an an output file "times.txt" which contains all timesteps that are contained in the results file.

    XMDF Information

    Input Switch: -xnfo
    Description
    Creates a text file which contains a list of the datasets contained within the .xmdf file. The number of output times and the output times are also exported to the text file.
    Examples

  31. res_to_res.exe -xnfo -out xmdf_info.txt results.xmdf
  32. Creates an an output file with the specified filename "xmdf_info.txt", which contains information about the contents of the xmdf file.

    Vector Angle

    Input Switch: -va
    Description
    Outputs the vector direction in degrees relative to north (North = 0°, East = 90°, South = 180°/-180°, West = -90°).
    Examples

  33. res_to_res.exe -va results_v.dat
  34. Outputs the velocity direction for all timesteps in the results_v_va.dat file.

    Concatenate

    Input Switch: -con
    Description
    Concatenates (joins) two or more results files into one. Each results file must be from the same 1D/2D mesh.
    Examples

  35. res_to_res.exe -con results1_h.dat results2_h.dat results3_h.dat
  36. Joins the three files into a single .dat file.
  37. res_to_res.exe -con -typeH results1.xmdf results2.xmdf results3.xmdf
  38. Joins the water level results contained in the .xmdf files into a single

    Convert

    Input Switch: -conv
    Description
    Converts between .dat and .xmdf format results. Not to be confused with -con (concatenate option described above)!
    Examples

  39. res_to_res.exe -conv -typeH -t99999 results1.xmdf
  40. Converts the maximum water level results in the xmdf file into .dat file format.
  41. res_to_res.exe -conv results1.xmdf
  42. Converts all datasets and times in the .xmdf file into .dat file format. This will output a number of .dat files.
  43. res_to_res.exe -conv results1_h.dat
  44. Converts all times in the .dat file into xmdf file format.

    Time of Increase

    Input Switch: -toi<cutoff>
    Calculates the time taken for the results to increase by the cutoff. For example if a value of 0.2 is used for a depth grid, the output result contains the time required for the depth to increase by 0.2m. If there are depth values greater than 0.2 initially (due to initial water level conditions), the output is the time for the depth to increase by 0.2m. For dry areas it is the time for the depth to reach 0.2m.
    Examples

  45. res_to_res.exe -toi0.2 -typeD results1.xmdf
  46. Extracts the time taken for the depth to increase by 0.2m

    Ensight (beta)

    Input Switch: -ensight
    Description
    Converts an .xmdf file (.dat not yet supported) into Ensight Gold format.
    If the input dataset is corner based (standard output) the Ensight results are output as scalar / vector per node (cell and triangle corners).
    If the result is high resolution (Map Output Format == xmdf high res) then the Ensight results are per element. For 2D cells this is based on the cell centre output, for triangles (1D water level lines) this is based on an interpolation of the triangle vertices. The conversion produces the following output files:

    • Ensight case file;
    • Ensight geometry file;
    • Ensight results as either per node or per element depending on the input file.

    This conversion is in its beta stage of development. This utility can currently only process 2D results. 1D channel result are currently not supported.
    Any feedback regarding this utility function is welcome and can be sent to support@tuflow.com.
    Examples

  47. res_to_res.exe -ensight results1.xmdf
  48. Converts all datasets in the xmdf file into Ensight format.

    General Options

    Batch Mode

    Input Switch: -b
    Batch mode suppresses prompt to press Enter at end of processing. Used in .bat files where two or more files are to be processed in succession.

    Output Filename

    Input Switch: -out "output_filename"
    Sets the output filename. This is not available for all outputs, particularly where multiple output files are required!

    Time Search Tolerance

    Input Switch: -dttol<search tolerance>
    Allows the user to specify the time search tolerance. This is particularly useful for TUFLOW FV model results, as model uses an adaptive timestep the output time might not exactly match the desired output interval. If hourly output is requested the closest output might actually be 01:00:05 (HH:MM:SS). If extracting results at time 1, the requested time may not be found due to time search tolerance. The default value is 0.001.

    XMDF Switches

    When working with the .xmdf outputs from TUFLOW, there are some additional input switches are available. This is because the .xmdf file uses a folder structure and multiple output parameters are stored in the same .xmdf file. When converting you can control which dataset is converted using the switches below. These switches are not valid for .dat files as these contain a single parameter for each file. E.g. the _d.dat contains only depth information.
    In the xmdf file, the data is stored in the following structure:
    Simulation ID/Folder/Dataset. Some examples for simulation "M01_5m_013_SA_CPU" are:
    M01_5m_013_SA_CPU/Maximums/ZAEM1
    M01_5m_013_SA_CPU/Temporal/Depth

    The xmdf specific switches are outlined in the table below:

    Switch Description
    "-type<output type>" Converts the specified output type in an xmdf file. Output types should be specified as per the output type in the .tcf e.g. h (water level), v (velocity), q (flow) or d (depth).
    "-s<output id(integer)>" Converts the specified scalar dataset in an xmdf file. For example, -s1 will convert the first scalar dataset. A list of the available datasets is listed within the DOS window when RES_to_RES is preprocessing results.
    "-v<output id(integer)>" Converts the specified vector dataset in an xmdf file. For example, -v1 will convert the first vector dataset. A list of the available datasets is listed within the DOS window when RES_to_RES is preprocessing results.
    "-Folder<Folder Name>" Converts all datasets within a particular xmdf file. For example, -Folder"Maximums" will convert all datasets in the \Maximums\ folder.
    "-path<path name>" Converts a dataset based on the path in the .xmdf file. For example, -path"Maximums/ZAEM1" would convert the dataset Maximum ZAEM1 dataset. This can be a full path in the .xmdf file or a partial match. E.g.:

    -path"Maximums/ZAEM1" M01_5m_013_SA_CPU.xmdf
    -path"M01_5m_013_SA_CPU/Maximums/ZAEM1" M01_5m_013_SA_CPU.xmdf

    XMDF Dataset Example

    Xmdf dataset example.png

    Up
    Go-up.png Back to TUFLOW Utilities