Running RIVET

The RIVET consists of two separate executables: RIVET, a GUI application, and rivet_console, a command-line application. All visualizations are done using RIVET and for most users trying our software for the first time, we recommend to start with this. RIVET and rivet_console are dependent, in the following senses: RIVET calls rivet_console, and rivet_console can precompute data files which RIVET can then load and visualize.

As we explain below, rivet_console also has functionality which we have found useful for working with 2-D persistence modules, even apart from visualization.

RIVET saves and loads the output of its main computations in a custom file format, which we call the computed data file type. This stores

  • the augmented arrangement data structure for querying the fibered barcode
  • Betti numbers
  • dimensions of all vector spaces.

The RIVET GUI

When the user runs RIVET, a window opens which allows the user to select a file. This file can be either a raw data file in one of the input formats described in the “Input Data” section of this documentation, or a computed data file.

If a raw data file is selected, then the user must choose the homology degree: RIVET currently handles one homology degree at a time. After the user clicks the compute button, the visualization data is computed and the visualization is started. (Note that once the dimension vectors and Betti numbers are shown in the visualization, it may take a significant amount of additional time to prepare the interactive visualization of the barcodes of 1-D slices.) Using the file menu in the GUI, the user may save a computed data file.

If a computed data file is selected in the file dialogue window, the RIVET visualization is started immediately.

rivet_console

rivet_console allows the user to directly compute a computed data file from a raw data file, without opening the GUI. Optionally, rivet_console can output the Betti numbers and dimensions directly to the console without computing the augmented arrangement. Further, rivet_console can also take as input a computed data file and a second file specifying a list of lines. RIVET then returns the barcodes of the 1-D slices of each line, using the same fast query framework used for the interactive visualization. (This last feature may be useful for testing the statistical significance of features found by RIVET.)

Note that rivet_console also has some technical functionality intended only for use by the GUI.

For details on how to run rivet_console , see the help file, which can be accessed via the command:

rivet_console (-h | --help)

Working with a Coarsened Persistence Module

When passing a raw data file to RIVET via either the GUI or the command line, the user has the option of choosing x-bins and y-bins parameters, which control how the persistence module is coarsened; if these parameters are not selected, no binning is done at all. The runtime of RIVET depends heavily on the choice of these parameters. Using no bins at all is the most computationally expensive option and is currently feasible only for very small examples. If you are trying RIVET for the first time, we suggest you try small values of x-bins and y-bins to start. For example, to start you might set both parameters equal to 10, and then try the computation again with a larger value afterwards.