Documentation status

This page was generated and edited with the assistance of an LLM and is still in development. It has not been fully vetted by the developer. Verify commands, UI labels, file paths, workflow descriptions, and scientific claims against the current code and your local workflow before relying on it.

If you notice an error, omission, or outdated guidance, please open an issue on GitHub.

GUI Overview

SAXSShell is not a single-window application. The repository contains multiple Qt workflows, each with its own focused UI and source-checkout module launch.

The current user-facing install path runs from a source checkout with the saxshell-py312 conda environment. Start the main application from the repository root with:

PYTHONPATH=src conda run --no-capture-output -n saxshell-py312 python -m saxshell.saxs

Main UI workflow elements

The primary SAXS workflow lives in the main SAXSShell application. 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.
• 1D Born Approximation (Average) opens the legacy radial-density workflow in computed-distribution mode.
• 3D FFT Born Approximation opens the separate Cartesian FFT Born workflow in computed-distribution mode.

Main SAXSShell Application

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

In plain language, this main window is where SAXSShell turns simulation-derived cluster populations and representative structures into a model that can be compared against experimental SAXS data for solvation-structure analysis.

Image placeholder

Add a screenshot of the main SAXSShell window showing the tab bar and the overall page layout a first-time user sees after opening a project.

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.

Image placeholder

Add a screenshot of Project Setup with the computed-distribution panel and component-build controls visible.

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.

Image placeholder

Add a screenshot of SAXS Prefit with the main plot, parameter table, and any geometry-aware controls visible.

SAXS DREAM Fit

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

Image placeholder

Add a screenshot of SAXS DREAM Fit with the runtime settings, prior-map editor button, and results panes visible.

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

• Project Configuration
• Template System
• Pre-loaded SAXS Models
• SAXS Contrast Mode
• SAXS Prefit
• LMFit Workflow
• pyDREAM Workflow
• Results and Export

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.
• Representative Structures selects project-backed representative structures from stoichiometry folders. The beta CLI setup path writes a run file for the same backend when headless execution is preferred.

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. It requires a separate Debyer installation with debyer available to the process.
• The fullrmc workflow remains the downstream setup path for fullrmc-oriented project artifacts.
• The main SAXS window also exposes File > Link Packmol Docker Container... so Packmol can be linked before opening the fullrmc setup window. This path requires Docker plus Packmol installed inside the linked container.
• Inside the fullrmc window, Tools > Link Packmol Docker Container can validate a Packmol-ready Docker container and remember the selected /packmol_input_files project folder for later Packmol input syncs.

Visualization

Use blenderxyz when you need publication-style structure renders that go beyond the inline previewer. It requires a separate Blender installation.

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.
• 1D Born Approximation is the 1D Born Approximation (Average) density-profile and Fourier-transform workflow.
• 3D FFT Born Approximation is the separate Cartesian contrast-density FFT workflow.

X-ray Toolkit

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

CLI Setup

Use this section when you want the GUI to prepare a project-local run file, but you want the heavier work to run later from a terminal.

• XYZ -> PDB CLI Setup saves xyz2pdb_cli_run.json in the project folder so xyz2pdb run /path/to/project can convert XYZ frames to PDB frames and register the PDB output folder with the project.
• Cluster Extraction CLI Setup saves cluster_extraction_cli_run.json in the project folder so clusters run /path/to/project can export clusters and register the clusters output folder with the project.
• Cluster Dynamics CLI Setup saves cluster_dynamics_cli_run.json in the project folder so clusterdynamics run /path/to/project can generate the time-binned heatmap dataset, cluster lifetime table, and association / dissociation rate exports from the terminal.
• Cluster Dynamics ML CLI Setup saves cluster_dynamics_ml_cli_run.json in the project folder so clusterdynamicsml run /path/to/project can run the prediction workflow, write predicted structures and SAXS/profile exports, and keep the outputs linked to the project folder.
• Representative CLI Setup saves representative_structure_cli_run.json in the project folder so representativefinder run /path/to/project can execute the representative-selection backend without the plotting and viewer UI.

Cluster Dynamics and Cluster Dynamics ML also provide batch-run --workers N subcommands for processing multiple prepared project folders from one terminal session.

(beta)

Use this section for early-access workflows that are exposed from the main Tools menu but still need extra caution.

• 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.

Debye-Waller status

The linked Compute Debye-Waller Factors (beta) workflow is currently in testing and has a known bug. Keep that in mind when documenting or using the Project Setup integration path.

Supporting application references

MD Extraction

• MD Extraction and Cluster Preparation
• XYZ to PDB Conversion

Structure Analysis

• Bond Analysis
• Representative Structure CLI

Cluster Dynamics

• Cluster Dynamics
• Cluster Dynamics ML

PDF

• PDF Calculation
• fullrmc Packmol Docker Link

Visualization

• Blender Structure Renderer

SAXS Calculation Preview

• SAXS Contrast Mode
• 1D Born Approximation (Average)
• 3D FFT Born Approximation

X-ray Toolkit

• X-ray Toolkit

(beta)

• Debye-Waller Analysis

External software summary

The conda environment provides the Python dependencies, but these optional applications need external software:

External software	Required by	Install / docs
Debyer	pdfsetup PDF and partial-PDF calculations	Debyer docs and Debyer GitHub
Blender	blenderxyz structure rendering	Blender download and Blender installation manual
Packmol	fullrmc Packmol setup and solvent packing workflows	Packmol GitHub and Packmol user guide
Docker	fullrmc Packmol Docker link workflow	Get Docker

Artwork Attribution

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