### Install pyFAI from Source

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/operations/macosx.rst

Steps to clone the pyFAI repository from GitHub, set up a virtual environment, install build tools, and then install pyFAI from the local source.

```shell
python3 -m venv pyfai
source pyfai/bin/activate
pip install build
git clone https://github.com/silx-kit/pyFAI
cd pyFAI
pip install -r requirements.txt
pip install . --upgrade
```

--------------------------------

### Initialize pyFAI and display version

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/usage/tutorial/Geometry/geometry.ipynb

Imports pyFAI modules, including detectors and GUI components, and prints the installed pyFAI version. This is useful for verifying the environment setup.

```python
import pyFAI, pyFAI.detectors
print("Using pyFAI version", pyFAI.version)
from pyFAI.gui import jupyter
from pyFAI.calibrant import get_calibrant
from pyFAI.integrator.azimuthal import AzimuthalIntegrator
```

--------------------------------

### MX-Calibrate Usage Example

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/man/MX-calibrate.rst

Example of how to run the MX-Calibrate tool with specified wavelength, calibrant file, and input diffraction patterns.

```bash
MX-Calibrate -w 1.54 -c CeO2 file1.cbf file2.cbf ...
```

--------------------------------

### Build and Install PyFAI Wheel

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/operations/index.rst

Clone the repository, install build tools and requirements, then build a wheel package and install it. This method is useful for creating distributable packages.

```shell
git clone https://github.com/silx-kit/pyFAI
cd pyFAI
pip install build --upgrade
pip install -r requirements.txt
python3 -m build --wheel
pip install --pre --no-index --find-links dist pyFAI
```

--------------------------------

### Install PyFAI using pip

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/operations/index.rst

Clone the repository, install requirements, and then install PyFAI using pip. This is a standard installation method.

```shell
git clone https://github.com/silx-kit/pyFAI
cd pyFAI
pip install -r requirements.txt
pip install . --upgrade
```

--------------------------------

### Install pyFAI with Full Extras

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/operations/macosx.rst

After activating the virtual environment, install pyFAI with all optional dependencies using pip. Ensure you have a Python3 stack installed.

```shell
pip install pyFAI[full]
```

--------------------------------

### Integrated Data File Header Example

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/usage/cookbook/integration_with_python.ipynb

Example output from reading the 'integrated.dat' file, showing the JSON header containing metadata about the integration process, such as detector parameters, wavelength, and PONI values.

```text
# {
#     "poni_version": 2.1,
#     "dist": 0.16254673947902704,
#     "poni1": 0.09636511239091199,
#     "poni2": 0.08600622810318177,
#     "rot1": 0.0026048269580961157,
#     "rot2": 0.0006408875619633374,
#     "rot3": 7.381054962294179e-11,
#     "detector": "Eiger4M",
#     "detector_config": {
#         "pixel1": 7.5e-05,
#         "pixel2": 7.5e-05,
#         "orientation": 3
#     },
#     "wavelength": 9.218156017338309e-11
# }
# Mask applied: user provided
# Dark current applied: False
# Flat field applied: False
# Polarization factor: None
# Normalization factor: 1.0
```

--------------------------------

### Build and install PyFAI from source on Debian/Ubuntu

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/operations/linux.rst

Installs development dependencies, clones the PyFAI repository, and builds/installs the package from source. This process may prompt for your password for installation.

```shell
sudo apt install git
sudo apt-get build-dep pyfai
git clone https://github.com/silx-kit/pyFAI
cd PyFAI
./build-deb.sh --install
```

--------------------------------

### Install Local Peakfinder8 from GitHub

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/usage/tutorial/Separation/Peakfinder8.ipynb

Installs a local version of the Cython-binded peakfinder8 from GitHub. This is a quick solution and requires git to be installed.

```python
targeturl = "https://github.com/kif/peakfinder8"
targetdir = posixpath.split(targeturl)[-1]
if os.path.exists(targetdir):
    shutil.rmtree(targetdir, ignore_errors=True)
pwd = os.getcwd()
try:
    os.system("git clone " + targeturl)
    os.chdir(targetdir)
    os.system(f"'{sys.executable}' setup.py build")
finally:
    os.chdir(pwd)
sys.path.append(pwd+"/"+glob.glob(f"{targetdir}/build/lib*")[0])
from ssc.peakfinder8_extension import peakfinder_8
```

--------------------------------

### Install PyFAI

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/project.rst

Standard installation command for PyFAI using pip. Ensure you have the necessary build dependencies.

```shell
pip install --upgrade .
```

--------------------------------

### Install PyFAI with GUI support using pip

Source: https://github.com/silx-kit/pyfai/blob/main/README.md

