Dev

docs/api.rst

@@ -1,14 +1,18 @@
 API Reference
 =============
 
-The API reference is generated automatically from the package docstrings.
+Generated automatically from the package docstrings. ``torchref.experimental``
+is deliberately absent: it holds unvalidated code (alignment, kinetics,
+ensemble and monolithic refinement) whose API is expected to move.
 
 .. autosummary::
    :toctree: api/
    :recursive:
 
    torchref.cli
+   torchref.config
    torchref.io
+   torchref.maps
    torchref.model
    torchref.refinement
    torchref.restraints

docs/changelog.rst

@@ -1,6 +1,20 @@
 Changelog
 =========
 
+Version 0.6.2
+-------------
+- Deprecated outlier flagging strategy 
+- Rewrote X‑ray targets into five independent classes (nll, nll_beta, ml, ml_noalpha, ml_full) and XRAY_TARGETS.by_name.
+- Consolidated X‑ray loss math into Gaussian, Rice, marginalised Rice primitives; NLLXrayTarget replaces GaussianXrayTarget.
+- Fixed crash in difference refinement with mismatched reflection files: HKL reindexing (``validate_hkl``/``remap``/``reduce_to_spacegroup``) now carries all per-reflection fields (including the anomalous bookkeeping read by ``hkl_for_sf()``) instead of a hardcoded subset.
+- Added a metal shader for structure factor calculation
+- Standardized structure factor calculation geometry
+- Split gpu tests into cuda and mps
+- Reworked VDW pair list creation
+- Reworked backend dispatch: which kernel runs is now read from one declarative table per kernel family (device, dtype, availability probe, failure policy), replacing two hand-written if/elif ladders.
+- Added preconditioned L-BFGS optimizer for joined refinement.
+
+
 Version 0.6.1
 -------------
 - Fixed bug in beta estimation that caused instability in GPU refinement
@@ -29,19 +43,19 @@ Version 0.6.0
 - Updated many docstrings, and fixed some bugs
 
 Version 0.5.3.3
--------------
+---------------
 - Fixed U_aniso parametrization and line search instability during refinement with anisotropic b-factor
 - Fixed kinetic module import 
 - Set default similarity weight in difference refinement to 0
 
 Version 0.5.3.2
