pyIrena

Coded by Claude from SAXS_IgorCode Irena. Planned, defined, debugged, and validated by Jan Ilavsky.

Python tools for small-angle scattering (SAS) data analysis. A port of the Igor Pro Irena package. Includes interactive GUI tools for fitting, modeling, data merging, and visualization of SAXS/SANS/USAXS data.

Current release: v1.0.1

Current beta release: v1.1.0b10

Installation

From PyPI (recommended):

pip install pyirena[gui]

on macos with zsh:

pip install "pyirena[gui]"

This installs pyirena with all GUI dependencies (PySide6, pyqtgraph, etc.). For the core library only (no GUI), use pip install pyirena.

Trying a pre-release (beta) version:

Beta releases (e.g. 1.1.0b10) are published to PyPI ahead of a stable release for early testing. pip does not install pre-releases by default, so pass --pre explicitly:

pip install --pre "pyirena[gui]"

To install a specific beta rather than whatever is newest:

pip install "pyirena[gui]==1.1.0b10"

Pre-releases may contain incomplete or breaking changes — see CHANGELOG.md for what's new, and please report issues at https://github.com/jilavsky/pyirena/issues.

From source (for development):

git clone https://github.com/jilavsky/pyirena.git
cd pyirena
pip install -e ".[gui]"

With conda:

git clone https://github.com/jilavsky/pyirena.git
cd pyirena
conda env create -f environment.yml
conda activate pyirena

environment.yml uses conda for Python + scientific stack and pip (inside conda) for the entire Qt6/GUI stack — this split is deliberate. Do not run conda install pyside6 in this env, and use Python 3.10 – 3.13 (Python 3.14 wheels are still flaky for compiled bindings).

See docs/installation.md for full details, troubleshooting, and platform notes.

Running the GUI

pyirena-gui

This launches the Data Selector, the main entry point for all analysis tools. See docs/gui_quickstart.md for a walkthrough.

Individual tools can also be launched directly:

Analysis Tools

Modeling

Parametric forward-modeling of SAS data. Combine up to 10 populations, each of which can be a Size Distribution, Unified Fit Level, or Diffraction Peak. Fits the combined model to experimental data using least-squares optimization.

• 5 distribution functions: Gaussian, LogNormal, LSW, Schulz-Zimm, Ardell
• 9 form factors: Sphere, Spheroid, Cylinder (aspect ratio / fixed length), Core-Shell Sphere and Spheroid (by core R / shell t / total R)
• 2 structure factors: Born-Green interferences, Hard Sphere (Percus-Yevick)
• Monte Carlo uncertainty estimation
• Modeling GUI guide

Unified Fit

Beaucage hierarchical model (1995, 1996) with 1-5 structural levels, each combining Guinier and power-law contributions. Optional Born-Green correlation function.

• Unified Fit GUI guide
• Unified Fit features & parameters

Size Distribution

Indirect Fourier transform to recover particle size distributions from SAS data. Four inversion methods: MaxEnt, Regularization, TNNLS, and Monte Carlo.

• Size Distribution methods

Simple Fits

13 direct analytical models: Guinier, Guinier-Porod, Porod, Sphere, Spheroid, Debye-Bueche, Teubner-Strey, Power Law, and more. Each with linearization plots and Monte Carlo uncertainty estimation.

• Simple Fits GUI guide

WAXS Peak Fit

Fit diffraction peaks (Gaussian, Lorentzian, Pseudo-Voigt, Log-Normal) on linear I vs Q scale. Auto-detect peaks via Savitzky-Golay + scipy.signal.find_peaks. Simultaneous background fitting (constant, linear, cubic, or 5th-order polynomial).

• WAXS Peak Fit GUI guide

Data Merge

Merge two SAS datasets (e.g., SAXS + WAXS) onto a common Q scale. Optimizes scale factor, flat background, and optional Q-shift using Nelder-Mead.

• Data Merge GUI guide

Data Explorer

Browse NXcanSAS HDF5 files, inspect raw data and analysis results, extract and plot datasets, and export to Igor Pro h5xp format. Supports all pyIrena result types (Unified Fit, Sizes, Simple Fits, WAXS Peaks, Modeling).

• Data Explorer guide

Import Igor Experiment

Open an Igor Pro packed experiment (.pxp or .h5xp) and export each reduced USAXS/SAXS/WAXS sample as a stand-alone NXcanSAS .h5 file. Brings legacy and modern Igor data into pyIrena's analysis tools without re-reducing from raw detector files.

• Import Igor Experiment guide

Scattering Contrast Calculator

Look up X-ray and neutron scattering length densities for materials by chemical formula. Computes contrast (Delta-rho-squared) between two materials.

• Contrast Calculator guide

Data Selector

Central GUI panel for managing data files and launching analysis tools. Load HDF5 files, select datasets, tabulate results across files, and generate reports.

Batch Scripting API

All analysis tools can be run headlessly from Python scripts or JSON configuration files:

from pyirena.batch import fit_pyirena

results = fit_pyirena(
    data_file='sample.h5',
    config_file='pyirena_config.json',
)

Individual functions: fit_unified, fit_sizes, fit_simple, fit_waxs, fit_modeling, merge_data.

See docs/batch_api.md for the full scripting guide.

NXcanSAS I/O

All data and results are stored in HDF5 files using the NXcanSAS format. Fit results are saved alongside raw data, making files self-contained and shareable.

• NXcanSAS format details

AI integration (MCP)

pyirena ships a Model Context Protocol server that exposes its HDF5 readers, parameter aggregation, and headless plotting to any MCP client — Claude Desktop, Claude Code, custom AI agents.

pip install pyirena[mcp]

Add to claude_desktop_config.json (or your client's MCP server config):

{
  "mcpServers": {
    "pyirena": {
      "command": "pyirena-mcp",
      "env": {
        "PYIRENA_DATA_ROOT": "/path/to/your/data",
        "PYIRENA_PLOT_CACHE": "/tmp/pyirena-plots",
        "PYIRENA_MAX_ARRAY_POINTS": "500"
      }
    }
  }
}

The agent can then call tools like pyirena_summarize_folder, pyirena_tabulate_parameter, pyirena_plot_iq, pyirena_read_modeling etc. to answer questions about analysis results in plain language. The underlying pyirena.api module is also usable as a regular Python library, with unprefixed names (api.summarize_folder, api.plot_iq, …) — no MCP needed.

Full instructions, including configs for Claude Desktop, Claude Code, and AnythingLLM:

• docs/ai_integration.md — install & configure
• docs/ai_tools_reference.md — tool reference for AI agents (system-prompt material)

Documentation

License

MIT -- see LICENSE.

Contact

• Author: Jan Ilavsky -- ilavsky@aps.anl.gov
• Affiliation: X-ray Science Division, Argonne National Laboratory
• Issues: https://github.com/jilavsky/pyirena/issues