# EDref v3

[![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 Engine** - A Python library for crystallographic structure refinement compatible with SHELXL.

## Overview

EDref is a modular implementation of least-squares crystallographic refinement on F². It can reproduce SHELXL's kinematic refinement workflow and supports both X-ray and electron diffraction data.

## Installation

```bash
# Development installation
cd EDref_v3
pip install -e .

# With development dependencies
pip install -e ".[dev]"
```

## Quick Start

```python
from edref import (
    InsFileReader, HklFileReader,
    SpaceGroup,
    calculate_reciprocal_cell,
    calculate_structure_factor,
    merge_reflections,
    calculate_R1,
)

# Load structure
ins = InsFileReader("structure.ins").read()
hkl = HklFileReader("structure.hkl").read()

# Setup
reciprocal = calculate_reciprocal_cell(ins.cell)
spacegroup = SpaceGroup(ins.latt, ins.symm)

# Merge reflections
merged = merge_reflections(hkl.reflections, spacegroup)

# Calculate structure factors
for refl in merged[:5]:
    Fc = calculate_structure_factor(
        refl.h, refl.k, refl.l,
        ins.atoms, ins.sfac,
        spacegroup, reciprocal,
        ins.wavelength
    )
    print(f"({refl.h},{refl.k},{refl.l}): |Fc|² = {abs(Fc)**2:.2f}")
```

## Package Structure

```
src/edref/
├── core/           # Crystallographic fundamentals
│   ├── crystallography.py   # Unit cell, d-spacing
│   ├── symmetry.py          # Space group operations
│   ├── scattering.py        # Atomic scattering factors
│   └── structure_factors.py # F(hkl) calculation
├── io/             # File I/O
│   ├── formats.py          # Data classes
│   └── shelxl.py           # SHELXL file readers
├── refinement/     # Least-squares refinement
│   ├── weighting.py        # SHELXL weighting scheme
│   └── statistics.py       # R-factors, GooF
└── analysis/       # Data processing
    └── merging.py          # Reflection merging
```

## Key Features

- **SHELXL-compatible**: Reproduces SHELXL kinematic refinement
- **Type hints**: Full type annotations for better IDE support
- **Modular design**: Use only the components you need
- **No hard-coded paths**: All paths are parameters
- **Electron diffraction**: Supports custom SFAC coefficients

## Validated Against SHELXL

- Aspirin (P2₁/c, 21 atoms): R1 within 0.32% of SHELXL
- Structure factors: Correlation > 0.9999 with SHELXL .fcf

## Command-Line Interface

EDref includes a CLI for running refinements:

```bash
# Run EDref refinement
edref structure.ins --edref

# Run SHELXL for comparison
edref structure.ins --shelxl

# Run both and compare results
edref structure.ins --compare

# With resolution cutoff
edref structure.ins --compare --resolution 99 0.8
```

## Requirements

- Python >= 3.10
- NumPy >= 1.21
- SciPy >= 1.7
- Matplotlib >= 3.5

## Documentation

- [Full Manual](manual.md) - Complete API reference and examples
- [Contributing Guide](CONTRIBUTING.md) - How to contribute
- [Citation](CITATION.cff) - How to cite EDref

## License

MIT License - see [LICENSE](LICENSE) for details
