midas-integrate 0.1.0__tar.gz

midas_integrate-0.1.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: midas-integrate
+Version: 0.1.0
+Summary: Pure-Python radial integration for area X-ray detectors (MIDAS) — DetectorMapper + CSR integration + streaming server, CPU/GPU selectable
+Author-email: Hemant Sharma <hsharma@anl.gov>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/marinerhemant/MIDAS
+Project-URL: Documentation, https://github.com/marinerhemant/MIDAS/tree/master/manuals
+Project-URL: Issues, https://github.com/marinerhemant/MIDAS/issues
+Keywords: MIDAS,X-ray,diffraction,radial integration,azimuthal integration,HEDM,SAXS,WAXS,PDF,detector,PyTorch,CUDA
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+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: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.22
+Requires-Dist: scipy>=1.9
+Requires-Dist: torch>=2.1
+Requires-Dist: tifffile>=2022.0
+Requires-Dist: h5py>=3.0
+Requires-Dist: numba>=0.59
+Requires-Dist: joblib>=1.2
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Provides-Extra: cuda
+
+# midas-integrate
+
+Pure-Python radial integration for area X-ray detectors. A drop-in,
+pip-installable replacement for the MIDAS C/CUDA radial integration
+pipeline — no compilers, no native libraries, no CMake.
+
+```bash
+pip install midas-integrate
+```
+
+## What's in the box
+
+| C/CUDA source                          | Python module                          |
+| -------------------------------------- | -------------------------------------- |
+| `MapperCore.c`, `DetectorGeometry.c`, `DetectorMapper.c` | `midas_integrate.detector_mapper`, `midas_integrate.geometry` |
+| `IntegratorFitPeaksGPUStream.cu` (GPU streaming) | `midas_integrate.kernels`, `midas_integrate.server`, `midas_integrate.pipeline` |
+| `IntegratorZarrOMP.c` (CPU OMP, bilinear) | `midas_integrate.kernels` (`mode='bilinear'`) |
+| `PeakFit.c`                            | `midas_integrate.peakfit`              |
+| `PeakFitIO.c`                          | `midas_integrate.peak_io`              |
+| `Map.bin` / `nMap.bin`                 | `midas_integrate.bin_io`               |
+
+## CPU/GPU selection
+
+Everything that touches arrays accepts a `device` argument that is forwarded
+to PyTorch. CPU and CUDA are first-class:
+
+```python
+from midas_integrate import build_csr, integrate, profile_1d, load_map
+
+pixmap = load_map('Map.bin', 'nMap.bin')
+geom_cpu  = build_csr(pixmap, n_r=990, n_eta=72, n_pixels_y=1475, n_pixels_z=1679, device='cpu')
+geom_cuda = build_csr(pixmap, ..., device='cuda')
+
+import torch
+img = torch.from_numpy(image_2d)
+profile = profile_1d(integrate(img, geom_cuda, mode='bilinear'), geom_cuda)
+```
+
+## Three integration modes (full parity with C codes)
+
+| `mode`      | Equivalent C kernel                                   | Use when |
+|-------------|--------------------------------------------------------|----------|
+| `'floor'`   | `integrate_noMapMask` in `IntegratorFitPeaksGPUStream.cu` | streaming, max throughput |
+| `'bilinear'`| pixel loop in `IntegratorZarrOMP.c` lines 1733–1744    | offline analysis, max accuracy |
+| `'gradient'`| `GradientCorrection=1` branch in the GPU stream         | strong tilt + small R |
+
+## CLI
+
+Three entry points mirror the C binaries:
+
+```bash
+# 1. Build Map.bin / nMap.bin from a parameter file (one-shot, slow):
+midas-detector-mapper params.txt -j 8
+
+# 2. Integrate one frame (one-shot, fast):
+midas-integrate params.txt --image frame.tif --device cuda
+
+# 3. Streaming socket server (matches the C wire protocol on port 60439):
+midas-integrate-server params.txt --device cuda --num-streams 4
+```
+
+## Numerical parity
+
+- DetectorMapper output (`Map.bin`/`nMap.bin`): byte-equivalent to the C
+  version (entry counts, sums of `frac` and `areaWeight` per bin agree to
+  ULP; entry order within a bin may differ).
+- Per-frame integration: float32 ULP-level (median 1.7e-8 relative error
+  vs the C/CUDA `IntegratorFitPeaksGPUStream` binary on PILATUS3 2M with
+  CeO₂ data; max 2.1e-7 relative).
+- Peak fitting: same model (pseudo-Voigt + global background, SNIP
+  background subtraction), different optimizer (scipy LM vs NLopt
+  Nelder-Mead). Fit parameters typically agree to ~1e-5 relative on
+  noisy real data.
+
+## Performance (PILATUS3 2M, 1475×1679, NVIDIA H100)
+
+|                                              | Throughput       |
+|----------------------------------------------|------------------|
+| C MIDAS GPU stream (per the paper)           | ~1,600 fps       |
+| **midas-integrate (PyTorch CSR, FP32, CUDA)**| **~3,250 fps**   |
+| midas-integrate (PyTorch CSR, FP64, CPU)     | ~675 fps         |
+| C MIDAS CPU (per the paper)                  | ~262 fps         |
+| pyFAI CSR-cython (per the paper)             | ~7 fps           |
+
+## Requirements
+
+- Python ≥ 3.9
+- numpy, scipy, torch, tifffile, h5py, joblib
+
+CUDA support is automatic if your installed `torch` has CUDA. macOS Metal (MPS)
+works for the integration kernel; sparse-CSR support on MPS is partial as of
+torch 2.7.
+
+## License
+
+BSD-3-Clause. See LICENSE.

