Merge pull request #817 from baagaard-usgs/feature-vtu-output-format

Switch VTK output from legacy ASCII to VTU/XML

Author: baagaard-usgs

CHANGES.md

@@ -8,7 +8,10 @@ The version numbers are in the form `MAJOR.MINOR.PATCH`, where major releases in
 ## Version 5.0.0
 
 * **Changed**
+  * Use the VTU (XML) format for VTK files instead of the legacy ASCII format.
   * Update PETSc to 3.22.3
+* **Added**
+  * Improve documentation for pylith_eqinfo and illustrate its use in examples.
 
 ## Version 4.2.0
 

docs/developer/testing/debugging-tools.md

@@ -103,7 +103,7 @@ caption: Printing PETsc and PyLith objects (same for gdb and lldb)
 #   "::ascii_info_detail" - ASCII to stdout
 #   ":mesh.txt:ascii_info_detail" - ASCII to mesh.txt
 #   ":mesh.tex:ascii_latex" - LaTeX to mesh.tex
-#   ":mesh.vtk:ascii_vtk" - VTK to mesh.vtk
+#   "vtk:mesh.vtu:vtk_vtu" - VTK to mesh.vtu
 (gdb) call mesh.view("::ascii_info_detail")
 
 # Print PyLith field "field"

docs/intro/development-plan.md

@@ -30,6 +30,7 @@ This version will include a few very minor changes to the public API.
 
 * Specify boundary conditions using faces instead of vertices ![expert](images/intermediate.png) [75%]
 * Parallel mesh loading ![expert](images/expert.png) [85%]
+* Update VTK output to use `vtu` files rather than legacy `vtk` files ![easy](images/easy.png) [100%]
 
 ## Version 5.1 (June 2025)
 
@@ -49,7 +50,6 @@ This version will include major changes to the public API associated with the sw
 * Add support for GeoModelGrids implementation of spatial databases for 3D seismic velocity models. ![intermediate](images/intermediate.png) [0%]
 * Update to current version of Pyre ![difficult](images/difficult.png)
 * Migrate examples to Jupyter notebooks ![intermediate](images/intermediate.png)
-* Update VTK output to use `vtu` files rather than legacy `vtk` files ![easy](images/easy.png) [0%]
 * Improve robustness of HDF5 output by opening/closing at each time step ![easy](images/easy.png)[0%]
 * Improve creation of auxiliary, diagnostic, and derived fields.
 * More flexible specification of time-dependent boundary conditions. ![difficult](images/difficult.png) [0%]

docs/intro/preface.md

@@ -1,11 +1,11 @@
 # Preface
 
-This documentation is aimed at two categories of users: (1) scientists who prefer to use prepackaged and specialized analysis tools, and (2) experienced computational Earth scientists.
-If you want to modify the source code, you will likely need to be familiar with object-oriented programming, Python and C++, and finite-element analysis.
+This documentation targets two categories of users: (1) scientists who prefer to use prepackaged and specialized analysis tools, and (2) experienced computational Earth scientists.
+If you want to modify the source code, it is helpful to be familiar with object-oriented programming, Python and C++, and finite-element analysis.
 
 ## Citation
 
-The Computational Infrastructure for Geodynamics (CIG) ([geodynamics.org](https://geodynamics.org/)) is making this software and source code available to you at no cost in hopes that the software will enhance your research in geophysics.
+The Computational Infrastructure for Geodynamics (CIG) ([geodynamics.org](https://geodynamics.org/)) makes this software and source code available to you at no cost in hopes that the software will enhance your research in geophysics.
 A number of individuals have contributed a significant portion of their careers toward the development of this software.
 It is essential that you recognize these individuals in the normal scientific practice by citing the appropriate software release and peer-reviewed papers as well as making appropriate acknowledgments in talks and publications.
 The preferred way to generate the list of publications (in BibTeX format) to cite is to run your simulations with the `--include-citations` command line argument, or equivalently, the `--petsc.citations` command line argument.
@@ -25,19 +25,17 @@ To cite the software and manual, use:
 
 Open research statements are now a common requirement when publishing research.
 These support reuse, validation, and citation and often take the form of *Data availability*, *Data access*, *Code availability*, *Open Research*, and *Software* availability statements.
-We recommend depositing input files that allow your published research to be reproduced and output model data in support of your research outcomes and figures.
-In addition, consider depositing model files that may be reused by others.
-
-Remember to cite software and data in your text as well as in your *Data availability* or similar statement.
-
+We recommend including all input files to allow your published research to be reproduced and output model data to support your research outcomes and figures.
+In addition, consider including model files that may be useful to others.
 Files should be deposited in an approved repository.
 
-Additional information on [*Publishing*](https://geodynamics.org/software/software-bp/software-publishing) and repositories are available on the CIG website.
+Remember to cite software and data in your text as well as in your *Data availability* or similar statement.
+Additional information on [*Publishing*](https://geodynamics.org/software/software-bp/software-publishing) and repositories is available on the CIG website.
 
 ### Files
 
-Common input files include `.cfg`, , `.spatialdb`, and mesh files `.exo`, `.msh`, or `mesh`.
-Common output files include the solution fields and state variables as `.h5`, `.xmf`, `vtk`, and `vtu`..
+Common input files include `.cfg`, `.spatialdb`, and `.exo`, `.msh`, or `mesh` mesh files.
+Common output files include the solution fields and state variables in `.h5`, `.xmf`, and `vtu` files.
 
 ### Example Statement
 

docs/user/problems/output.md

@@ -216,18 +216,16 @@ This is very useful if you add fields to HDF5 files in post-processing and wish
 (sec-user-data-writer-vtk)=
 ### VTK Output
 
-PyLith writes legacy (non-XML) VTK files.
-These are simple files with vertex coordinates, the mesh topology, and fields over vertices and/or
-cells.
+PyLith writes VTU files for VTK output, which are in the XML format.
+The XML files contain metadata in XML tags and raw data for the vertex coordinates, mesh topology, and fields over vertices and/or cells.
 Each time step is written to a different file.
 The time stamp is included in the filename with the decimal point removed.
 This allows automatic generation of animations with many visualization packages that use VTK files.
 The default time stamp is the time in seconds, but this can be changed using the normalization constant to give a time stamp in years, tens of years, or any other value.
 
 :::{warning}
-We strongly discourage use of using VTK output.
-It is slow, inefficient, and not easily read from post-processing scripts.
-We strongly recommwnd using HDF5 output instead, which is the default starting in PyLith v3.0.0.
+We discourage use of the VTK output as the files are not easily read from post-processing scripts.
+We strongly recommend using HDF5 output instead, which is the default starting in PyLith v3.0.0.
 :::
 
 :::{seealso}