Metadata-Version: 2.1
Name: pyFAI
Version: 2026.2.0
Summary: Python implementation of fast azimuthal integration
Author-Email: =?utf-8?q?J=C3=A9r=C3=B4me_Kieffer?= <jerome.kieffer@esrf.fr>, Edgar Gutierrez Fernandez <edgar.gutierrez-fernandez@esrf.fr>, Valentin Valls <valentin.valls@esrf.fr>, =?utf-8?q?Lo=C3=AFc_Huder?= <loic.huder@esrf.fr>
License: Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
         Upstream-Name: pyfai
         Source: https://github.com/silx-kit/pyFAI
         Files-Excluded: pyFAI/third_party/_local
         
         Files: *
         Copyright: 2011-2017 European Synchrotron Radiation Facility
         License: MIT/X11 (BSD like)
         
         Files: package/debian?/*
         Copyright: 2012-2014 Jerome Kieffer <jerome.kieffer@esrf.fr>
         	       2013-2016 Picca Frédéric-Emmanuel <picca@debian.org>
         	       2015-2016 European Synchrotron Radiation Facility
         License: GPL-3.0+
         
         Files: pyFAI/resources/openCL/bitonic.cl
                openCL/bsort.cl
         Copyright: Matthew Scarpino
         License: public-domain
         
         Files: doc/source/mathjax.py
         Copyright: 2007-2013 by the Sphinx team
         License: BSD-3
         
         Files: pyFAI/third_party/transformation.py
         Copyright: 2006-2018, Christoph Gohlke, University of California
         License: BSD-3
         
         
         License: BSD-3
          Redistribution and use in source and binary forms, with or without
          modification, are permitted provided that the following conditions
          are met:
              * Redistributions of source code must retain the above copyright
                notice, this list of conditions and the following disclaimer.
              * Redistributions in binary form must reproduce the above
                copyright notice, this list of conditions and the following
                disclaimer in the documentation and/or other materials provided
                with the distribution.
              * Neither the name of the <organization> nor the names of its
                contributors may be used to endorse or promote products derived
                from this software without specific prior written permission.
          .
          THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
          "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
          LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
          A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT
          HOLDER> BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
          EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
          PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
          PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
          OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
          (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
          OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
         
         License: GPL-3.0+
          This package is free software; you can redistribute it and/or modify
          it under the terms of the GNU General Public License as published by
          the Free Software Foundation; either version 3 of the License, or
          (at your option) any later version.
          .
          This package is distributed in the hope that it will be useful,
          but WITHOUT ANY WARRANTY; without even the implied warranty of
          MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
          GNU General Public License for more details.
          .
          You should have received a copy of the GNU General Public License
          along with this program. If not, see <http://www.gnu.org/licenses/>
          .
          On Debian systems, the complete text of the GNU General
          Public License version 3 can be found in "/usr/share/common-licenses/GPL-3".
         
         License: public-domain
          You can use this free for any purpose. It's in the public domain. It
          has no warranty
         
         License: MIT/X11 (BSD like)
          Permission is hereby granted, free of charge, to any person obtaining a copy
          of this software and associated documentation files (the "Software"), to deal
          in the Software without restriction, including without limitation the rights
          to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
          copies of the Software, and to permit persons to whom the Software is
          furnished to do so, subject to the following conditions:
          .
          The above copyright notice and this permission notice shall be included in
          all copies or substantial portions of the Software.
          .
          THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
          IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
          FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
          AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
          LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
          OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
          THE SOFTWARE.
         
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Cython
Classifier: Environment :: Console
Classifier: Environment :: X11 Applications :: Qt
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: Unix
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX
Classifier: Topic :: Scientific/Engineering :: Physics
Project-URL: homepage, http://www.silx.org
Project-URL: documentation, http://www.silx.org/doc/pyFAI/latest/
Project-URL: source, https://github.com/silx-kit/pyFAI
Project-URL: download, https://github.com/silx-kit/pyFAI/releases
Project-URL: tracker, https://github.com/silx-kit/pyFAI/issues
Requires-Python: >=3.10
Requires-Dist: numpy>=1.10
Requires-Dist: h5py
Requires-Dist: fabio
Requires-Dist: silx>=2
Requires-Dist: numexpr!=2.8.6
Requires-Dist: scipy
Requires-Dist: matplotlib
Provides-Extra: gui
Requires-Dist: PySide6; extra == "gui"
Provides-Extra: opencl
Requires-Dist: pyopencl; extra == "opencl"
Provides-Extra: all
Requires-Dist: PySide6; extra == "all"
Requires-Dist: pyopencl; extra == "all"
Requires-Dist: hdf5plugin; extra == "all"
Description-Content-Type: text/markdown

# Fast Azimuthal Integration in Python

Main development website: [https://github.com/silx-kit/pyFAI](https://github.com/silx-kit/pyFAI)

[![Github Actions](https://github.com/silx-kit/pyFAI/actions/workflows/python-package.yml/badge.svg)](https://github.com/silx-kit/pyFAI/actions)
[![Appveyor Status](https://ci.appveyor.com/api/projects/status/github/silx-kit/pyfai?svg=true)](https://ci.appveyor.com/project/ESRF/pyfai)
[![myBinder Launcher](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/silx-kit/pyFAI/main?filepath=binder%2Findex.ipynb)
[![RTD docs](https://readthedocs.org/projects/pyfai/badge/?version=latest)](https://pyfai.readthedocs.io/en/latest/)
[![Zenodo DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.832896.svg)](https://doi.org/10.5281/zenodo.832896)

PyFAI is an azimuthal integration library designed for high-performance, achieving performance comparable to C and even greater through OpenCL-based GPU acceleration.
It is based on histogramming the 2θ/Q positions of each pixel centre, weighted by pixel intensity, whereas the parallel version performs a SparseMatrix-DenseVector multiplication.
Both method achieve the same numerical result.
Neighboring output bins also receive contributions from pixels adjacent to the border through pixel splitting.
PyFAI also provides tools to calibrate the experimental setup using Debye-Scherrer rings of a reference compound.

## References

- The philosophy of pyFAI is described in the proceedings of [SRI2012](https://doi.org/10.1088/1742-6596/425/20/202012)
- Implementation in parallel is described in the proceedings of [EPDIC13](https://doi.org/10.1017/S0885715613000924)
- Benchmarks and optimization procedure are described in the proceedings of [EuroSciPy2014](https://doi.org/10.48550/arXiv.1412.6367)
- Calibration procedures are described in [J. Synch. Radiation (2020)](https://doi.org/10.1107/S1600577520000776)
- Application of signal separation to diffraction image compression and serial crystallography in [J. Appl. Cryst. (2025)]( https://doi.org/10.1107/S1600576724011038)

## Installation

### Using PIP (python-package installer)

As with most Python packages, pyFAI is available via pip:

```sh
pip install pyFAI[gui]
```

It is recommended to run this in a [virtual environment](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments).
Provide the `--user` option to perform an installation local to your user-space (**not recommended**).
Under UNIX, you may have to run the command via `sudo` to gain root access and perform a system wide installation (which is **neither recommended**).

### Using conda installer

PyFAI is also available via the `conda` installer from Anaconda:

```sh
conda install pyfai -c conda-forge
```

To install conda please see either [conda](https://conda.io/docs/install/quick.html) or [Anaconda](https://www.continuum.io/downloads).

### From source code

The current development version of pyFAI can be downloaded from [GitHub](https://github.com/silx-kit/pyFAI/archive/main.zip).
The source code is currently distributed as a zip package. 

Download and unpack it:

```sh
unzip pyFAI-main.zip
cd pyFAI-main
```

Install dependencies:

```sh
pip install -r requirements.txt
```

Build and test it:

```sh
python run_tests.py
```

For its tests, pyFAI downloads test images from the internet. Depending on your network connection and your local network configuration, you may have to set up a proxy configuration like this (not needed at ESRF):

```sh
export http_proxy=http://proxy.site.org:3128
```

Finally, install pyFAI in the virtualenv after testing it:

```sh
pip install .
```

The latest development version is available by checking out the Git repository:

```sh
git clone https://github.com/silx-kit/pyFAI.git
cd pyFAI
pip install .
```

To enable GPU acceleration in pyFAI, please install [pyopencl](http://mathema.tician.de/software/pyopencl).

## Documentation

Documentation can be built using this command and Sphinx (installed on your computer):

```sh
python build-doc.py
```

## Dependencies

Python 3.10 ... 3.14 are well tested and officially supported (thread-free is untested).

For full functionality of pyFAI, the following modules need to be installed:

- [`numpy`](http://www.numpy.org)
- [`scipy`](http://www.scipy.org)
- [`matplotlib`](http://matplotlib.sourceforge.net/)
- [`fabio`](http://sourceforge.net/projects/fable/files/fabio/)
- [`h5py`](http://www.h5py.org/)
- [`pyopencl`](http://mathema.tician.de/software/pyopencl/)
- [`pyside6`](https://wiki.qt.io/Qt_for_Python)
- [`silx`](http://www.silx.org)
- [`numexpr`](https://github.com/pydata/numexpr)

Those dependencies can simply be installed by:

```sh
pip install -r requirements.txt
```

## Ubuntu and Debian-like Linux distributions

On Ubuntu or Debian, the required Python modules for pyFAI can be installed either via the Synaptic Package Manager (under System → Administration) or from the command line using apt-get: 

```sh
sudo apt-get install pyfai
```

## MacOSX

On macOS, a recent version of [Python](https://www.python.org/downloads/) (≥3.10) must be installed before installing pyFAI. 
Apple provides only an outdated version of Python 2.7 which is deprecated.
To build pyFAI from source, you will also need Xcode, which is available from the Mac App Store.
The binary extensions will use only a single core due to the limitation of the compiler from Apple.
OpenCL is hence greatly advised on Apple systems.
Next, install the missing dependencies using pip:

```sh
pip install -r requirements.txt
```

## Windows

On Windows, a recent version of [Python](https://www.python.org/downloads/) (>=3.10) must be installed before pyFAI.
The Visual Studio C++ compiler is required when building from source
Next, install any missing dependencies using pip:

```sh
pip install -r requirements.txt
```

## Getting Help

A mailing-list, pyfai@esrf.fr, is available to get help on the program and how to use it.
One needs to subscribe by sending an email to sympa@esrf.fr with the subject "subscribe pyfai".
There is also a discussion space at [GitHub](https://github.com/silx-kit/pyFAI/discussions) and an [issue tracker](https://github.com/silx-kit/pyFAI/issues) where bugs can be reported.

## Maintainers

- Jérôme Kieffer (ESRF)
- Edgar Gutierrez Fernandez (ESRF)
- Loïc Huder (ESRF)

## Contributors

Thanks to all who have contributed to pyFAI!

[![Contributors image](https://contrib.rocks/image?repo=silx-kit/pyFAI)](https://github.com/silx-kit/pyFAI/graphs/contributors)

## Indirect contributors (ideas, ...)

- Peter Boesecke
- Manuel Sánchez del Río
- Thomas Vincent
- Vicente Armando Solé
- Brian Pauw
- Veijo Honkimaki
