diff --git a/doc/src/Howto_lammps_gui.rst b/doc/src/Howto_lammps_gui.rst index c96130cb89..b1996a3480 100644 --- a/doc/src/Howto_lammps_gui.rst +++ b/doc/src/Howto_lammps_gui.rst @@ -5,39 +5,44 @@ This document describes **LAMMPS GUI version 1.5**. ----- -Pre-compiled, ready-to-use LAMMPS GUI executables for Linux (Ubuntu -20.04LTS or later and compatible), macOS (version 11 aka Big Sur or -later), and Windows (version 10 or later) :ref:`are available -`. The source code of the LAMMPS GUI is included in -the ``tools/lammps-gui`` folder of the LAMMPS distribution and it can be -compiled alongside LAMMPS. - ------ - LAMMPS GUI is a simple graphical text editor that is linked to the :ref:`LAMMPS library ` and thus can run LAMMPS 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 adapted in multiple ways specifically for editing LAMMPS input files. -LAMMPS GUI tries to be similar to what people traditionally would do to -run LAMMPS using a command line window: editing inputs with a text +.. note:: + + Pre-compiled, ready-to-use LAMMPS GUI executables for Linux (Ubuntu + 20.04LTS or later and compatible), macOS (version 11 aka Big Sur or + later), and Windows (version 10 or later) :ref:`are available + ` for download. The executables are linked to + a current version of LAMMPS as well. The source code for the + LAMMPS GUI is included in the ``tools/lammps-gui`` folder of the + LAMMPS distribution and it can be compiled alongside LAMMPS with + CMake. + +LAMMPS GUI tries to be similar to what people traditionally would do +to run LAMMPS using a command line window: editing inputs with a text editor, run LAMMPS on the input with selected command line flags, and -then extract data from the created files and view them. That procedure -is quite effective and often required when running LAMMPS on -high-performance computing facilities, or for people proficient in using -the command line, as that would allow them to select tools for the -individual steps they are more comfortable with. The main benefit of a -GUI application is that it integrates well with graphical desktop -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 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. +then extract data from the created files and view them. That +procedure is quite effective and often required when running LAMMPS on +high-performance computing facilities, or for people proficient in +using the command line, as that allows them to use tools for the +individual steps which they are most comfortable with. + +The main benefit of a GUI application is that 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. It also integrates well with graphical desktop +environments. + +LAMMPS GUI thus makes it easier for beginners to get started running +simple LAMMPS simulations. It is very suitable for tutorials on +LAMMPS since you only need to learn how to use a single program. It +is also designed to keep the barrier low when you decide to switch to +a full featured, standalone programming editor and more sophisticated +visualization and analysis tools and run LAMMPS from a command line. The following text provides a detailed tour of the features and functionality of the LAMMPS GUI. @@ -47,8 +52,8 @@ functionality of the LAMMPS GUI. 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 +When LAMMPS GUI starts, it will show a main window with either an +empty buffer or the contents of a loaded file. In the latter case it may look like the following: .. image:: JPG/lammps-gui-main.png @@ -56,60 +61,64 @@ may look like the following: :scale: 50% There is the typical 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. +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; the word `*modified*` is added if +the buffer edits have not yet saved to a file. The size of the main +window will be stored when exiting and restored when starting again. 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 -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. +argument as a LAMMPS input script, 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 graphical file manager into the editor window. Only one +file can be open at a time, so opening a new file with a filled buffer +will close the buffer. If the buffer has unsaved modifications, you +will be asked to either cancel the operation, discard the changes, or +save them. 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 "Run" button in the status bar. +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 "Run" button in the status bar. All of these +operations will cause LAMMPS to process the entire input script, which +may contain multiple :doc:`run ` or :doc:`minimize ` +commands. LAMMPS runs in a separate thread, so the GUI stays responsive and 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 +able to interact with the running calculation and access data it +produces. 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 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. +interface), and **not** the original file it was read from. Thus, if +there are unsaved changes in the buffer, they *will* be used. As an +alternative, it is also possible to run LAMMPS by reading the contents +of a 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 :align: center :scale: 75% -While LAMMPS is running, the contents of the status bar change: on the -left side there is a text indicating that LAMMPS is running, which will -also show the number of active threads, if thread-parallel acceleration -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 `. +While LAMMPS is running, the contents of the status bar change. On +the left side there is a text indicating that LAMMPS is running, which +will also show the number of active threads, if thread-parallel +acceleration was selected in the ``Preferences`` dialog. On the right +side, a progress bar is shown that displays the estimated progress for +the current :doc:`run command `. Also, the line number of the currently executed command will be highlighted in green. @@ -118,36 +127,36 @@ highlighted in green. :align: center :scale: 75% - -In case of an error (in the example below the command :doc:`label +If an error occurs (in the example below the command :doc:`label