add lammps_kokos_finalize() support to various LAMMPS wrappers and document

doc/src/Library_create.rst

@@ -9,6 +9,7 @@ This section documents the following functions:
 - :cpp:func:`lammps_close`
 - :cpp:func:`lammps_mpi_init`
 - :cpp:func:`lammps_mpi_finalize`
+- :cpp:func:`lammps_kokkos_finalize`
 
 --------------------
 

doc/src/Python_create.rst

@@ -134,7 +134,10 @@ compiled with.
 The :py:func:`lmp.close() <lammps.lammps.close()>` call is
 optional since the LAMMPS class instance will also be deleted
 automatically during the :py:class:`lammps <lammps.lammps>` class
-destructor.
+destructor.  Instead of :py:func:`lmp.close() <lammps.lammps.close()>`
+it is also possible to call :py:func:`lmp.finalize() <lammps.lammps.finalize()>`;
+this will destruct the LAMMPS instance, but also finalized and release
+the MPI and/or Kokkos environment if enabled and active.
 
 Note that you can create multiple LAMMPS objects in your Python
 script, and coordinate and run multiple simulations, e.g.

fortran/lammps.f90

@@ -76,17 +76,15 @@ MODULE LIBLAMMPS
         TYPE(c_ptr), VALUE :: handle
       END SUBROUTINE lammps_close
 
-      SUBROUTINE lammps_mpi_init(handle) BIND(C, name='lammps_mpi_init')
-        IMPORT :: c_ptr
-        TYPE(c_ptr), VALUE :: handle
+      SUBROUTINE lammps_mpi_init() BIND(C, name='lammps_mpi_init')
       END SUBROUTINE lammps_mpi_init
 
-      SUBROUTINE lammps_mpi_finalize(handle) &
-          BIND(C, name='lammps_mpi_finalize')
-        IMPORT :: c_ptr
-        TYPE(c_ptr), VALUE :: handle
+      SUBROUTINE lammps_mpi_finalize() BIND(C, name='lammps_mpi_finalize')
       END SUBROUTINE lammps_mpi_finalize
 
+      SUBROUTINE lammps_kokkos_finalize() BIND(C, name='lammps_kokkos_finalize')
+      END SUBROUTINE lammps_kokkos_finalize
+
       SUBROUTINE lammps_file(handle,filename) BIND(C, name='lammps_file')
         IMPORT :: c_ptr
         TYPE(c_ptr), VALUE :: handle
@@ -188,7 +186,8 @@ CONTAINS
 
     IF (PRESENT(finalize)) THEN
         IF (finalize) THEN
-            CALL lammps_mpi_finalize(self%handle)
+            CALL lammps_kokkos_finalize()
+            CALL lammps_mpi_finalize()
         END IF
     END IF
   END SUBROUTINE lmp_close

python/lammps/core.py

@@ -460,10 +460,16 @@ class lammps(object):
   # -------------------------------------------------------------------------
 
   def finalize(self):
-    """Shut down the MPI communication through the library interface by calling :cpp:func:`lammps_finalize`.
+    """Shut down the MPI communication and Kokkos environment (if active) through the
+       library interface by  calling :cpp:func:`lammps_mpi_finalize` and
+       :cpp:func:`lammps_kokkos_finalize`.
+
+       You cannot create or use any LAMMPS instances after this function is called
+       unless LAMMPS was compiled without MPI and without Kokkos support.
     """
     self.close()
-    self.lib.lammps_finalize()
+    self.lib.lammps_kokkos_finalize()
+    self.lib.lammps_mpi_finalize()
 
   # -------------------------------------------------------------------------
 

src/library.cpp

@@ -334,8 +334,8 @@ The MPI standard requires that any MPI application calls
 do any MPI calls, MPI is still initialized internally to avoid errors
 accessing any MPI functions.  This function should then be called right
 before exiting the program to wait until all (parallel) tasks are
-completed and then MPI is cleanly shut down.  After this function no
-more MPI calls may be made.
+completed and then MPI is cleanly shut down.  After calling this
+function no more MPI calls may be made.
 
 .. versionadded:: 18Sep2020
 
@@ -354,6 +354,23 @@ void lammps_mpi_finalize()
   }
 }
 
+/* ---------------------------------------------------------------------- */
+
+/** Shut down the Kokkos library environment.
+ *
+\verbatim embed:rst
+
+The Kokkos library may only be initialized once during the execution of
+a process.  This is done automatically the first time Kokkos
+functionality is used.  This requires that the Kokkos environment
+must be explicitly shut down after any LAMMPS instance using it is
+closed (to release associated resources).
+After calling this function no Kokkos functionality may be used.
+
+.. versionadded:: TBD
+
+\endverbatim */
+
 void lammps_kokkos_finalize()
 {
   KokkosLMP::finalize();

tools/swig/lammps.i

@@ -63,6 +63,7 @@ extern void  *lammps_open_fortran(int argc, char **argv, int f_comm);
 extern void   lammps_close(void *handle);
 extern void   lammps_mpi_init();
 extern void   lammps_mpi_finalize();
+extern void   lammps_kokkos_finalize();
 extern void   lammps_file(void *handle, const char *file);
 extern char  *lammps_command(void *handle, const char *cmd);
 extern void   lammps_commands_list(void *handle, int ncmd, const char **cmds);
@@ -185,6 +186,7 @@ extern void  *lammps_open_fortran(int argc, char **argv, int f_comm);
 extern void   lammps_close(void *handle);
 extern void   lammps_mpi_init();
 extern void   lammps_mpi_finalize();
+extern void   lammps_kokkos_finalize();
 extern void   lammps_file(void *handle, const char *file);
 extern char  *lammps_command(void *handle, const char *cmd);
 extern void   lammps_commands_list(void *handle, int ncmd, const char **cmds);