--------------
+---------------
 - Added 10GB Gram requirement for default gpu device selection
 - Slaved cli device detection to the default device selection
 - Fixed device mismatch crash on CUDA/MPS when the VDW pair list was refreshed mid-refinement: the maintenance-triggered rebuild now migrates the fresh VDW pair list, hydrogen topology, and exclusion hash to the model device (PR #19)
 
 Version 0.5.3.1
--------------
+---------------
 - Fixed problem where TorchRef defaults to old gpus and crashes, now checking if gpu is actually usable, before setting default device to cuda, if not it will default to cpu and print a warning.
 
 Version 0.5.3
@@ -63,7 +77,7 @@ Version 0.5.1
 - Separated out loss functions from targets, logic moved to base/targets
 - Added Triton kernels with analytic backward for all four xray Targets and most other Targets
 - Cached XrayTarget.get_data constants across closures
-- Replaced slow tensor[indices] backwards (sort + dedup scatter) with index_add_ in the symmetry extractor, scaler bin gathers, and MixedTensor; skip the indexing in get_iso / get_aniso when it covers all atoms
+- Replaced slow tensor[indices] backwards (sort + dedup scatter) with ``index_add_`` in the symmetry extractor, scaler bin gathers, and MixedTensor; skip the indexing in get_iso / get_aniso when it covers all atoms
 
 Version 0.5.0
 -------------

docs/conf.py

@@ -16,8 +16,7 @@
 copyright = '2026, Hans Peter Seidel'
 author = 'Hans Peter Seidel'
 
-# Derive the documented version from the installed package so the docs are
-# always stamped with the real release (torchref/__init__.py __version__).
+# Single source of truth for the version: torchref/__init__.py __version__.
 import torchref  # noqa: E402
 
 release = torchref.__version__
@@ -81,13 +80,12 @@
 }
 
 templates_path = ['_templates']
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'api/torchref.alignment*.rst', 'api/torchref.math_functions*.rst']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = 'sphinx_rtd_theme'  # Read the Docs theme (popular, clean)
-html_static_path = ['_static']
 
 # Theme options
 html_theme_options = {

docs/contributing.rst

@@ -1,51 +1,45 @@
 Contributing
 ============
 
-Contributions are very welcome. This started as a small personal project but has become quite complex.
-If you have any idea for improvement or find a bug let me know via a github issue or fix it yourself and submit a pull request!
-
+Contributions are very welcome. If you have an idea for an improvement or find a
+bug, open a GitHub issue — or fix it yourself and send a pull request.
 
 Development Setup
 -----------------
 
-1. Clone the repository:
-
-   .. code-block:: bash
-
-      git clone https://github.com/HatPdotS/TorchRef.git
-      cd torchref
-
-2. Install in development mode:
-
-   .. code-block:: bash
+.. code-block:: bash
 
-      pip install -e ".[dev]"
+   git clone https://github.com/HatPdotS/TorchRef.git
+   cd TorchRef
+   pip install -e ".[dev]"
 
 Use of Generative AI
 --------------------
 
-Please feel free to use it; most of the docstrings were written with its help
-and only corrected. I used it a lot for docstrings and refactoring.
+Please feel free to use it, including for docstrings and refactoring. Review what
+it produces against the code before submitting.
 
 Code Style
 ----------
 
-We follow these conventions:
-
-- **Python Style**: PEP 8 with 88 character line length (Black formatter)
-- **Docstrings**: NumPy style (see below)
-- **Type Hints**: Use type hints for all public functions
+- **Python**: PEP 8, 88-character lines (Black)
+- **Type hints**: on all public functions
+- **Docstrings**: NumPy style on every public function, method, and class
 
 Docstring Format
 ----------------
 
-All public functions, methods, and classes must have NumPy-style docstrings:
+A docstring answers "how do I call this and what will it do to me?" for someone
+who is not going to read the body. Document the contract — what it does,
+parameters, returns, raises — and any trap a caller needs to avoid a silently
+wrong result: dtype or device restrictions, in-place mutation, a cache that must
+be invalidated afterwards. Keep design rationale to a clause, and leave benchmark
+numbers and superseded approaches to the commit history.
 
 .. code-block:: python
 
    def compute_structure_factors(hkl, xyz, b_factors):
-       """
-       Compute structure factors for given reflections.
+       """Compute structure factors for the given reflections.
 
        Parameters
        ----------
@@ -65,43 +59,26 @@ All public functions, methods, and classes must have NumPy-style docstrings:
        ------
        ValueError
            If tensor shapes are incompatible.
-
-       Examples
-       --------
-       >>> hkl = torch.tensor([[1, 0, 0], [0, 1, 0]])
-       >>> xyz = torch.tensor([[0.0, 0.0, 0.0]])
-       >>> b = torch.tensor([20.0])
-       >>> F = compute_structure_factors(hkl, xyz, b)
        """
-       pass
+
+Don't restate the signature in prose — types live in the annotations. Don't add
+an ``Examples`` block that is entirely ``# doctest: +SKIP``: it costs lines and
+tests nothing. The examples in :doc:`quickstart` run under
+``sphinx.ext.doctest``, so put runnable examples there and they will be checked.
 
 Running Tests
 -------------
 
-Run the test suite:
-
 .. code-block:: bash
 
-   # All tests
-   pytest tests/
+   pytest tests/                    # all tests
+   pytest tests/ --cov=torchref     # with coverage
+   pytest tests/unit/               # fast unit tests only
 
-   # With coverage
-   pytest tests/ --cov=torchref
-
-   # Specific test categories
-   pytest tests/unit/           # Fast unit tests
-   pytest tests/integration/    # Integration tests
+GPU, slow, and Amber tests are skipped unless enabled. See :doc:`user_guide/testing`.
 
 Submitting Changes
 ------------------
 
-1. Create a branch for your changes
-2. Make your changes with appropriate tests
-3. Ensure all tests pass
-4. Submit a pull request
-
-Please include:
-
-- Clear description of the changes
-- Any relevant issue numbers
-- Tests for new functionality
+1. Branch, change, add tests, confirm the suite passes.
+2. Open a pull request with a clear description and any relevant issue numbers.

docs/index.rst

@@ -5,19 +5,21 @@ TorchRef Documentation
 
 **A PyTorch-based crystallographic refinement library**
 
-TorchRef is a modern 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.
+TorchRef is a crystallographic refinement package built entirely on PyTorch.
+Autograd and GPU acceleration make it composable with machine-learning
+workflows and cheap to extend with new targets, restraints, and optimizers.
+
+It is mainly a library to build and experiment with, not a replacement for
+mainline refinement programs on standard problems.
 
 Key Features
 ------------
 
-- **Native PyTorch Integration**: Built on PyTorch's ``nn.Module`` architecture
-- **Automatic Differentiation**: No manual gradient implementations required
-- **Modular Architecture**: Easily composable and extensible components
-- **GPU Acceleration**: CUDA support for fast structure factor calculations
-- **State Management**: Full ``state_dict`` support for checkpointing
+- **Native PyTorch Integration**: built on ``nn.Module``
+- **Automatic Differentiation**: define a forward pass, get gradients
+- **Modular Architecture**: composable targets, restraints, optimizers
+- **GPU Acceleration**: CUDA and Apple Silicon (MPS)
+- **State Management**: full ``state_dict`` support for checkpointing
 
 .. toctree::
    :maxdepth: 2

docs/installation.rst

@@ -4,19 +4,15 @@ Installation
 Requirements
 ------------
 
-- Python ≥ 3.10
-- PyTorch ≥ 2.4
-- NumPy ≥ 2.0
-- Gemmi ≥ 0.5
-- reciprocalspaceship ≥ 0.9.18
-- SciPy ≥ 1.10
-- Pandas ≥ 2.0
-- Numba ≥ 0.59
-- Matplotlib ≥ 3.7
+Python ≥ 3.10, PyTorch ≥ 2.4, NumPy ≥ 2.0, Pandas ≥ 2.0, SciPy ≥ 1.10,
+Gemmi ≥ 0.5, reciprocalspaceship ≥ 0.9.18, Numba ≥ 0.59, Matplotlib ≥ 3.7.
 
+``pyproject.toml`` carries the authoritative pinned ranges. Upper bounds are set
+one minor version above the tested maximum, so an untested dependency version
+fails at install time rather than surfacing as a runtime error.
 
 Installing via pip
-----------------------
+------------------
 
 .. code-block:: bash
 
@@ -25,27 +21,24 @@ Installing via pip
 Installing from Source
 ----------------------
 
-Clone the repository and install with pip:
-
 .. code-block:: bash
 
-   git clone https://github.com/your-org/torchref.git
-   cd torchref
+   git clone https://github.com/HatPdotS/TorchRef.git
+   cd TorchRef
    pip install -e .
 
-For development, install with additional dependencies:
+For development, add the extras (pytest, black, isort, flake8):
 
 .. code-block:: bash
 
    pip install -e ".[dev]"
 
-This includes testing tools (pytest), code formatting (black, isort), and linting (flake8).
+The optional ``[amber]`` extra pulls in OpenMM for the Amber target; see
+:doc:`user_guide/testing` for what it gates.
 
 Verifying Installation
 ----------------------
 
-After installation, verify that TorchRef is correctly installed:
-
 .. code-block:: python
 
    import torchref
@@ -54,11 +47,17 @@ After installation, verify that TorchRef is correctly installed:
 GPU Support
 -----------
 
-TorchRef supports GPU acceleration if PyTorch is installed with CUDA support. 
-To verify GPU availability:
+Auto-selection is stricter than ``torch.cuda.is_available()``: TorchRef also
+requires ≥ 10 GB VRAM and a compute capability your PyTorch build was compiled
+for, and falls back to CPU with a warning otherwise. A machine that reports CUDA
+as available may therefore still run on CPU by design — set
+``TORCHREF_DEVICE=cuda`` to force it.
+
+Apple Silicon runs through the MPS backend. Unsupported ops fall back to CPU
+via ``PYTORCH_ENABLE_MPS_FALLBACK=1``, which TorchRef sets on import.
 
 .. code-block:: python
 
    import torch
    print(f"CUDA available: {torch.cuda.is_available()}")
-   print(f"CUDA device: {torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'N/A'}")
+   print(f"MPS available: {torch.backends.mps.is_available()}")