Use this command to install PyFAI along with its graphical user interface components. It is recommended to perform this installation within a virtual environment.

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

--------------------------------

### Install Dependencies

Source: https://github.com/silx-kit/pyfai/blob/main/CONTRIBUTING.md

Install project dependencies using pip, ensuring all binary packages are used.

```bash
pip install --upgrade -r requirements.txt --only-binary :all:
```

--------------------------------

### Integration Method Output

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/usage/tutorial/Variance/Validator.ipynb

Example output showing the selected integration method details.

```text
IntegrationMethod(1d int, bbox split, CSR, cython)
```

--------------------------------

### Install PyFAI requirements from source

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/operations/windows.rst

Before installing PyFAI from source, ensure all development requirements are met by running this command. This is typically used when building from a Git repository.

```shell
pip install -r requirements.txt --upgrade
```

--------------------------------

### Install Numba and Cython

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/usage/tutorial/ThickDetector/raytracing.ipynb

Installs the numba and cython libraries, which are used for speeding up calculations.

```python
! pip install numba cython
```

--------------------------------

### Install PyFAI from source using pip

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/operations/linux.rst

Installs the 'build' package, clones the PyFAI repository, and installs PyFAI from its sources within an activated Python virtual environment. Avoid using 'sudo pip'.

```shell
pip install build
git clone https://github.com/silx-kit/pyFAI
cd PyFAI
pip install -r requirements.txt
pip install . --upgrade
```

--------------------------------

### Calibrant file header example

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/usage/tutorial/Calibrant/make_calibrant.ipynb

This is an example of the header and initial lines of a calibrant file, showing metadata and d-spacing values with Miller indices.

```text
# Calibrant: Silver Behenate (AgBh)
# Pseudocrystal a=inf b=inf c=58.380
# Ref: doi:10.1107/S0021889899012388
5.83800000e+01 # (0,0,1)
2.91900000e+01 # (0,0,2)
1.94600000e+01 # (0,0,3)
1.45950000e+01 # (0,0,4)
1.16760000e+01 # (0,0,5)
9.73000000e+00 # (0,0,6)
8.34000000e+00 # (0,0,7)
7.29750000e+00 # (0,0,8)
6.48666667e+00 # (0,0,9)
(...)
```

--------------------------------

### Example pyFAI-saxs Usage

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/usage/cookbook/integration_with_scripts.ipynb

This example demonstrates the basic usage of pyFAI-saxs for azimuthal integration. It specifies the number of points for the radial dimension (-n), the wavelength of the X-ray beam (-w), and the input image files. The output is saved with a .dat extension by default.

```bash
pyFAI-saxs -n 1000 -w 1.24 -p mygeometry.poni "*.edf"
```

--------------------------------

### Launch pyFAI-calib2 GUI

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/usage/cookbook/calib-gui/index.rst

Start the graphical tool for geometry calibration by typing 'pyFAI-calib2' in the terminal.

```shell
$ pyFAI-calib2
```

--------------------------------

### Build PyFAI documentation

Source: https://github.com/silx-kit/pyfai/blob/main/README.md

Command to build the project's documentation using Sphinx. Ensure Sphinx is installed in your environment.

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

--------------------------------

### Initialize Detector and Print Version

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/usage/tutorial/Calibrant/Calibrant.ipynb

Initializes the Pilatus6M detector and prints the pyFAI version. Ensure pyFAI is installed to run this code.

```python
import time
start_time = time.perf_counter()
import pyFAI, pyFAI.detectors
print(f"PyFAI version: {pyFAI.version}")
dete = pyFAI.detectors.Pilatus6M()
print(dete)
```

--------------------------------

### Install PyFAI with GUI support via PIP

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/operations/windows.rst

Use this command to install PyFAI along with its GUI dependencies. The --upgrade flag ensures you get the latest version.

```shell
pip install pyFAI[gui] --upgrade
```

--------------------------------

### Initialize Calibration Parameters and Load Data

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/usage/cookbook/calibration_with_jupyter.ipynb

Sets up essential parameters like wavelength, detector, and calibrant, then loads diffraction image data for calibration.

```python
# Some parameters like the wavelength, the calibrant and the diffraction image:
wavelength = 1e-10
pilatus = pyFAI.detector_factory("Pilatus1M")
AgBh = pyFAI.calibrant.CALIBRANT_FACTORY("AgBh")
AgBh.wavelength = wavelength

#load some test data (requires an internet connection)
img = fabio.open(pyFAI.test.utilstest.UtilsTest.getimage("Pilatus1M.edf")).data
```

--------------------------------

