Metadata-Version: 2.4
Name: pyirena
Version: 0.7.0
Summary: Python tools for small-angle scattering data analysis.
Author-email: Jan Ilavsky <ilavsky@anl.gov>
Maintainer-email: Jan Ilavsky <ilavsky@anl.gov>
License: MIT
Project-URL: Homepage, https://github.com/jilavsky/pyirena
Project-URL: Documentation, https://github.com/jilavsky/pyirena/tree/main/docs
Project-URL: Repository, https://github.com/jilavsky/pyirena
Project-URL: Changelog, https://github.com/jilavsky/pyirena/blob/main/CHANGELOG.md
Project-URL: Bug Tracker, https://github.com/jilavsky/pyirena/issues
Keywords: SAXS,SANS,USAXS,small-angle scattering,unified fit,Beaucage,X-ray scattering,neutron scattering,SAS,size distribution,core-shell,form factor
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.22.0
Requires-Dist: scipy>=1.8.0
Requires-Dist: h5py>=3.0.0
Provides-Extra: gui
Requires-Dist: matplotlib>=3.5.0; extra == "gui"
Requires-Dist: PySide6!=6.10.*,!=6.7.*,>=6.4.0; extra == "gui"
Requires-Dist: pyqtgraph>=0.13.0; extra == "gui"
Requires-Dist: xraydb>=4.5; extra == "gui"
Requires-Dist: periodictable>=1.7; extra == "gui"
Requires-Dist: Dans-Diffraction>=3.0; extra == "gui"
Provides-Extra: gui3d
Requires-Dist: pyvista>=0.45; extra == "gui3d"
Requires-Dist: pyvistaqt>=0.11; extra == "gui3d"
Requires-Dist: vtk>=9.3; extra == "gui3d"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == "mcp"
Requires-Dist: matplotlib>=3.5.0; extra == "mcp"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Provides-Extra: all
Requires-Dist: pyirena[gui]; extra == "all"
Requires-Dist: pyirena[gui3d]; extra == "all"
Requires-Dist: pyirena[mcp]; extra == "all"
Requires-Dist: pyirena[dev]; extra == "all"
Dynamic: license-file

# 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](https://usaxs.xray.aps.anl.gov/software/irena) package. Includes interactive
GUI tools for fitting, modeling, data merging, and visualization of SAXS/SANS/USAXS data.

**Current release: v0.7.0 (public beta)**

[![PyPI version](https://img.shields.io/pypi/v/pyirena.svg)](https://pypi.org/project/pyirena/)
[![Python Version](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## Installation

**From PyPI (recommended):**

```bash
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`.

**From source (for development):**

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

**With conda:**

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

See [docs/installation.md](docs/installation.md) for full details, troubleshooting, and platform notes.

---

## Running the GUI

```bash
pyirena-gui
```

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

Individual tools can also be launched directly:

| Command | Tool |
|---------|------|
| `pyirena-gui` | Data Selector (main entry point) |
| `pyirena-viewer` | Data Explorer |
| `pyirena-modeling` | Modeling tool (standalone) |
| `pyirena-datamerge` | Data Merge tool (standalone) |
| `pyirena-contrast` | Scattering Contrast Calculator |

---

## 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](docs/modeling_gui.md)

### 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](docs/unified_fit_gui.md)
- [Unified Fit features & parameters](docs/unified_fit_features.md)

### 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](docs/sizes_methods.md)

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

- [Simple Fits GUI guide](docs/simple_fits_gui.md)

### 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](docs/waxs_peakfit_gui.md)

### 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](docs/data_merge_gui.md)

### 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](docs/hdf5_viewer_gui.md)

### 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](docs/scattering_contrast_gui.md)

### 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:

```python
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](docs/batch_api.md) for the full scripting guide.

---

## NXcanSAS I/O

All data and results are stored in HDF5 files using the
[NXcanSAS](https://www.nexusformat.org/NXcanSAS.html) format. Fit results are saved
alongside raw data, making files self-contained and shareable.

- [NXcanSAS format details](docs/NXcanSAS_UnifiedFit_Format.md)

---

## AI integration (MCP)

pyirena ships a [Model Context Protocol](https://modelcontextprotocol.io/) server
that exposes its HDF5 readers, parameter aggregation, and headless plotting to any
MCP client — Claude Desktop, Claude Code, custom AI agents.

```bash
pip install pyirena[mcp]
```

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

```json
{
  "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 `summarize_folder`, `tabulate_parameter`,
`plot_iq`, `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 (no MCP needed).

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

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

---

## Documentation

| Topic | File |
|-------|------|
| Installation | [docs/installation.md](docs/installation.md) |
| Quick start (GUI) | [docs/gui_quickstart.md](docs/gui_quickstart.md) |
| Modeling GUI guide | [docs/modeling_gui.md](docs/modeling_gui.md) |
| Unified Fit GUI guide | [docs/unified_fit_gui.md](docs/unified_fit_gui.md) |
| Unified Fit features & parameters | [docs/unified_fit_features.md](docs/unified_fit_features.md) |
| Size Distribution methods | [docs/sizes_methods.md](docs/sizes_methods.md) |
| Simple Fits GUI guide | [docs/simple_fits_gui.md](docs/simple_fits_gui.md) |
| WAXS Peak Fit GUI guide | [docs/waxs_peakfit_gui.md](docs/waxs_peakfit_gui.md) |
| Data Merge GUI guide | [docs/data_merge_gui.md](docs/data_merge_gui.md) |
| Data Explorer guide | [docs/hdf5_viewer_gui.md](docs/hdf5_viewer_gui.md) |
| Contrast Calculator guide | [docs/scattering_contrast_gui.md](docs/scattering_contrast_gui.md) |
| NXcanSAS file format | [docs/NXcanSAS_UnifiedFit_Format.md](docs/NXcanSAS_UnifiedFit_Format.md) |
| Batch fitting API | [docs/batch_api.md](docs/batch_api.md) |
| Usage guide (scripting) | [docs/usage_guide.md](docs/usage_guide.md) |
| AI integration (MCP) — install & configure | [docs/ai_integration.md](docs/ai_integration.md) |
| AI integration (MCP) — tool reference for agents | [docs/ai_tools_reference.md](docs/ai_tools_reference.md) |
| Developer: adding form factors | [docs/developer_adding_form_factors.md](docs/developer_adding_form_factors.md) |
| Developer: adding structure factors | [docs/developer_adding_structure_factors.md](docs/developer_adding_structure_factors.md) |
| Testing | [docs/testing.md](docs/testing.md) |
| Distribution / packaging | [docs/distribution.md](docs/distribution.md) |
| Contributing | [CONTRIBUTING.md](CONTRIBUTING.md) |
| Changelog | [CHANGELOG.md](CHANGELOG.md) |

---

## License

MIT -- see [LICENSE](LICENSE).

## Contact

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