Update ParaView docs (#3934)

This PR adds to the Paraview docs describing how to create a time series
(`.series`) file to load and re-load plotfiles similar to the `.visit`
file in VisIt. A bash script to generate the `.series` file is provided
and the procedure to generate and (re)load the `.series` file is
described.

Docs/sphinx_documentation/source/Visualization.rst

@@ -331,6 +331,52 @@ To open a plotfile (for example, you could run the
 
    \end{center}
 
+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.
+
+.. highlight:: console
+
+::
+
+{ "file-series-version": "1.0", "files": [
+{ "name": "plt00000", "time": 0},
+{ "name": "plt00100", "time": 1},
+{ "name": "plt00200", "time": 2},
+{ "name": "plt00300", "time": 3},
+{ "name": "plt00400", "time": 4},
+{ "name": "plt00500", "time": 5},
+{ "name": "plt00600", "time": 6},
+{ "name": "plt00700", "time": 7},
+{ "name": "plt00800", "time": 8},
+{ "name": "plt00900", "time": 9},
+{ "name": "plt01000", "time": 10},] }
+
+:download:`write_series_file.sh </Visualization/write_series_file.sh>` is a bash script
+that can generate such a ``.series`` file. Navigate to the directory with the plotfiles and
+save this script. Then run the bash script by executing the following command in the terminal.
+
+.. highlight:: console
+
+::
+
+    bash write_series_file.sh
+
+This will generate a file ``plot_files.series``. Open ParaView, and then select
+"File" :math:`\rightarrow` "Open". In the "Files of Type" dropdown menu (see :numref:`fig:ParaView_filegroup`)
+choose the option ``All Files (*)``. Then choose ``plot_files.series`` and click "OK". Now the plotfiles have been
+loaded as a Group as in Step 2 of section :ref:`section-1`. Now, you can follow the steps 2 to 7 in the section
+:ref:`section-1` to plot. As new plotfiles are generated, just re-run the bash script to re-generate the
+``plot_files.series`` file, right-click on ``plot_files.series`` in the ParaView menu, and click on
+"Reload Files" (see :numref:`fig:ParaView_series_reload`).
+
+.. _fig:ParaView_series_reload:
+
+.. figure:: ./Visualization/ParaView_series_reload.png
+   :width: 3.0in
+
+   : File dialog in ParaView showing how to reload a series file
+
 Building an Iso-surface
 -----------------------
 

Docs/sphinx_documentation/source/Visualization/write_series_file.sh

@@ -0,0 +1,56 @@
+#!/bin/bash
+
+# Specify the root directory for traversal
+root_directory="./"
+
+# Create a temporary file to store the list of directories
+temp_file=$(mktemp)
+find "$root_directory" -type d -print0 > "$temp_file"
+
+# Initialize an empty string to store file information
+files_list=""
+
+# file counter to be used as time entry
+count=0
+
+ls -d */ | sort -z > temporary_file
+
+# Read from the temporary file
+for dir in */; do
+
+    dir_name=$(basename "$dir")
+
+    # Check if the folder starts with "plt" and contains a file named "Header"
+    if [[ "$dir_name" == plt* && -f "$dir/Header" ]]; then
+        # Extract version number from folder name
+        version="${dir_name#plt}"
+        echo $version
+
+        # Create file information
+        files_list+="$(printf "{ \"name\": \"plt$version\", \"time\": $count},")"
+        files_list+=$'\n'
+
+        ((count++))
+    fi
+done < "$temp_file"
+
+# Remove trailing comma from the last entry
+files_list="${files_list%,}"
+
+# Create the final JSON structure
+# Header line
+header_line="{ \"file-series-version\": \"1.0\", \"files\": ["
+# Write the files list
+all_files="$(printf '%s\n' "$files_list") ] }"
+
+file_series_data="$header_line"
+file_series_data+=$'\n'
+file_series_data+="$all_files"
+
+# Write the generated JSON structure to a file named plot_files.series
+echo "$file_series_data" > plot_files.series
+
+# Remove the temporary file
+rm "$temp_file"
+
+echo "JSON structure has been written to plot_files.series"