add python script for making vectors in paraview (#4549)

## Summary

## Additional background

## Checklist

The proposed changes:
- [ ] fix a bug or incorrect behavior in AMReX
- [ ] add new capabilities to AMReX
- [ ] changes answers in the test suite to more than roundoff level
- [ ] are likely to significantly affect the results of downstream AMReX
users
- [X] include documentation in the code and/or rst files, if appropriate

Author: asalmgren

Docs/sphinx_documentation/source/Visualization.rst

@@ -458,15 +458,33 @@ Plot a Vector Field
 
 Paraview can be used to plot a vector field from AMR plotfile data. In this example
 we will assume a single vector has been stored as three separate variables,
-``V_x``, ``V_y`` and ``V_z``. The steps below outline a basic construction:
+``V_x``, ``V_y`` and ``V_z``.
 
-#. Open a plotfile or plotfile group, using ``File`` :math:`\rightarrow` ``Open``.
+The easiest way to create a vector ``V`` from the components is to
+first download the python file
+:download:`makevector.py </Visualization/makevector.py>`.
+
+If you are running paraview remotely, put ``makevector.py`` in the location
+of the plotfiles you will open under the heading ``Remote Plugins``.
+
+#. Now open a plotfile or plotfile group, using ``File`` :math:`\rightarrow` ``Open``.
    A pop-up will appear, select "AMReX/Boxlib Grid Reader".
 
 #. Select the plotfile or group in the Pipeline Browser. The Cell Array Status
    window of the Properties should populate with the values ``V_x``, ``V_y``
    and ``V_z``. Select these values and click apply.
 
+#. Select ``Tools``  :math:`\rightarrow` ``Manage Plugins...`` then choose
+``Load New...``.   Select ``makevector.py``; after you load it you will see
+``makevector`` in the list of plugins.
+
+#. Select the MakeVector filter from ``Filters`` :math:`\rightarrow` ``Alphabetical``
+   :math:`\rightarrow` ``MakeVector`` and apply.  You will now have the vector ``V``
+   listed with your other variables.
+
+Alternatively, if you prefer not to use the python plugin, you can follow the
+steps below:
+
 #. Select the Cell Centers filter from ``Filters`` :math:`\rightarrow` ``Alphabetical``
    :math:`\rightarrow` ``Cell Centers`` and apply.
 
@@ -479,7 +497,9 @@ we will assume a single vector has been stored as three separate variables,
    Note that, the values ``V_x``, ``V_y`` and ``V_z``, should be selectable
    from the dropdown Scalars menu. Apply the filter.
 
-#. To plot the arrows, select the Glyph filter,
+To plot the arrows corresponding to this vector field
+
+#. Select the Glyph filter,
    ``Filters`` :math:`\rightarrow` ``Alphabetical`` :math:`\rightarrow` ``Glyph``.
    Under the heading, Glyph Source, select ``Arrow``. Under Orientation, select
    the name of the vector value created in the last step. The default name is

Docs/sphinx_documentation/source/Visualization/makevector.py

@@ -0,0 +1,82 @@
+from paraview.util.vtkAlgorithm import *
+
+@smproxy.filter()
+@smproperty.input(name="InputDataset", port_index=0)
+@smdomain.datatype(dataTypes=["vtkOverlappingAMR"])
+class MakeVector(VTKPythonAlgorithmBase):
+    def __init__(self):
+        VTKPythonAlgorithmBase.__init__(self, nInputPorts=1, nOutputPorts=1, outputType="vtkOverlappingAMR", inputType="vtkOverlappingAMR")
+
+    def _find_names(self, fields):
+        # This method uses regular expressions to figure out
+        # vectors that can be merged. It assumes that the component
+        # scalars are named as [xyz]name or name[xyz]
+        import re
+        array_names = fields.keys()
+        to_merge = {}
+        matches = {}
+        for a in array_names:
+            grp = re.search(r'^([xyz])[_-]?([\w]*)', a)
+            if grp:
+                grp = grp.groups()
+                if grp[0] and grp[1]:
+                    try:
+                        matches[grp[1]][grp[0]] = a
+                    except KeyError:
+                        matches[grp[1]] = { grp[0] : a }
+        for a in array_names:
+            grp = re.search(r'([\w]*)[_-]?([xyz])$', a)
+            if grp:
+                grp = grp.groups()
+                if grp[0] and grp[1]:
+                    try:
+                        matches[grp[0]][grp[1]] = a
+                    except KeyError:
+                        matches[grp[0]] = { grp[1] : a }
+        for key, value in matches.items():
+            keys = set(value.keys())
+            if (len(keys) == 2 or len(keys) == 3) and 'x' in keys \
+                and 'y' in keys:
+                try:
+                    to_merge[key] = (value['x'], value['y'], value['z'])
+                except KeyError:
+                    to_merge[key] = (value['x'], value['y'])
+        return to_merge
+
+    def RequestData(self, request, inInfoVec, outInfoVec):
+        # These modules are needed for the data model and numpy convenience
+        # methods.
+        from vtkmodules.vtkCommonDataModel import vtkOverlappingAMR
+        from vtkmodules.numpy_interface import dataset_adapter as dsa
+        from vtkmodules.numpy_interface import algorithms as algs
+        # Boilerplate code to get the input and output
+        inp = vtkOverlappingAMR.GetData(inInfoVec[0], 0)
+        output = vtkOverlappingAMR.GetData(outInfoVec, 0)
+
+        # Pass all of the AMR structure and fields to the output.
+        output.ShallowCopy(inp)
+
+        # Create objects that offer convenience APIs that interact
+        # with numpy.
+        inp = dsa.WrapDataObject(inp)
+        output = dsa.WrapDataObject(output)
+
+        # Workhorse. Merge all arrays of for [xyz]name and name[xyz] in
+        # point and cell data
+        for inp_field, output_field in [(inp.CellData, output.CellData), \
+                                        (inp.PointData, output.PointData)]:
+            # This method find the arrays names that match the criteria
+            to_merge = self._find_names(inp_field)
+            for name, arrays in to_merge.items():
+                if len(arrays) == 2:
+                    # make_vector is really all we need.
+                    output_field.append(
+                        algs.make_vector(inp_field[arrays[0]],
+                                         inp_field[arrays[1]]), name)
+                else:
+                    output_field.append(
+                        algs.make_vector(inp_field[arrays[0]],
+                                         inp_field[arrays[1]],
+                                         inp_field[arrays[2]]), name)
+
+        return 1