update documentation. more examples. document fix_modify options

doc/src/Howto_structured_data.rst

@@ -112,20 +112,28 @@ of that run:
    Number of runs:  2
    TotEng  =  -4.62140097780047
 
-Processing/plotting extracted data with Pandas
-----------------------------------------------
+.. versionadded:: 4May2022
+
+YAML format output has been added to multiple commands in LAMMPS,
+for example :doc:`dump yaml <dump>` or :doc:`fix ave/time <fix_ave_time>`
+Depending on the kind of data being written, organization of the data
+or the specific syntax used may change, but the principles are very
+similar and all files should be readable with a suitable YAML parser.
+
+Processing scalar data with Pandas
+----------------------------------
 
 .. figure:: JPG/thermo_bondeng.png
             :figwidth: 33%
             :align: right
 
-After extracting the YAML format data and parsing it, it can be easily
-imported for further processing with the `pandas
+After reading and parsing the YAML format data, it can be easily
+imported for further processing and visualization with the `pandas
 <https://pandas.pydata.org/>`_ and `matplotlib
 <https://matplotlib.org/>`_ Python modules.  Because of the organization
 of the data in the YAML format thermo output, it needs to be told to
 process only the 'data' part of the imported data to create a pandas
-dataframe, and one needs to set the column names from the 'keywords'
+data frame, and one needs to set the column names from the 'keywords'
 entry.  The following Python script code example demonstrates this, and
 creates the image shown on the right of a simple plot of various bonded
 energy contributions versus the timestep from a run of the 'peptide'
@@ -158,6 +166,47 @@ colname <thermo_modify>` command.
    fig = df.plot(x='Step', y=['E_bond', 'E_angle', 'E_dihed', 'E_impro'], ylabel='Energy in kcal/mol')
    plt.savefig('thermo_bondeng.png')
 
+Processing vector data with Pandas
+----------------------------------
+
+Global *vector* data as produced by :doc:`fix ave/time <fix_ave_time>`
+uses a slightly different organization of the data. You still have the
+dictionary keys 'keywords' and 'data' for the column headers and the
+data.  But the data is a dictionary indexed by the time step and for
+each step there are multiple rows of values each with a list of the
+averaged properties.  This requires a slightly different processing,
+since the entire data cannot be directly imported into a single pandas
+DataFrame class instance.  The following Python script example
+demonstrates how to read such data.  The result will combine the data
+for the different steps into one large "multi-index" table.  The pandas
+IndexSlice class can then be used to select data from this combined data
+frame.
+
+.. code-block:: python
+
+   import re, yaml
+   import pandas as pd
+
+   try:
+       from yaml import CSafeLoader as Loader
+   except ImportError:
+       from yaml import SafeLoader as Loader
+
+   with open("ave.yaml") as f:
+       ave = yaml.load(docs, Loader=Loader)
+
+   keys = ave['keywords']
+   df = {}
+   for k in ave['data'].keys():
+       df[k] = pd.DataFrame(data=ave['data'][k], columns=keys)
+
+   # create multi-index data frame
+   df = pd.concat(df)
+
+   # output only the first 3 value for steps 200 to 300 of the column Pressure
+   idx = pd.IndexSlice
+   print(df['Pressure'].loc[idx[200:300, 0:2]])
+
 
 Writing continuous data during a simulation
 ===========================================

doc/src/fix_ave_time.rst

@@ -258,10 +258,16 @@ each input value specified in the fix ave/time command.  For *mode* =
 scalar, this means a single line is written each time output is
 performed.  Thus the file ends up to be a series of lines, i.e. one
 column of numbers for each input value.  For *mode* = vector, an array
-of numbers is written each time output is performed.  The number of
-rows is the length of the input vectors, and the number of columns is
-the number of values.  Thus the file ends up to be a series of these
-array sections.
+of numbers is written each time output is performed.  The number of rows
+is the length of the input vectors, and the number of columns is the
+number of values.  Thus the file ends up to be a series of these array
+sections.  If the filename ends in '.yaml' or '.yml' then the output
+format is conforming to the `YAML standard <https://yaml.org/>`_ which
+allows to easily import that data into tools and scripts that support
+reading YAML files. The :doc:`structured data Howto
+<Howto_structured_data>` contains examples for parsing and plotting such
+data with very little programming effort in Python using the *pyyaml*,
+*pandas*, and *matplotlib* packages.
 
 The *overwrite* keyword will continuously overwrite the output file
 with the latest output, so that it only contains one timestep worth of
