diff --git a/cmake/CMakeLists.txt b/cmake/CMakeLists.txt index daa2a7d90a..f6b1f204b4 100644 --- a/cmake/CMakeLists.txt +++ b/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 PkgConfig::READLINE) + target_link_libraries(lammps-shell PRIVATE lammps;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() diff --git a/doc/src/Build_basics.rst b/doc/src/Build_basics.rst index 87863e3042..74b6023c3e 100644 --- a/doc/src/Build_basics.rst +++ b/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: diff --git a/doc/src/Howto_cmake.rst b/doc/src/Howto_cmake.rst index 9176600820..30d71edd87 100644 --- a/doc/src/Howto_cmake.rst +++ b/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`` diff --git a/doc/src/Tools.rst b/doc/src/Tools.rst index e3e6b344c0..96c49623d8 100644 --- a/doc/src/Tools.rst +++ b/doc/src/Tools.rst @@ -92,6 +92,7 @@ Miscellaneous tools * :ref:`emacs ` * :ref:`i-pi ` * :ref:`kate ` + * :ref:`LAMMPS shell ` * :ref:`singularity ` * :ref:`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 ` command). + +- For :doc:`compute `, :doc:`fix `, or :doc:`dump ` + it will also expand only to already defined groups for the group-ID + keyword. + +- For commands like :doc:`compute_modify `, + :doc:`fix_modify `, or :doc:`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 `_ + +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 + \| execute 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 diff --git a/tools/lammps-shell/README b/tools/lammps-shell/README index 568d5a1d9e..8a0ec73734 100644 --- a/tools/lammps-shell/README +++ b/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 - -For all other +- In all other cases, expansion will be performed on filenames. Command line editing and history ================================ @@ -95,8 +93,8 @@ regular LAMMPS commands: Compilation =========== -Compilation of the LAMMPS shell can be enabled by setting the -CMake variable LAMMPS_SHELL to on or using the makefile in the +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 @@ -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". diff --git a/tools/lammps-shell/lammps-shell.cpp b/tools/lammps-shell/lammps-shell.cpp index eba89b0a84..cfae8ad50b 100644 --- a/tools/lammps-shell/lammps-shell.cpp +++ b/tools/lammps-shell/lammps-shell.cpp @@ -3,6 +3,8 @@ // Copyright (c) 2020 Axel Kohlmeyer +// 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;