From 2d178944302076f1eae15e12c42d53307606dc0d Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Sat, 2 Sep 2023 11:50:20 -0400 Subject: [PATCH] Update LAMMPS GUI documentation for Version 1.5 --- doc/src/Howto_lammps_gui.rst | 286 ++++++++++++++--------- doc/src/JPG/lammps-gui-prefs-accel.png | Bin 34172 -> 36728 bytes doc/src/JPG/lammps-gui-prefs-editor.png | Bin 0 -> 44506 bytes doc/src/JPG/lammps-gui-prefs-general.png | Bin 69378 -> 76737 bytes doc/src/JPG/lammps-gui-prefs-image.png | Bin 48404 -> 50767 bytes tools/lammps-gui/CMakeLists.txt | 2 +- tools/lammps-gui/preferences.cpp | 2 +- 7 files changed, 181 insertions(+), 109 deletions(-) create mode 100644 doc/src/JPG/lammps-gui-prefs-editor.png diff --git a/doc/src/Howto_lammps_gui.rst b/doc/src/Howto_lammps_gui.rst index aa8a224231..cbe119943b 100644 --- a/doc/src/Howto_lammps_gui.rst +++ b/doc/src/Howto_lammps_gui.rst @@ -1,7 +1,7 @@ Using the LAMMPS GUI ==================== -This document describes **LAMMPS GUI version 1.4**. +This document describes **LAMMPS GUI version 1.5**. ----- @@ -16,8 +16,9 @@ compiled alongside LAMMPS. LAMMPS GUI is a simple graphical text editor that is linked to the :ref:`LAMMPS C-library interface ` and thus can run LAMMPS -directly using the contents of the editor's text buffer as input and can -retrieve and display information from LAMMPS while it is running. +directly using the contents of the editor's text buffer as input. It +can retrieve and display information from LAMMPS while it is running and +is in several ways adapted specifically for editing LAMMPS input files. This is similar to what people traditionally would do to run LAMMPS using a command line window: using a regular text editor to edit the @@ -32,9 +33,11 @@ environments and many basic tasks can be done directly from the GUI without switching to a text console or requiring external programs, let alone scripts to extract data from the generated output. This makes it easier for beginners to get started running simple LAMMPS simulations -and thus very suitable for tutorials on LAMMPS. But also keeps the -barrier low to switch to a full featured programming editor and more -sophisticated visualization and analysis tools later. +and thus very suitable for tutorials on LAMMPS since you only need to +use an learn how to use a single program. It is designed, however, to +keep the barrier low to switch to a full featured, standalone +programming editor and more sophisticated visualization and analysis +tools later, when running LAMMPS from a command line. The following text provides a detailed tour of the features and functionality of the LAMMPS GUI. @@ -45,22 +48,23 @@ Main window ----------- When LAMMPS GUI starts, it will show the main window with either an -empty buffer, or the contents of a file loaded. In the latter case it +empty buffer or the contents of a file loaded. In the latter case it may look like the following: .. image:: JPG/lammps-gui-main.png :align: center :scale: 50% -There is the menu bar at the top, then the main editor buffer with the -input file contents in the center with line numbers on the left and the -input colored according to the LAMMPS input file syntax. At the bottom -is the status bar, which shows the status of LAMMPS execution on the -left ("Ready." when idle) and the current working directory on the -right. The size of the main window will be stored when exiting and -restored when starting again. The name of the current file in the -buffer is shown in the window title and the text `*modified*` is added -in case the buffer has modifications that are not yet saved to a file. +There is the menu bar at the top, then the main editor buffer, and a +status bar at the bottom. The input file contents are shown with line +numbers on the left and the input is colored according to the LAMMPS +input file syntax. The status bar shows the status of LAMMPS execution +on the left (e.g. "Ready." when idle) and the current working directory +on the right. The name of the current file in the buffer is shown in +the window title and the text `*modified*` is added in case the buffer +has modifications that are not yet saved to a file. The size of the +main window will be stored when exiting and restored when starting +again. Opening Files ^^^^^^^^^^^^^ @@ -68,12 +72,11 @@ Opening Files The LAMMPS GUI application will try to open the first command line argument as input file, further arguments are ignored. When no argument is given, LAMMPS GUI will start with an empty buffer. Files can also be -opened via the ``File`` menu or by drag-and-drop of a file from a file -manager to the editor window. Only one file can be open at a time, so -opening a new file with a filled buffer will close this buffer and - in -case the buffer has unsaved modifications - will ask to either cancel -the load, discard the changes, or save them to the file. - +opened via the ``File`` menu or by drag-and-drop of a file from a +graphical file manager to the editor window. Only one file can be open +at a time, so opening a new file with a filled buffer will close this +buffer and - in case the buffer has unsaved modifications - will ask to +either cancel the load, discard the changes, or save them to the file. Running LAMMPS ^^^^^^^^^^^^^^ @@ -81,20 +84,20 @@ Running LAMMPS From within the LAMMPS GUI main window LAMMPS can be started either from the ``Run`` menu using the ``Run LAMMPS from Editor Buffer`` entry, by the hotkey `Ctrl-Enter` (`Command-Enter` on macOS), or by clicking on -the green button in the status bar. +the green "Run" button in the status bar. -LAMMPS runs in a separate thread, so the GUI stays responsive and thus -it is able to interact with the running calculation and access its data. -It is important to note, that running LAMMPS this way is using the -contents of the input buffer for the run (via the +LAMMPS runs in a separate thread, so the GUI stays responsive and is is +able to interact with the running calculation and access its data. It +is important to note, that running LAMMPS this way is using the contents +of the input buffer for the run (via the :cpp:func:`lammps_commands_string()` function of the LAMMPS C-library interface), and **not** the file it was read from. Thus, if there are unsaved changes in the buffer, they *will* be used. As an alternative, -it is possible to start LAMMPS with the contents of the file from the -``Run LAMMPS from File`` menu entry or with `Ctrl-Shift-Enter`. This -option is intended as a fallback option, in case the input uses some -functionality that is not compatible with running LAMMPS from a list of -strings. For consistency, any unsaved changes in the buffer must be +it is also possible to start LAMMPS by reading the contents of the file +from the ``Run LAMMPS from File`` menu entry or with `Ctrl-Shift-Enter`. +This option may be required in some rare cases where the input uses some +functionality that is not compatible with running LAMMPS from a string +buffer. For consistency, any unsaved changes in the buffer must be either saved to the file or undone before LAMMPS can be run from a file. .. image:: JPG/lammps-gui-running.png @@ -108,8 +111,8 @@ was selected in the ``Preferences`` dialog. On the right side, a progress bar is shown that displays the estimated progress on the current :doc:`run command `. -Also, line number of the currently executed command will be highlighted -in green. +Also, the line number of the currently executed command will be +highlighted in green. .. image:: JPG/lammps-gui-run-highlight.png :align: center @@ -117,79 +120,90 @@ in green. In case of an error (in the example below the command :doc:`label -