midas_integrate-0.1.0/README.md

@@ -0,0 +1,96 @@
+# midas-integrate
+
+Pure-Python radial integration for area X-ray detectors. A drop-in,
+pip-installable replacement for the MIDAS C/CUDA radial integration
+pipeline — no compilers, no native libraries, no CMake.
+
+```bash
+pip install midas-integrate
+```
+
+## What's in the box
+
+| C/CUDA source                          | Python module                          |
+| -------------------------------------- | -------------------------------------- |
+| `MapperCore.c`, `DetectorGeometry.c`, `DetectorMapper.c` | `midas_integrate.detector_mapper`, `midas_integrate.geometry` |
+| `IntegratorFitPeaksGPUStream.cu` (GPU streaming) | `midas_integrate.kernels`, `midas_integrate.server`, `midas_integrate.pipeline` |
+| `IntegratorZarrOMP.c` (CPU OMP, bilinear) | `midas_integrate.kernels` (`mode='bilinear'`) |
+| `PeakFit.c`                            | `midas_integrate.peakfit`              |
+| `PeakFitIO.c`                          | `midas_integrate.peak_io`              |
+| `Map.bin` / `nMap.bin`                 | `midas_integrate.bin_io`               |
+
+## CPU/GPU selection
+
+Everything that touches arrays accepts a `device` argument that is forwarded
+to PyTorch. CPU and CUDA are first-class:
+
+```python
+from midas_integrate import build_csr, integrate, profile_1d, load_map
+
+pixmap = load_map('Map.bin', 'nMap.bin')
+geom_cpu  = build_csr(pixmap, n_r=990, n_eta=72, n_pixels_y=1475, n_pixels_z=1679, device='cpu')
+geom_cuda = build_csr(pixmap, ..., device='cuda')
+
+import torch
+img = torch.from_numpy(image_2d)
+profile = profile_1d(integrate(img, geom_cuda, mode='bilinear'), geom_cuda)
+```
+
+## Three integration modes (full parity with C codes)
+
+| `mode`      | Equivalent C kernel                                   | Use when |
+|-------------|--------------------------------------------------------|----------|
+| `'floor'`   | `integrate_noMapMask` in `IntegratorFitPeaksGPUStream.cu` | streaming, max throughput |
+| `'bilinear'`| pixel loop in `IntegratorZarrOMP.c` lines 1733–1744    | offline analysis, max accuracy |
+| `'gradient'`| `GradientCorrection=1` branch in the GPU stream         | strong tilt + small R |
+
+## CLI
+
+Three entry points mirror the C binaries:
+
+```bash
+# 1. Build Map.bin / nMap.bin from a parameter file (one-shot, slow):
+midas-detector-mapper params.txt -j 8
+
+# 2. Integrate one frame (one-shot, fast):
+midas-integrate params.txt --image frame.tif --device cuda
+
+# 3. Streaming socket server (matches the C wire protocol on port 60439):
+midas-integrate-server params.txt --device cuda --num-streams 4
+```
+
+## Numerical parity
+
+- DetectorMapper output (`Map.bin`/`nMap.bin`): byte-equivalent to the C
+  version (entry counts, sums of `frac` and `areaWeight` per bin agree to
+  ULP; entry order within a bin may differ).
+- Per-frame integration: float32 ULP-level (median 1.7e-8 relative error
+  vs the C/CUDA `IntegratorFitPeaksGPUStream` binary on PILATUS3 2M with
+  CeO₂ data; max 2.1e-7 relative).
+- Peak fitting: same model (pseudo-Voigt + global background, SNIP
+  background subtraction), different optimizer (scipy LM vs NLopt
+  Nelder-Mead). Fit parameters typically agree to ~1e-5 relative on
+  noisy real data.
+
+## Performance (PILATUS3 2M, 1475×1679, NVIDIA H100)
+
+|                                              | Throughput       |
+|----------------------------------------------|------------------|
+| C MIDAS GPU stream (per the paper)           | ~1,600 fps       |
+| **midas-integrate (PyTorch CSR, FP32, CUDA)**| **~3,250 fps**   |
+| midas-integrate (PyTorch CSR, FP64, CPU)     | ~675 fps         |
+| C MIDAS CPU (per the paper)                  | ~262 fps         |
+| pyFAI CSR-cython (per the paper)             | ~7 fps           |
+
+## Requirements
+
+- Python ≥ 3.9
+- numpy, scipy, torch, tifffile, h5py, joblib
+
+CUDA support is automatic if your installed `torch` has CUDA. macOS Metal (MPS)
+works for the integration kernel; sparse-CSR support on MPS is partial as of
+torch 2.7.
+
+## License
+
+BSD-3-Clause. See LICENSE.

