APS USAXS/SAXS/WAXS facility

Ultra-Small-Angle X-ray Scattering Facility

pyIrena & Bernardyn

Tools for analysis & graphing 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.

Bernardyn is optional plotting tool for SAS and WAXS data and for pyIrena results.  

pyIrena & Bernardyn are both Python packages (Python 3.10+, MIT license) that run on macOS, Windows, and Linux. They are translations of the original Igor Pro Irena tools into Python, developed with the assistance of Anthropic's Claude and validated against the current Irena. They 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. They also both offer mcp server for AI agent integration and pyIrena offers ZMQ server mode. 

Current versions: 
pyIrena 1.2.0 (released 10/18/2026)
Bernardyn 1.0.0 (released 10/18/20206)

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

Bernardyn is WORKSPACE BASED, data from (pyIrena) NXcanSAS HDF5 files are imported in Bernardyn workspace which can be saved into independent HDF5 ("fileName.bernardyn.h5"). Workspace files are fully portable, all data and formatting are included in each file. 

Installation

From PyPI (recommended):

pip install pyirena[gui]
pip install bernardyn

On macOS with zsh, quote the brackets:

pip install "pyirena[gui]"
pip install "bernardyn"

This installs pyIrena and Bernardyn 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 	#launches pyIrena Data Selector GUI
bernardyn		#launches Bernardyn GUI

For pyIrena 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.

For use details, command line options, mcp, and for pyIrena ZMQ options, read the Github documentation. https://github.com/jilavsky/bernardyn
https://github.com/jilavsky/pyirena 

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
  • 3D saxsMorph - new version of old saxsMorph package. Much faster. 
  • Carbon model - modeling of Carbon USAXS+SAXS+WAXS data, beta for now. 
  • Fractals - visualization of fractals. 

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

Bernardyn

  • Browse all discoverable NXcanSAS/simple-HDF5 entries and 2–4 column text data.
  • Add saved pyIrena results (Unified Fit, Size Distribution, Modeling, Simple Fits, WAXS Peak Fit, Carbon fitting) from the same data selector as I(Q) data: measured data with fits and components, residuals, and size distributions, with units read from the files.
  • Keep a workspace-wide dataset catalog and independent graph tabs.
  • Plot General I(Q), Guinier, rod/sheet Guinier, Kratky, dimensionless Kratky, Porod, modified Porod, Zimm, and Debye–Bueche views.
  • Style each curve, errors, labels, axes, legends, typography, and annotations.
    Render 3D line waterfalls and common-grid surfaces with an isolated, lazily-loaded PyQtGraph OpenGL backend and 2D fallback.
  • Save one graph or a deduplicated multi-graph workspace as *.bernardyn.h5, including canonical data, resolved snapshots, configuration, checksums, previews, and 3D renderer data.
  • Export PNG/JPEG/SVG, CSV, Igor ITX, and canonical data through PyIrena's H5XP writer. H5XP export is data interoperability, not Bernardyn graph persistence.

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.

ZMQ server mode 

pyIrena can run in server mode, accessible from local area network through ZMQ protocol. This allows local users to use dedicated powerful computer for fitting of complex/slow models without overloading their computers. Uses same json file syntax as scripting. 

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.