Update LAMMPS GUI documentation for Version 1.5

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 <lammps_c_api>` and thus can run LAMMPS
-directly using the contents of the editor's text buffer as input and can
+directly using the contents of the editor's text buffer as input.  It
-retrieve and display information from LAMMPS while it is running.
+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
+and thus very suitable for tutorials on LAMMPS since you only need to
-barrier low to switch to a full featured programming editor and more
+use an learn how to use a single program.  It is designed, however, to
-sophisticated visualization and analysis tools later.
+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
+There is the menu bar at the top, then the main editor buffer, and a
-input file contents in the center with line numbers on the left and the
+status bar at the bottom.  The input file contents are shown with line
-input colored according to the LAMMPS input file syntax.  At the bottom
+numbers on the left and the input is colored according to the LAMMPS
-is the status bar, which shows the status of LAMMPS execution on the
+input file syntax.  The status bar shows the status of LAMMPS execution
-left ("Ready." when idle) and the current working directory on the
+on the left (e.g. "Ready." when idle) and the current working directory
-right.  The size of the main window will be stored when exiting and
+on the right.  The name of the current file in the buffer is shown in
-restored when starting again.  The name of the current file in the
+the window title and the text `*modified*` is added in case the buffer
-buffer is shown in the window title and the text `*modified*` is added
+has modifications that are not yet saved to a file.  The size of the
-in case the buffer has modifications that are not yet saved to a file.
+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
+opened via the ``File`` menu or by drag-and-drop of a file from a
-manager to the editor window.  Only one file can be open at a time, so
+graphical file manager to the editor window.  Only one file can be open
-opening a new file with a filled buffer will close this buffer and - in
+at a time, so opening a new file with a filled buffer will close this
-case the buffer has unsaved modifications - will ask to either cancel
+buffer and - in case the buffer has unsaved modifications - will ask to
-the load, discard the changes, or save them to the file.
+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
+LAMMPS runs in a separate thread, so the GUI stays responsive and is is
-it is able to interact with the running calculation and access its data.
+able to interact with the running calculation and access its data.  It
-It is important to note, that running LAMMPS this way is using the
+is important to note, that running LAMMPS this way is using the contents
-contents of the input buffer for the run (via the
+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
+it is also possible to start LAMMPS by reading the contents of the file
-``Run LAMMPS from File`` menu entry or with `Ctrl-Shift-Enter`.  This
+from the ``Run LAMMPS from File`` menu entry or with `Ctrl-Shift-Enter`.
-option is intended as a fallback option, in case the input uses some
+This option may be required in some rare cases where the input uses some
-functionality that is not compatible with running LAMMPS from a list of
+functionality that is not compatible with running LAMMPS from a string
-strings.  For consistency, any unsaved changes in the buffer must be
+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 <run>`.
 
-Also, line number of the currently executed command will be highlighted
+Also, the line number of the currently executed command will be
-in green.
+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
-<label>` was incorrectly capitalized as 'Label'), and error message
+<label>` was incorrectly capitalized as "Label"), an error message
 dialog will be shown and the line of the input where the error was
-triggered will be highlighted. And the state of LAMMPS as shown in the
+triggered will be highlighted.  The state of LAMMPS as shown in the
-status bar will be "Failed." instead of "Ready."
+status bar will be set to "Failed." instead of "Ready."
 
 .. image:: JPG/lammps-gui-run-error.png
    :align: center
    :scale: 75%
 
-Additionally, two windows will open: the log window with the captured
+Additionally,  up to three windows will open during a run:
-screen output and the chart window with a line graph created from the
-thermodynamic output of the run. More information on those is below.
 
