6.1. Launching the GUI

This guide covers installing and starting the NLSQ desktop application.

6.1.1. Installation

Install NLSQ with GUI support:

pip install nlsq

This installs:

  • PySide6 (Qt bindings)

  • pyqtgraph (GPU-accelerated plotting)

6.1.2. Starting the Application

From command line:

nlsq-gui

From Python:

from nlsq.gui_qt import run_desktop

run_desktop()

As a module:

python -m nlsq.gui_qt

6.1.3. First Launch

On first launch:

  1. The main window opens with the Data Loading page

  2. Default theme is light (toggle with Ctrl+T)

  3. Window position and size are saved for next launch

6.1.4. Command Line Options

# Open a specific file
nlsq-gui /path/to/data.csv

# Force dark theme
nlsq-gui --dark

# Show version
nlsq-gui --version

6.1.5. System Requirements

  • Python 3.12+

  • Qt 6.5+ (via PySide6)

  • OpenGL support (for GPU-accelerated plots)

  • ~100MB disk space for dependencies

6.1.6. Platform Notes

Linux:

Install OpenGL libraries if needed:

# Ubuntu/Debian
sudo apt install libgl1-mesa-glx

macOS:

Works on macOS 12+. NLSQ automatically applies several stability guards at import time to prevent SIGBUS crashes on Apple Silicon:

  • Forces software OpenGL rendering (QT_OPENGL=software)

  • Sets MPLBACKEND=Agg for matplotlib

  • Disables multi-threaded XLA (XLA_FLAGS)

  • Enforces CPU-only JAX backend

The sidebar uses native Qt style icons (not emoji) to avoid a Qt text shaping crash on PySide6 6.10+ with macOS 26.

Windows:

Requires Visual C++ Redistributable. Usually already installed. CPU-only JAX backend is enforced automatically.

6.1.7. Troubleshooting Launch Issues

“PySide6 not found”:

pip install nlsq

“Cannot find OpenGL”:

Install graphics drivers or OpenGL libraries.

Application doesn’t start:

# Check for errors with debug logging
NLSQ_DEBUG=1 nlsq-gui

# Or run directly from Python
python -c "from nlsq.gui_qt import run_desktop; run_desktop()"

Blank window or rendering issues:

Try disabling OpenGL acceleration for pyqtgraph plots:

export NLSQ_GUI_USE_OPENGL=0
nlsq-gui

To re-enable OpenGL later:

export NLSQ_GUI_USE_OPENGL=1
nlsq-gui

SIGBUS crash on macOS (safe mode):

If the application crashes on launch, try safe mode which disables deferred timers (autosave, session recovery):

NLSQ_SAFE_MODE=1 nlsq-gui

6.1.8. Next Steps