edref 3.7.3
Electron Diffraction Refinement Engine - SHELXL-compatible crystallographic refinement for 3D ED/microED
License: MIT
Requires Python: >=3.10
Keywords: crystallography, electron-diffraction, 3D-ED, microED, structure-refinement, SHELXL, least-squares, structure-factors

# EDref

[![Pipeline Status](https://gitlab.com/crystaldiffractor/edref/badges/main/pipeline.svg)](https://gitlab.com/crystaldiffractor/edref/-/pipelines)
[![Coverage](https://gitlab.com/crystaldiffractor/edref/badges/main/coverage.svg)](https://gitlab.com/crystaldiffractor/edref/-/commits/main)
[![PyPI version](https://img.shields.io/pypi/v/edref.svg)](https://pypi.org/project/edref/)
[![Python versions](https://img.shields.io/pypi/pyversions/edref.svg)](https://pypi.org/project/edref/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Electron Diffraction Refinement** - SHELXL-compatible least-squares refinement with dynamical scattering correction for 3D ED data.

## Installation

```bash
pip install edref
```

## Quick Start

```bash
# Basic refinement
edref structure.ins --edref

# With dynamical correction (recommended for ED data)
edref structure.ins --edref --dyn-power

# Anisotropic with dynamical correction
edref structure.ins --edref --dyn-power --aniso
```

## Dynamical Scattering Correction

EDref can correct for dynamical scattering effects that cause systematic intensity errors in electron diffraction data:

```bash
# Power-shape model (recommended)
edref structure.ins --edref --dyn-power

# With fixed parameters (no auto-optimization)
edref structure.ins --edref --dyn-power-params 0.8 0.3
```

**Available models:**
| Flag | Parameters | Description |
|------|------------|-------------|
| `--dyn-power` | α, γ | Power-shape correction (recommended) |
| `--dyn-exp` | α, d_decay | Exponential decay |
| `--dyn-abs` | α, d_half, γ | Absolute intensity model |
| `--dynamical1` | κ | Simple 1-parameter |

## Auto-Dyn Workflow

Automated refinement with cascading outlier removal:

```bash
# Auto-dyn with dynamical correction
edref structure.ins --auto-dyn --dyn-power

# With anisotropic refinement and weight optimization
edref structure.ins --auto-dyn --dyn-power --aniso --refine-weights
```

The auto-dyn workflow:
1. Initial refinement (50 cycles)
2. Cascading Z-threshold outlier removal (Z=8, 6, 4)
3. Re-refinement after each omit round

## Common Options

```bash
# Resolution limits (d_max to d_min in Angstrom)
edref structure.ins --edref --resolution 20 0.8

# Number of refinement cycles
edref structure.ins --edref --cycles 100

# Extinction correction
edref structure.ins --edref --exti

# R-free cross-validation
edref structure.ins --edref --rfree

# Custom output path
edref structure.ins --edref --output refined/mystructure
```

## Iterative Outlier Removal

For manual control over outlier removal:

```bash
edref structure.ins --edref --dyn-power --iterative \
    --iter-threshold 4 \
    --iter-rounds 10
```

## Output Files

EDref generates:
- `structure_edref.res` - Refined structure (SHELXL format)
- `structure_edref.fcf` - Structure factors (Olex2-compatible)
- `structure_corrected.hkl` - Dynamically-corrected intensities
- `structure_edref_refine.png` - Refinement diagnostics
- `structure_edref_outliers.png` - Outlier analysis

## SHELXL Comparison

```bash
# Run SHELXL only
edref structure.ins --shelxl

# Compare EDref vs SHELXL
edref structure.ins --compare
```

## Key Features

- **Dynamical correction** - Multiple models for ED intensity correction
- **Auto-dyn workflow** - Automated outlier removal with cascading thresholds
- **SHELXL-compatible** - Reads/writes standard .ins/.res/.hkl/.fcf files
- **Olex2-compatible** - FCF output works directly in Olex2
- **R-free validation** - Cross-validation to detect overfitting
- **Anisotropic ADPs** - Full anisotropic refinement support
- **Special positions** - Automatic constraint detection

## Requirements

- Python >= 3.10
- NumPy, SciPy, Matplotlib

## Documentation

- [Full Manual](https://gitlab.com/crystaldiffractor/edref/-/blob/main/manual.md) - Complete reference
- [GitLab Repository](https://gitlab.com/crystaldiffractor/edref)

## License

MIT License