1. Overview

LAMMPS-GUI is built using C++17 and the Qt framework (Qt 5.15+ or Qt 6.2+). The application follows object-oriented design principles with separation of concerns between different components:

  • Editor Components: Handle text editing, syntax highlighting, and auto-completion

  • LAMMPS Interface: Wraps the LAMMPS C library API

  • Visualization: Displays images, charts, and simulation output

  • GUI Framework: Main window, dialogs, and preferences

1.1. LAMMPS Interface

LAMMPS-GUI can operate in two modes: Plugin Mode and Linked Mode. The mode is controlled by the -D LAMMPS_GUI_USE_PLUGIN=(ON|OFF) CMake configuration option.

Plugin Mode (default)

LAMMPS is loaded dynamically at runtime from a shared library file (.so, .dll, .dylib). This allows using different LAMMPS builds with different compilation setting and different LAMMPS versions without recompiling the GUI. The library loading is handled in LammpsWrapper using platform-specific dynamic loading functions (dlopen() on Unix/Linux/macOS, LoadLibrary() on Windows). The path to the shared library file is auto-detected or configured via command line or preferences.

Linked Mode LAMMPS library is linked at compile time. Used by

default when building LAMMPS-GUI as part of a LAMMPS CMake build with -D BUILD_LAMMPS_GUI=on. For standalone builds also the -D LAMMPS_SOURCE_DIR=<path to LAMMPS' src folder> and -D LAMMPS_LIBRARY=<path to LAMMPS shared or static library file> settings are required when configuring with CMake. It may be needed to adjust the environment variable to find shared libraries (LD_LIBRARY_PATH on Linux, DYLD_LIBRARY_PATH on macOS, or PATH on Windows) when linked to a shared library.

1.2. Qt Integration

LAMMPS-GUI makes extensive use of Qt features:

Signals and Slots

Used for inter-component communication, especially between GUI components and background threads.

Qt Designer Forms

The main window layout uses a .ui file edited in Qt Designer. Dialogs are created programmatically in C++.

Qt Resource System

Icons and resources embedded via resources/lammpsgui.qrc.

Qt Models

Used for data display in various viewers and inspectors.

LAMMPS-GUI is compatible with Qt version 5.15 or Qt 6.2 and later. If a Qt 6.x version is available it is preferred unless the CMake setting -D LAMMPS_GUI_USE_QT5=yes is used. For Qt versions 6.10 and later the QtGraphs module is used for creating charts instead of the QtCharts module. Using QtCharts can be enforced by setting -D LAMMPS_GUI_USE_QTCHARTS=yes.

For more details on Qt in general, see the Qt Documentation.

2. Architecture

2.1. Main Components

The application architecture consists of several key components organized into functional groups:

2.1.1. Main Window

LammpsGui (lammpsgui.h/.cpp)

The main window class that coordinates all other components. It manages the editor, handles file operations, controls LAMMPS execution, and manages the overall application state. This is the central hub of the application that integrates all other components. See LammpsGui

2.1.2. Editor Components

CodeEditor (codeeditor.h/.cpp)

Custom text editor widget based on QPlainTextEdit, providing LAMMPS-specific features including syntax highlighting, auto-completion, line numbers, and context-sensitive help. The main editing surface for LAMMPS input scripts. See CodeEditor

LineNumberArea (linenumberarea.h)

Widget that displays line numbers in the left margin of the CodeEditor. Updates dynamically as text is added or removed. See LineNumberArea

Highlighter (highlighter.h/.cpp)

Syntax highlighter for LAMMPS input scripts. Categorizes and colors different types of commands, keywords, variables, and comments using Qt’s QSyntaxHighlighter framework. See Highlighter

FindAndReplace (findandreplace.h/.cpp)

Dialog for searching and replacing text in the editor. Supports case sensitivity and whole word matching options. See FindAndReplace

2.1.3. LAMMPS Interface

LammpsWrapper (lammpswrapper.h/.cpp)

C++ wrapper around the LAMMPS C library interface. Provides a clean C++ API and handles dynamic library loading in plugin mode. Manages LAMMPS initialization, command execution, and error handling. See LammpsWrapper

LammpsRunner (lammpsrunner.h)

Worker thread for executing LAMMPS simulations without blocking the GUI. Uses Qt’s threading facilities to run simulations in the background, allowing the UI to remain responsive during long calculations. See LammpsRunner

2.1.4. Visualization Components

ImageViewer (imageviewer.h/.cpp)

Dialog for viewing and manipulating LAMMPS snapshot images created by the dump image command. Supports interactive control of visualization parameters such as zoom, rotation, atom size, coloring, and rendering options. Changes can be applied to regenerate the image using the LAMMPS library interface. See ImageViewer. This uses two internal helper classes:

  • ImageInfo - Stores settings for displaying graphics from a LAMMPS compute or fix in snapshot images.

  • RegionInfo - Stores settings for displaying a region in snapshot images.

ChartWindow (chartviewer.h/.cpp)

Window for displaying thermodynamic data as charts using Qt Charts. Supports line plots and multiple data series. See ChartWindow

ChartViewer (chartviewer.h/.cpp) Custom chart view widget that

provides interactive features like zooming, smoothing, and panning for data visualization. See ChartViewer.

