3. API Reference¶

The following sections provide detailed API documentation for the main classes in LAMMPS-GUI. Documentation is generated from Doxygen comments in the source code.

3.1. Main Window¶

3.1.1. LammpsGui Class¶

class LammpsGui : public QMainWindow¶

Main application window for LAMMPS-GUI.

LammpsGui is the central component of the LAMMPS-GUI application, serving as the main window that coordinates all other components. It manages:

The code editor for LAMMPS input scripts with syntax highlighting
File operations (open, save, recent files)
LAMMPS simulation execution and control
Visualization windows (images, charts, log output)
Application preferences and settings
Tutorial wizard for interactive learning

The class integrates with Qt’s main window framework and provides menu actions, toolbars, and status bar components. It uses a LammpsWrapper to interface with the LAMMPS library and LammpsRunner to execute simulations in a separate thread.

3.1.2. TutorialWizard Class¶

class TutorialWizard : public QWizard¶

Wizard dialog for interactive LAMMPS tutorials.

TutorialWizard provides a step-by-step wizard interface for setting up and running LAMMPS tutorials. It guides users through directory selection, file preparation, and launching tutorial exercises.

Public Functions

TutorialWizard(int ntutorial, QWidget *parent = nullptr)¶

Construct a tutorial wizard.

Parameters:

ntutorial – Tutorial number (1-8)
parent – Parent widget

void accept() override¶

Accept the wizard and set up the tutorial.

Called when the user completes the wizard. Sets up tutorial files and opens the tutorial in the main window.

3.2. Editor Components¶

3.2.1. CodeEditor Class¶

class CodeEditor : public QPlainTextEdit¶

Custom text editor with LAMMPS syntax support and auto-completion.

The CodeEditor class extends QPlainTextEdit to provide specialized features for editing LAMMPS input scripts, including:

Line numbers in a margin area
LAMMPS syntax highlighting via Highlighter
Context-aware auto-completion for LAMMPS commands
Automatic indentation and formatting
Context menu with LAMMPS-specific help
Line highlighting for errors

Public Functions

CodeEditor(QWidget *parent = nullptr)¶

Constructor.

Parameters:: parent – Parent widget (typically the main window)

~CodeEditor() override¶: Destructor.

CodeEditor() = delete¶

CodeEditor(const CodeEditor&) = delete¶

CodeEditor(CodeEditor&&) = delete¶

CodeEditor &operator=(const CodeEditor&) = delete¶

CodeEditor &operator=(CodeEditor&&) = delete¶

void lineNumberAreaPaintEvent(QPaintEvent *event)¶

Paint line numbers in the line number area.

Parameters:: event – Paint event to handle

int lineNumberAreaWidth()¶

Calculate width needed for line number area.

Returns:: Width in pixels

void setFont(const QFont &newfont)¶

Set editor font.

Parameters:: newfont – Font to use for editor text

void setCursor(int block)¶

Set cursor to specific text block.

Parameters:: block – Block number (line number) to position cursor

void setHighlight(int block, bool error)¶

Highlight a specific line (used for error indication)

Parameters:

block – Block number to highlight
error – true for error highlight, false to clear

inline void setReformatOnReturn(bool flag)¶

Enable/disable automatic reformatting on Enter key.

Parameters:: flag – true to enable, false to disable

inline void setAutoComplete(bool flag)¶

Enable/disable automatic completion popup.

Parameters:: flag – true to enable, false to disable

QString reformatLine(const QString &line)¶

Reformat a line with proper indentation.

Parameters:: line – Line to reformat
Returns:: Reformatted line

void setCommandList(const QStringList &words)¶

Set word list for LAMMPS command completion.

Parameters:: words – List of command names

void setFixList(const QStringList &words)¶

Set word list for fix style completion.

Parameters:: words – List of fix style names

void setComputeList(const QStringList &words)¶

Set word list for compute style completion.

Parameters:: words – List of compute style names

void setDumpList(const QStringList &words)¶

Set word list for dump style completion.

Parameters:: words – List of dump style names

void setAtomList(const QStringList &words)¶

Set word list for atom style completion.

Parameters:: words – List of atom style names

void setPairList(const QStringList &words)¶

Set word list for pair style completion.

Parameters:: words – List of pair style names

void setBondList(const QStringList &words)¶

Set word list for bond style completion.

Parameters:: words – List of bond style names

void setAngleList(const QStringList &words)¶

Set word list for angle style completion.

Parameters:: words – List of angle style names

