Metadata-Version: 2.4
Name: epattern
Version: 1.2.0
Summary: Electron diffraction pattern simulation, spot detection, and vector matching toolkit.
License-Expression: Apache-2.0
License-File: LICENSE
Author: Liu François
Author-email: liu.francois.kanayama@gmail.com
Maintainer: Arnaud Demortière
Maintainer-email: arnaud.demortiere@u-picardie.fr
Requires-Python: >=3.11,<3.15
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Provides-Extra: cuda11
Provides-Extra: cuda12
Provides-Extra: order
Requires-Dist: abtem (>=1.0.9,<2.0.0)
Requires-Dist: ase (>=3.22)
Requires-Dist: cupy-cuda11x (>=13.6.0,<14.0.0) ; extra == "cuda11"
Requires-Dist: cupy-cuda12x (>=13.6.0,<14.0.0) ; extra == "cuda12"
Requires-Dist: h5py (>=3.10,<4.0.0)
Requires-Dist: joblib (>=1.4,<2.0.0)
Requires-Dist: matplotlib (>=3.8,<4.0.0)
Requires-Dist: numpy (<2.0)
Requires-Dist: opencv-python (<5.0.0)
Requires-Dist: pandas (>=2.2,<3.0.0)
Requires-Dist: pillow (>=10.0.0,<12.0.0)
Requires-Dist: scikit-image (>=0.22,<1.0.0)
Requires-Dist: scipy (>=1.12,<2.0.0)
Requires-Dist: seaborn (==0.13.2) ; extra == "order"
Requires-Dist: torch (>=2.4.0)
Requires-Dist: tqdm (>=4.66,<5.0.0)
Description-Content-Type: text/markdown

# ePattern

ePattern is a Python toolkit for electron diffraction pattern simulation, spot detection, and crystal orientation indexing via vector matching.

## Features

### Simulation
- Bloch-wave diffraction spot simulation using abTEM
- HDF5 export with orientation index
- Configurable tilt ranges and parallel execution

### Spot Detection
- Preprocessing pipeline with multiple noise reduction methods (Gaussian, DoG, Top-Hat, Rolling Ball)
- Auto-prominence or manual prominence peak detection
- Sub-pixel centroid refinement
- Optional coordinate alignment
- HDF5 export of detected spots

### Vector Matching

#### Geometric Baseline
Direct spot-to-spot comparison between experimental and simulated patterns:
- Gaussian-weighted position matching (σ configurable)
- Pearson intensity correlation on matched spots
- Combined score: 70% position + 30% intensity
- No training required — works out of the box

#### DeePattern Encoder
Deep Sets architecture trained with contrastive learning for fast latent-space matching:
- Per-spot MLP (4 → 128 → 256 → 256) with SiLU, LayerNorm, Dropout
- Masked pooling: mean + max + attention
- Global MLP (768 → 512 → 256 → 64) producing a compact latent vector
- Triplet Loss training with cosine distance
- ~480× faster than baseline at inference

Both methods support multi-material databases and GPU acceleration.

### Order Quantification
- Cation ordering analysis from superstructure spot intensities
- Alignment, detection and intensity ratio computation
- Color-mapped order ratio visualization
- Install with `pip install "epattern[order]"`

### GUI
- Integrated Tkinter interface for all features
- Visual verification of detected spots

## Requirements

- Python 3.11 or higher
- NVIDIA GPU (optional, for CUDA acceleration)

## Installation

### CPU only

```bash
pip install epattern
```

### GPU (CUDA 12)

```bash
pip install torch --index-url https://download.pytorch.org/whl/cu124
pip install "epattern[cuda12]"
```

### GPU (CUDA 11)

```bash
pip install torch --index-url https://download.pytorch.org/whl/cu118
pip install "epattern[cuda11]"
```

> **Note**: Check your CUDA version with `nvidia-smi` before choosing.

## Quick Start

### Launch the GUI

```bash
epattern
```

### Programmatic Usage

#### Simulation