### Set Initial Parameters and Bounds for Refinement

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/usage/tutorial/ThickDetector/goniometer_id28.ipynb

Defines the starting values and acceptable ranges for goniometer parameters. This is crucial for guiding the refinement process and ensuring physically meaningful results.

```python
import numpy

epsilon = numpy.finfo(numpy.float32).eps
#Definition of the parameters start values and the bounds
param = {"dist":0.30,
         "poni1":0.08,
         "poni2":0.08,
         "rot1":0,
         "rot2":0,
         "scale1": numpy.pi/180., # rot2 is in radians, while the motor position is in degrees
         "scale2": 0
        }

#Defines the bounds for some variables. We start with very strict bounds
bounds = {"dist": (0.25, 0.31),
          "poni1": (0.07, 0.1),
          "poni2": (0.07, 0.1),
          "rot1": (-0.01, 0.01),
          "rot2": (-0.01, 0.01),
          "scale1": (numpy.pi/180.-epsilon, numpy.pi/180.+epsilon), #strict bounds on the scale: we expect the gonio to be precise
          "scale2": (-epsilon, +epsilon) #strictly bound to 0
         }
```

--------------------------------

### Refine geometry and get azimuthal integration object

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/usage/tutorial/Recalib/Recalib_notebook.ipynb

Refines the geometry parameters, fixing rotation and wavelength in this SAXS geometry example. It then retrieves the azimuthal integration object based on the refined geometry.

```python
# Refine the geometry ... here in SAXS geometry, the rotation is fixed in orthogonal setup
sg.geometry_refinement.refine2(fix=["rot1", "rot2", "rot3", "wavelength"])
sg.get_ai()
```

--------------------------------

### Initialize pyFAI and Load Data

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/usage/tutorial/ThickDetector/Parallax_simple.ipynb

Sets up the pyFAI environment, imports necessary libraries, and defines parameters for integration. Includes printing the pyFAI version and timing the initialization.

```python
%matplotlib inline
import time
import copy
from matplotlib.pyplot import subplots
from scipy.sparse import csc_array
import fabio
import pyFAI
from pyFAI.gui import jupyter
from pyFAI.test.utilstest import UtilsTest
from pyFAI.calibrant import get_calibrant
import pyFAI.ext.parallax_raytracing

kwargs = {
    "npt": 2000,  # this is a lot of oversampling ... do not use with actual images.
    "method": (
        "no",
        "histogram",
        "cython",
    ),  # without pixel splitting, results are correct despite ugly images.
    "unit": "2th_deg",
    "radial_range": (10, 40),
    "dummy": 4e9,
    "delta_dummy": 1e9,
}

print(f"Using pyFAI version {pyFAI.version}")
start_time = time.perf_counter()
```

--------------------------------

### Configure Detector with Binning and Load from File

Source: https://context7.com/silx-kit/pyfai/llms.txt

Configures a detector with binning and demonstrates loading a detector from a NeXus/HDF5 file. Also shows how to set masks, flat fields, and dark current corrections.

```python
from pyFAI import detectors
from pyFAI.detectors import Detector, ALL_DETECTORS

# Configure detector with binning
detector = detectors.detector_factory("Pilatus2M")
detector.binning = (2, 2)  # 2x2 binning
print(f"Detector: {detector.name}")
print(f"Pixel size: {detector.pixel1*1e6:.1f} x {detector.pixel2*1e6:.1f} µm")
print(f"Shape: {detector.shape}")

# Load detector from NeXus/HDF5 file
nexus_detector = detectors.NexusDetector("detector_description.h5")

# Set mask on detector (persisted with geometry)
mask = np.zeros(detector.shape, dtype=np.int8)
mask[100:200, 300:400] = 1  # Mask a region
detector.mask = mask

# Set flat field correction
detector.flatfield = flat_field_image
# detector.darkcurrent = dark_image # Assuming dark_image is defined elsewhere
```

--------------------------------

### Install PyFAI from source

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/operations/windows.rst

Install PyFAI directly from its source code. This command is used after cloning the repository and installing requirements, ensuring the latest development version is built and installed.

```shell
pip install . --upgrade
```

--------------------------------

### Build and Test Project

Source: https://github.com/silx-kit/pyfai/blob/main/CONTRIBUTING.md

Build the project and run the test suite to ensure the local environment is set up correctly.

```bash
python run_tests.py
```

--------------------------------

### Install PyFAI using conda

Source: https://github.com/silx-kit/pyfai/blob/main/README.md

Install PyFAI from the conda-forge channel. Ensure you have conda installed and configured.

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

--------------------------------

### Import pyFAI and detector setup

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/usage/tutorial/Variance/Variance.ipynb