void setDihedralList(const QStringList &words)¶

Set word list for dihedral style completion.

Parameters:: words – List of dihedral style names

void setImproperList(const QStringList &words)¶

Set word list for improper style completion.

Parameters:: words – List of improper style names

void setKspaceList(const QStringList &words)¶

Set word list for kspace style completion.

Parameters:: words – List of kspace style names

void setRegionList(const QStringList &words)¶

Set word list for region style completion.

Parameters:: words – List of region style names

void setIntegrateList(const QStringList &words)¶

Set word list for integration style completion.

Parameters:: words – List of integration style names

void setMinimizeList(const QStringList &words)¶

Set word list for minimization style completion.

Parameters:: words – List of minimization style names

void setVariableList(const QStringList &words)¶

Set word list for variable style completion.

Parameters:: words – List of variable style names

void setUnitsList(const QStringList &words)¶

Set word list for units style completion.

Parameters:: words – List of units style names

void setExtraList(const QStringList &words)¶

Set extra word list for completion.

Parameters:: words – List of extra words

void setGroupList()¶: Update group ID list from current LAMMPS instance.

void setVarNameList()¶: Update variable name list from current LAMMPS instance.

void setComputeIDList()¶: Update compute ID list from current LAMMPS instance.

void setFixIDList()¶: Update fix ID list from current LAMMPS instance.

void setFileList()¶: Update file list from current directory.

Public Static Attributes

static constexpr int NO_HIGHLIGHT = 1 << 30¶: Constant for disabled highlighting.

Protected Functions

void resizeEvent(QResizeEvent *event) override¶

Handle resize events to update line number area.

Parameters:: event – The resize event

bool canInsertFromMimeData(const QMimeData *source) const override¶

Check if MIME data can be inserted (for drag-and-drop)

Parameters:: source – The MIME data to check
Returns:: true if data can be inserted

void dragEnterEvent(QDragEnterEvent *event) override¶

Handle drag enter events.

Parameters:: event – The drag enter event

void dragLeaveEvent(QDragLeaveEvent *event) override¶

Handle drag leave events.

Parameters:: event – The drag leave event

void dropEvent(QDropEvent *event) override¶

Handle drop events.

Parameters:: event – The drop event

void contextMenuEvent(QContextMenuEvent *event) override¶

Handle context menu events.

Parameters:: event – The context menu event

void keyPressEvent(QKeyEvent *event) override¶

Handle key press events (for auto-completion and formatting)

Parameters:: event – The key event

void setDocver()¶: Set LAMMPS documentation version for help links.

3.2.2. LineNumberArea Class¶

class LineNumberArea : public QWidget¶

Widget for displaying line numbers alongside the code editor.

This class provides a custom widget that displays line numbers in the margin of the CodeEditor. It delegates painting to the CodeEditor class.

Public Functions

inline explicit LineNumberArea(CodeEditor *editor)¶

Constructor.

Parameters:: editor – Pointer to the associated CodeEditor

~LineNumberArea() override = default¶: Destructor.

LineNumberArea() = delete¶

LineNumberArea(const LineNumberArea&) = delete¶

LineNumberArea(LineNumberArea&&) = delete¶

LineNumberArea &operator=(const LineNumberArea&) = delete¶

LineNumberArea &operator=(LineNumberArea&&) = delete¶

inline QSize sizeHint() const override¶

Get the ideal size for the line number area.

Returns:: QSize with width from editor, height 0 (fills available height)

3.2.3. Highlighter Class¶

class Highlighter : public QSyntaxHighlighter¶

Syntax highlighter for LAMMPS input scripts.

This class provides syntax highlighting for LAMMPS input files in the CodeEditor. It categorizes and colors different types of LAMMPS commands, keywords, variables, numbers, strings, and comments.

Public Functions

explicit Highlighter(QTextDocument *parent = nullptr)¶

Constructor.

Parameters:: parent – Parent text document to highlight

~Highlighter() override = default¶: Destructor.

Highlighter() = delete¶

Highlighter(const Highlighter&) = delete¶

Highlighter(Highlighter&&) = delete¶

Highlighter &operator=(const Highlighter&) = delete¶

Highlighter &operator=(Highlighter&&) = delete¶

Protected Functions

void highlightBlock(const QString &text) override¶

Highlight a single block (line) of text.

Parameters:: text – The text to highlight

3.3. LAMMPS Interface¶

3.3.1. LammpsWrapper Class¶

class LammpsWrapper¶

