Documentation and examples for saving and loading state in Paraview (#4559)

## Summary

I have added two files to
`Docs/sphinx_documentation/source/Visualization/` which can be used as
example state files in Paraview. These were generated by Paraview. I
modified the saved file paths in these by hand, as Paraview exports them
by default with the absolute path from the host machine. I have also
added documentation to
`Docs/sphinx_documentation/source/Visualization.rst` to explain how to
save state files and load them in Paraview, using these two files as
examples.

## Additional background

Undertaken as directed by Jean Sexton. Please review the added
documentation for clarity and correctness and reply with any suggested
edits.

## 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

---------

Co-authored-by: Spencer Lamoureux <[email protected]>

Author: stlamoureux1

Docs/sphinx_documentation/source/Visualization.rst

@@ -331,6 +331,10 @@ To open a plotfile (for example, you could run the
 
    \end{center}
 
+
+Creating and Loading ``.series`` Files
+--------------------------------------
+
 Another useful feature in ParaView to load and re-load a group of plotfiles is using a ``.series`` file
 (similar to the ``.visit`` file in VisIt). It is a text file (say ``plot_files.series``) which lists
 the plotfiles in a JSON format as below.
@@ -521,6 +525,121 @@ To plot the arrows corresponding to this vector field
 
    Vector Field generated with ParaView
 
+Saving and Loading State Files
+------------------------------
+
+Paraview allows users to save the *state* of their visualization, viz. variable mappings,
+filters, color maps, etc. The same display style can then be applied to different datasets.
+See also the Paraview documentation at `section 10`__ and `section 8.4`__.
+
+__ https://docs.paraview.org/en/latest/Tutorials/ClassroomTutorials/advancedStateManagement.html
+__ https://docs.paraview.org/en/v5.8/UsersGuide/savingResults.html#saving-state
+
+There are two file formats available for saving and loading state: ``.pvsm`` (XML) and ``.py`` (Python).
+Examples of both methods are given below. For these examples, we will be working with the data stored
+in the folder ``plt..`` that results from running ``HeatEquation_EX1_C`` in 3D, as in the example at the
+`beginning of this section`__.
+
+__ https://amrex-codes.github.io/amrex/docs_html/Visualization.html#paraview
+
+To save the state of this example, go to ``File > Save State...``, and select the format, location, and name
+of the state file you want to save. In order to later reload the state you've saved, see below.
+
+Note that the ``Save State`` option will write state files containing the absolute path to the data files you have loaded.
+This can cause issues if you're using state files saved on another machine, have moved your data files, or
+if Paraview doesn't know which directory to look in. When loading state from a ``pvsm`` file, there are menu
+options available to navigate to the data source directory. When running a Python script to load data, this can
+cause an error or crash. We outline the way to avoid this below.
+
+For demonstration purposes, we have also included state files in both formats:
+:download:`slice_state1.pvsm </Visualization/slice_state1.pvsm>` and :download:`slice_state1.py </Visualization/slice_state1.py>`
+
+
+Loading from a Paraview state file (.pvsm)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+#. Go to ``File > Load State``, navigate to ``slice_state1.pvsm`` in the file browser and click ``OK``. A new window labeled ``Load State Options`` appears with a drop-down menu.
+
+#. Select ``Search files under specified directory``, and click the ``...`` button to the right of the ``Data Directory`` line.
+
+#. Navigate to ``amrex-tutorials/ExampleCodes/Basic/HeatEquation_EX1_C/Exec`` and click ``OK``. This is where the plotfiles will have been saved by default if you've built and run the example code ``HeatEquation_EX1_C``.
+
+What you see displayed should be a 2D slice of the solution to the 3D equation.
+
+In general, you can use the load state menu options to navigate to whichever data files you wish to load using your saved ``pvsm`` state.
+
+
+Loading from a Python state file (.py)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In order to load state from a ``.py`` file, you must execute the file as a script from the Python Shell within Paraview.
+
+#. If the Python Shell is not displayed, click the checkbox in ``View > Python Shell``.
+
+#. Click the ``Run Script`` button to the bottom right of the Python shell, navigate to the file ``amrex/Docs/sphinx_documentation/source/Visualization/slice_state1.py`` in the file navigator, and click ``OK``.
+
+You should see a 2D slice of the solution to the 3D heat equation. If Paraview reports
+an error or crashes, see below.
+
+Aside: Working directory in the Paraview Python shell
++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+When you load a state from a Python script in Paraview, it will look in the current working directory of the Python shell to
+resolve the paths to the data files provided in the Python script.
+
+By default, the current working directory of the Paraview Python shell will be the directory from which you launched Paraview.
+
+.. warning:: If your Python script makes direct reference to a set of files that can't be found from your current working directory, then running that script will result in an error, and potentially cause Paraview to crash. This can be addressed by changing the cwd of your Python shell to the proper location.
+
+
+To check the cwd of the Paraview Python shell, run
+
+.. code-block:: python
+
+   >>> import os
+   >>> os.getcwd()
+
+and make sure that your cwd contains the folder you want to search in so that Python can resolve the path. To change the cwd, run
+
+.. code-block:: python
+
+   >>> os.chdir('path/to/folder/containing/your/plotfiles')
+
+Modifying a State File to Work with Different Data
+++++++++++++++++++++++++++++++++++++++++++++++++++
+
+As noted above, a Python state file exported from Paraview will save the path to the data files you used, if any, from your working directory.
+In order to use such a file with different data, you can modify your Python state file to use the `glob`__ package to create a list
+of potential data file names to search in your current path. The steps are outlined below, including the line numbers in the file
+``slice_state1.py``.
+
+__ https://docs.python.org/3/library/glob.html
+
+#. Import the glob package
+
+   .. code-block:: python
+
+      4: import glob
+
+
+#. Create a variable that will hold the list of names to search for. Following the AMReX convention for naming plotfiles, use
+
+   .. code-block:: python
+
+      62: PlotFiles = sorted(glob.glob("plt" + "[0-9]" * 5))
+
+#. In the code section that builds an ``AMReX/BoxLib Grid Reader``, replace the list of data paths with the variable ``PlotFiles``
+
+   .. code-block:: python
+
+      65: plt00000 = AMReXBoxLibGridReader(registrationName="plt00000*", FileNames=PlotFiles)
+
+#. Change the cwd of your Python shell, as outlined above, to a directory containing the other plotfiles you wish to view.
+
+#. Click ``Run Script`` and navigate to the Python state file you wish to run in the pop-up file navigator.
+
+You should now be able to view a new data set with the same filters, color mappings, etc. that you saved to your state file.
+
 ParaView HDF5 Format
 --------------------