update thermo style yaml docs and examples for reading and parsing

doc/src/Howto_structured_data.rst

@@ -21,7 +21,8 @@ YAML
    print """---
    timestep: $(step)
    pe: $(pe)
-   ke: $(ke)""" file current_state.yaml screen no
+   ke: $(ke)
+   ...""" file current_state.yaml screen no
 
 .. code-block:: yaml
    :caption: current_state.yaml
@@ -51,6 +52,58 @@ JSON
      "ke": 2.4962152903997174569
    }
 
+YAML format thermo_style output
+===============================
+
+.. versionadded:: 24Mar2022
+
+LAMMPS supports the thermo style "yaml" and for "custom" style
+thermodynamic output the format can be changed to YAML with
+:doc:`thermo_modify line yaml <thermo_modify>`.  This will produce a
+block of output in a compact YAML format - one "document" per run - of
+the following style:
+
+.. code-block:: yaml
+
+   ---
+   keywords: [Step, Temp, E_pair, E_mol, TotEng, Press, ]
+   data:
+     - [100, 0.757453103239935, -5.7585054860159, 0, -4.62236133677021, 0.207261053624721, ]
+     - [110, 0.759322359337036, -5.7614668389562, 0, -4.62251889318624, 0.194314975399602, ]
+     - [120, 0.759372342462676, -5.76149365656489, 0, -4.62247073844943, 0.191600048851267, ]
+     - [130, 0.756833027516501, -5.75777334823494, 0, -4.62255928350835, 0.208792327853067, ]
+   ...
+
+This data can be extracted and parsed from a log file using python with:
+
+.. code-block:: python
+
+   import re, yaml
+
+   docs = ""
+   with open("log.lammps") as f:
+       for line in f:
+           m = re.search(r"^(keywords:.*$|data:$|---$|\.\.\.$|  - \[.*\]$)", line)
+           if m: docs += m.group(0) + '\n'
+
+   thermo = list(yaml.load_all(docs, Loader=yaml.SafeLoader))
+
+   print("Number of runs: ", len(thermo))
+   print(thermo[1]['keywords'][4], ' = ', thermo[1]['data'][2][4])
+
+After loading the YAML data, `thermo` is a list containing a dictionary
+for each "run" where the tag "keywords" maps to the list of thermo
+header strings and the tag "data" has a list of lists where the outer
+list represents the lines of output and the inner list the values of the
+columns matching the header keywords for that step.  The second print()
+command for example will print the header string for the fifth keyword
+of the second run and the corresponding value for the third output line
+of that run:
+
+.. parsed-literal::
+
+   Number of runs:  2
+   TotEng  =  -4.62140097780047
 
 Writing continuous data during a simulation
 ===========================================

doc/src/thermo_style.rst

@@ -114,6 +114,8 @@ that is the equivalent of "thermo_style custom etotal ke temp pe ebond
 eangle edihed eimp evdwl ecoul elong press".  The listing contains
 numeric values and a string ID for each quantity.
 
+.. versionadded:: 24Mar2022
+
 Style *yaml* is similar to style *one* but prints the output in `YAML
 <https://yaml.org/>`_ format which can be easily read by a variety of
 script languages and data handling packages.  Since LAMMPS may print
@@ -126,17 +128,8 @@ and can thus be extracted with commands like ``egrep`` as follows:
 
    egrep  '^(keywords:|data:$|---$|\.\.\.$|  - \[)' log.lammps > log.yaml
 
-A typical block of YAML format output looks like this:
-
-.. code-block:: yaml
-
-   ---
-   keywords: [Step, Temp, KinEng, PotEng, E_bond, E_angle, E_dihed, E_impro, E_vdwl, E_coul, E_long, Press, Volume, ]
-   data:
-     - [0, 1.44000000000001, 2.15993250000001, -6.77336805323422, 0, 0, 0, 0, -6.77336805323422, 0, 0, -5.01970725908556, 37905.7095475006, ]
-     - [50, 0.740091517740786, 1.11010258482128, -5.73150426762886, 0, 0, 0, 0, -5.73150426762886, 0, 0, 0.335273324523691, 37905.7095475006, ]
-     - [100, 0.757453103239936, 1.13614414924569, -5.75850548601596, 0, 0, 0, 0, -5.75850548601596, 0, 0, 0.207261053624723, 37905.7095475006, ]
-   ...
+Information about processing such YAML files is in the :doc:`structured
+data output howto <Howto_structured_data>`.
 
 Style *custom* is the most general setting and allows you to specify
 which of the keywords listed above you want printed on each