C++ wrapper for the LAMMPS C library interface.

This class provides a C++ interface to the LAMMPS library. It wraps the C library API functions and handles dynamic loading of the LAMMPS library when built in plugin mode. All LAMMPS library function calls are routed through this wrapper class.

Public Functions

LammpsWrapper()¶: Constructor - initializes wrapper.

~LammpsWrapper() = default¶: Destructor - cleans up LAMMPS instance if open.

LammpsWrapper(const LammpsWrapper&) = delete¶

LammpsWrapper(LammpsWrapper&&) = delete¶

LammpsWrapper &operator=(const LammpsWrapper&) = delete¶

LammpsWrapper &operator=(LammpsWrapper&&) = delete¶

void open(int nargs, char **args)¶

Create a new LAMMPS instance.

Parameters:

nargs – Number of command-line arguments
args – Command-line arguments array

void close()¶: Close the LAMMPS instance.

void finalize()¶: Finalize MPI (if used) and close LAMMPS.

inline void file(const QString &fname)¶

Process commands from a LAMMPS input file.

Parameters:: fname – Filename (QString version)

inline void file(const std::string &fname)¶

Process commands from a LAMMPS input file.

Parameters:: fname – Filename (std::string version)

void file(const char*)¶

Process commands from a LAMMPS input file.

Parameters:: fname – Filename (C-string version)

inline void command(const QString &cmd)¶

Execute a single LAMMPS command.

Parameters:: cmd – Command string (QString version)

inline void command(const std::string &cmd)¶

Execute a single LAMMPS command.

Parameters:: cmd – Command string (std::string version)

void command(const char*)¶

Execute a single LAMMPS command.

Parameters:: cmd – Command string (C-string version)

inline void commands_string(const QString &cmd)¶

Execute multiple LAMMPS commands from a string.

Parameters:: cmd – Commands string with newlines (QString version)

inline void commands_string(const std::string &cmd)¶

Execute multiple LAMMPS commands from a string.

Parameters:: cmd – Commands string with newlines (std::string version)

void commands_string(const char*)¶

Execute multiple LAMMPS commands from a string.

Parameters:: cmd – Commands string with newlines (C-string version)

void force_timeout()¶: Force a timeout condition in LAMMPS.

int version()¶

Get LAMMPS version number.

Returns:: Version number as integer (YYYYMMDD format)

int extract_setting(const char *keyword)¶

Extract a global setting from LAMMPS.

Parameters:: keyword – Setting name to extract
Returns:: Integer value of the setting

void *extract_global(const char *keyword)¶

Extract a pointer to global data from LAMMPS.

Parameters:: keyword – Name of global data to extract
Returns:: Pointer to the data

void *extract_pair(const char *keyword)¶

Extract pair style data from LAMMPS.

Parameters:: keyword – Name of pair data to extract
Returns:: Pointer to the pair data

void *extract_atom(const char *keyword)¶

Extract atom data from LAMMPS.

Parameters:: keyword – Name of atom data to extract
Returns:: Pointer to the atom data

double extract_variable(const char *keyword)¶

Extract a variable value from LAMMPS.

Parameters:: keyword – Variable name to extract
Returns:: Value of the variable as double

int has_id(const char *idtype, const char *id)¶

Check if a compute/fix/variable ID exists.

Parameters:

idtype – Type of ID (“compute”, “fix”, “variable”)
id – The ID to check

Returns:

1 if exists, 0 otherwise

int id_count(const char *idtype)¶

Get count of IDs of a specific type.

Parameters:: idtype – Type of ID (“compute”, “fix”, “variable”, “group”)
Returns:: Number of IDs of that type

int id_name(const char *idtype, int idx, char *buf, int buflen)¶

Get name of an ID by index.

Parameters:

idtype – Type of ID
idx – Index of the ID
buf – Buffer to store the name
buflen – Length of buffer

Returns:

0 on success, -1 on error

int style_count(const char *keyword)¶

Get count of styles of a specific type.

Parameters:: keyword – Type of style (“compute”, “fix”, “pair”, etc.)
Returns:: Number of available styles

int style_name(const char *keyword, int idx, char *buf, int buflen)¶

Get name of a style by index.

Parameters:

keyword – Type of style
idx – Index of the style
buf – Buffer to store the name
buflen – Length of buffer

Returns:

0 on success, -1 on error

int variable_info(int idx, char *buf, int buflen)¶

Get information about a variable by index.

Parameters:

idx – Variable index
buf – Buffer to store variable info
buflen – Length of buffer