Imports core pyFAI libraries, plotting tools, and logging. Initializes a Detector object and sets its shape, then prints the detector configuration.

```python
import numpy, numexpr, numba
from scipy.stats import chi2 as chi2_dist
from matplotlib.pyplot import subplots
from matplotlib.colors import LogNorm
import logging
logging.basicConfig(level=logging.ERROR)
import pyFAI
print(f"pyFAI version: {pyFAI.version}")
from pyFAI.detectors import Detector
from pyFAI.method_registry import IntegrationMethod
from pyFAI.gui import jupyter
detector = Detector(pix, pix)
detector.shape = detector.max_shape = shape
print(detector)
```

--------------------------------

### Initialize pyFAI Environment and Download Test Data

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/usage/tutorial/ThickDetector/goniometer_id28.ipynb

Imports necessary libraries, prints the Python version, and downloads test images for detector calibration. Ensure you have `fabio`, `pyFAI`, `silx`, and `numpy` installed.

```python
%matplotlib inline
# use `widget` instead of `inline` for better user-exeperience. `inline` allows to store plots into notebooks.
```

```python
import os, sys, time
start_time = time.perf_counter()
print(sys.version)
```

```python
import numpy
import fabio, pyFAI
print(f"Using pyFAI version: {pyFAI.version}")
from os.path import basename
from pyFAI.gui import jupyter
from pyFAI.calibrant import get_calibrant
from silx.resources import ExternalResources
from scipy.interpolate import interp1d
from scipy.optimize import bisect
from matplotlib.pyplot import subplots
from matplotlib.lines import Line2D
downloader = ExternalResources("thick", "http://www.silx.org/pub/pyFAI/testimages")
all_files = downloader.getdir("gonio_ID28.tar.bz2")
for afile in all_files:
    print(basename(afile))
```

--------------------------------

### Set up plotting and display system topology

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/usage/tutorial/Parallelization/MultiGPU-scisoft16.ipynb

Initializes matplotlib for inline plotting and displays the system's hardware topology using `lstopo`. This is useful for understanding resource distribution.

```python
%matplotlib inline
# use `widget` for better user experience; `inline` is for documentation generation

#Topology of the computer:
!lstopo /tmp/topo.png
from IPython.display import Image
Image(filename='/tmp/topo.png')
```

--------------------------------

### Initialize pyFAI and Print Version

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/usage/tutorial/Introduction/introduction.ipynb

Imports necessary libraries for pyFAI and prints the installed version. May require proxy settings for internet access.

```python
#Nota: May be used if you are behind a firewall and need to setup a proxy
import os
#os.environ["http_proxy"] = "http://proxy.company.fr:3128"
import time
import numpy
start_time = time.perf_counter()
import pyFAI
from pyFAI.integrator.azimuthal import AzimuthalIntegrator
print("Using pyFAI version", pyFAI.version)
```

--------------------------------

### Create and Load Custom Calibrants

Source: https://context7.com/silx-kit/pyfai/llms.txt

Demonstrates creating a custom calibrant from a list of d-spacings and loading a calibrant from a file. Also shows initialization of AzimuthalIntegrator with a wavelength.

```python
from pyFAI import calibrant
from pyFAI.calibrant import get_calibrant, names, ALL_CALIBRANTS
from pyFAI.crystallography.calibrant import Calibrant
import pyFAI

# Create custom calibrant from d-spacings
custom_cal = Calibrant(dspacing=[3.135, 2.714, 1.920, 1.638])
custom_cal.wavelength = 1.0e-10 # Assuming wavelength is set

# Load calibrant from file
# Format: one d-spacing per line in Angstrom
cal_from_file = Calibrant("my_calibrant.D")
cal_from_file.wavelength = 1.0e-10 # Assuming wavelength is set

# Use calibrant for peak detection in calibration
ai = pyFAI.AzimuthalIntegrator(wavelength=1.0e-10)
# ... perform calibration using pyFAI-calib2 GUI or GeometryRefinement
```

--------------------------------

### Setup Sparse Integrator and Peak Finder

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/usage/tutorial/Separation/Laue.ipynb

Sets up a sparse integrator and initializes an OpenCL PeakFinder for detecting diffraction peaks. Requires an OpenCL device for optimal performance.

```python
from pyFAI.opencl.peak_finder import OCL_PeakFinder

engine = ai.setup_sparse_integrator(data.shape, npt, mask, unit=unit, split="no")
radius2d = ai.array_from_unit(data.shape, unit=unit)
pf = OCL_PeakFinder(engine.lut, data.size, 
                   unit=unit, 
                   bin_centers=engine.bin_centers,
                   radius=radius2d,
                   mask = mask)
```

