APS USAXS/SAXS/WAXS facility

Ultra-Small-Angle X-ray Scattering Facility

pyIrena

pyIrena — Tools for analysis of small-angle scattering data (Python)

pyIrena is a collection of tools for processing and analyzing small-angle scattering data — SAXS, SANS, USAXS, and USANS — as well as powder diffraction data (XRD, WAXS). It is primarily used in materials science, chemistry, polymer science, metallurgy, and physics, where it supports the study of solid and liquid systems. The software is designed to handle complex structural problems, including systems with broad size distributions, hierarchical structure across multiple length scales, and the presence of diffraction or structure factors.

pyIrena is a Python package (Python 3.9+, MIT license) that runs on macOS, Windows, and Linux. It is a translation of the original Igor Pro Irena tools into Python, developed with the assistance of Anthropic's Claude and validated against the current Irena. It can be used through its graphical interface, through JSON-based scripting, or via its Python and command-line APIs, making it suitable for integration into SAXS and SANS instrument data-analysis pipelines.

Current version: 1.0.1 (released 7/15/2026) — the first stable release.

Data format note: pyIrena is FILE BASED. Optimal input is NXcanSAS HDF5 files with calibrated 1D SAS data, but generic HDF5 files or ASCII (2–3 columns: q, intensity, optional uncertainty) also work. Results from all tools are stored back into the HDF5 NXcanSAS file (created if needed), making files self-contained and shareable. All graphs have right-click export options into various formats (including Igor Pro itx format).

Installation

From PyPI (recommended):

pip install pyirena[gui]

On macOS with zsh, quote the brackets:

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. Installation from source and conda instructions are in docs/installation.md, including troubleshooting and platform notes. Use Python 3.10–3.13.

To start, run:

pyirena-gui

This launches the Data Selector, the main entry point for all analysis tools — see the GUI quick start. Individual tools can also be launched directly: pyirena-viewer (Data Explorer), pyirena-modeling, pyirena-datamerge, and pyirena-contrast.

Analysis tools

  • Modeling — parametric forward-modeling of SAS data. Combine up to 10 populations, each a size distribution, Unified fit level, or diffraction peak. 5 distribution functions (Gaussian, LogNormal, LSW, Schulz-Zimm, Ardell), 9 form factors (sphere, spheroid, cylinders, core-shell spheres and spheroids), 2 structure factors (Born-Green, Hard Sphere/Percus-Yevick), Monte Carlo uncertainty estimation. 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. Guide, features & parameters
  • Size distribution — indirect Fourier transform to recover particle size distributions. Four inversion methods: MaxEnt, Regularization, TNNLS, and Monte Carlo. Methods
  • Simple fits — 13 direct analytical models: Guinier, Guinier-Porod, Porod, sphere, spheroid, Debye-Bueche, Teubner-Strey, power law, Invariant (Porod invariant and two-phase volume fraction, new in 1.0.1), and more. Each with linearization plots and Monte Carlo uncertainty estimation. Guide
  • WAXS peak fit — fit diffraction peaks (Gaussian, Lorentzian, Pseudo-Voigt, Log-Normal) with auto peak detection and simultaneous background fitting. Guide

Support tools

  • Data Selector — central panel for managing data files, launching tools, tabulating results across files, and generating reports
  • Data Merge — merge two SAS datasets (e.g., SAXS + WAXS) onto a common Q scale; optimizes scale factor, flat background, and optional Q-shift. Guide
  • Data Explorer — browse NXcanSAS HDF5 files, inspect raw data and analysis results, extract and plot datasets, export to Igor Pro h5xp format. 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 Igor data into pyIrena without re-reducing. Guide
  • Scattering contrast calculator — X-ray and neutron scattering length densities by chemical formula, including contrast between two materials. Guide
  • Data export — to csv, itx (Igor Pro exchange format), jpg, and other formats; report generation from tool results

Scripting and APIs

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 include fit_unified, fit_sizes, fit_simple, fit_waxs, fit_modeling, and merge_data. See the batch API guide and usage guide.

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, or custom AI agents. Install with pip install pyirena[mcp]; the agent can then answer questions about your analysis results in plain language. Full instructions, including configurations for Claude Desktop, Claude Code, and AnythingLLM: AI integration guide, tool reference for agents.

Documentation and help

License

MIT — free for both open science and proprietary use; see LICENSE. There are no warranties with respect to functionality; please verify all results by independent methods.