Skip to content

GUI Overview

SAXSShell is not a single-window application. The repository contains multiple Qt workflows, each with its own UI and CLI entry point.

Most tools install as direct top-level commands. The SAXS and fullrmc applications currently route through the umbrella saxshell CLI, or through python -m module execution when you are running from a source checkout.

Main UI workflow elements

The primary SAXS workflow lives in saxshell saxs. Its tabs are not isolated: the active template, component list, geometry metadata, and saved state all move between them.

Project Setup now separates two linked actions:

  • Create Computed Distribution saves the current Project Setup snapshot for a specific modeling branch.
  • Build SAXS Components follows the selected build mode for that saved distribution.

The linked supporting-application launches are build-mode aware:

  • No Contrast (Debye) stays in the main SAXS UI and runs the direct Debye component builder.
  • Contrast (Debye) opens the contrast workflow window.
  • Born Approximation (Average) opens Electron Density Mapping in computed-distribution mode.

saxshell saxs

Use this for SAXS project management, prefit modeling, pyDREAM refinement, and template-driven workflows.

Project Setup

Defines the project inputs, computed distributions, and component-build choice.

This is where you:

  • choose the project, datasets, clusters folder, and template
  • set q-range, grid, and excluded-element controls
  • create or load computed distributions
  • optionally compute Debye-Waller factors from PDB cluster folders
  • build SAXS components with the current build mode

The Active Computed Distribution panel on this tab summarizes the saved distribution identity and whether component, prior, Prefit, and DREAM artifacts already exist for that branch.

SAXS Prefit

Builds the lmfit-side preview around the current template, parameter table, and cluster geometry metadata.

Geometry-aware templates can require component metadata derived from the cluster-support workflow before Prefit updates are possible.

SAXS DREAM Fit

Builds and runs the pyDREAM workflow once Prefit is in a usable state.

Results and export

Stores the saved project state, fit artifacts, and downstream handoff files generated by the main SAXS UI.

Shared UI patterns

Several newer SAXS UI surfaces follow the same patterns:

  • progress bars with text status
  • long-running background tasks
  • distribution or readiness indicators next to optional project-backed steps
  • table-based editing for parameters or cluster geometry metadata
  • plot control toggles for experimental, model, and solvent traces

Main UI workflow references

Supporting applications

These applications prepare, analyze, or extend the data that the main SAXS UI consumes. The documentation below is grouped the same way as the main Tools menu.

MD Extraction

Use these tools when you need to move from a raw trajectory to a sorted cluster folder that the rest of the SAXSShell workflow can consume.

  • mdtrajectory inspects trajectories, helps choose an equilibration cutoff, and exports frames for downstream analysis.
  • xyz2pdb converts extracted XYZ frames into residue-aware PDB files when molecule identity matters downstream.
  • clusters builds the stoichiometry-sorted cluster exports used by later workflows.

Structure Analysis

Use these tools when you want to analyze the sorted clusters themselves.

  • bondanalysis measures bond-pair and angle distributions from the cluster folders.
  • Debye-Waller Analysis estimates intra-molecular and inter-molecular Debye-Waller coefficients from sorted PDB cluster folders and saves them in the active project when requested from Project Setup or the Tools menu.

Cluster Dynamics

Use these tools when you need time-resolved cluster populations or want to extend the observed structure series.

  • clusterdynamics builds time-binned cluster-distribution heatmaps, optional energy overlays, and lifetime / association / dissociation summaries.
  • clusterdynamicsml extrapolates larger cluster candidates, generates predicted structures, and compares observed-only versus observed-plus-predicted SAXS models.

PDF

Use this section for pair-distribution workflows tied to the active project.

  • pdfsetup runs Debyer-backed trajectory-averaged PDF and partial-PDF calculations and stores the saved calculation sets in the project.
  • saxshell fullrmc remains the downstream setup path for fullrmc-oriented project artifacts.

Visualization

Use blenderxyz when you need publication-style structure renders that go beyond the inline previewer.

SAXS Calculation Preview

Use these preview-mode tools when you want to inspect SAXS component-building settings outside the main computed-distribution flow.

  • SAXS Contrast Mode is the Contrast (Debye) representative-structure workflow.
  • Electron Density Mapping is the Born Approximation (Average) density-profile and Fourier-transform workflow.

X-ray Toolkit

Use this section for smaller estimate windows such as volume-fraction, number density, attenuation, and fluorescence calculators.

Supporting application references

MD Extraction

Structure Analysis

Cluster Dynamics

PDF

Visualization

SAXS Calculation Preview

X-ray Toolkit

TODO

TODO: add screenshots once the docs site has a stable asset pipeline and the UI labels settle after the current SAXS workflow changes.

Artwork Attribution

The SAXSShell application icon used across the UI, documentation site, and repository README pages is based on artwork generated with ChatGPT (OpenAI).