```python
from epattern import simulate_diffraction

simulate_diffraction(
    cif_file="structure.cif",
    output_path="simulation.h5",
    detector_size=512,
    camera_length=200,
    pixel_size=14,
    energy=200000,
    thickness=500,
    g_max=1.5,
    sg_max=0.1,
    intensity_threshold=1.5,
    tilt_x_min=-2,
    tilt_x_max=2,
    tilt_x_step=1,
    tilt_y_min=-2,
    tilt_y_max=2,
    tilt_y_step=1,
    tilt_z_min=-2,
    tilt_z_max=2,
    tilt_z_step=1,
    batch_size=10,
    parallel_workers=2,
)
```

#### Spot Detection

```python
from epattern import detect_spots

peaks, transforms, settings = detect_spots(
    data_path="path/to/images",
    scan_cols=100,
    output_path="output/detection.h5",
    binning=True,
    align=True,
    auto_prominence=True,
    prominence_min=2.0,
    noise_factor=1.8,
    background_percentile=20.0,
    min_distance=8,
    threshold=3.0,
    max_items=150,
    noise_reduction_methods=[
        {"name": "Gaussian", "params": {"sigma": 1.0}},
    ],
)
```

#### Encoder Training

```python
from epattern import train_encoder

# Train DeePattern on simulation databases
model = train_encoder(
    sim_h5_paths=["LMNO.h5", "LFP.h5", "SiO2.h5"],
    output_path="weights/deepattern.pt",
    epochs=100,
    batch_size=256,
    latent_dim=64,
    device="cuda",
)
```

#### Vector Matching (Encoder)

```python
from epattern import create_encoder, run_matching

# Load the pre-trained encoder shipped with ePattern
model = create_encoder(use_default_weights=True, device="cuda")

# Or load your own weights
# model = create_encoder(weights_path="weights/deepattern.pt", device="cuda")

# Match experimental patterns against reference databases
results = run_matching(
    query_h5="detection.h5",
    ref_h5_paths=["LMNO.h5", "LFP.h5"],
    method="encoder",
    model=model,
    top_k=5,
    device="cuda",
    output_path="results/matching.csv",
)

# Results is a DataFrame with predicted materials and orientations
print(results[["scan_x", "scan_y", "pred_material_name", "confidence"]])
```

#### Vector Matching (Baseline)

```python
from epattern import run_matching

# No model needed — direct geometric comparison
results = run_matching(
    query_h5="detection.h5",
    ref_h5_paths=["LMNO.h5", "LFP.h5"],
    method="baseline",
    sigma_px=3.0,
    top_k=5,
    output_path="results/baseline.csv",
)
```


#### Order Quantification
```python
from epattern.order import Order_quantification
Order_quantification(
    file_path="data/spots.csv",
    output_path="output/",
    columns=["X_scan", "Y_scan", "X_acc", "Y_acc", "Mean"],
    principal_spots_o3=[[100, 200], [150, 250]],
    extra_spots_o3=[[120, 180], [170, 230]],
    radius_limit=15.0,
    x_c_o3=256.0,
    y_c_o3=256.0,
    real_space_image_size=(512, 512),
    custom_colors={"high": "red", "low": "blue"},
)
```

## abTEM Patch

abTEM (≥1.0.9) contains a bug where in-place operations are performed on read-only NumPy arrays during Bloch wave calculations, causing `ValueError: output array is read-only`.

ePattern includes an automatic patch that fixes this. Apply it once after installing abTEM:

### Via the GUI

Click the **"Patch abTEM"** button on the home page or in the header.

### Via Python

```python
from epattern.utils.abtem_patch import apply_abtem_patch

success, message = apply_abtem_patch()
print(message)
```

The patch modifies `abtem/bloch/dynamical.py` to insert `.copy()` calls before in-place operations. A backup of the original file is created automatically. Restart Python after applying.


## Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history.


## About

This project was developed within the **Image & Data Science** group of the [LRCS laboratory](https://www.lrcs.u-picardie.fr/) / [RS2E network](https://www.energie-rs2e.com/en), led by Arnaud Demortière (Director of Research at CNRS). The group develops Deep Learning and AI-based algorithms to analyze diffraction patterns and multispectral imagery for battery materials research.


## Authors and Contributors

Author:
- Liu François

Contributors:
- Fayçal Adrar
- Junhao Cao
- Nicolas Folastre
- Arnaud Demortière

## License

This project is distributed under the Apache License 2.0.
See the [LICENSE](LICENSE) file for details.