Returns:

Variable type code

double get_thermo(const char *keyword)¶

Get current value of a thermodynamic quantity.

Parameters:: keyword – Thermo keyword
Returns:: Value of the thermo quantity

void *last_thermo(const char *keyword, int idx)¶

Get a specific value from last thermo output.

Parameters:

keyword – Thermo keyword
idx – Index for vector quantities

Returns:

Pointer to the value

inline bool is_open() const¶

Check if LAMMPS instance is open.

Returns:: true if LAMMPS is initialized, false otherwise

bool is_running()¶

Check if LAMMPS is currently executing a run.

Returns:: true if running, false otherwise

bool has_error() const¶

Check if LAMMPS has encountered an error.

Returns:: true if error occurred, false otherwise

int get_last_error_message(char *errorbuf, int buflen)¶

Get the last error message from LAMMPS.

Parameters:

errorbuf – Buffer to store error message
buflen – Length of buffer

Returns:

Error type code

bool config_accelerator(const char *package, const char *category, const char *setting) const¶

Check if an accelerator package is available.

Parameters:

package – Package name
category – Category name
setting – Setting name

Returns:

true if available, false otherwise

bool config_has_package(const char *pkg) const¶

Check if a package is included in LAMMPS build.

Parameters:: pkg – Package name
Returns:: true if included, false otherwise

bool config_has_curl_support() const¶

Check if LAMMPS was built with CURL support.

Returns:: true if CURL is available, false otherwise

bool config_has_omp_support() const¶

Check if LAMMPS was built with OpenMP support.

Returns:: true if OpenMP is available, false otherwise

bool has_gpu_device() const¶

Check if GPU device is available for GPU package.

Returns:: true if GPU device found, false otherwise

inline bool load_lib(const QString &fname)¶

Load LAMMPS shared library (plugin mode)

Parameters:: fname – Library filename (QString version)
Returns:: true on success, false on failure

bool load_lib(const char *lammpslib)¶

Load LAMMPS shared library (plugin mode)

Parameters:: lammpslib – Library filename (C-string version)
Returns:: true on success, false on failure

bool has_plugin() const¶

Check if running in plugin mode.

Returns:: true if plugin mode enabled, false if linked mode

3.3.2. LammpsRunner Class¶

class LammpsRunner : public QThread¶

Worker thread for executing LAMMPS simulations.

This class provides a separate thread for running LAMMPS simulations so that the GUI remains responsive during long-running calculations. It executes LAMMPS commands or input files in the background and emits a signal when complete.

Public Functions

inline LammpsRunner(QObject *parent = nullptr)¶

Constructor.

Parameters:: parent – Parent QObject

~LammpsRunner() override = default¶: Destructor.

LammpsRunner() = delete¶

LammpsRunner(const LammpsRunner&) = delete¶

LammpsRunner(LammpsRunner&&) = delete¶

LammpsRunner &operator=(const LammpsRunner&) = delete¶

LammpsRunner &operator=(LammpsRunner&&) = delete¶

inline void run() override¶

Thread execution function - runs LAMMPS commands or input file.

This function executes in the worker thread. It processes either a string of LAMMPS commands or an input file, then signals completion.

inline void setup_run(LammpsWrapper *_lammps, const char *_input, const char *_file = nullptr)¶

Prepare the runner thread with LAMMPS instance and commands.

Sets up the runner with the LAMMPS instance and input. Clears any previous LAMMPS state with the “clear” command. Either input or file should be provided, not both.

Parameters:

_lammps – Pointer to LammpsWrapper instance
_input – String of LAMMPS commands to execute (can be nullptr)
_file – Input file path to execute (can be nullptr)

Signals

void resultReady()¶: Signal emitted when LAMMPS execution completes.

3.4. Visualization Components¶

3.4.1. ChartWindow Class¶

class ChartWindow : public QWidget¶

Window for displaying and managing multiple time-series charts.

ChartWindow provides a GUI for displaying and manipulating multiple charts showing time-series data from LAMMPS simulations (thermodynamic output). It supports features like data smoothing, normalization, zoom/pan, and export to various formats (PNG, CSV, YAML, DAT).

Public Functions

ChartWindow(const QString &filename, QWidget *parent = nullptr)¶

Constructor.

Parameters:

filename – Path to the log file containing the data
parent – Parent widget

inline int num_charts() const¶

Get the number of charts currently displayed.

Returns:: Number of charts

inline bool has_title(const QString &title, int index) const¶

