ICODE-ADC/lammps
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update LAMMPS GUI documentation for Version 1.5

Browse Source
This commit is contained in:
Axel Kohlmeyer
2023-09-02 11:50:20 -04:00
parent cf9ce0ebed
commit 2d17894430
7 changed files with 181 additions and 109 deletions
Download Patch File Download Diff File Expand all files Collapse all files

286
doc/src/Howto_lammps_gui.rst
View File

@ -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
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 <run>`.
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
<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
status bar will be "Failed." instead of "Ready."
triggered will be highlighted. The state of LAMMPS as shown in the
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
screen output and the chart window with a line graph created from the
thermodynamic output of the run. More information on those is below.
Additionally, up to three windows will open during a run:
The run can be stopped cleanly by using either the ``Stop LAMMPS`` entry
in the ``Run`` menu, the hotkey `Ctrl-/` (`Command-/` on macOS), or
clicking on the red button in the status bar. This will cause that the
running LAMMPS process will complete the current iteration and then
stop. 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.
- a log window with the captured screen output
- a chart window with a line graph created from the thermodynamic output of the run
- a slide show window with images created by a :doc:`dump image command <dump_image>`
More information on those windows and how to adjust their behavior and
contents is below.
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
output of the LAMMPS calculation as shown below.
By default, when starting a run, a "Log Window" will open that displays
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
the LAMMPS command in a command line window. LAMMPS GUI captures it and will
update the window regularly during a run with the output as it is generated.
LAMMPS GUI captures the screen output and updates the log window
regularly during a run with it as it is generated.
By default, there will be a new window for each run, so that it is possible to
compare outputs from different runs with, for example, changes to some settings.
But it is also possible to change the behavior of LAMMPS GUI to *replace* an
existing log window for a new run or to not show the window by default. It
is possible to show or hide this window from the ``View`` menu.
By default, there will be a new window for each run, so that it is
possible to visually compare outputs from different runs. It is also
possible to change the behavior of LAMMPS GUI in the preferences dialog
to *replace* an existing log window for a new run or to not show the log
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
of the thermodynamic output of the LAMMPS calculation as shown below.
By default, when starting a run, a "Chart Window" will open that
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
they can be used to visually monitor the evolution of the available
properties. The drop down menu on the top right allows to select
between the different properties that are written to the output. Only
one property can be shown at a time. From the ``File`` menu on the top
left, it is possible to save an image of the currently displayed chart
or export the data in either plain text columns (as usable for plotting
tools like `gnuplot <http://www.gnuplot.info/>`_ or `grace
The drop down menu on the top right allows to select between the
different properties that are computed and written to the output. Only
one property can be shown at a time. These charts will be updated with
new data as the run progresses, so they can be used to visually monitor
the evolution of the available properties. From the ``File`` menu on
the top left, it is possible to save an image of the currently displayed
chart or export the data in either plain text columns (as usable for
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
unless the format, number, or names of output columns are changed or the
current time step is reset with :doc:`reset_timestep <reset_timestep>`
or a :doc:`clear <clear>` command is issued.
Data from multiple successive run commands will be combined into a
single data set unless the format, number, or names of output columns
are changed with a :doc:`thermo_style <thermo_style>` or
: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
will try to detect which elements the atoms correspond to (via their
mass) and then colorize them accordingly. Otherwise some predefined
sequence of colors is assigned to the different atom types.
snapshot image with the current state of the system into an image viewer
window. This functionality is not available *during* an ongoing run.
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
horizontally and vertically and it is possible to only display the atoms
within a predefined group (default is "all"). After each change, the
image is rendered again and the display updated. The small palette icon
on the top left will be colored while LAMMPS is running to render the
new image and it will be grayed out again, when it is done. When there
are many items to show and high quality images with anti-aliasing are
requested, re-rendering can take several seconds. From the ``File``
menu, the shown image can be saved to a file permanently or copied into
the cut-n-paste buffer for pasting into another application.
display of box or axes, zoom factor. The view on the system can be
rotated horizontally and vertically, and it is possible to only display
the atoms within a group defined in the input (default is "all"). After
each change, the image is rendered again and the display updated. The
small palette icon on the top left will be colored while LAMMPS is
running to render the new image and it will be grayed out again, when it
is done. When there are many items to show and high quality images with
anti-aliasing are requested, re-rendering can take several seconds.
From the ``File`` menu of the image window, the shown image can be saved
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
log output, charts, variables, images. The default settings for those
can be changed in the ``Preferences dialog``.
The ``View`` menu offers to show or hide the additional windows with log
output, charts, slide show, variables, or snapshot images. The default
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
the main page of this LAMMPS documentation at https://docs.lammps.org/.
a minimal description of LAMMPS GUI. The ``LAMMPS GUI Howto`` entry
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

BIN
doc/src/JPG/lammps-gui-prefs-accel.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 33 KiB

After

Width:  |  Height:  |  Size: 36 KiB

BIN
doc/src/JPG/lammps-gui-prefs-editor.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 44 KiB

BIN
doc/src/JPG/lammps-gui-prefs-general.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 68 KiB

After

Width:  |  Height:  |  Size: 75 KiB

BIN
doc/src/JPG/lammps-gui-prefs-image.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 47 KiB

After

Width:  |  Height:  |  Size: 50 KiB

2
tools/lammps-gui/CMakeLists.txt
View File

@ -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)

2
tools/lammps-gui/preferences.cpp
View File

@ -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;