Two implementations exist: The older is based on the QChartView widget from the QtCharts module and the newer implementation is based on QQuickWidget and the QtGraphs module. For Qt versions 6.10 and later the QtGraphs module variant is used and for older versions the QtGraphs module variant. Using the QtCharts can be enforced by setting -D LAMMPS_GUI_USE_QTCHARTS=yes.

SlideShow (slideshow.h/.cpp)

Dialog for viewing multiple images as a slideshow or animation with navigation controls. Supports converting an animation to a movie file when FFmpeg or ImageMagick is available. See SlideShow

RangeSlider (rangeslider.h/.cpp)

Custom slider widget with two handles for selecting a range of values. This is code written by Hoyoung Lee and distributed under the CeCILL-A license as circulated by CEA, CNRS and INRIA at the following URL: “http://www.cecill.info”. Used in ChartWindow for selecting x- and y-direction plot ranges. See RangeSlider

2.1.5. Dialog and Utility Components

LogWindow (logwindow.h/.cpp)

Window displaying captured output from LAMMPS simulations. Updates in real-time as the simulation progresses and highlights warning and error messages. Provides navigation to jump between warnings. See LogWindow

Preferences (preferences.h/.cpp)

Dialog for configuring application settings including accelerator packages, editor appearance, snapshot settings, and chart preferences. Settings are made persistent across LAMMPS-GUI sessions using the QSettings class. See Preferences. The dialog is organized into five tabs, each implemented as a separate widget class:

SetVariables (setvariables.h/.cpp)

Dialog for editing LAMMPS index-style variable definitions. Allows users to define name-value pairs that are substituted in input scripts using ${varname} syntax. See SetVariables

FileViewer (fileviewer.h/.cpp)

Read-only text viewer dialog for displaying file contents. Used for viewing auxiliary files without allowing modifications. See FileViewer

TutorialWizard (lammpsgui.h/.cpp)

Wizard dialog for interactive LAMMPS tutorials. Guides users through setting up tutorial directories and files, providing a structured learning experience. See TutorialWizard

AboutDialog (aboutdialog.h/.cpp)

Custom About dialog that displays version information, LAMMPS configuration details, and available styles in two scrollable text areas. The dialog automatically scrolls down when the content exceeds the visible area, pauses at the bottom, and then returns back to the top. See AboutDialog

2.1.6. Support Components

StdCapture (stdcapture.h/.cpp)

Utility class that captures stdout and stderr output from LAMMPS. Redirects C-level file descriptors to allow capturing output from the LAMMPS library. See StdCapture

FlagWarnings (flagwarnings.h/.cpp)

Syntax highlighter for LAMMPS warning and error messages in log output. Detects and highlights WARNING/ERROR lines and URLs for documentation links. Maintains a count of warnings and updates a summary label. See FlagWarnings

QHline (qaddon.h/.cpp)

Simple horizontal line widget for visual separation in dialogs and forms. See QHline

QColorCompleter (qaddon.h/.cpp)

Auto-completer for color name inputs, suggesting valid Qt color names as the user types. See QColorCompleter

QColorValidator (qaddon.h/.cpp)

Validator for color input fields, ensuring they contain valid color names or hex color codes. See QColorValidator

2.1.7. Helper Functions

The helpers module provides utility functions used throughout the application:

  • String manipulation (mystrdup variants for different string types)

  • Date comparison (date_compare for version comparisons)

  • Command-line parsing (split_line with quote handling)

  • System utilities (has_exe for executable detection)

  • UI utilities (is_light_theme for theme detection)

2.2. Data Flow

  1. User Input: User edits LAMMPS input in CodeEditor with syntax highlighting

  2. Execution Request: User triggers execution via menu or button

  3. Preparation: LammpsGui creates/configures LammpsWrapper and prepares variables

  4. Threading: Commands sent to LammpsRunner thread to avoid UI blocking

  5. Execution: LammpsRunner executes commands via LammpsWrapper

  6. Output Capture: Output captured via StdCapture for display

  7. Visualization: Results displayed in LogWindow, ImageViewer, or ChartWindow

  8. Completion: UI updated when execution completes, progress indicators cleared

2.3. Settings and State Management

The application uses Qt’s QSettings mechanism to persist:

  • Recent files list

  • Window geometry and state

  • Editor preferences (font, colors)

  • Accelerator settings

  • LAMMPS plugin path

  • Tutorial preferences

Settings are stored in platform-specific locations (the application name includes the Qt major version, e.g. LAMMPS-GUI (QT6)):

  • Linux: ~/.config/The LAMMPS Developers/LAMMPS-GUI (QT6).conf

  • macOS: ~/Library/Preferences/org.lammps.LAMMPS-GUI (QT6).plist

  • Windows: Registry under HKEY_CURRENT_USER\Software\The LAMMPS Developers\LAMMPS-GUI (QT6)

2.4. Threading Model

The application uses Qt’s event-driven architecture with threading:

  • Main Thread: Handles all UI operations and user interactions

  • LAMMPS Thread: LammpsRunner executes LAMMPS in a separate QThread

  • Communication: Signals/slots for thread-safe communication between threads

This design keeps the UI responsive even during long-running simulations.