Check if a chart at given index has the specified title.

Parameters:

title – Title to check
index – Chart index

Returns:

true if chart has the title, false otherwise

int get_step() const¶

Get the current simulation step number.

Returns:: Current step

void reset_charts()¶: Reset all charts to initial state.

void add_chart(const QString &title, int index)¶

Add a new chart to the window.

Parameters:

title – Chart title (thermodynamic property name)
index – Chart index

void add_data(int step, double data, int index)¶

Add a data point to a chart.

Parameters:

step – Simulation step number
data – Data value
index – Chart index

void set_units(const QString &_units)¶

Set the units displayed for thermodynamic quantities.

Parameters:: _units – Units string (e.g., “real”, “metal”, “lj”)

void set_norm(bool norm)¶

Enable/disable data normalization.

Parameters:: norm – true to normalize data, false otherwise

Protected Functions

void closeEvent(QCloseEvent *event) override¶

Handle window close event.

Parameters:: event – Close event

bool eventFilter(QObject *watched, QEvent *event) override¶

Event filter for keyboard shortcuts.

Parameters:

watched – Object being watched
event – Event to filter

Returns:

true if event handled, false otherwise

3.4.2. ChartViewer Class¶

class ChartViewer : public QChartView¶

Individual chart viewer for displaying a single time-series.

ChartViewer extends QChartView to display a single thermodynamic property as a function of simulation time. It supports both raw and smoothed data display, interactive zoom/pan, and provides accessors for data export.

Public Functions

explicit ChartViewer(const QString &title, int index, QWidget *parent = nullptr)¶

Constructor.

Parameters:

title – Chart title (property name)
index – Chart index
parent – Parent widget

~ChartViewer() override¶: Destructor.

ChartViewer() = delete¶

ChartViewer(const ChartViewer&) = delete¶

ChartViewer(ChartViewer&&) = delete¶

ChartViewer &operator=(const ChartViewer&) = delete¶

ChartViewer &operator=(ChartViewer&&) = delete¶

void add_data(int step, double data)¶

Add a data point to the chart.

Parameters:

step – Simulation step number
data – Data value for this step

QRectF get_minmax() const¶

Get the min/max bounds of the data.

Returns:: Rectangle containing data bounds

inline QList<QAbstractAxis*> get_axes() const¶

Get list of chart axes.

Returns:: List of axes (X and Y)

void reset_zoom()¶: Reset zoom to show all data.

void smooth_param(bool _do_raw, bool _do_smooth, int _window, int _order)¶

Set smoothing parameters.

Parameters:

_do_raw – Show raw data series
_do_smooth – Show smoothed data series
_window – Smoothing window size
_order – Polynomial order for Savitzky-Golay

void update_smooth()¶: Recalculate and update smoothed data.

inline int get_index() const¶

Get chart index.

Returns:: Index of this chart

inline int get_count() const¶

Get number of data points.

Returns:: Number of points in series

inline QString get_title() const¶

Get chart title.

Returns:: Title string

inline double get_step(int index) const¶

Get step number at given index.

Parameters:: index – Data point index
Returns:: Step number (X value)

inline double get_data(int index) const¶

Get data value at given index.

Parameters:: index – Data point index
Returns:: Data value (Y value)

void set_tlabel(const QString &tlabel)¶

Set chart title.

Parameters:: tlabel – New title

void set_ylabel(const QString &ylabel)¶

Set Y-axis label.

Parameters:: ylabel – New Y-axis label

inline QString get_tlabel() const¶

Get current chart title.

Returns:: Chart title

inline QString get_xlabel() const¶

Get X-axis label.

Returns:: X-axis label

inline QString get_ylabel() const¶

Get Y-axis label.

Returns:: Y-axis label

3.4.3. ImageViewer Class¶

class ImageViewer : public QDialog¶

Dialog for viewing and manipulating LAMMPS snapshot images.

This class provides an image viewer dialog for displaying LAMMPS snapshots created by the dump image command. It allows interactive manipulation 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.

Public Functions

explicit ImageViewer(const QString &fileName, LammpsWrapper *_lammps, QWidget *parent = nullptr)¶

Constructor.

Parameters:

fileName – Path to the image file to display
_lammps – Pointer to LammpsWrapper for regenerating images
parent – Parent widget

~ImageViewer() override = default¶: Destructor.

ImageViewer() = delete¶

ImageViewer(const ImageViewer&) = delete¶

ImageViewer(ImageViewer&&) = delete¶

