document Fortran version of lammps_last_thermo

doc/src/Fortran.rst

@@ -205,12 +205,14 @@ Below is an example demonstrating some of the possible uses.
 
    PROGRAM testprop
      USE LIBLAMMPS
-    USE, INTRINSIC :: ISO_C_BINDING, ONLY : c_double, c_int64_t
+     USE, INTRINSIC :: ISO_C_BINDING, ONLY : c_double, c_int64_t, c_int
      USE, INTRINSIC :: ISO_FORTRAN_ENV, ONLY : OUTPUT_UNIT
      TYPE(lammps) :: lmp
-    INTEGER(KIND=c_int64_t), POINTER :: natoms
+     INTEGER(KIND=c_int64_t), POINTER :: natoms, ntimestep, bval
-    REAL(KIND=c_double), POINTER :: dt
+     REAL(KIND=c_double), POINTER :: dt, dval
-    INTEGER(KIND=c_int64_t), POINTER :: ntimestep
+     INTEGER(KIND=c_int), POINTER :: nfield, typ, ival
+     INTEGER(KIND=c_int) :: i
+     CHARACTER(LEN=11) :: key
      REAL(KIND=c_double) :: pe, ke
 
      lmp = lammps()
@@ -222,6 +224,26 @@ Below is an example demonstrating some of the possible uses.
          lmp%extract_setting('ntypes'), ' atom types'
 
      CALL lmp%command('run 2 post no')
+
+     ntimestep = lmp%last_thermo('step', 0)
+     nfield = lmp%last_thermo('num', 0)
+     WRITE(OUTPUT_UNIT,'(A,I0,A,I0)') 'Last thermo output on step: ', ntimestep, &
+         ',  number of fields: ', nfield
+     DO i=1, nfield
+         key = lmp%last_thermo('keyword',i)
+         typ = lmp%last_thermo('type',i)
+         IF (typ == lmp%dtype%i32) THEN
+             ival = lmp%last_thermo('data',i)
+             WRITE(OUTPUT_UNIT,*) key, ':', ival
+         ELSE IF (typ == lmp%dtype%i64) THEN
+             bval = lmp%last_thermo('data',i)
+             WRITE(OUTPUT_UNIT,*) key, ':', bval
+         ELSE IF (typ == lmp%dtype%r64) THEN
+             dval = lmp%last_thermo('data',i)
+             WRITE(OUTPUT_UNIT,*) key, ':', dval
+         END IF
+     END DO
+
      dt = lmp%extract_global('dt')
      ntimestep = lmp%extract_global('ntimestep')
      WRITE(OUTPUT_UNIT,'(A,I0,A,F4.1,A)') 'At step: ', ntimestep, &
@@ -232,8 +254,8 @@ Below is an example demonstrating some of the possible uses.
      WRITE(OUTPUT_UNIT,'(A,I0)') 'At step: ', ntimestep
      pe = lmp%get_thermo('pe')
      ke = lmp%get_thermo('ke')
-    PRINT*, 'PE = ', pe
+     WRITE(OUTPUT_UNIT,*) 'PE = ', pe
-    PRINT*, 'KE = ', ke
+     WRITE(OUTPUT_UNIT,*) 'KE = ', ke
 
      CALL lmp%close(.TRUE.)
    END PROGRAM testprop
@@ -262,6 +284,8 @@ of the contents of the :f:mod:`LIBLAMMPS` Fortran interface to LAMMPS.
    :ftype style: type(lammps_style)
    :f type: derived type to access lammps type constants
    :ftype type: type(lammps_type)
+   :f dtype: derived type to access lammps data type constants
+   :ftype dtype: type(lammps_dtype)
    :f close: :f:subr:`close`
    :ftype close: subroutine
    :f subroutine error: :f:subr:`error`
@@ -278,6 +302,8 @@ of the contents of the :f:mod:`LIBLAMMPS` Fortran interface to LAMMPS.
    :ftype get_natoms: function
    :f get_thermo: :f:func:`get_thermo`
    :ftype get_thermo: function
+   :f last_thermo: :f:func:`last_thermo`
+   :ftype last_thermo: function
    :f extract_box: :f:subr:`extract_box`
    :ftype extract_box: subroutine
    :f reset_box: :f:subr:`reset_box`
@@ -587,6 +613,96 @@ Procedures Bound to the :f:type:`lammps` Derived Type
 
 --------
 
