This tutorial describes using Python expressions. Python expressions are an advanced feature and should olny be used if the needed functionality is not available in the standard expression system <Expressions>
.
When the available expressions fail to provide needed functionality, users can extend VisIt's expression system in arbitrary ways using Python expressions. However, Python expressions require users to become somewhat converscent in detailed aspects of how mesh and variable data is represented in terms of VTK objects as well as how they are decomposed and processed in parallel. Nonetheless, Python expressions provide a powerful approach to filling in gaps in needed functionality.
Python expressions are run on the compute engine and will run in parallel whenever a) the compute engine is parallel and b) the input dataset is decomposed for parallel. Python expressions operate on vtkDataSets
, which provide access to mesh variables as well as the mesh coordinates and topology. Python expression also have access to VisIt's metadata as well as access to MPI when running in parallel. Python expressions return a vtkDataArray
, which allows returning new variables. It is not possible to change the mesh topology or coordinates within a Python expression. However, it is possible to combine Python expressions with Cross Mesh Field Evaluation (CMFE) functions <Comparison_Expressions>
which can have the effect of changing mesh topology and coordinates. The functionality is available through the GUI and the CLI. When using the GUI, they can be created in the Expressions window. When using the CLI, they can be created with the DefinePythonExpression function.
We will now go through the steps required to create a Python expression using the GUI.
Let us start by opening a file and creating a plot.
- Open the file
curv2d.silo
. - Create a Psuedocolor plot of
d
.
Now let us go ahead and create the Python expression.
- Go to Controls->Expressions.
- This brings up the Expressions window.
- Click New in the Expression list to create a new expression.
- Change the Name in the Definition section to "MyExpression".
- Click on the Python expression editor tab in the Definition section.
- Select Insert variable...->Scalars->d to add
d
to the Arguments text field. - Select Insert variable...->Scalars->p to add
p
to the Arguments text field. Note that the variable names are seperated by a comma. If the variable names are not separated by commas you will get a cryptic error message when you try to plot the expression. - Click Load script->Template->Simple filter to add a template of a Python expression in the Python expression script editor.
At this point you modify the template to create your expression. A common practice is to make modifications to the script and test it using the Pseudocolor plot. Changes to the script can be made either by modifying the script in the Python expression script editor or modifying it in an external text editor and then reloading the script. Generaly speaking, modifying the script in the Python expression script editor is easier than doing it in an external text editor except that it is difficult to tell how many spaces are at the beginning of the line since the editor does not use a fixed width font.
The following steps can be used to iteratively develop your script using the Python expression script editor.
- Edit the script.
- Click the Apply button.
- Go to Variables->d to change the variable to
d
. The first time you try your script this will not be necessary since the variable is alreadyd
. - Go to Variables->MyExpression to change the variable to "MyExpression" and execute the script.
The following steps can be used to iteratively develop your script using a text editor.
Before you can modify the script you will need to save it.
- Click Save script to save the script.
Now you are ready to modify the script.
- Edit the script with your favorit editor.
- Go to Load script->File to load the script.
- Click the Apply button.
- Go to Variables->d to change the variable to
d
. The first time you try your script this will not be necessary since the variable is alreadyd
. - Go to Variables->MyExpression to change the variable to "MyExpression" and execute the script.
This example adds two cell centered variables. It demonstrates accessing multiple variables and performing simple operations with them to generate a result.
Here is the example script.
../../test/tests/hybrid/python_example_1.vpe
Let us start off by creating a Pseudocolor plot from the expression.
- Copy the script into the Python expression script editor.
- Click the Apply button.
- Go to Variables->MyExpression to change the variable to the expression.
Now let us take a look at the script and see what each portion does.
The __init__
method provides information about the expression, including
- That it inherits from
SimplePythonExpression
. - The name of the expression.
- A description of the expression.
- A flag indicating that the output is not a point centered value.
- A flag that the output is a scalar.
../../test/tests/hybrid/python_example_1.vpe
The modify_contract
method can be used to request special information for the expression from VisIt. In this case it is a no-op.
../../test/tests/hybrid/python_example_1.vpe
The derive_variable
method performs the real work of the expression. It is passed the input vtkDataSet
and the domain_id
.
../../test/tests/hybrid/python_example_1.vpe
The following lines get the vtkDataArrays
for the cell values for the two variables and the number of cells.
../../test/tests/hybrid/python_example_1.vpe
The following lines set the output vtkDataArray
to be an array of floats with 1 component and ncells values.
../../test/tests/hybrid/python_example_1.vpe
Now we loop over the cells, setting the output value for each cell.
../../test/tests/hybrid/python_example_1.vpe
The following lines add the two variables for the current cell.
../../test/tests/hybrid/python_example_1.vpe
The following lines set the result value for the current cell.
../../test/tests/hybrid/python_example_1.vpe
Once we have finished processing all the cells, we return the vtkDataArray
.
../../test/tests/hybrid/python_example_1.vpe
The Python expression we just created can also be used with the CLI.
We will start by saving the script we just created.
- Click Save script and save the script with the name
MyExpression.py
.
The following script will open curv2d.silo
and create a Pseudocolor plot of the expression.
OpenDatabase("/usr/gapps/visit/data/curv2d.silo")
DefinePythonExpression("MyExpression", ['d', 'p'], file="MyExpression.py")
AddPlot("Pseudocolor", "MyExpression")
DrawPlots()
This example operates on 2D meshes and takes the distance around the edges of each cell and multiplies it by the value of the cell. It demonstrates accessing the coordinates and topology of the mesh as well as a variable.
Here is the example script.
../../test/tests/hybrid/python_example_2.vpe
Let us start off by creating a Pseudocolor plot from the expression.
- Copy the script into the Python expression script editor.
- Click the Apply button.
- Go to Variables->MyExpression to change the variable to the expression.
The __init__
and modify_contract
methods are the same as the previous example, so we will only look at the derive_variable
method.
../../test/tests/hybrid/python_example_2.vpe
The following lines get the vtkDataArray
for the cell values and the number of cells.
../../test/tests/hybrid/python_example_2.vpe
The following lines set the output vtkDataArray
to be an array of floats with 1 component and ncells values.
../../test/tests/hybrid/python_example_2.vpe
Now we loop over the cells, setting the output value for each cell.
../../test/tests/hybrid/python_example_2.vpe
The following lines get the current cell and the number of edges in the cell.
../../test/tests/hybrid/python_example_2.vpe
Now we loop over the edges, calculating the sum of the lengths of the edges.
../../test/tests/hybrid/python_example_2.vpe
We calculate the length of the edge from the 3D coordinates of the end points of the edge, which we add to the sum.
../../test/tests/hybrid/python_example_2.vpe
Once we have summed the lengths of the edges we multiply the sum by the cell value and set it in the result.
../../test/tests/hybrid/python_example_2.vpe
Once we have finished processing all the cells, we return the vtkDataArray
.
../../test/tests/hybrid/python_example_2.vpe
This Python expression can also be used with the CLI, just as the one in the first example, except the specification of the variables to use is slightly different. Since you are only passing a single variable you would use ("d")
for the list of variables.
OpenDatabase("/usr/gapps/visit/data/curv2d.silo")
DefinePythonExpression("MyExpression", ("d"), file="MyExpression.py")
AddPlot("Pseudocolor", "MyExpression")
DrawPlots()
The VTK Python interface mirrors the C++ interface.
To find out information on a particular VTK class, type the name of the class in your favorite search engine.
Here are links to some VTK classes that will be of most use to you.