torchref 0.3.1

Tools for multicopy refinement of crystallographic models

TorchRef

A PyTorch-based crystallographic refinement library

TorchRef is a crystallographic refinement package built entirely on PyTorch. By leveraging PyTorch's automatic differentiation and GPU acceleration, TorchRef enables seamless integration with machine learning workflows and provides a flexible, extensible framework for crystallographic structure refinement.

Key Features

• Native PyTorch Integration: Built on PyTorch's nn.Module architecture, TorchRef integrates naturally with the PyTorch ecosystem, including machine learning models, optimizers, and GPU acceleration.

• Automatic Differentiation: Dynamic computational graphs eliminate the need for manually implemented gradient calculations. Define new refinement targets directly—PyTorch handles the derivatives automatically.

• Modular Architecture: Following PyTorch's module pattern, components are easily composable and extensible. Add custom targets, restraints, or optimizers without modifying core code.

• GPU Acceleration: Leverage CUDA for structure factor calculations, scaling, and optimization—achieving significant speedups for large structures.

• FFT-based Structure Factors: Efficient structure factor calculation using Fast Fourier Transform (FFT) methods, enabling rapid F_calc computation even for large unit cells.

• State Management: Full state_dict support enables saving and loading complete refinement states, including model parameters, scaler settings, and restraints.

Installation

# Clone the repository
git clone https://github.com/HatPdotS/TorchRef.git
cd torchref

# Install with pip
pip install -e .

# Or install with development dependencies
pip install -e ".[dev]"

Dependencies

• Python ≥ 3.8
• PyTorch ≥ 1.9
• NumPy ≥ 1.20
• Gemmi ≥ 0.5
• reciprocalspaceship ≥ 0.9
• SciPy ≥ 1.7

Getting Started

For demonstrations and usage examples, see the example notebooks in example_notebooks/:

• basic_usage.ipynb - Getting started tutorial
• code_examples.ipynb - Code examples and patterns
• target_exploration.ipynb - Exploring refinement targets

Testing

# Run all tests
pytest tests/

# Run with coverage
pytest tests/ --cov=torchref

# Run specific test categories
pytest tests/unit/           # Fast unit tests
pytest tests/integration/    # Integration tests
pytest tests/functional/     # Full workflow tests

Contributing

Contributions are welcome! Please follow these guidelines:

1. Follow the NumPy docstring style
2. Add tests for new functionality
3. Ensure all tests pass before submitting

License

This project is licensed under the MIT License - see the LICENSE file for details.