diff --git a/doc/src/Howto_structured_data.rst b/doc/src/Howto_structured_data.rst index 6b45f945c5..deadb72fc7 100644 --- a/doc/src/Howto_structured_data.rst +++ b/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 ` or :doc:`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 `_ and `matplotlib `_ 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 ` 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 ` +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 =========================================== diff --git a/doc/src/fix_ave_time.rst b/doc/src/fix_ave_time.rst index dfa385ea46..4b25e7c174 100644 --- a/doc/src/fix_ave_time.rst +++ b/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 `_ which +allows to easily import that data into tools and scripts that support +reading YAML files. The :doc:`structured data Howto +` 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 `. None of the :doc:`fix_modify ` options -are relevant to this fix. +No information about this fix is written to :doc:`binary restart files +`. The :doc:`fix_modify colname ` 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 `. diff --git a/doc/src/fix_modify.rst b/doc/src/fix_modify.rst index 47080fcd58..9f5f0b3d90 100644 --- a/doc/src/fix_modify.rst +++ b/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 ` 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 `, :doc:`compute temp `, :doc:`compute pressure `, :doc:`thermo_style ` +:doc:`fix `, :doc:`compute temp `, +:doc:`compute pressure `, :doc:`thermo_style ` Default """"""" diff --git a/doc/utils/sphinx-config/false_positives.txt b/doc/utils/sphinx-config/false_positives.txt index 62983f4f39..81d9ff34c9 100644 --- a/doc/utils/sphinx-config/false_positives.txt +++ b/doc/utils/sphinx-config/false_positives.txt @@ -3754,6 +3754,7 @@ ylat ylo ymax ymin +yml Yoshida ys ysu