SAXSShell

SAXSShell is a Python toolkit for simulation-driven scattering workflows. It combines Qt applications, supporting tools, and reusable Python workflows for:

• trajectory inspection and frame export
• XYZ to PDB conversion using reference molecules
• cluster extraction and bond-analysis pipelines
• SAXS project setup, prefit modeling, and pyDREAM fitting
• downstream fullrmc preparation helpers

Documentation

Project documentation is published at:

• https://kewh5868.github.io/SAXSShell/

The documentation is organized by workflow rather than by source file. First learn how to process your molecular dynamics trajectory into frames and clusters, then create a project folder for the SAXSShell session:

• Getting Started
• MD Extraction and Cluster Preparation
• Quickstart
• XYZ to PDB Conversion
• SAXS Prefit
• pyDREAM Workflow
• Template System

Installation

SAXSShell is not pip-installable yet. Run it from a source checkout with the repository conda environment file.

git clone https://github.com/kewh5868/SAXSShell.git
cd SAXSShell

macOS, Linux, and WSL

Create the Python 3.12 conda environment from the default environment file:

conda env create -f requirements/saxshell-py312.yml

If the saxshell-py312 environment already exists, update it from the same file:

conda env update -n saxshell-py312 -f requirements/saxshell-py312.yml --prune

Launch the main SAXSShell application from the repository root:

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

Native Windows

On native Windows, use the Windows-specific environment file:

conda env create -f requirements\saxshell-py312-win.yml

If the saxshell-py312 environment already exists, update it from the same file:

conda env update -n saxshell-py312 -f requirements\saxshell-py312-win.yml --prune

From Anaconda Prompt, activate the environment, set PYTHONPATH, and launch the SAXS UI:

conda activate saxshell-py312
set PYTHONPATH=src
python -m saxshell.saxs

You can also launch without activating the environment:

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

From Windows PowerShell, set PYTHONPATH with PowerShell syntax:

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

First Project

Start by preparing the simulation data that the SAXS project will consume:

1. Inspect the MD trajectory and export usable frames with mdtrajectory.
2. Convert frames with xyz2pdb only if residue-aware PDB files are needed.
3. Extract stoichiometry-sorted clusters with clusters.
4. Create a dedicated project folder for the SAXSShell session.
5. Open the SAXSShell application and choose that project folder in Project Setup before building SAXS components.

Docs Local Preview

Install the pinned docs dependencies and start the local preview server from the repository root:

conda run --no-capture-output -n saxshell-py312 python -m pip install -r requirements/docs.txt
conda run --no-capture-output -n saxshell-py312 mkdocs serve

Then open http://127.0.0.1:8000/.

Standalone Tools

These supporting tools can be used independently from the main SAXSShell window, or opened from the main UI when a project-backed workflow is needed:

• mdtrajectory: inspect MD trajectories, review optional CP2K energy data, choose an equilibration cutoff, and export selected frames.
• xyz2pdb: convert extracted XYZ frames into residue-aware PDB files with reference molecule definitions.
• clusters: extract stoichiometry-sorted cluster folders from exported XYZ or PDB frames.
• bondanalysis: measure bond-pair and angle distributions from cluster folders.
• clusterdynamics: build time-binned cluster population heatmaps and lifetime summaries.
• clusterdynamicsml: extend observed cluster dynamics with predicted larger structures and model-comparison outputs.
• pdfsetup: run Debyer-backed trajectory-averaged PDF and partial-PDF calculations.
• blenderxyz: render publication-style structure images with Blender.
• representativefinder: select representative structures from project-backed stoichiometry folders.
• structureviewer: inspect individual structure files in the SAXSShell structure viewer.

External Applications

The conda environment file installs the Python stack, but several optional SAXSShell applications call external software that must be installed separately:

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