implement LAMMPS_LIB_NO_MPI to LAMMPS_LIB_MPI change

cmake/CMakeLists.txt

@@ -650,7 +650,6 @@ if(BUILD_LAMMPS_SHELL)
     message(WARNING "The LAMMPS shell needs LAMMPS_EXCEPTIONS enabled for full functionality")
   endif()
   add_executable(lammps-shell ${LAMMPS_TOOLS_DIR}/lammps-shell/lammps-shell.cpp)
-  target_compile_definitions(lammps-shell PRIVATE -DLAMMPS_LIB_NO_MPI)
   target_link_libraries(lammps-shell PRIVATE lammps PkgConfig::READLINE)
   install(TARGETS lammps-shell EXPORT LAMMPS_Targets DESTINATION ${CMAKE_INSTALL_BINDIR})
 endif()

doc/src/Library.rst

@@ -58,16 +58,22 @@ functions of the C language API require an argument containing a
 "handle" in the form of a ``void *`` type variable, which points to the
 location of a LAMMPS class instance.
 
-The ``library.h`` header file by default includes the ``mpi.h`` header
-for an MPI library, so it must be present when compiling code using the
-library interface.  This usually must be the header from the same MPI
-library as the LAMMPS library was compiled with.  The exception is when
-LAMMPS was compiled in serial mode using the ``STUBS`` MPI library.  In
-that case the calling code may be compiled with a different MPI library
-so long as :cpp:func:`lammps_open_no_mpi` is called to create a
-LAMMPS instance. Then you may set the define ``-DLAMMPS_LIB_NO_MPI``
-when compiling your code and the inclusion of ``mpi.h`` will be skipped
-and consequently the function :cpp:func:`lammps_open` may not be used.
+The ``library.h`` header file by default does not include the ``mpi.h``
+header file and thus hides the :cpp:func:`lammps_open` function which
+requires the declaration of the ``MPI_comm`` data type.  This is only
+a problem when the communicator that would be passed is different from
+``MPI_COMM_WORLD``.  Otherwise calling :cpp:func:`lammps_open_no_mpi`
+will work just as well.  To make :cpp:func:`lammps_open` available,
+you need to compile the code with ``-DLAMMPS_LIB_MPI`` or add the line
+``#define LAMMPS_LIB_MPI 1`` before ``#include "library.h"``.
+
+Please note the ``mpi.h`` file must usually be the same (and thus the
+MPI library in use) for the LAMMPS code and library and the calling code.
+The exception is when LAMMPS was compiled in serial mode using the
+``STUBS`` MPI library.  In that case the calling code may be compiled
+with a different MPI library so long as :cpp:func:`lammps_open_no_mpi`
+is called to create a LAMMPS instance.  In that case each MPI rank will
+run LAMMPS in serial mode.
 
 .. admonition:: Errors versus exceptions
    :class: note

src/library.cpp

@@ -14,6 +14,7 @@
 // C style library interface to LAMMPS.
 // See the manual for detailed documentation.
 
+#define LAMMPS_LIB_MPI 1
 #include "library.h"
 #include <mpi.h>
 
@@ -140,11 +141,12 @@ fails a null pointer is returned.
 
 .. note::
 
-   This function is not declared when the code linking to the LAMMPS
-   library interface is compiled with ``-DLAMMPS_LIB_NO_MPI``, or
-   contains a ``#define LAMMPS_LIB_NO_MPI 1`` statement before
-   ``#include "library.h"``.  In that case, you must use the
-   :cpp:func:`lammps_open_no_mpi` function.
+   This function is **only** declared when the code using the LAMMPS
+   ``library.h`` include file is compiled with ``-DLAMMPS_LIB_MPI``,
+   or contains a ``#define LAMMPS_LIB_MPI 1`` statement before
+   ``#include "library.h"``.  Otherwise you can only use the
+   :cpp:func:`lammps_open_no_mpi` or :cpp:func:`lammps_open_fortran`
+   functions.
 
 *See also*
    :cpp:func:`lammps_open_no_mpi`, :cpp:func:`lammps_open_fortran`

src/library.h

@@ -32,7 +32,7 @@
 
 /* To allow including the library interface without MPI */
 
-#if !defined(LAMMPS_LIB_NO_MPI)
+#if defined(LAMMPS_LIB_MPI)
 #include <mpi.h>
 #endif
 
@@ -87,7 +87,7 @@ extern "C" {
  * Library functions to create/destroy an instance of LAMMPS
  * ---------------------------------------------------------------------- */
 
-#if !defined(LAMMPS_LIB_NO_MPI)
+#if defined(LAMMPS_LIB_MPI)
 void *lammps_open(int argc, char **argv, MPI_Comm comm, void **ptr);
 #endif
 void *lammps_open_no_mpi(int argc, char **argv, void **ptr);

unittest/c-library/test_library_open.cpp

@@ -1,6 +1,7 @@
 // unit tests creating LAMMPS instances via the library interface
 
 #include "lammps.h"
+#define LAMMPS_LIB_MPI 1
 #include "library.h"
 #include <cstdio> // for stdin, stdout
 #include <mpi.h>