epattern 1.0.0

Electron diffraction pattern simulation, spot detection, and vector matching toolkit.

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: Gaussian-weighted spot-to-spot matching with intensity correlation
• Deep Sets encoder: Contrastive learning (Triplet Loss) for fast latent-space matching
• GPU acceleration via PyTorch (encoder) and CuPy (preprocessing)
• Multi-material phase identification and orientation determination

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

pip install epattern

GPU (CUDA 12)

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

GPU (CUDA 11)

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

epattern

Programmatic Usage

Simulation

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

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}},
    ],
)

Vector Matching

from epattern import create_encoder, run_matching

# Load a trained encoder
model = create_encoder(
    latent_dim=64,
    weights_path="weights/encoder.pt",
    device="cuda",
)

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

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

About

This project was developed within the Image & Data Science group of the LRCS laboratory / RS2E network, 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 file for details.