Metadata-Version: 2.4
Name: xpcs-correlator
Version: 0.1.0
Summary: XPCS correlation calculations for synchrotron experiments
Author-email: Maciej Jankowski <maciej.jankowski@esrf.fr>
License-Expression: MIT
Project-URL: Repository, https://gitlab.esrf.fr/mj/xpcs_developments/xpcscorr
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: dask
Requires-Dist: dask_jobqueue
Requires-Dist: h5py
Requires-Dist: hdf5plugin
Requires-Dist: threadpoolctl
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: memory_profiler; extra == "dev"
Requires-Dist: line_profiler; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

# xpcs-correlator

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![Repository](https://img.shields.io/badge/Repo-GitLab-ff69b4.svg)](https://gitlab.esrf.fr/mj/xpcs_developments/xpcscorr)

## Table of contents
- About
- Features
- Requirements
- Installation
- Quickstart
- Configuration / Logging
- Tests
- Contributing
- License
- Contact

## About
This package consolidates ongoing development of correlators for XPCS data analysis at ESRF, with a focus on the ID02 and ID10-coh beamlines.

## Features
- Dense frames data reference and chunked correlator implementations.
- Calculates g2, g2 errors, and ttcf (2-time correlation function).
- The ttcf calculations support linear binning for t1,t2 format and hybrid linear log binning for age,lag format.
- Designed to handle large frame stacks via chunked (partitioned) processing.
- Supports Dask for both cluster (SLURM) and local parallel execution

## Requirements
- Python 3.10+ (recommended: 3.10, 3.11, 3.12)
- numpy
- dask
- dask_jobqueue
- h5py
- hdf5plugin
- threadpoolctl

## Installation
Install in editable/develop mode (recommended during development):

```bash
pip install -e .
```

Install with development extras (for running tests and linters):

```bash
pip install -e .[dev]
```

When published to PyPI the package can be installed with:

```bash
pip install xpcs-correlator
```

## Quickstart
Basic usage example — adapt to your data shape and correlator options:

```python
import numpy as np
from xpcscorr import correlator_dense_reference, correlator_dense_chunked

# Replace with your frames array; shape here is (n_frames, nx_pixels, ny_pixels)
frames = np.random.random((100,512, 512))
roimask= np.ones((512,512), dtype=bool)

# Run reference  correlator
result_ref = correlator_dense_reference(frames, roimask)

# Run chunked correlator (handles large data in chunks)
extra_options = {'chunks_N': 3}
result_chunked = correlator_dense_chunked(frames, roimask, extra_options=extra_options)

print(type(result_ref), type(result_chunked))
```

Notes:
- Replace the synthetic `frames` with your real dataset (HDF5 dataset or numpy array).
- Check correlator function docstrings for exact argument names and options.

## Configuration / Logging
Control logging with environment variables used by the package (see `src/xpcscorr/__init__.py`):

- `XPCSCORR_LOG_TO_CLI` — set to `1` to enable logging to stdout (default in development)
- `XPCSCORR_LOG_TO_FILE` — set to `1` to enable logging to a file named `xpcscorr.log`

Example:

```bash
export XPCSCORR_LOG_TO_CLI=1
export XPCSCORR_LOG_TO_FILE=0
```

## Tests
Run tests with pytest:

```bash
pip install -e .[dev]
pytest -q
```

There are unit tests under `tests/` that exercise correlator behavior and core utilities.

## Contributing
- Open issues for bugs or feature requests.
- Fork the repo, create a feature branch, add tests, and submit a pull request.
- Keep changes small, document API changes, and add tests for new behavior.

## License
This project is licensed under the MIT License — see the `LICENSE` file for details.

## Contact
Maintainer: Maciej Jankowski — maciej.jankowski@esrf.fr


<!-- EOF -->