ImageViewer &operator=(const ImageViewer&) = delete¶

ImageViewer &operator=(ImageViewer&&) = delete¶

void createImage()¶

Generate image using current settings.

Constructs and executes a LAMMPS dump image command with current visualization parameters and updates the displayed image.

3.4.4. SlideShow Class¶

class SlideShow : public QDialog¶

Slideshow viewer for displaying sequences of images.

SlideShow provides a dialog for viewing and navigating through sequences of images, typically from LAMMPS dump image commands. It supports manual navigation (first/prev/next/last), automatic playback with configurable timing, looping, and zoom controls. Images can be exported as a movie file.

Public Functions

explicit SlideShow(const QString &fileName, QWidget *parent = nullptr)¶

Constructor.

Parameters:

fileName – Path to first image file
parent – Parent widget

~SlideShow() override = default¶: Destructor.

SlideShow() = delete¶

SlideShow(const SlideShow&) = delete¶

SlideShow(SlideShow&&) = delete¶

SlideShow &operator=(const SlideShow&) = delete¶

SlideShow &operator=(SlideShow&&) = delete¶

void add_image(const QString &filename)¶

Add an image to the slideshow sequence.

Parameters:: filename – Path to image file to add

void clear()¶: Clear all images from slideshow.

3.5. Dialog Components¶

3.5.1. FindAndReplace Class¶

class FindAndReplace : public QDialog¶

Find and Replace dialog for the code editor.

FindAndReplace provides a dialog for searching and replacing text in the CodeEditor. It supports case-sensitive/insensitive search, whole word matching, text wrapping, and batch replace operations. The dialog is non-modal so users can continue editing while searching.

Public Functions

explicit FindAndReplace(CodeEditor *_editor, QWidget *parent = nullptr)¶

Constructor.

Parameters:

_editor – Pointer to the CodeEditor to search in
parent – Parent widget

~FindAndReplace() override = default¶: Destructor.

FindAndReplace() = delete¶

FindAndReplace(const FindAndReplace&) = delete¶

FindAndReplace(FindAndReplace&&) = delete¶

FindAndReplace &operator=(const FindAndReplace&) = delete¶

FindAndReplace &operator=(FindAndReplace&&) = delete¶

3.5.2. SetVariables Class¶

class SetVariables : public QDialog¶

Dialog for editing LAMMPS index-style variable definitions.

SetVariables provides a dialog for managing name-value pairs that will be used as index-style variables in LAMMPS input scripts. Users can add, delete, and edit variable definitions. The dialog supports variable substitution using ${varname} syntax.

Public Functions

explicit SetVariables(QList<QPair<QString, QString>> &vars, QWidget *parent = nullptr)¶

Constructor.

Parameters:

vars – Reference to list of variable name-value pairs (modified in place)
parent – Parent widget

~SetVariables() override = default¶: Destructor.

SetVariables() = delete¶

SetVariables(const SetVariables&) = delete¶

SetVariables(SetVariables&&) = delete¶

SetVariables &operator=(const SetVariables&) = delete¶

SetVariables &operator=(SetVariables&&) = delete¶

3.5.3. Preferences Class¶

class Preferences : public QDialog¶

Preferences/Settings dialog for LAMMPS-GUI.

This dialog provides a tabbed interface for configuring various aspects of LAMMPS-GUI including:

General settings (LAMMPS library path, plugins, etc.)
Accelerator package settings
Image viewer defaults
Editor appearance and behavior
Chart viewer settings

Settings are persisted using QSettings and loaded on startup.

Public Functions

explicit Preferences(LammpsWrapper *lammps, QWidget *parent = nullptr)¶

Constructor.

Parameters:

lammps – Pointer to LammpsWrapper for querying LAMMPS configuration
parent – Parent widget

~Preferences() override¶: Destructor - saves settings on close.

Preferences() = delete¶

Preferences(const Preferences&) = delete¶

Preferences(Preferences&&) = delete¶

Preferences &operator=(const Preferences&) = delete¶

Preferences &operator=(Preferences&&) = delete¶

inline void set_relaunch(bool val)¶

Set flag indicating application needs restart.

Some settings require restarting the application to take effect.

Parameters:: val – true if restart needed, false otherwise

3.6. Utility Components¶

3.6.1. FileViewer Class¶

class FileViewer : public QPlainTextEdit¶

Read-only text viewer for displaying file contents.