midas_integrate-0.1.0/midas_integrate/__init__.py

@@ -0,0 +1,124 @@
+"""midas-integrate — pure-Python radial integration for area X-ray detectors.
+
+Public API surface (re-exports from submodules so users can do
+`from midas_integrate import build_csr` etc.).
+"""
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from midas_integrate.bin_io import (
+    PXLIST_DTYPE,
+    MAP_HEADER_MAGIC,
+    MAP_HEADER_SIZE,
+    MapHeader,
+    PixelMap,
+    load_map,
+    write_map,
+    write_synthetic_map,
+)
+from midas_integrate.params import IntegrationParams, parse_params
+from midas_integrate.geometry import (
+    DEG2RAD,
+    RAD2DEG,
+    build_tilt_matrix,
+    pixel_to_REta,
+    REta_to_YZ,
+    build_bin_edges,
+    build_q_bin_edges_in_R,
+    polygon_area,
+    circle_seg_intersect,
+    ray_seg_intersect,
+    point_in_quad,
+    invert_REta_to_pixel,
+)
+from midas_integrate.detector_mapper import build_map, BuildMapResult
+from midas_integrate.kernels import (
+    AREA_THRESHOLD,
+    CSRGeometry,
+    build_csr,
+    integrate,
+    profile_1d,
+)
+from midas_integrate.image import (
+    bytes_per_pixel,
+    decode_payload,
+    decode_hybrid_payload,
+    NUMPY_DTYPE_FOR_CODE,
+    DTYPE_CODE_UINT8,
+    DTYPE_CODE_UINT16,
+    DTYPE_CODE_UINT32,
+    DTYPE_CODE_INT64,
+    DTYPE_CODE_FLOAT32,
+    DTYPE_CODE_FLOAT64,
+    DTYPE_CODE_HYBRID,
+)
+from midas_integrate.peakfit import (
+    fit_peaks,
+    fit_peaks_autodetect,
+    pseudo_voigt,
+    snip_background,
+    PF_PARAMS_PER_PEAK,
+)
+from midas_integrate.fused_csr import build_fused_geometry
+from midas_integrate.postprocess import gauss_smooth_eta, median_filter_eta
+
+__all__ = [
+    "__version__",
+    # bin_io
+    "PXLIST_DTYPE",
+    "MAP_HEADER_MAGIC",
+    "MAP_HEADER_SIZE",
+    "MapHeader",
+    "PixelMap",
+    "load_map",
+    "write_map",
+    "write_synthetic_map",
+    # params
+    "IntegrationParams",
+    "parse_params",
+    # geometry
+    "DEG2RAD",
+    "RAD2DEG",
+    "build_tilt_matrix",
+    "pixel_to_REta",
+    "REta_to_YZ",
+    "build_bin_edges",
+    "build_q_bin_edges_in_R",
+    "polygon_area",
+    "circle_seg_intersect",
+    "ray_seg_intersect",
+    "point_in_quad",
+    "invert_REta_to_pixel",
+    # detector_mapper
+    "build_map",
+    "BuildMapResult",
+    # kernels
+    "AREA_THRESHOLD",
+    "CSRGeometry",
+    "build_csr",
+    "integrate",
+    "profile_1d",
+    # image
+    "bytes_per_pixel",
+    "decode_payload",
+    "decode_hybrid_payload",
+    "NUMPY_DTYPE_FOR_CODE",
+    "DTYPE_CODE_UINT8",
+    "DTYPE_CODE_UINT16",
+    "DTYPE_CODE_UINT32",
+    "DTYPE_CODE_INT64",
+    "DTYPE_CODE_FLOAT32",
+    "DTYPE_CODE_FLOAT64",
+    "DTYPE_CODE_HYBRID",
+    # peakfit
+    "fit_peaks",
+    "fit_peaks_autodetect",
+    "pseudo_voigt",
+    "snip_background",
+    "PF_PARAMS_PER_PEAK",
+    # alias-mitigation API (Family II + III)
+    "build_fused_geometry",
+    "gauss_smooth_eta",
+    "median_filter_eta",
+]