complete LAMMPS shell docs interation. Warn if exceptions are missing but don't fail

cmake/CMakeLists.txt

@@ -643,20 +643,19 @@ if(BUILD_TOOLS)
   install(FILES ${LAMMPS_DOC_DIR}/msi2lmp.1 DESTINATION ${CMAKE_INSTALL_MANDIR}/man1)
 endif()
 
-if(BUILD_SHELL)
+if(BUILD_LAMMPS_SHELL)
   include(FindPkgConfig)
   pkg_check_modules(READLINE IMPORTED_TARGET readline)
   if(PKG_CONFIG_FOUND AND READLINE_FOUND)
     if(NOT LAMMPS_EXCEPTIONS)
-      message(FATAL_ERROR "The LAMMPS shell requires LAMMPS_EXCEPTIONS enabled")
+      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)
+    target_link_libraries(lammps-shell PRIVATE lammps;PkgConfig::READLINE)
-    target_link_libraries(lammps-shell PRIVATE PkgConfig::READLINE)
     install(TARGETS lammps-shell DESTINATION ${CMAKE_INSTALL_BINDIR})
   else()
-    message(WARNING "PkgConfig info for readline library not found, skipping build of 'lammps-shell'")
+    message(FATAL_ERROR "pkg-config and readline library not found. Cannot build LAMMPS shell")
   endif()
 endif()
 

doc/src/Build_basics.rst

@@ -541,7 +541,8 @@ using CMake or Make.
 
       .. code-block:: bash
 
-         -D BUILD_TOOLS=value       # yes or no (default)
+         -D BUILD_TOOLS=value         # yes or no (default)
+         -D BUILD_LAMMPS_SHELL=value  # yes or no (default)
 
       The generated binaries will also become part of the LAMMPS installation
       (see below).
@@ -557,6 +558,9 @@ using CMake or Make.
          make micelle2d        # build only micelle2d tool
          make thermo_extract   # build only thermo_extract tool
 
+         cd lammps/tools/lammps-shell
+         make                  # build LAMMPS shell
+
 ----------
 
 .. _install:

doc/src/Howto_cmake.rst

@@ -328,6 +328,8 @@ Some common LAMMPS specific variables
      - build LAMMPS with OpenMP support (default: ``on`` if compiler supports OpenMP fully, else ``off``)
    * - ``BUILD_TOOLS``
      - compile some additional executables from the ``tools`` folder (default: ``off``)
+   * - ``BUILD_LAMMPS_SHELL``
+     - compile the LAMMPS shell from the ``tools/lammps-shell`` folder (default: ``off``)
    * - ``BUILD_DOC``
      - include building the HTML format documentation for packaging/installing (default: ``off``)
    * - ``CMAKE_TUNE_FLAGS``

doc/src/Tools.rst

@@ -92,6 +92,7 @@ Miscellaneous tools
    * :ref:`emacs <emacs>`
    * :ref:`i-pi <ipi>`
    * :ref:`kate <kate>`
+   * :ref:`LAMMPS shell <lammps_shell>`
    * :ref:`singularity <singularity_tool>`
    * :ref:`vim <vim>`
 
@@ -397,10 +398,130 @@ The file was provided by Alessandro Luigi Sellerio
 
 ----------
 
