Running Titan2D on Vhub: Example on Colima Volcano

by Matt Jones, Steve Gallo, Kyle Marcus, Abani Patra, Jose L. Palma, Sarah Elizabeth Ogburn


The Titan2D toolkit is used for modeling of geophysical mass flows over natural terrain (volcanic flows, avalanches, landslides etc.). Titan2D uses an adaptive finite volume scheme, and assumes that a large class of granular flows of geophysical origin can be modeled as an incompressible continuum satisfying a Mohr-Coulomb law (see References on the Titan2D tool page for detailed mathematical formulation). The solution is parallelized using the message-passing interface (MPI), and simulations for difficult terrains can be relatively time consuming even on large computational clusters. An essential input is the digital elevation model (DEM), since the flow simulation requires elevation, slope, curvature, and material information at every cell to be computed. This tool fronts a Titan2D simulation, but does not prepare the necessary DEM input that Titan2D relies upon, which is a prerequisite. (Note that the preparation of these DEMs could, and probably should, be a tutorial topic of its own.)

The Titan2D User Guide (titan_userguide.pdf (3 MB, uploaded by catalina balbis 2 years 8 months ago)) contains a detailed description of Titan2D and some information on the preparation of the inputs. This particular tutorial is intended to briefly describe how to run Titan2D in the VHub environment. Within VHub, Titan2D and its Java-based GUI (graphical user interface) are already installed, along with the supporting cast of necessary software packages. At this time (2011-01) the actual execution of the Titan2D code can occur either within the limitations of the VHub server (local execution in the GUI job submission tab), or remotely on a large cluster (the Hub-submit option in the GUI). For local execution the runs must necessarily be limited in their size to a few (less than 4) processing cores, at most 1 GB or so of memory, and at most a few hundred MB of disk. When using the remote cluster there are fewer restrictions, you can utilize tens to hundreds of cores and the associated memory (currently about 1GB per core). Storage is still an issue until the VHub storage pool is increased – you will need to ensure that your calculation will not generate more data than you can easily transfer back to VHub (at most a few hundred MB). You can approximate how much storage you need by the size of your DEM – multiply the size of your DEM by the number of time steps for which you output images of the flow. Decreasing the number of output steps will greatly reduce the storage requirements.

Walk-Through Example

The stock example (also available from comes as a prepared GIS/DEM for Vulcan de Colima, and can be found in the /apps/titan2d/current/examples directory on VHub, which also contains a file called example.readme (6 KB, uploaded by Matt Jones 9 years 5 months ago) that lists a set of initial mass flow parameters. The example.readme description refers to the old Python-style GUI for Titan2D, but the mapping to the Java GUI for the mass flow parameters should be direct and intuitive, as they both use the same input fields and styles. Ignore the last few paragraphs on how to run Titan2D, as we are using VHub instead.

Load/Save Tab

Here you specify the path (directory) where you want to store your new run. The directory name must begin with /home/vhub/username where username corresponds to your personal Vhub username (shown at the very top of this web page). In this example the test run is saved in the subdirectory test. Another appropriate name for this subdirectory could be titan2d. The Run Name is actually a folder inside the previous subdirectory where all the files with the parameters and results are saved. You need to press the Save button in order to create the folder (if it doesn’t exist already) and to save the parameters that you have entered. To load a previous run you need to enter in the field next to Input Directory the full path, including the name of the run, to the files with parameters and results. Following the example of the figure, the directory would be /home/vhub/kmarcus/test/TEST1.



For this example we’ll be using a digital elevation model (DEM) of Volcan de Colima (Mexico). These data are located in the directory of the application. The Main Directory is /apps/titan2d/current/examples/Colima/ and the Sub-Directory is Colima. Both the GIS Map Set and GIS Map folder names are ColimaR. And the GIS Vector file name is Flow1991_lin.spr.

General Tab


Material Map Tab


Piles Tab

titan_piles_tab_new.jpg The orientation angle value must range from -180° (clockwise rotation) to +180° (counter-clockwise rotation) from east = 0°

Job Submission Tab

Once the GUI tabs have been filled out for the GIS/DEM and mass flow parameters, you reach the Job Submission tab. For execution in the VHub environment you should choose Local execution (the Hub-submit option can be used to run on a remote cluster, useful for larger jobs, but it takes longer to queue up and wait for the jobs to run). The stock example parameters should take less than a minute to run on a single processing core, and once completed successfully you can use your preferred method for accessing the VHub filesystem to browse the results. Note that you can find some help in using WebDAV here.

Please only use the ‘Local’ and ‘Hub-Submit’ options, the ‘PBS’ and ‘Condor’ options will not work in the VHub environment.


Job Monitor Tab

From the ‘Job Monitor’ tab, click on a job and then click on the ‘Job Details’ button. A new window will appear that will show the output from the job.


Job Details Window

The following two images were created in a previous version of the tool TITAN2D, but this capability is obsolete. For creating a preliminary plot with the results you can use the Titan2d Viewer tool.



WebDav Access

You can use webdav to access the output files on VHub (Mac OS X example, see this page for help using webdav on other platforms).



Created on , Last modified on