--------------------------------

### Configure detector and HDF5 plugin

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/usage/tutorial/Parallelization/GPU-decompression.ipynb

Sets up the detector parameters and initializes the HDF5 plugin for compression. This step defines the detector type, shape, data type, and compression method.

```python
det = pyFAI.detector_factory("eiger_4M")
shape = det.shape
dtype = numpy.dtype("uint32")
filename = "/tmp/big.h5"
nbins = 1000
cmp = hdf5plugin.Bitshuffle()
hdf5plugin.get_config()
```

--------------------------------

### Initialize Detector and Calibrant

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/usage/tutorial/Goniometer/Rotation-Pilatus100k/Multi120_Pilatus100k.ipynb

Sets up the detector (Pilatus100k), applies a mask, and defines a calibrant (LaB6) with a specific wavelength.

```python
#Definition of the detector, its mask, the calibrant
mask_files = [i for i in all_files if i.endswith("-mask.edf")]
mask = numpy.logical_or(fabio.open(mask_files[0]).data, fabio.open(mask_files[1]).data)
pilatus = pyFAI.detector_factory("Pilatus100k")
pilatus.mask = mask
    
LaB6 = pyFAI.calibrant.CALIBRANT_FACTORY("LaB6")
wavelength = 7.7490120575e-11
LaB6.wavelength = wavelength
```

--------------------------------

### Print pyFAI version

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/usage/tutorial/Calibrant/new_calibrant.ipynb

Prints the installed version of the pyFAI library. Ensure you have pyFAI installed.

```python
import pyFAI
print("pyFAI version",pyFAI.version)
```

--------------------------------

### Initial Guess Output

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/usage/tutorial/Detector/Pilatus_Calibration/Pilatus900kw-ID06.ipynb

Example output showing the initial guess for the center fitting parameters, including step size and per-module offsets and rotations.

```text
step: 29.303
 6L: Δx: 1262.883, Δy:  6.524 rot: -0.014°
 9C: Δx: 1984.213, Δy:  9.888 rot: -0.023°
12R: Δx: 2852.995, Δy:  8.526 rot: -0.031°
 1L: Δx:    0.000, Δy:  0.000 rot:  0.000°
 2L: Δx:    0.000, Δy:  0.000 rot:  0.000°
 3L: Δx:    0.000, Δy:  0.000 rot:  0.000°
 4L: Δx:    0.000, Δy:  0.000 rot:  0.000°
 5L: Δx:    0.000, Δy:  0.000 rot:  0.000°
 6C: Δx:    0.000, Δy:  0.000 rot:  0.000°
 7C: Δx:    0.000, Δy:  0.000 rot:  0.000°
 8C: Δx:    0.000, Δy:  0.000 rot:  0.000°
 9C: Δx:    0.000, Δy:  0.000 rot:  0.000°
10C: Δx:    0.000, Δy:  0.000 rot:  0.000°
11C: Δx:    0.000, Δy:  0.000 rot:  0.000°
12C: Δx:    0.000, Δy:  0.000 rot:  0.000°
13R: Δx:    0.000, Δy:  0.000 rot:  0.000°
14R: Δx:    0.000, Δy:  0.000 rot:  0.000°
15R: Δx:    0.000, Δy:  0.000 rot:  0.000°
16R: Δx:    0.000, Δy:  0.000 rot:  0.000°
17R: Δx:    0.000, Δy:  0.000 rot:  0.000°
18R: Δx:    0.000, Δy:  0.000 rot:  0.000°
472.8915314583428
```

--------------------------------

### Check PyFAI Version

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/usage/tutorial/Goniometer/Rotation-Pilatus100k/Multi120_Pilatus100k.ipynb

Prints the installed version of the PyFAI library. Ensure you have PyFAI installed to run this.

```python
# %matplotlib widget

import numpy
from matplotlib.pyplot import subplots
import time, pyFAI
start_time = time.perf_counter()
print(f"Using pyFAI version {pyFAI.version}")
```

--------------------------------

### Install PyFAI on Ubuntu/Debian

Source: https://github.com/silx-kit/pyfai/blob/main/README.md

Use apt-get to install the pyfai package on Debian-based Linux distributions. This is the recommended method for these systems.

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

--------------------------------

### Create and Save PONI File

Source: https://context7.com/silx-kit/pyfai/llms.txt

Create a PoniFile object from scratch, set its parameters, save it to disk, and then load it back to verify.