+.. _lammps_shell:
+
+LAMMPS shell
+------------
+
+Overview
+========
+
+The LAMMPS Shell, ``lammps-shell`` is a program that functions very
+similar to the regular LAMMPS executable but has several modifications
+and additions that make it more powerful for interactive sessions,
+i.e. where you type LAMMPS commands from the prompt instead of reading
+them from a file.
+
+- It uses the readline and history libraries to provide command line
+  editing and context aware TAB-expansion (details on that below).
+
+- When processing an input file with the '-in' or '-i' flag from the
+  command line, it does not exit at the end of that input file but
+  stops at a prompt, so that additional commands can be issued
+
+- Errors will not abort the shell but return to the prompt.
+
+- It has additional commands aimed at interactive use (details below).
+
+- Interrupting a calculation with CTRL-C will not terminate the
+  session but rather enforce a timeout to cleanly stop an ongoing
+  run (more info on timeouts is in the timer command documentation).
+
+These enhancements makes the LAMMPS shell an attractive choice for
+interactive LAMMPS sessions in graphical user interfaces.
+
+TAB-expansion
+=============
+
+When writing commands interactively at the shell prompt, you can hit
+the TAB key at any time to try and complete the text.  This completion
+is context aware and will expand any first word only to commands
+available in that executable.
+
+- For style commands it will expand to available styles of the
+  corresponding categrory (e.g. pair styles after a
+  :doc:`pair_style <pair_style>` command).
+
+- For :doc:`compute <compute>`, :doc:`fix <fix>`, or :doc:`dump <dump>`
+  it will also expand only to already defined groups for the group-ID
+  keyword.
+
+- For commands like :doc:`compute_modify <compute_modify>`,
+  :doc:`fix_modify <fix_modify>`, or :doc:`dump_modify <dump_modify>`
+  it will expand to known compute/fix/dump IDs only.
+
+- When typing references to computes, fixes, or variables with a
+  "c\_", "f\_", or "v\_" prefix, respectively, then the expansion will
+  to known compute/fix IDs and variable names. Variable name expansion
+  is also available for the ${name} variable syntax.
+
+- In all other cases, expansion will be performed on filenames.
+
+
+Command line editing and history
+================================
+
+When typing commands, command line editing similar to what BASH
+provides is available.  Thus it is possible to move around the
+currently line and perform various cut and insert and edit operations.
+Previous commands can be retrieved by scrolling up (and down)
+or searching (e.g. with CTRL-r).
+
+Also history expansion through using the exclamation mark '!'
+can be performed.  Examples: '!!' will be replaced with the previous
+command, '!-2' will repeat the command before that, '!30' will be
+replaced with event number 30 in the command history list, and
+'!run' with the last command line that started with "run".  Adding
+a ":p" to such a history expansion will result that the expansion is
+printed and added to the history list, but NOT executed.
+On exit the LAMMPS shell will write the history list to a file
+".lammps_history" in the current working directory.  If such a
+file exists when the LAMMPS shell is launched it will be read to
+populate the history list.
+
+This is realized via the readline library and can thus be customised
+with an .inputrc file in the home directory.  For application specific
+customizations, the LAMMPS shell uses the name "lammps-shell".
+For more information about using and customizing an application using
+readline, please see the available documentation at:
+`http://www.gnu.org/s/readline/#Documentation <http://www.gnu.org/s/readline/#Documentation>`_
+
+Additional commands
+===================
+
+The followind commands are added to the LAMMPS shell on top of the
+regular LAMMPS commands:
+
+.. parsed-literal::
+
+   help (or ?)    print a brief help message
+   history        display the current command history list
+   clear_history  wipe out the current command history list
+   \|<command>     execute <command> as a shell command and return to the command prompt
+   exit           exit the LAMMPS shell cleanly (unlike the "quit" command)
+
+Compilation
+===========
+
+Compilation of the LAMMPS shell can be enabled by setting the CMake
+variable ``BUILD_LAMMPS_SHELL`` to "on" or using the makefile in the
+``tools/lammps-shell`` folder to compile after building LAMMPS using
+the conventional make procedure.  The makefile will likely need
+customization depending on the features and settings used for
+compiling LAMMPS.
+
+Limitations
+===========
+
+The LAMMPS shell was not designed for use with MPI parallelization
+via ``mpirun`` or ``mpiexec`` or ``srun``.
+
+----------
+
 .. _arc:
 
 lmp2arc tool
-----------------------
+------------
 
 The lmp2arc sub-directory contains a tool for converting LAMMPS output
 files to the format for Accelrys' Insight MD code (formerly

tools/lammps-shell/README

@@ -48,9 +48,7 @@ available in that executable.
   to known compute/fix IDs and variable names. Variable name expansion
   is also available for the ${name} variable syntax.
 
-- In all other cases, expansion will be 
+- In all other cases, expansion will be performed on filenames.
-
-For all other
 
 Command line editing and history
 ================================
@@ -95,8 +93,8 @@ regular LAMMPS commands:
 Compilation
 ===========
 
-Compilation of the LAMMPS shell can be enabled by setting the
+Compilation of the LAMMPS shell can be enabled by setting the CMake
-CMake variable LAMMPS_SHELL to on or using the makefile in the
+variable BUILD_LAMMPS_SHELL to "on" or using the makefile in the
 tools/lammps-shell folder to compile after building LAMMPS using
 the conventional make procedure.  The makefile will likely need
 customization depending on the features and settings used for
@@ -105,4 +103,5 @@ compiling LAMMPS.
 Limitations
 ===========
 
-The LAMMPS shell was not designed for use with MPI parallelization.
+The LAMMPS shell was not designed for use with MPI parallelization
+via "mpirun" or "mpiexec" or "srun".

tools/lammps-shell/lammps-shell.cpp

@@ -3,6 +3,8 @@
 
 // Copyright (c) 2020 Axel Kohlmeyer <akohlmey@gmail.com>
 
+// This software is distributed under the GNU General Public License.
+
 #include "library.h"
 #include "utils.h"
 
@@ -561,6 +563,10 @@ int main(int argc, char **argv)
     std::string trimmed;
 
     std::cout << "LAMMPS Shell version 1.0\n";
+    if (!lammps_config_has_exceptions())
+        std::cout << "WARNING: LAMMPS was compiled without exceptions\n"
+                     "WARNING: Some features will not work as expected\n";
+
     lmp = lammps_open_no_mpi(argc, argv, nullptr);
     if (lmp == nullptr) return 1;