-The run can be stopped cleanly by using either the ``Stop LAMMPS`` entry
+- a log window with the captured screen output
-in the ``Run`` menu, the hotkey `Ctrl-/` (`Command-/` on macOS), or
+- a chart window with a line graph created from the thermodynamic output of the run
-clicking on the red button in the status bar.  This will cause that the
+- a slide show window with images created by a :doc:`dump image command <dump_image>`
-running LAMMPS process will complete the current iteration and then
+
-stop.  This is equivalent to the command :doc:`timer timeout 0 <timer>`
+More information on those windows and how to adjust their behavior and
-and implemented by calling the :cpp:func:`lammps_force_timeout()`
+contents is below.
-function of the LAMMPS C-library interface.
+
+An active LAMMPS run can be stopped cleanly by using either the ``Stop
+LAMMPS`` entry in the ``Run`` menu, the hotkey `Ctrl-/` (`Command-/` on
+macOS), or by clicking on the red button in the status bar.  This will
+cause that the running LAMMPS process to complete the current iteration
+and then complete the processing the input while skipping all run or
+minimize commands.  This is equivalent to the command :doc:`timer
+timeout 0 <timer>` and implemented by calling the
+:cpp:func:`lammps_force_timeout()` function of the LAMMPS C-library
+interface.  Please see the corresponding documentation pages to
+understand the implications of this feature.
 
 Log Window
 ----------
 
-By default, when starting a run, a "Log Window" will open that displays the current
+By default, when starting a run, a "Log Window" will open that displays
-output of the LAMMPS calculation as shown below.
+the current screen output of the LAMMPS calculation, that would normally
+be seen in the command line window, as shown below.
 
 .. image:: JPG/lammps-gui-log.png
    :align: center
    :scale: 50%
 
-This shows the output that would normally be printed to the screen when running
+LAMMPS GUI captures the screen output and updates the log window
-the LAMMPS command in a command line window.  LAMMPS GUI captures it and will
+regularly during a run with it as it is generated.
-update the window regularly during a run with the output as it is generated.
 
-By default, there will be a new window for each run, so that it is possible to
+By default, there will be a new window for each run, so that it is
-compare outputs from different runs with, for example, changes to some settings.
+possible to visually compare outputs from different runs.  It is also
-But it is also possible to change the behavior of LAMMPS GUI to *replace* an
+possible to change the behavior of LAMMPS GUI in the preferences dialog
-existing log window for a new run or to not show the window by default.  It
+to *replace* an existing log window for a new run or to not show the log
-is possible to show or hide this window from the ``View`` menu.
+window by default.  It is also possible to show or hide the current log
+window from the ``View`` menu.
 
 The text in the log window is read-only and cannot be modified, but
 editor commands to select and copy all or parts of the text can be used.
 The "Select All" and "Copy" functions are also available via a context
 menu by clicking with the right mouse button.
 
-
 Chart Window
 ------------
 
-By default, when starting a run, a "Chart Window" will open that displays charts
+By default, when starting a run, a "Chart Window" will open that
-of the thermodynamic output of the LAMMPS calculation as shown below.
+displays a line chart of thermodynamic output of the LAMMPS calculation
+as shown below.
 
 .. image:: JPG/lammps-gui-chart.png
    :align: center
    :scale: 50%
 