```python
from pyFAI.io import PoniFile
from pyFAI import detectors

# Create PONI from scratch
poni = PoniFile()
poni.detector = detectors.detector_factory("Pilatus1M")
poni.dist = 0.1          # Sample-detector distance (m)
poni.poni1 = 0.05        # PONI Y coordinate (m)
poni.poni2 = 0.05        # PONI X coordinate (m)
poni.rot1 = 0.001        # Rotation 1 (rad)
poni.rot2 = -0.002       # Rotation 2 (rad)
poni.rot3 = 0.0          # Rotation 3 (rad)
poni.wavelength = 1e-10  # Wavelength (m)

# Save to file
poni.write("geometry.poni")

# Load from file
loaded_poni = PoniFile("geometry.poni")
print(f"Distance: {loaded_poni.dist} m")
print(f"Wavelength: {loaded_poni.wavelength*1e10:.4f} Å")
print(f"Detector: {loaded_poni.detector}")
```

--------------------------------

### Display pyFAI-integrate help message

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/usage/cookbook/integration_with_scripts.ipynb

The --help option displays all available command-line arguments and their descriptions for pyFAI-integrate, including options for output format, slow/fast motor dimensions, and configuration files.

```bash
pyFAI-integrate --help
```

--------------------------------

### Import pyFAI and Check Version

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/usage/tutorial/AzimuthalFilter.ipynb

Imports necessary libraries and prints the installed pyFAI version. Ensure pyFAI is installed and accessible.

```python
import os
import time
os.environ["PYOPENCL_COMPILER_OUTPUT"]="0"
import pyFAI
print(f"pyFAI version: {pyFAI.version}")
```

--------------------------------

### Set Locale for UTF-8 Issues

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/operations/macosx.rst

If you encounter UTF-8 related errors during installation, set the LC_ALL environment variable to 'C' before proceeding with the installation.

```shell
export LC_ALL=C
```

--------------------------------

### Detector and Instrument Setup

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/usage/tutorial/Inpainting/Inpainting.ipynb

Configures a specific detector ('Pilatus2MCdTe'), creates a mask, and initializes the pyFAI instrument object with specified wavelength and direct beam position.

```python
detector = pyFAI.detector_factory("Pilatus2MCdTe")
mask = detector.mask.copy()
nomask = numpy.zeros_like(mask)
detector.mask=nomask
ai = pyFAI.load({"detector":detector})
ai.setFit2D(200, 200, 200)
ai.wavelength = 3e-11
print(ai)
```

--------------------------------

### Set up sparse integrator using pyFAI

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/usage/tutorial/Separation/Wilson.ipynb

Loads configuration, initializes a pyFAI integrator with sparse capabilities, and sets up the engine for sparse integration. This involves defining the detector shape, number of points, mask, and algorithm.

```python
%%time
sparsify = nx_data.parent["sparsify"]
config = json.loads(sparsify["configuration/data"][()])
ai = pyFAI.load(config["geometry"])
engine = ai.setup_sparse_integrator(shape=ai.detector.shape,
                      npt=resolution.size, 
                      mask=numpy.logical_not(numpy.isfinite(mask)), 
                      unit="d*2_nm^-2",
                      split='no',
                      algo='CSR',
                      scale=True)
```

--------------------------------

### Clone PyFAI repository and install

Source: https://github.com/silx-kit/pyfai/blob/main/README.md

Clones the PyFAI Git repository and installs it. This is an alternative to downloading a zip archive for obtaining the latest development version.

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

--------------------------------

### Install pyFAI on Debian

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/project.rst

Use this command to update your package list and install pyFAI on Debian-based systems. Note that non-signed packages may need to be accepted.

```shell
sudo apt-get update
sudo apt-get install pyfai
```

--------------------------------

### Create and Activate Virtual Environment

Source: https://github.com/silx-kit/pyfai/blob/main/CONTRIBUTING.md

Create a Python 3 virtual environment and activate it for development.

```bash
python3 -m venv ~/.py3
```

```bash
source ~/.py3/bin/activate
```

--------------------------------

### Initialize and Configure Calibration Object

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/usage/tutorial/Flatfield.ipynb

Sets up an AbstractCalibration object with provided data, mask, detector, wavelength, and calibrant. It then preprocesses the data, initializes the geometry reference, and configures it with the adjusted detector parameters.

```python
AbstractCalibration.extract_cpt = extract_cpt
```

```python
calib1 = AbstractCalibration(data[1].calibration_data, detector.mask, detector, wavelength=wavelength, calibrant=calibrant)
calib1.preprocess()
calib1.data = []
calib1.geoRef = calib1.initgeoRef()
calib1.geoRef.set_config(ai1.get_config())
```

--------------------------------

### Install PyFAI using pip with wheels

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/operations/linux.rst

Installs PyFAI using pip after activating a Python virtual environment. This method is recommended for distributions without PyFAI packages.