@@ -307,8 +313,10 @@ appropriate fields from the fix ave/time command.
 Restart, fix_modify, output, run start/stop, minimize info
 """""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 
-No information about this fix is written to :doc:`binary restart files <restart>`.  None of the :doc:`fix_modify <fix_modify>` options
-are relevant to this fix.
+No information about this fix is written to :doc:`binary restart files
+<restart>`.  The :doc:`fix_modify colname <fix_modify>` options can be
+used to change the name of the column in the output file.  When writing
+a YAML format file this name will be in the list of keywords.
 
 This fix produces a global scalar or global vector or global array
 which can be accessed by various :doc:`output commands <Howto_output>`.

doc/src/fix_modify.rst

@@ -12,7 +12,7 @@ Syntax
 
 * fix-ID = ID of the fix to modify
 * one or more keyword/value pairs may be appended
-* keyword = *temp* or *press* or *energy* or *virial* or *respa* or *dynamic/dof* or *bodyforces*
+* keyword = *temp* or *press* or *energy* or *virial* or *respa* or *dynamic/dof* or *bodyforces* or *colname*
 
   .. parsed-literal::
 
@@ -25,6 +25,11 @@ Syntax
          yes/no = do or do not re-compute the number of degrees of freedom (DOF) contributing to the temperature
        *bodyforces* value = *early* or *late*
          early/late = compute rigid-body forces/torques early or late in the timestep
+       *colname* values =  ID string
+         string = new column header name
+         ID = integer from 1 to N, or integer from -1 to -N, where N = # of quantities being output
+              *or* a fix output property keyword or reference to compute, fix, property or variable.
+
 
 Examples
 """"""""
@@ -34,6 +39,7 @@ Examples
    fix_modify 3 temp myTemp press myPress
    fix_modify 1 energy yes
    fix_modify tether respa 2
+   fix_modify ave colname c_thermo_press Pressure colname 1 Temperature
 
 Description
 """""""""""
@@ -165,6 +171,20 @@ will have no effect on the motion of the rigid bodies if they are
 specified in the input script after the fix rigid command.  LAMMPS
 will give a warning if that is the case.
 
+
+The *colname* keyword can be used to change the default header keywords
+in output files of fix styles that support it: currently only :doc:`fix
+ave/time <fix_ave_time>` is supported.  The setting for *ID string*
+replaces the default text with the provided string.  *ID* can be a
+positive integer when it represents the column number counting from the
+left, a negative integer when it represents the column number from the
+right (i.e. -1 is the last column/keyword), or a custom fix output
+keyword (or compute, fix, property, or variable reference) and then it
+replaces the string for that specific keyword. The *colname* keyword can
+be used multiple times. If multiple *colname* settings refer to the same
+keyword, the last setting has precedence.
+
+
 Restrictions
 """"""""""""
 none
@@ -172,7 +192,8 @@ none
 Related commands
 """"""""""""""""
 
-:doc:`fix <fix>`, :doc:`compute temp <compute_temp>`, :doc:`compute pressure <compute_pressure>`, :doc:`thermo_style <thermo_style>`
+:doc:`fix <fix>`, :doc:`compute temp <compute_temp>`,
+:doc:`compute pressure <compute_pressure>`, :doc:`thermo_style <thermo_style>`
 
 Default
 """""""

doc/utils/sphinx-config/false_positives.txt

@@ -3754,6 +3754,7 @@ ylat
 ylo
 ymax
 ymin
+yml
 Yoshida
 ys
 ysu