-These charts will be updated with new data as the run progresses, so
+The drop down menu on the top right allows to select between the
-they can be used to visually monitor the evolution of the available
+different properties that are computed and written to the output.  Only
-properties.  The drop down menu on the top right allows to select
+one property can be shown at a time.  These charts will be updated with
-between the different properties that are written to the output.  Only
+new data as the run progresses, so they can be used to visually monitor
-one property can be shown at a time.  From the ``File`` menu on the top
+the evolution of the available properties.  From the ``File`` menu on
-left, it is possible to save an image of the currently displayed chart
+the top left, it is possible to save an image of the currently displayed
-or export the data in either plain text columns (as usable for plotting
+chart or export the data in either plain text columns (as usable for
-tools like `gnuplot <http://www.gnuplot.info/>`_ or `grace
+plotting tools like `gnuplot <http://www.gnuplot.info/>`_ or `grace
 <https://plasma-gate.weizmann.ac.il/Grace/>`_), or as CSV data which can
 be imported for further processing with Microsoft Excel or `pandas
 <https://pandas.pydata.org/>`_
 
-Data from multiple run commands will be combined into a single data set
+Data from multiple successive run commands will be combined into a
-unless the format, number, or names of output columns are changed or the
+single data set unless the format, number, or names of output columns
-current time step is reset with :doc:`reset_timestep <reset_timestep>`
+are changed with a :doc:`thermo_style <thermo_style>` or
-or a :doc:`clear <clear>` command is issued.
+:doc:`thermo_modify <thermo_modify>` or the current time step is reset
+with :doc:`reset_timestep <reset_timestep>` or if a :doc:`clear <clear>`
+command is issued.
 
 Image Slide Show
 ----------------
@@ -205,7 +219,7 @@ displays the images created by LAMMPS as they are written.
 The various buttons at the bottom right of the window allow to either
 single step through the list of images or play an animation (as a
 continuous loop or once from first to last).  It is also possible to
-zoom in or zoom out.
+zoom in or zoom out if the displayed image.
 
 Variable Info
 -------------
@@ -231,12 +245,15 @@ Viewing Snapshot Images
 
 By selecting the ``Create Image`` entry in the ``Run`` menu, by hitting
 the `Ctrl-I` (`Command-I` on macOS) hotkey, or by clicking on the
-"palette" button in the status bar, LAMMPS GUI will issue a
+"palette" button in the status bar, LAMMPS GUI will send a custom
 :doc:`write_dump image <dump_image>` command and read the resulting
-snapshot image into an image viewer window.  When possible, LAMMPS GUI
+snapshot image with the current state of the system into an image viewer
-will try to detect which elements the atoms correspond to (via their
+window.  This functionality is not available *during* an ongoing run.
-mass) and then colorize them accordingly.  Otherwise some predefined
+
-sequence of colors is assigned to the different atom types.
+When possible, LAMMPS GUI will try to detect which elements the atoms
+correspond to (via their mass) and then colorize them in the image
+accordingly.  Otherwise the default predefined sequence of colors is
+assigned to the different atom types.
 
 .. image:: JPG/lammps-gui-image.png
    :align: center
@@ -246,16 +263,17 @@ The default image size, some default image quality settings, the view
 style and some colors can be changed in the ``Preferences`` dialog
 window.  From the image viewer window further adjustments can be made:
 actual image size, high-quality rendering, anti-aliasing, view style,
-display of box or axes, zoom factor. The the image can be rotated
+display of box or axes, zoom factor.  The view on the system can be
-horizontally and vertically and it is possible to only display the atoms
+rotated horizontally and vertically, and it is possible to only display
-within a predefined group (default is "all").  After each change, the
+the atoms within a group defined in the input (default is "all").  After
-image is rendered again and the display updated.  The small palette icon
+each change, the image is rendered again and the display updated.  The
-on the top left will be colored while LAMMPS is running to render the
+small palette icon on the top left will be colored while LAMMPS is
-new image and it will be grayed out again, when it is done.  When there
+running to render the new image and it will be grayed out again, when it
-are many items to show and high quality images with anti-aliasing are
+is done.  When there are many items to show and high quality images with
-requested, re-rendering can take several seconds.  From the ``File``
+anti-aliasing are requested, re-rendering can take several seconds.
-menu, the shown image can be saved to a file permanently or copied into
+From the ``File`` menu of the image window, the shown image can be saved
-the cut-n-paste buffer for pasting into another application.
+to a file or copied into the cut-n-paste buffer for pasting into another
+application.
 
 
 Editor Functions
@@ -270,6 +288,36 @@ the editor with a modified buffer, a dialog will pop up asking whether
 to cancel the quit, or don't save or save the buffer's contents to a
 file.
 
+Context Specific Word Completion
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+By default, LAMMPS GUI will display a popup window with possible
+completions for commands or styles after 3 characters of a word have
+been typed. The word can then be completed through selecting an entry by
+scrolling down with the cursor keys and selecting with the 'Enter' key
+or by clicking on the entry with the mouse.  The automatic completion
+popup can be disabled in the ``Preferences`` dialog, but the completion
+can still be requested manually by either hitting 'Shift-TAB' key or by
+right-clicking with the mouse and selecting the option from the context
+menu.  Most of the completion information is taken from the LAMMPS
+instance and thus it will be adjusted to only show options available
+that have been enabled while compiling LAMMPS, however that excludes
+accelerated styles and commands.  Only non-suffix versions are shown.
+
+Line Reformatting
+^^^^^^^^^^^^^^^^^
+
+The editor supports reformatting lines according to the syntax in order
+to have consistently aligned lines.  This primarily means to add padding
+to commands, type specifiers, IDs and names.  This reformatting is
+performed by default when hitting the 'Enter' key to start a new line.
+This feature can be turned off in the ``Preferences`` dialog, but it can
+still be manually performed by hitting the 'TAB' key.
+
+Internally this functionality is achieved by splitting the line into
+"words" and then putting it back together with padding added where
+the context can be detected; otherwise a single blank is used.
+
 Context Specific Help
 ^^^^^^^^^^^^^^^^^^^^^
 
@@ -291,9 +339,9 @@ Menu
 The menu bar the entries ``File``, ``Edit``, ``Run``, ``View``, and ``About``.
 Instead of using the mouse to click on them, the individual menus can also
 be activated by hitting the `Alt` key together with the corresponding underlined
-letter, that is `Alt-f` will activate the ``File`` menu.  For the corresponding
+letter, that is `Alt-F` will activate the ``File`` menu.  For the corresponding
 activated sub-menus, also the underlined letter, together with the `Alt` key can
-be used to select instead of the mouse.
+be used to select entries instead of the using mouse.
 
 File
 ^^^^
@@ -311,7 +359,7 @@ The ``File`` menu offers the usual options:
   edited file.
 
 In addition, up to 5 recent file names will be listed after the ``Open``
-entry that allows to re-open recent files. This list is stored when
+entry that allows to re-open those recent files. This list is stored when
 quitting and recovered when starting again.
 
 Edit
@@ -380,20 +428,22 @@ in the system path.
 View
 ^^^^
 
-The ``View`` menu offers to show or hide the additional windows with
+The ``View`` menu offers to show or hide the additional windows with log
-log output, charts, variables, images.  The default settings for those
+output, charts, slide show, variables, or snapshot images.  The default
-can be changed in the ``Preferences dialog``.
+settings for those can be changed in the ``Preferences dialog``.
 
 About
 ^^^^^
 
 The ``About`` menu finally offers a couple of dialog windows and an
 option to launch the LAMMPS online documentation in a web browser.  The
-``About LAMMPS GUI`` entry displays a dialog with a summary of the
+``About LAMMPS`` entry displays a dialog with a summary of the
 configuration settings of the LAMMPS library in use and the version
 number of LAMMPS GUI itself.  The ``Quick Help`` displays a dialog with
-a minimal description of LAMMPS GUI.  And ``LAMMPS Manual`` will open
+a minimal description of LAMMPS GUI.  The ``LAMMPS GUI Howto`` entry
-the main page of this LAMMPS documentation at https://docs.lammps.org/.
+will open this documentation page from the online documentation in a web
+browser window.  And ``LAMMPS Manual`` will open the main page of the
+LAMMPS documentation in the web browser.
 
 -----
 
@@ -405,15 +455,18 @@ and looks of the LAMMPS GUI application.  The settings are grouped
 and each group is displayed within a tab.
 
 .. |guiprefs1| image:: JPG/lammps-gui-prefs-general.png
-   :width: 32%
+   :width: 24%
 
 .. |guiprefs2| image:: JPG/lammps-gui-prefs-accel.png
-   :width: 32%
+   :width: 24%
 
 .. |guiprefs3| image:: JPG/lammps-gui-prefs-image.png
-   :width: 32%
+   :width: 24%
 
-|guiprefs1|  |guiprefs2|  |guiprefs3|
+.. |guiprefs4| image:: JPG/lammps-gui-prefs-editor.png
+   :width: 24%
+
+|guiprefs1|  |guiprefs2|  |guiprefs3|  |guiprefs4|
 
 General Settings:
 ^^^^^^^^^^^^^^^^^
@@ -481,6 +534,19 @@ by space filling spheres when checked or by smaller spheres and stick.
 Finally there are a couple of drop down lists to select the background
 and box color.
 
+Editor Settings:
+^^^^^^^^^^^^^^^^
+
+This tab allows to tweak some settings of the editor window.  Specifically
+the amount of padding to be added to LAMMPS commands, types or type ranges,
+IDs (e.g. for fixes), and names (e.g. for groups).  The value set is the
+minimum width for the text element and it can be chosen in the range between
+1 and 32.
+
+The following two settings allow to enable or disable the automatic
+reformatting on hitting the 'Enter' key and the automatic display of the
+completion popup window.
+
 -----------
 
 Hotkeys
@@ -505,14 +571,14 @@ instead of Ctrl/Control).
      - Ctrl+Z
      - Undo edit
      - Ctrl+Enter
-     - Run LAMMPS
+     - Run Input
    * - Ctrl+O
      - Open File
      - Ctrl+Shift+Z
      - Redo edit
      - Ctrl+/
      - Stop Active Run
-   * - CTRL+S
+   * - Ctrl+S
      - Save File
      - Ctrl+C
      - Copy text
@@ -528,11 +594,11 @@ instead of Ctrl/Control).
      - Quit
      - Ctrl+V
      - Paste text
