epattern 1.2.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

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

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

Encoder Training

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)

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)

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

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

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 for version history.

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.