MeshBuilder

MeshBuilder is a utility program required to generate the *.reach graphfile for parallel tRIBS simulations.

Obtaining MeshBuilder

Two options are available for using MeshBuilder: (1) use the docker image maintained by the tRIBS developers, or (2) Build your own from the source code in this repository. We highly recommend the former for ease of use. Instructions for using the docker image are found on the tRIBS documentation page.

If you decide to build MeshBuilder, note that is only supported by the GNU compiler collection. This version of MeshBuilder can be compiled and built using CMake as follows:

cmake -B path/to/build/directory -S path/to/source directory
cmake --build path/to/build/directory --target all

Additional information on working with CMake is available on the tRIBS documentation page.

Working with MeshBuilder

MeshBuilder requires a .in file, similar to tRIBS, with at least the keywords:POINTFILENAME and OUTFILENAME provided. OPTMESHINPUT should also be set to option 9. MeshBuilder can be run via the command line as follows.:

meshBuilder example.in

MeshBuilder will produce a number of output files in identifying how the model nodes are connected through runoff and sub-surface fluxes. Of these the most important one is the connectivity.meshb file which provides a list of reaches to be partitioned. Once connectivity.meshb is generated it must be converted into a readable format by METIS. METIS then takes the different reaches and partitions them based on three options:

1. SurfaceFlow (SF)
2. Surface-Subsurface Flow (SSF)
3. Surface-Subsurface Flow with Headwaters (SSF-H).

Once METIS is complete, the outputs are then converted back into a format readable by tRIBS denoted as *.reach. This is the graphfile required for the keyword GRAPHFILE if PARALLEMODE is turned on. To aid in these conversions we provide 2 pearl scripts connectivity2metis.pl and metis_2tribs.pl utilized by the shell script. run_metis.zsh. These files are stored under src/workflow. Before you use this script you must build your own version of METIS as outlined here and also ensure the connectivity.meshb was generated from MeshBuilder. To run this basic utility script, your must provide the additional argument specifying the number of cores for partitioning, how the mesh should be partitioned based on the above options, and the base name of your simulation. For example to partition a mesh for the Big Spring Benchmark onto three cores by Surface Flow (option 1) only, you would run:

# ./run_metis.zsh NumberOfNodes OPT_Part basename
./run_metis.zsh 3 1 bigsp

Finally, we recommend that:

1. All executables, including MeshBuilder, METIS, and the perl/shell script are located in the same folder as your .in file.
2. That you review the output files from METIS denoted .out. These provide valuable information about whether the partitioning was successful on the requested number of cores. In some instances you can request that the mesh be partitioned finer then is possible. In this case you will over-allocate the number of cores required for the actual task of running your tRIBS simulation.
3. Finally, note that If the points file changes MeshBuilder must be run again.

To wrap up this section, some of the above steps can be bypassed by using the docker image of MeshBuilder. The image includes the METIS executable as well as the required pearl and shell scrips. All that is required in this case is to provide the input file as well as the points file to the appropriate volume (directory) that will be mounted to the image and then you can run meshbuild_workflow.sh which will take you through the above steps. Further documentation is provided here.