FileViewer provides a simple read-only text window for viewing file contents. It’s used in the context menu of the code editor to view files referenced in LAMMPS input scripts (data files, potential files, etc.). The viewer supports keyboard shortcuts for closing and stopping the simulation.

Public Functions

FileViewer(const QString &filename, const QString &title = "", QWidget *parent = nullptr)¶

Constructor.

Parameters:

filename – Path to file to display
title – Window title (defaults to filename if empty)
parent – Parent widget

~FileViewer() override = default¶: Destructor.

FileViewer() = delete¶

FileViewer(const FileViewer&) = delete¶

FileViewer(FileViewer&&) = delete¶

FileViewer &operator=(const FileViewer&) = delete¶

FileViewer &operator=(FileViewer&&) = delete¶

Protected Functions

bool eventFilter(QObject *watched, QEvent *event) override¶

Event filter for keyboard shortcuts.

Parameters:

watched – Object being watched
event – Event to filter

Returns:

true if event handled, false otherwise

3.6.2. LogWindow Class¶

class LogWindow : public QPlainTextEdit¶

Window for displaying LAMMPS log output with warning detection.

LogWindow provides a specialized text viewer for LAMMPS log files. It highlights warnings and errors using FlagWarnings, supports extraction of embedded YAML data, navigation to warnings, and opening error documentation URLs. The window shows a summary of detected warnings in the title bar.

Public Functions

LogWindow(const QString &filename, QWidget *parent = nullptr)¶

Constructor.

Parameters:

filename – Path to log file to display
parent – Parent widget

~LogWindow() override¶: Destructor.

LogWindow() = delete¶

LogWindow(const LogWindow&) = delete¶

LogWindow(LogWindow&&) = delete¶

LogWindow &operator=(const LogWindow&) = delete¶

LogWindow &operator=(LogWindow&&) = delete¶

Protected Functions

void closeEvent(QCloseEvent *event) override¶

Handle window close event.

Parameters:: event – Close event

void mouseDoubleClickEvent(QMouseEvent *event) override¶

Handle double-click to open URLs.

Parameters:: event – Mouse event

void contextMenuEvent(QContextMenuEvent *event) override¶

Show context menu with log-specific actions.

Parameters:: event – Context menu event

bool eventFilter(QObject *watched, QEvent *event) override¶

Event filter for keyboard shortcuts.

Parameters:

watched – Object being watched
event – Event to filter

Returns:

true if event handled, false otherwise

bool check_yaml()¶

Check if log contains embedded YAML data.

Returns:: true if YAML data detected, false otherwise

3.6.3. FlagWarnings Class¶

class FlagWarnings : public QSyntaxHighlighter¶

Syntax highlighter for LAMMPS warning and error messages.

FlagWarnings extends QSyntaxHighlighter to detect and highlight warning and error messages in LAMMPS log output. It also detects and highlights URLs for documentation links. The class maintains a count of warnings and updates a summary label.

Public Functions

explicit FlagWarnings(QLabel *label = nullptr, QTextDocument *parent = nullptr)¶

Constructor.

Parameters:

label – Optional label to display warning count summary
parent – Text document to apply highlighting to

~FlagWarnings() override = default¶: Destructor.

FlagWarnings() = delete¶

FlagWarnings(const FlagWarnings&) = delete¶

FlagWarnings(FlagWarnings&&) = delete¶

FlagWarnings &operator=(const FlagWarnings&) = delete¶

FlagWarnings &operator=(FlagWarnings&&) = delete¶

inline int get_nwarnings() const¶

Get the current number of warnings detected.

Returns:: Number of warnings found in the document

Protected Functions

void highlightBlock(const QString &text) override¶

Highlight a single block (line) of text.

Searches for warning/error patterns and URLs, applies formatting, and updates warning count.

Parameters:: text – Text to highlight

3.6.4. StdCapture Class¶

class StdCapture¶

Capture stdout output to a string buffer.

This class provides functionality to redirect and capture standard output (stdout) into a string buffer. Used to capture output from LAMMPS library calls for display in the GUI.

Public Functions

StdCapture()¶: Constructor - initializes capture buffers.

StdCapture(const StdCapture&) = delete¶

StdCapture(StdCapture&&) = delete¶

StdCapture &operator=(const StdCapture&) = delete¶

StdCapture &operator=(StdCapture&&) = delete¶

virtual ~StdCapture()¶: Destructor - restores stdout and frees buffers.

void BeginCapture()¶

Start capturing stdout.

Redirects stdout to an internal pipe for capture

bool EndCapture()¶

Stop capturing stdout and restore original stdout.