```shell
pip install pyFAI
```

--------------------------------

### Set up file path and import libraries

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/usage/tutorial/Separation/Wilson.ipynb

Sets the filename and imports necessary libraries, changing the current directory to the file's directory. This is a common setup for file processing.

```python
filename="/mnt/data/jungfrau/sparse_512_3_0_2_fit_q2.h5"
import os, time
os.chdir(os.path.dirname(filename))
start_time = time.perf_counter()
```

--------------------------------

### Install PyFAI nightly build from silx repository

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/operations/linux.rst

Installs the latest nightly build of PyFAI by adding the silx repository to your apt sources. The nightly packages are not signed.

```shell
wget http://www.silx.org/pub/debian/silx.list
wget http://www.silx.org/pub/debian/silx.pref
sudo mv silx.list /etc/apt/sources.list.d/
sudo mv silx.pref /etc/apt/preferences.d/
sudo apt-get update
sudo apt-get install pyfai
```

--------------------------------

### Install PyFAI in editable mode after testing

Source: https://github.com/silx-kit/pyfai/blob/main/README.md

Installs PyFAI into the current Python environment after successful testing. This command should be run from the root directory of the PyFAI source code.

```sh
pip install .
```

--------------------------------

### Instantiate and Configure Calibrants

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/usage/tutorial/Calibrant/Calibrant.ipynb

Creates a dictionary of specified calibrant objects and prints their initial state. This prepares calibrants for use by setting their names.

```python
cals = dict((name,pyFAI.calibrant.ALL_CALIBRANTS(name)) for name in ("Si", "LaB6", "CeO2", "alpha_Al2O3"))
for k,v in cals.items():
    print(k,": ", v)
```

--------------------------------

### Install PyFAI dependencies from requirements.txt

Source: https://github.com/silx-kit/pyfai/blob/main/README.md

Installs all necessary Python packages required for PyFAI to function correctly. This command should be run after downloading the source code or cloning the repository.

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

--------------------------------

### Import necessary libraries and set up logging

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/usage/tutorial/Goniometer/Fit_wavelength/fit_energy.ipynb

Imports required modules for plotting, geometry transformations, calibration, data handling, and time measurement. Sets up basic logging and prints the pyFAI version.

```python
%matplotlib inline
#For documentation purpose, `inline` is used to enforce the storage of images into the notebook
# %matplotlib widget
import numpy
from matplotlib.pyplot import subplots
from pyFAI.goniometer import GeometryTransformation, ExtendedTransformation, SingleGeometry,
                             GoniometerRefinement, Goniometer
from pyFAI.calibrant import get_calibrant
import h5py
import pyFAI
from pyFAI.gui import jupyter
import time
start_time = time.perf_counter()
import logging
logging.basicConfig(level=logging.WARNING)
print(f"Running pyFAI version {pyFAI.version}")
```

--------------------------------

### Build and Start a Thread Pool

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/usage/tutorial/Parallelization/Direct_chunk_read.ipynb

Creates and starts a specified number of worker threads. Each thread runs a given worker function, consuming from an input queue and producing to an output queue.

```python
def build_pool(nbthreads, qin, qout, worker=None, funct=None):
    """Build a pool of threads with workers, and starts them"""
    pool = []
    for i in range(nbthreads):
        if funct is not None:
            worker = dummy_worker
            thread = threading.Thread(target=worker, name=f"{worker.__name__}_{i:02d}", args=(qin, qout, funct))
        elif worker is None:
            worker = dummy_worker
            thread = threading.Thread(target=worker, name=f"{worker.__name__}_{i:02d}", args=(qin, qout))
        else:
            thread = threading.Thread(target=worker, name=f"{worker.__name__}_{i:02d}", args=(qin, qout, filename))
        thread.start()
        pool.append(thread)
    return pool
```

--------------------------------

### Initialize Calibrant and Detector

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/usage/tutorial/ThickDetector/deconvolution.ipynb

Set up the calibrant with a specific wavelength and initialize the detector. Ensure the mask is correctly applied if needed.

```python
wavelength=0.6968e-10
calibrant = get_calibrant("LaB6")
calibrant.wavelength = wavelength
print(calibrant)

detector =  pyFAI.detector_factory("Pilatus1M")
detector.mask = mask

fimages = []
fimages.append(fabio.cbfimage.CbfImage(data=deconvoluted[0], header={"angle":0}))
fimages.append(fabio.cbfimage.CbfImage(data=deconvoluted[1], header={"angle":17}))
fimages.append(fabio.cbfimage.CbfImage(data=deconvoluted[2], header={"angle":45}))
```

--------------------------------

