Debugging avtFilters

This page describes techniques that can be used for debugging new avtFilter subclasses such as what you would write for a new built-in pipeline filter or new plot or operator plugin. avtFilter subclasses are executed exclusively on the compute engine so debugging techniques for the compute engine are relevant as are other techniques such using the -dump command line argument.

Examine VTK filter output with -dump

VisIt provides a "-dump" command line argument that makes the engine output large amounts of debugging information. This flag is only useful for debugging code that executes on the engine. The –dump flag outputs information in two forms:

  1. exhaustively dumping of all of the meshes and fields that pass through each filter as VTK files, and
  2. webpages that describe all of VisIt’s meta-information about the pipeline.
visit -dump

Outputting raw data

-dump affects every AVT filter and also VisIt’s parallel rendering engine.

For the AVT filters, the input and output of each filter is dumped. The dumps are VTK files. Each avtDataset has an avtDataTree, which contains zero or more VTK data sets. Each one of these vtkDataSets gets its own file, using an ASCII VTK format. So, if a filter has 4 vtkDataSets in its input and three vtkDataSets in its output, then there will be four files of the form “before_avt<FILTER_NAME>.#.vtk” and three files of the form “after_avt<FILTER_NAME>.#.vtk”. The number that is encoded in each filename is an ever-increasing counter. This ensures that there is never a collision in file names, even if you re-execute the same pipeline over again. (If running in parallel, an extra integer is put in the filename with the ID of the processor VisIt is processing that chunk of data on.) The counter is set to zero every time the engine is started. (So you can re-start the numbering by closing the engine and re-drawing the plot.) It is hard to do an “ls” and understand how this data is flowing through the pipeline. This information, however, can be obtained by looking at the webpages described in the next section. Obviously, this information is useful for understanding the input and output of each filter, which allows you to determine what modifications the filter has made. Note that these VTK files are only dumped when the AVT filters have inputs and outputs that are “avtDatasets”, which is often the case. For scalable rendering that takes place on the engine, files are created that show the input and output of each compositor. This is primarily useful for debugging compositing code for VisIt’s parallel renderer, and this mode is used less often.

Outputting webpages

With “-dump”, VisIt will output two types of webpages. The first type is a summary of the pipeline execution. There is only one of these per pipeline execution and it is named “visit_dump_#.html”, where the number again is an increasing counter. This webpage allows you to see the ordering of the filters and also allows you to click to the second type of webpage, which gives an overview of a filter’s execution. In addition, some filters set up “sub-pipelines” that create new pipelines when executing. The webpage demonstrates this by indenting filters that are part of the sub-pipeline (including multiple indentations for sub-pipelines within sub-pipelines, etc).

Again, the second type of webpage gives an overview of a filter’s execution. There is one of these webpages for each filter. The webpage is broken into four parts, each of which contains meta-data. Two parts deal with an “avtPipelineSpecification”, which is the “contract” that VisIt uses to direct execution. (Should probably add a link here). The pipeline specification that was sent into the filter and the one that came out of the pipeline are each dumped in their own section of the webpage. The other two parts describe the meta-data about the data object input and output to the filter (the avtDataAttributes). This contains information such as topological dimension, variables, and it also contains pointers to all of the VTK data files that were described in 6.2.1.1.

If you only want the webpages and not VTK data sets, you can use the –info-dump flag instead of -dump.

Using -dump

  1. Use case: you have written a plugin database reader and you want to see the output that was fed up to VisIt.
    • How to do it: Look at “visit_dump_0.html” and see what the first filter in the pipeline is. (It is almost certainly avtExpressionEvaluatorFilter.) Then look at the files “before_avtExpressionEvaluatorFilter*.vtk”. Each one of the files corresponds to a chunk of data that the plugin database reader served up.
  2. Use case: you are using secondary variables and you want to understand when variables are being created and deleted.
    • How to do it: Look at each of the filter webpages and look at the variables array in the data attributes section. Each time a filter adds a variable, a new entry will show up in its output meta-data. Each time a filter removes a variable, an entry will be removed from the output meta-data.
  3. Use case: VisIt is crashing in a filter and you’re not sure why.
    • How to do it: The problem may be with a corrupted input to the file. You can run –dump and then look at the “before_avt<FILTER_THAT_CRASHES>.*.vtk” files and try to eyeball errors. If that doesn’t work, you can have VisIt make a plot of those files. If the plot works, the input to the filter is probably not corrupted, so you should spend your time debugging the filter. If the plot fails, then the input to the filter is corrupted and you should spend your time debugging what happened upstream.