+.. f:function:: last_thermo(what, index)
+
+   This function will call :cpp:func:`lammps_last_thermo` and returns
+   either a string or a pointer to a cached copy of LAMMPS last thermodynamic
+   output, depending on the data requested through *what*.  Note that *index*
+   uses 1-based indexing to access thermo output columns.
+
+   .. versionadded:: TBD
+
+   Note that this function actually does not return a value, but rather
+   associates the pointer on the left side of the assignment to point to
+   internal LAMMPS data (with the exception of string data, which are
+   copied and returned as ordinary Fortran strings).  Pointers must be
+   of the correct data type to point to said data (typically
+   ``INTEGER(c_int)``, ``INTEGER(c_int64_t)``, or ``REAL(c_double)``).
+   The pointer being associated with LAMMPS data is type-checked at
+   run-time via an overloaded assignment operator.  The pointers
+   returned by this function point to temporary, read-only data that may
+   be overwritten at any time, so their target values need to be copied
+   to local storage if they are supposed to persist.
+
+   For example,
+
+   .. code-block:: fortran
+
+      PROGRAM thermo
+        USE LIBLAMMPS
+        USE, INTRINSIC :: ISO_C_BINDING, ONLY : c_double, c_int64_t, c_int
+        TYPE(lammps) :: lmp
+        INTEGER(KIND=c_int64_t), POINTER :: ntimestep, bval
+        REAL(KIND=c_double), POINTER :: dval
+        INTEGER(KIND=c_int), POINTER :: nfield, typ, ival
+        INTEGER(KIND=c_int) :: i
+        CHARACTER(LEN=11) :: key
+
+        lmp = lammps()
+        CALL lmp%file('in.sysinit')
+
+        ntimestep = lmp%last_thermo('step', 0)
+        nfield = lmp%last_thermo('num', 0)
+        PRINT*, 'Last thermo output on step: ', ntimestep, '  Number of fields: ', nfield
+        DO i=1, nfield
+            key = lmp%last_thermo('keyword',i)
+            typ = lmp%last_thermo('type',i)
+            IF (typ == lmp%dtype%i32) THEN
+                ival = lmp%last_thermo('data',i)
+                PRINT*, key, ':', ival
+            ELSE IF (typ == lmp%dtype%i64) THEN
+                bval = lmp%last_thermo('data',i)
+                PRINT*, key, ':', bval
+            ELSE IF (typ == lmp%dtype%r64) THEN
+                dval = lmp%last_thermo('data',i)
+                PRINT*, key, ':', dval
+            END IF
+        END DO
+        CALL lmp%close(.TRUE.)
+      END PROGRAM thermo
+
+   would extract the last timestep where thermo output was done and the number
+   of columns it printed.  Then it loops over the columns to print out column
+   header keywords and the corresponding data.
+
+   .. note::
+
+      If :f:func:`last_thermo` returns a string, the string must have a length
+      greater than or equal to the length of the string (not including the
+      terminal ``NULL`` character) that LAMMPS returns. If the variable's
+      length is too short, the string will be truncated.  As usual in Fortran,
+      strings are padded with spaces at the end.  If you use an allocatable
+      string, the string **must be allocated** prior to calling this function.
+
+   :p character(len=\*) what: string with the name of the thermo keyword
+   :p integer(c_int) index: 1-based column index
+   :to: :cpp:func:`lammps_last_thermo`
+   :r pointer [polymorphic]: pointer to LAMMPS data. The left-hand side of the
+    assignment should be either a string (if expecting string data) or a
+    C-compatible pointer (e.g., ``INTEGER(c_int), POINTER :: nlocal``) to the
+    extracted property.
+
+   .. warning::
+
+       Modifying the data in the location pointed to by the returned pointer
+       may lead to inconsistent internal data and thus may cause failures,
+       crashes, or bogus simulations.  In general, it is much better
+       to use a LAMMPS input command that sets or changes these parameters.
+       Using an input command will take care of all side effects and necessary
+       updates of settings derived from such settings.
+
+--------
+
 .. f:subroutine:: extract_box([boxlo][, boxhi][, xy][, yz][, xz][, pflags][, boxflag])
 
    This subroutine will call :cpp:func:`lammps_extract_box`. All
@@ -764,13 +880,14 @@ Procedures Bound to the :f:type:`lammps` Derived Type
 
    .. note::
 
-      If :f:func:`extract_global` returns a string, the string must have length
+      If :f:func:`extract_global` returns a string, the string must have
-      greater than or equal to the length of the string (not including the
+      a length greater than or equal to the length of the string (not
-      terminal ``NULL`` character) that LAMMPS returns. If the variable's
+      including the terminal ``NULL`` character) that LAMMPS returns. If
-      length is too short, the string will be truncated. As usual in Fortran,
+      the variable's length is too short, the string will be
-      strings are padded with spaces at the end. If you use an allocatable
+      truncated. As usual in Fortran, strings are padded with spaces at
-      string, the string **must be allocated** prior to calling this function,
+      the end. If you use an allocatable string, the string **must be
-      but you can automatically reallocate it to the correct length after the
+      allocated** prior to calling this function, but you can
+      automatically reallocate it to the correct length after the
       function returns, viz.,
 
       .. code-block :: fortran