Returns:: true if capture was active, false otherwise

std::string GetCapture()¶

Get all captured output and clear the buffer.

Returns:: String containing all captured output

std::string GetChunk()¶

Get a chunk of captured output without clearing.

Returns:: String containing new output since last GetChunk call

double get_bufferuse() const¶

Get the buffer usage as a fraction of max buffer size.

Returns:: Value between 0.0 and 1.0 indicating buffer fullness

3.6.5. Qt Helper Widgets¶

class QHline : public QFrame¶

Horizontal line widget for visual separation in dialogs.

QHline provides a simple horizontal line widget that can be used to visually separate sections in forms and dialogs. It’s essentially a styled QFrame with a horizontal line shape.

Public Functions

QHline(QWidget *parent = nullptr)¶

Constructor.

Parameters:: parent – Parent widget

class QColorCompleter : public QCompleter¶

Auto-completer for color name inputs.

QColorCompleter provides auto-completion for color names in text input fields. It suggests valid color names from Qt’s color name list as the user types.

Public Functions

QColorCompleter(QWidget *parent = nullptr)¶

Constructor.

Parameters:: parent – Parent widget

class QColorValidator : public QValidator¶

Validator for color name inputs.

QColorValidator validates color input fields to ensure they contain valid color names or hex color codes. It can also fix up partially entered color names to valid values.

Public Functions

QColorValidator(QWidget *parent = nullptr)¶

Constructor.

Parameters:: parent – Parent widget

void fixup(QString &input) const override¶

Attempt to fix invalid color input.

Parameters:: input – String to fix (modified in place)

QValidator::State validate(QString &input, int &pos) const override¶

Validate color input string.

Parameters:

input – String to validate
pos – Cursor position (unused)

Returns:

Validation state (Invalid, Intermediate, Acceptable)

3.6.6. Helper Functions¶

Functions

char *mystrdup(const std::string &text)¶

Duplicate a string from std::string.

Parameters:: text – The string to duplicate
Returns:: Pointer to newly allocated C-string (caller must free)

char *mystrdup(const char *text)¶

Duplicate a string from C-string.

Parameters:: text – The C-string to duplicate
Returns:: Pointer to newly allocated C-string (caller must free)

char *mystrdup(const QString &text)¶

Duplicate a string from QString.

Parameters:: text – The QString to duplicate
Returns:: Pointer to newly allocated C-string (caller must free)

int date_compare(const QString &one, const QString &two)¶

Compare two date strings in “YYYY-MM-DD” format.

Parameters:

one – First date string
two – Second date string

Returns:

-1 if one < two, 0 if equal, 1 if one > two

std::vector<std::string> split_line(const std::string &text)¶

Split a string into words while respecting quotes.

Parameters:: text – The string to split
Returns:: Vector of words extracted from the string

class QWidget *get_main_widget()¶

Get pointer to the main LAMMPS-GUI widget.

Returns:: Pointer to the main widget (used for dialogs)

bool has_exe(const QString &exe)¶

Check if an executable is in the system PATH.

Parameters:: exe – The executable name to search for
Returns:: true if executable is found in PATH, false otherwise

void purge_directory(const QString &dir)¶

Recursively delete all files in a directory.

Parameters:: dir – The directory to purge

bool is_light_theme()¶

Determine if the current Qt theme is light or dark.

Returns:: true if light theme, false if dark theme

3. API Reference¶

3.1. Main Window¶

3.1.1. LammpsGui Class¶

3.1.2. TutorialWizard Class¶

3.2. Editor Components¶

3.2.1. CodeEditor Class¶

3.2.2. LineNumberArea Class¶

3.2.3. Highlighter Class¶

3.3. LAMMPS Interface¶

3.3.1. LammpsWrapper Class¶

3.3.2. LammpsRunner Class¶

3.4. Visualization Components¶

3.4.1. ChartWindow Class¶

3.4.2. ChartViewer Class¶

3.4.3. ImageViewer Class¶

3.4.4. SlideShow Class¶

3.5. Dialog Components¶

3.5.1. FindAndReplace Class¶

3.5.2. SetVariables Class¶

3.5.3. Preferences Class¶

3.6. Utility Components¶

3.6.1. FileViewer Class¶

3.6.2. LogWindow Class¶

3.6.3. FlagWarnings Class¶

3.6.4. StdCapture Class¶

3.6.5. Qt Helper Widgets¶

3.6.6. Helper Functions¶

Table of Contents

Previous topic

Next topic