From c70b0b39ac571bd276d6407f5481c2da333da3d9 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Sat, 19 Mar 2022 18:06:56 -0400 Subject: [PATCH] update documentation for modifying LAMMPS to reflect changes to Thermo class --- doc/src/Modify_thermo.rst | 67 ++++++++++++++++++++++++++----------- doc/src/Modify_variable.rst | 19 ++++++----- 2 files changed, 57 insertions(+), 29 deletions(-) diff --git a/doc/src/Modify_thermo.rst b/doc/src/Modify_thermo.rst index ea09e30c1d..522a806613 100644 --- a/doc/src/Modify_thermo.rst +++ b/doc/src/Modify_thermo.rst @@ -1,27 +1,54 @@ Thermodynamic output options ============================ -There is one class that computes and prints thermodynamic information -to the screen and log file; see the file thermo.cpp. +The ``Thermo`` class computes and prints thermodynamic information to +the screen and log file; see the files ``thermo.cpp`` and ``thermo.h``. -There are two styles defined in thermo.cpp: "one" and "multi". There -is also a flexible "custom" style which allows the user to explicitly -list keywords for quantities to print when thermodynamic info is -output. See the :doc:`thermo_style ` command for a list -of defined quantities. +There are four styles defined in ``thermo.cpp``: "one", "multi", "yaml", +and "custom". The "custom" style allows the user to explicitly list +keywords for individual quantities to print when thermodynamic output is +generated. The others have a fixed list of keywords. See the +:doc:`thermo_style ` command for a list of available +quantities. The formatting of the "custom" style defaults to the "one" +style, but can be adapted using :doc:`thermo_modify line `. -The thermo styles (one, multi, etc) are simply lists of keywords. -Adding a new style thus only requires defining a new list of keywords. -Search for the word "customize" with references to "thermo style" in -thermo.cpp to see the two locations where code will need to be added. +The thermo styles (one, multi, etc) are defined by lists of keywords +with associated formats for integer and floating point numbers and +identified but an enumerator constant. Adding a new style thus mostly +requires defining a new list of keywords and the associated formats and +then inserting the required output processing where the enumerators are +identified. Search for the word "CUSTOMIZATION" with references to +"thermo style" in the ``thermo.cpp`` file to see the locations where +code will need to be added. The member function ``Thermo::header()`` +prints output at the very beginning of a thermodynamic output block and +can be used to print column headers or other front matter. The member +function ``Thermo::footer()`` prints output at the end of a +thermodynamic output block. The formatting of the output is done by +assembling a "line" (which may span multiple lines if the style inserts +newline characters ("\n" as in the "multi" style). -New keywords can also be added to thermo.cpp to compute new quantities -for output. Search for the word "customize" with references to -"keyword" in thermo.cpp to see the several locations where code will -need to be added. +New thermodynamic keywords can also be added to ``thermo.cpp`` to +compute new quantities for output. Search for the word "CUSTOMIZATION" +with references to "keyword" in ``thermo.cpp`` to see the several +locations where code will need to be added. Effectively, you need to +define a member function that computes the property, add an if statement +in ``Thermo::parse_fields()`` where the corresponding header string for +the keyword and the function pointer is registered by calling the +``Thermo::addfield()`` method, and add an if statement in +``Thermo::evaluate_keyword()`` which is called from the ``Variable`` +class when a thermo keyword is encountered. -Note that the :doc:`thermo_style custom ` command already allows -for thermo output of quantities calculated by :doc:`fixes `, -:doc:`computes `, and :doc:`variables `. Thus, it may -be simpler to compute what you wish via one of those constructs, than -by adding a new keyword to the thermo command. +.. note:: + + The third argument to ``Thermo::addfield()`` is a flag indicating + whether the function for the keyword computes a floating point + (FLOAT), regular integer (INT), or big integer (BIGINT) value. This + information is used for formatting the thermodynamic output. Inside + the function the result must then be stored either in the ``dvalue``, + ``ivalue`` or ``bivalue`` member variable, respectively. + +Since the :doc:`thermo_style custom ` command allows to +use output of quantities calculated by :doc:`fixes `, +:doc:`computes `, and :doc:`variables `, it may often +be simpler to compute what you wish via one of those constructs, rather +than by adding a new keyword to the thermo_style command. diff --git a/doc/src/Modify_variable.rst b/doc/src/Modify_variable.rst index ded76af9da..915ed5fcf3 100644 --- a/doc/src/Modify_variable.rst +++ b/doc/src/Modify_variable.rst @@ -1,8 +1,8 @@ Variable options ================ -There is one class that computes and stores :doc:`variable ` -information in LAMMPS; see the file variable.cpp. The value +The ``Variable`` class computes and stores :doc:`variable ` +information in LAMMPS; see the file ``variable.cpp``. The value associated with a variable can be periodically printed to the screen via the :doc:`print `, :doc:`fix print `, or :doc:`thermo_style custom ` commands. Variables of style @@ -19,21 +19,22 @@ of arguments: compute values = c_mytemp[0], c_thermo_press[3], ... Adding keywords for the :doc:`thermo_style custom ` -command (which can then be accessed by variables) is discussed on the -:doc:`Modify thermo ` doc page. +command (which can then be accessed by variables) is discussed in the +:doc:`Modify thermo ` documentation. Adding a new math function of one or two arguments can be done by -editing one section of the Variable::evaluate() method. Search for +editing one section of the ``Variable::evaluate()`` method. Search for the word "customize" to find the appropriate location. Adding a new group function can be done by editing one section of the -Variable::evaluate() method. Search for the word "customize" to find -the appropriate location. You may need to add a new method to the -Group class as well (see the group.cpp file). +``Variable::evaluate()`` method. Search for the word "customize" to +find the appropriate location. You may need to add a new method to the +Group class as well (see the ``group.cpp`` file). Accessing a new atom-based vector can be done by editing one section of the Variable::evaluate() method. Search for the word "customize" to find the appropriate location. Adding new :doc:`compute styles ` (whose calculated values can -then be accessed by variables) is discussed on the :doc:`Modify compute ` doc page. +then be accessed by variables) is discussed in the :doc:`Modify compute +` documentation.