### Download sample data

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/usage/tutorial/Goniometer/Fit_wavelength/fit_energy.ipynb

Downloads the LaB6_20keV.h5 dataset from the specified URL using `silx.resources.ExternalResources`. This file contains sample data for geometry refinement.

```python
#Download data from internet

from silx.resources import ExternalResources

#Comment out and configure the proxy if you are behind a firewall
#os.environ["http_proxy"] = "http://proxy.company.com:3128"

downloader = ExternalResources("pyFAI", "http://www.silx.org/pub/pyFAI/gonio/", "PYFAI_DATA")
data_file = downloader.getfile("LaB6_20keV.h5")

print("file downloaded:", data_file)
```

--------------------------------

### Define Extended Transformation for Stage Setup

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/usage/tutorial/Goniometer/Fit_wavelength/fit_energy.ipynb

Defines an ExtendedTransformation for a sample stage setup, specifying parameters like distance, center positions, rotations, and energy. This is used when optimizing multiple geometric parameters simultaneously.

```python
goniotrans = ExtendedTransformation(param_names = ["dist0", "scale0", 
                                                   "poni1", "scale1",
                                                   "poni2", "scale2",
                                                   "rot1", "rot2", 
                                                   "energy"],
                                    dist_expr="dist0  + pos*scale0",
                                    poni1_expr="poni1 + pos*scale1",
                                    poni2_expr="poni2 + pos*scale2",
                                    rot1_expr="rot1",
                                    rot2_expr="rot2",
                                    rot3_expr="0",
                                    wavelength_expr="hc/energy*1e-10")
```

--------------------------------

### Generate and Display Ellipse Fit Example

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/usage/tutorial/Ellipse/ellipse.ipynb

This example generates noisy 2D points following an elliptical path, fits an ellipse to these points using `fit_ellipse`, and then displays the result using the `display` function. It requires numpy and pyFAI.utils.ellipse to be imported.

```python
from numpy import sin, cos, random, pi, linspace
arc = 0.8
npt = 100
R = linspace(0, arc * pi, npt)
ptx = 1.5 * cos(R) + 2 + random.normal(scale=0.05, size=npt)
pty = sin(R) + 1. + random.normal(scale=0.05, size=npt)

ellipse = fit_ellipse(pty, ptx)
print(ellipse)
display(ptx, pty, ellipse)
```

--------------------------------

### Instantiate and Populate GoniometerRefinement

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/usage/tutorial/Goniometer/Fit_wavelength/fit_energy.ipynb

Create a GoniometerRefinement object with initial parameters, bounds, and functions, then add geometries to it.

```python
gonioref = GoniometerRefinement(param,         # Initial guess
                                bounds=bounds, # Enforces constrains
                                pos_function=distance,
                                trans_function=goniotrans,
                                detector=detector, 
                                wavelength=wavelength_guess)
print("Empty refinement object:", gonioref)
for lbl, geo in geometries.items():
    sg = gonioref.new_geometry(str(lbl), image=geo.image, metadata=lbl, control_points=geo.control_points, calibrant=LaB6)
    print(lbl, sg.get_position())
print("Populated refinement object:", gonioref)
```

--------------------------------

### Display Video Tutorial

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/usage/cookbook/Integration_with_the_GUI.ipynb

Use this code to display an embedded video tutorial for PyFAI GUI integration. Ensure IPython.display is imported.

```python
# Video of this tutorial
from IPython.display import Video

Video("http://www.silx.org/pub/pyFAI/video/integration.mp4", width=800)
```

--------------------------------

### Start pyFAI-calib for Calibration

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/usage/cookbook/calib-cli/calibrate.rst

Initiate the pyFAI-calib process by providing essential parameters: energy (-e), detector distortion spline file (-s), calibrant type (-c), and the input image file. This command starts the interactive calibration process.

```shell
$ pyFAI-calib -e 29.4 -s F_K4320T_Cam43_30012013_distorsion.spline -c LaB6 LaB6_29.4keV.tif
```

--------------------------------

### Get Detector Energy

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/usage/tutorial/ThickDetector/Parallax_simple.ipynb

Retrieves the energy value from the detector configuration.

```python
ai.energy
```

--------------------------------

### OptimizeWarning Example

Source: https://github.com/silx-kit/pyfai/blob/main/doc/source/usage/tutorial/Goniometer/Rotation-XPADS540/D2AM-15.ipynb

This warning indicates that an unknown solver option was provided to the optimization method.

```text
/users/kieffer/.venv/py314/lib/python3.14/site-packages/pyFAI/goniometer.py:1001: OptimizeWarning: Unknown solver options: ftol
  res = minimize(self.residu3, param, method=method,

```