Writing queries

Queries are VisIt’s vehicle for data analysis. Because new queries are frequently developed, and it is anticipated that they will be into the future, it would be appropriate for VisIt to employ its plugin mechanism for the handling of queries. However, that step has not been taken yet. For now, adding a new query requires making modifications to the main code.

The purpose of this page is to detail the steps necessary to add a query to VisIt.

Interface

The first step is to have VisIt add your new query to the user interface. VisIt is has a modular design. One module, the viewer, contains the centralized state. User interface modules (i.e. the gui and the cli) connect to the viewer. You must only tell the viewer about your new query. It will automatically tell the user interface modules about the list of valid queries when they exchange handshakes during start up.

To tell the viewer about your query, check out the file “/viewer/main/ViewerQueryManager.C”. Modify the method “InitializeQueryList”. You will want to add a call such as:

 queryTypes->AddQuery(“My Query Name”, …..);

The arguments to the call are documented at the top of the method.

Adding your query

Your actual query will be performed by the engine module. VisIt employs a client-server design and the engine acts as the server. Your query should be placed in the directory /components/Queries/Queries, where the engine can access them. The easiest approach is to find an existing query that is similar (i.e. operates on similar inputs, has similar outputs, and/or does similar processing) and use its .C and .h files as a starting point for your development.

To make VisIt recognize your file, you will have to perform three actions.

1)Edit the file “/components/Queries/Misc/avtQueryFactory.C”, and modify the method “CreateQuery”. Add your query using the exact text string that you used to register the query in the user interface (i.e. “My Query Name” above). Add an additional “else if” clause that instantiates your “AVT” query. You will also have to add an include statement to the top of the file so that the compiler is aware of your AVT query.

….
else if (qname == “My Query Name”)
{
     query = new avtMyNewQuery();
}
….

2)You will have to modify VisIt’s build system to be aware of your new file. VisIt uses CMake, so you will have to modify “/components/Queries/CMakeLists.txt” to include your new AVT query.

Documentation

Updates to VisIt’s documentation are typically done en masse for each major release. This is because it is too much effort to update the manual (and its images) every time the interface changes slightly. However, many of VisIt’s queries can be quite opaque and it is time consuming for the editor of the documentation to infer their meaning. So the documentation should be updated for the addition of each new query. To do this, check out the file “/docs/UserManual/Quantitative.fm”. This file is a FrameMaker file. FrameMaker is a sophisticated publishing program.

To add the documentation, find the section where each query is listed with a several sentence description of what that query does. The easiest way to modify the document is to cut-and-paste a similar entry and then modify that copy.

Because the FrameMaker document is binary in nature, changes to the document can not be merged in an automated way by the version control system. As such, a checkout of FrameMaker documents is treated as exclusive, meaning that no other checkouts of that file are allowed until the changes are merged in. So it is preferable that developers make their documentation changes shortly before merging their changes in.

Regression tests

Finally, you should add regression tests for your new query. See Regression Testing more information.