autosaxs 3.0.0

Interactive SAXS pipeline core: calibration, integration, subtraction, ATSAS descriptors, plots, shape fitting, reports. After install, run `autosaxs --help`: epilog lists get-docs, get-skills, get-default-config (export docs and default config into your workspace).

autoSAXS

autoSAXS is a Python toolkit for reproducible small-angle X-ray scattering (SAXS) pipelines — from detector images to subtracted curves, size distributions, and shape models — usable from a CLI, from Python, from desktop GUIs or through your favourite AI agent.

Why autoSAXS

• One skills API for everything — the same processing steps run as autosaxs <skill> … or as Python functions with stable signatures, so scripts, GUIs, and agents share one surface.
• Unique algorithms — automatic calibration from calibrant frames and automatic buffer scaling for robust sample−buffer subtraction, reducing manual tuning at the beamline.
• Flexible inputs — path expressions (file, directory, or glob) instead of “one file only,” with consistent expansion rules.
• Opt-in caching — re-run interactive work without recomputing unchanged steps.
• GUIs when you want them — guisaxs-skills (form-driven skill runner) and guisaxs-liveview (watch-folder live processing with optional monodisperse / polydisperse analysis).
• Built for automation — designed for reproducible beamline-to-analysis workflows and LLM/agent-driven runs via the CLI.
• Seamless AI integration — ship a built-in saxs-processing Cursor/agent skill (autosaxs get-skills) so assistants can orchestrate the pipeline from documented procedures.

Use cases

• Synchrotron or lab SAXS: calibrate geometry, integrate TIFF stacks, average frames, and subtract buffer.
• Monodisperse analysis: Guinier → pair-distance distribution p(r) → optional ab initio shape recovery, 3d primitives modeling or electron density inference.
• Polydisperse analysis: Guinier → size distribution D(R) → optional McSAS or ATSAS MIXTURE.
• Live experiments: watch a folder for new detector images and process them as they arrive.
• Scripting and agents: drive the full pipeline from Python or autosaxs without reimplementing I/O conventions.

Install

Core + CLI:

python -m pip install autosaxs
autosaxs --help

With desktop GUIs (guisaxs-skills, guisaxs-liveview):

python -m pip install "autosaxs[gui]"

Optional LLM helper stack (openai / httpx / requests):

python -m pip install "autosaxs[llm]"

Helper commands (export docs and defaults into a directory):

• autosaxs get-docs — write the short README.md and detailed autosaxs-docs/skills_reference.md
• autosaxs get-skills — write Cursor-style saxs-processing/ skill
• autosaxs get-default-config — copy bundled config_base.conf

From git main (development): python -m pip install "autosaxs @ git+https://github.com/MikhailLifar/autoSAXS.git" or autosaxs -U

Main features

Pipeline stages exposed as skills: calibrate → integrate / average → subtract → analyze → model → report, including Guinier, Kratky, fit-distances (p(r)), fit-sizes (D(R)), model-dam, model-bodies, model-density (DENSS), model-dr-mc (McSAS), model-mixture, and reporting helpers.

Apps: guisaxs-skills (catalog + forms + isolated CLI runs, beta version) guisaxs-liveview (queued live integration, buffer subtraction, optional analysis wizards).

Full per-skill documentation: autosaxs-docs/skills_reference.md.

Quick start

Monodisperse protein walkthrough using examples/monodisperse_protein/ (AgBh calibrant, mask, sample + buffer TIFFs). --q-min / --q-max are the buffer-matching window in nm⁻¹ — pick them from the sample+buffer overlay; 4.8–5.8 fits this example.

Python

from pathlib import Path
from autosaxs.skill import calibrate, integrate, subtract, process_monodisperse

ex = Path("examples/monodisperse_protein")

calibrate(
    ex / "AgBh700_96.9_calib.tif",
    output_dir=str(ex / "calibration"),
    mask=ex / "mask-20260706_133745.txt",
    wavelength=1.445,
)
integrate(
    f"{ex / 'ihs27_buffer.tif'}, {ex / 'ihs27_sample.tif'}",
    ex / "calibration" / "integrator",
    output_dir=str(ex / "integrated"),
)
subtract(
    ex / "integrated" / "int_ihs27_sample.dat",
    ex / "integrated" / "int_ihs27_buffer.dat",
    output_dir=str(ex / "subtracted"),
    q_min=4.8,
    q_max=5.8,
)
process_monodisperse(ex / "subtracted" / "sub_ihs27_sample.dat")

CLI

cd examples/monodisperse_protein

autosaxs calibrate AgBh700_96.9_calib.tif \
  --mask mask-20260706_133745.txt --wavelength 1.445 -o calibration/

autosaxs integrate "ihs27_buffer.tif, ihs27_sample.tif" \
  calibration/integrator/ -o integrated/

autosaxs subtract integrated/int_ihs27_sample.dat integrated/int_ihs27_buffer.dat \
  --q-min 4.8 --q-max 5.8 -o subtracted/

autosaxs process-monodisperse subtracted/sub_ihs27_sample.dat

Online GUI

guisaxs-liveview

Acknowledgements

autoSAXS builds on the SAXS ecosystem rather than replacing it:

• pyFAI — detector geometry, calibration, and 1D integration.
• ATSAS — tools such as autorg, datgnom, gnom, dammif, mixture, and bodies (external install; recommended ATSAS 3.2.1). Importing autoSAXS warns if ATSAS is missing; skills that shell out to ATSAS raise immediately when it is unavailable.
• DENSS — electron-density reconstruction (model_density); pulled in via the denss PyPI dependency.
• McSAS / McSAS3 — Monte Carlo polydisperse sizing (model_dr_mc).

Contacts

• Mikhail S. Lifar — [e-mail]
• Affiliation: The Smart Materials Research Institute, Southern Federal University (Rostov-on-Don)
• Project: github.com/MikhailLifar/autoSAXS

Contributing

Issues and pull requests are welcome on GitHub. Bug reports, clearer docs, and new skill coverage all help. Licensed under the Apache License 2.0.