ParaView/Users Guide/Python Calculator
Introduction
The Python Calculator is a ParaView filter that processes one or more input arrays based on an expression provided by the user to produce a new output array. The parameters of the filter include the expression, the association of the output array (Point or Cell Data), the name of output array and a toggle that controls whether the input arrays are copied to the output. This section introduces the use of the Python Calculator and provides a list of functions available to the user.
Note that the Python Calculator depends on Python and NumPy. All ParaView binaries distributed by Kitware are built with these to enable the calculator. If you have built ParaView yourself, you have to make sure that NumPy is installed and that PARAVIEW_ENABLE_PYTHON is turned on when configuring the ParaView build.
Basic Tutorial
Start by creating a Sphere source and applying the Python Calculator to it. As the first expression, use the following and apply:
<source lang="python"> 5 </source>
This should create an array name "result" in the output point data. Note that this is an array that has a value of 5 for each point. When the expression results in a single value, the calculator will automatically make a constant array. Next, try the following:
<source lang="python"> Normals </source>
Now the "result" array should be the same as the input array Normals. As described in detail later, various functions are available through the calculator. For example, the following is a valid expression.
<source lang="python"> sin(Normals) + 5 </source>
It is very important to note that the Python Calculator has to produce one value per point or cell depending on the Array Association parameter. Most of the functions described here apply individually to all point or cell values and produce an array the same dimensions as the input. However, some of them (such as min() and max()) produce single values.
Accessing Data
There are several ways of accessing input arrays within expressions. The simplest way is to access it by name:
<source lang="python"> sin(Normals) + 5 </source>
This is equivalent to:
<source lang="python"> sin(inputs[0].PointData['Normals']) + 5 </source>
The example above requires some explanation. Here inputs[0] refer to the first input (dataset) to the filter. Python Calculator can accept multiple inputs. Each input can be accessed as inputs[0], inputs[1], ... You can access the point or cell data of an input using the .PointData or .CellData qualifiers. You can then access individual arrays within the point or cell data containers using the [] operator. Make sure to use quotes or double-quotes around the array name. Arrays that have names with certain characters (such as space, +, -, *, /) in their name can only be accessed using this method.
Certain functions apply directly on the input mesh. These filters expect an input dataset as argument. For example,
<source lang="python"> area(inputs[0]) </source>
For data types that explicitly define the point coordinates, you can access the coordinates array using the .Points qualifier. The following extracts the first component of the coordinates array:
<source lang="python"> inputs[0].Points[:,0] </source>
Note that certain data types, mainly image data (uniform rectilinear grid) and rectilinear grid, point coordinates are defined implicitly and cannot be accessed as an array.
Comparing Multiple Datasets
The Python Calculator can be used to compare multiple datasets, as shown by the following example.
- Go to the Menu Bar, and select File > Disconnect to clear the Pipeline.
- Select Source > Mandelbrot, and then click Apply, which will set up a default version of the Mandelbrot Set. The data for this set are stored in a 251x251 scalar array.
- Select Source > Mandelbrot again, and then go to the Object Inspector and set the Maximum Number of Iterations to 50. Click Apply, which will set up a different version of the Mandelbrot Set, represented by the same size array.
- Hold the Shift key down and select both of the Mandelbrot entries in the Pipeline Inspector, and then go to the Menu Bar and select Filter > Python Calculator. The two Mandelbrot entries will now be shown as linked, as inputs, to the Python Calculator.
- In the Object Inspector for the Python Calculator filter, enter the following into the Expression box:
inputs[1].PointData['Iterations'] - inputs[0].PointData['Iterations']
This expression specifies the difference between the second and first Mandelbrot arrays. The result is saved in a new array called 'results'. The prefixes in the names for the array variables, inputs[1] and inputs[0], refer to the first and second Mandelbrot entries, respectively, in the Pipeline. PointData specifies that the inputs contain point values. The quoted label 'Iterations' is the local name for these arrays. Click Apply to initiate the calculation.
Click the Display tab in the Object Inspector for the Python Calculator, and go to the first tab to the right of the 'Color by' label. Select the item results in that tab, which will cause the display window to the right to show the results of the expression we entered in the Python Calculator. The scalar values representing the difference between the two Mandelbrot arrays are represented by colors that are set by the current color map (see Edit Color Map... for details).
There are a few things to note:
- Python Calculator will always copy the mesh from the first input to its output.
- All operations are applied point by point. In most cases, this requires that the input meshes (topology and geometry) are the same. At the least, it requires that the inputs have the same number of points and cells.
- In parallel execution mode, the inputs have to be distributed exactly the same way across processes.
Basic Operations
The Python calculator supports all of the basic arithmetic operations using the +, -, * and / operators. These are always applied element-by-element to point and cell data including scalars, vectors and tensors. These operations also work with single values. For example, the following adds 5 to all components of all Normals.
<source lang="python"> Normals + 5 </source>
The following adds 1 to the first component, 2 to the second component and 3 to the third component:
<source lang="python"> Normals + [1,2,3] </source>
This is specially useful when mixing functions that return single values. For example, the following normalizes the Normals array:
<source lang="python"> (Normals - min(Normals))/(max(Normals) - min(Normals)) </source>
A common use case in a calculator is to work on one component of an array. This can be accomplished with the following:
<source lang="python"> Normals[:, 0] </source>
The expression above extracts the first component of the Normals vector. Here, : is a placeholder for "all elements". One element can be extracted by replacing : with an index. For example, the following creates a constant array from the first component of the normal of the first point:
<source lang="python"> Normals[0, 0] </source>
Whereas the following assigns the normal of the first point to all points:
<source lang="python"> Normals[0, :] </source>
It is also possible to merge multiple scalars into an array using the hstack() function:
<source lang="python"> hstack([velocity_x, velocity_y, velocity_z]) </source>
Note the use of square brackets ([]).
Under the cover, the Python Calculator uses NumPy. All arrays in the expression are compatible with NumPy arrays and can be used where NumPy arrays can be used. For more information on what you can do with these arrays, consult with the NumPy book, which can be downloaded here.
Functions
The following is a list of functions available in the Python Calculator. Note that this list is partial since most of the NumPy and SciPy functions can be used in the Python Calculator. Many of these functions can take single values or arrays as argument.
abs (x) : Returns the absolute value(s) of x.
add (x, y): Returns the sum of two values. x and y can be single values or arrays. Same as x+y.
area (dataset) : Returns the surface area of each cell in a mesh.
aspect (dataset) : Returns the aspect ratio of each cell in a mesh.
aspect_gamma (dataset) : Returns the aspect ratio gamma of each cell in a mesh.
condition (dataset) : Returns the condition number of each cell in a mesh.
cross (x, y) : Returns the cross product for two 3D vectors from two arrays of 3D vectors.
curl (array): Returns the curl of an array of 3D vectors.
divergence (array): Returns the divergence of an array of 3D vectors.
divide (x, y): Element by element division. x and y can be single values or arrays. Same as x/y.
det (array) : Returns the determinant of an array of 2D square matrices.
determinant (array) : Returns the determinant of an array of 2D square matrices.
diagonal (dataset) : Returns the diagonal length of each cell in a dataset.
dot (a1, a2): Returns the dot product of two scalars/vectors of two array of scalars/vectors.
eigenvalue (array) : Returns the eigenvalue of an array of 2D square matrices.
eigenvector (array) : Returns the eigenvector of an array of 2D square matrices.
exp (x): Returns power(e, x).
global_max(array): Returns the maximum value of an array of scalars/vectors/tensors among all process. Not yet supported for multi-block and AMR datasets.
global_mean (array) : Returns the mean value of an array of scalars/vectors/tensors among all process. Not yet supported for multi-block and AMR datasets.
global_min(array): Returns the minimum value of an array of scalars/vectors/tensors among all process. Not yet supported for multi-block and AMR datasets.
gradient(array): Returns the gradient of an array of scalars/vectors.
inv (array) : Returns the inverse an array of 2D square matrices.
inverse (array) : Returns the inverse of an array of 2D square matrices.
jacobian (dataset) : Returns the jacobian of an array of 2D square matrices.
laplacian (array) : Returns the jacobian of an array of scalars.
ln (array) : Returns the natural logarithm of an array of scalars/vectors/tensors.
log (array) : Returns the natural logarithm of an array of scalars/vectors/tensors.
log10 (array) : Returns the base 10 logarithm of an array of scalars/vectors/tensors.
max (array): Returns the maximum value of the array as a single value. Note that this function returns the maximum within a block for AMR and multi-block datasets, not across blocks/grids. Also, this returns the maximum within each process when running in parallel.
max_angle (dataset) : Returns the maximum angle of each cell in a dataset.
mag (a) : Returns the magnigude of an array of scalars/vectors.
mean (array) : Returns the mean value of an array of scalars/vectors/tensors.
min (array) : Returns the minimum value of the array as a single value. Note that this function returns the minimum within a block for AMR and multi-block datasets, not across blocks/grids. Also, this returns the minimum within each process when running in parallel.
min_angle (dataset) : Returns the minimum angle of each cell in a dataset.
mod (x, y): Same as remainder (x, y).
multiply (x, y): Returns the product of x and y. x and y can be single values or arrays. Note that this is an element by element operation when x and y are both arrays. Same as x * y.
negative (x): Same as -x.
norm (a) : Returns the normalized values of an array of scalars/vectors.
power (x, a): Exponentiation of x with a. Here both x and a can either be a single value or an array. If x and y are both arrays, a one-by-one mapping is used between two arrays.
reciprocal (x): Returns 1/x.
remainder (x, y): Returns x − y*floor(x/y). x and y can be single values or arrays.
rint (x): Rounds x to the nearest integer(s).
shear (dataset) : Returns the shear of each cell in a dataset.
skew (dataset) : Returns the skew of each cell in a dataset.
square (x): Returns x*x.
sqrt (x): Returns square root of x.
strain (array) : Returns the strain of an array of 3D vectors.
subtract (x, y): Returns the difference between two values. x and y can be single values or arrays. Same as x - y.
surface_normal (dataset) : Returns the surface normal of each cell in a dataset.
trace (array) : Returns the trace of an array of 2D square matrices.
volume (dataset) : Returns the volume normal of each cell in a dataset.
vorticity(array): Returns the vorticity/curl of an array of 3D vectors.
vertex_normal (dataset) : Returns the vertex normal of each point in a dataset.
Trigonometric Functions
Below is a list of supported triginometric functions.
sin (x)
cos (x)
tan (x)
arcsin (x)
arccos (x)
arctan (x)
hypot (x1, x2)
sinh(x)
cosh (x)
tanh (x)
arcsinh (x)
arccosh (x)
arctanh (x)