-     - Ctrl-L
+     - Ctrl+L
      - Slide Show
-   * - Ctrl-W
+   * - Ctrl+W
      - Close Window
-     - Ctrl-A
+     - Ctrl+A
      - Select All
      - Ctrl+P
      - Preferences
@@ -546,8 +612,14 @@ instead of Ctrl/Control).
      - LAMMPS Manual
      - Ctrl+?
      - Context Help
-     - Ctrl-Shift-W
+     - Ctrl+Shift+W
      - Show Variables
+   * - Ctrl+Shift+Enter
+     - Run File
+     - TAB
+     - Reformat line
+     - Shift+TAB
+     - Show Completions
 
 Further editing keybindings `are documented with the Qt documentation
 <https://doc.qt.io/qt-5/qplaintextedit.html#editing-key-bindings>`_.  In

tools/lammps-gui/CMakeLists.txt

@@ -1,6 +1,6 @@
 cmake_minimum_required(VERSION 3.16)
 
-project(lammps-gui VERSION 1.5.2 LANGUAGES CXX)
+project(lammps-gui VERSION 1.5.3 LANGUAGES CXX)
 
 set(CMAKE_AUTOUIC ON)
 set(CMAKE_AUTOMOC ON)

tools/lammps-gui/preferences.cpp

@@ -512,7 +512,7 @@ EditorTab::EditorTab(QSettings *_settings, QWidget *parent) : QWidget(parent), s
     auto *typelbl  = new QLabel("Type width:");
     auto *idlbl    = new QLabel("ID width:");
     auto *namelbl  = new QLabel("Name width:");
-    auto *retlbl   = new QLabel("Reformat with 'Return':");
+    auto *retlbl   = new QLabel("Reformat with 'Enter':");
     auto *autolbl  = new QLabel("Automatic completion:");
     auto *cmdval   = new QSpinBox;
     auto *typeval  = new QSpinBox;