# Create an XDS.INP file

This tutorial shows how to use the `CreateXDSInp` task to generate an
`XDS.INP` input file for [XDS](https://xds.mr.mpg.de/) data processing.

If you want a bundled graph that converts HDF5 frames to CBF and then writes
`XDS.INP`, use `src/ewoksscxrd/workflows/demo_eiger2cbf.json`.

## Overview

`CreateXDSInp` writes an `XDS.INP` file into a directory derived from the
`output` input.  When `output` contains an `{index}` token (e.g.
`/data/scan0001/cbf/frame_{index}.cbf`), the parent directory is used and the
token is converted to the `?` wildcard expected by XDS
(`NAME_TEMPLATE_OF_DATA_FRAMES= frame_?.cbf`).  Otherwise `output` must be a
plain directory path and `name_template_of_data_frames` must be provided
explicitly.

## Minimal example

```python
from ewoksscxrd.tasks.createxdsinp import CreateXDSInp

task = CreateXDSInp(
    inputs={
        "output": "/data/scan0001/cbf/frame_{index:04d}.cbf",
        "detector": "EIGER",
        "nx": 3110,
        "ny": 3269,
        "qx": 0.075,
        "qy": 0.075,
        "beam": [1555, 1635],
        "distance": 151.8,
        "wavelength": 0.2846,
        "data_range": [1, 720],
        "oscillation_range": 0.5,
        "starting_angle": -180.0,
    }
)
task.execute()
print(task.outputs.saved_files_path)
# ['/data/scan0001/cbf/XDS.INP']
```

This produces `/data/scan0001/cbf/XDS.INP` with sensible defaults for all
other parameters.

The generated file uses a fixed layout so the most common XDS sections always
appear in the same order: `JOB`, file template, lattice metadata, beam and
detector geometry, frame ranges, detector dimensions, untrusted rectangles,
silicon parameters, spot-finding parameters, refine directives, then optional
resolution and divergence lines.

## Key inputs

| Input | Required | Description |
|---|---|---|
| `output` | yes | Destination path (directory or path with `{index}` token) |
| `detector` | yes | XDS detector keyword, e.g. `EIGER`, `PILATUS` |
| `nx`, `ny` | yes | Detector size in pixels |
| `qx`, `qy` | yes | Pixel size in mm |
| `data_range` | yes | `[first_frame, last_frame]` of the sweep |
| `oscillation_range` | yes | Angular step per frame (degrees) |
| `starting_angle` | no | Angle at the first frame (degrees); when omitted, `STARTING_ANGLE` is not written |
| `beam` | yes* | Beam centre `[orgx, orgy]` in pixels |
| `distance` | yes* | Sample-to-detector distance (mm) |
| `wavelength` | yes* | X-ray wavelength (Å) |

*Required at runtime — no default is applied.

## Defaults worth knowing

- `starting_frame` defaults to the first frame of `data_range`.
- `starting_angle` is optional; if you provide it, `STARTING_FRAME` is written
  alongside it.
- `spot_range` and `background_range` both default to `data_range`.
- `untrusted_rectangles` defaults to the inter-module gap positions of an
  **Eiger 9M** detector — override this for other detector models.
- Weak-data spot-finding defaults are written explicitly even without
  `xds_extra`:
  `MINIMUM_NUMBER_OF_PIXELS_IN_A_SPOT=4`,
  `MAXIMUM_NUMBER_OF_STRONG_PIXELS=18000`,
  `BACKGROUND_PIXEL=2.0`,
  `SIGNAL_PIXEL=3.0`.
- Default refine directives are also written explicitly:
  `REFINE(IDXREF)`, `REFINE(INTEGRATE)`, and `REFINE(CORRECT)`.

## Legacy input aliases

| Preferred name | Legacy alias |
|---|---|
| `distance` | `detector_distance` |
| `orgx` / `orgy` | (use `beam` instead) |

## Customising the output

Override any optional input to adapt the file to your experiment:

```python
task = CreateXDSInp(
    inputs={
        # ... required inputs ...
        "filename": "MY_XDS.INP",
        "job_comment_lines": [
            "!JOB= XYCORR INIT COLSPOT IDXREF DEFPIX INTEGRATE CORRECT",
            "!JOB= XYCORR INIT COLSPOT IDXREF",
        ],
        "job": "DEFPIX INTEGRATE CORRECT",
        "library": "/path/to/dectris-neggia.so",
        "space_group_number": 96,
        "unit_cell_constants": [127.77, 127.77, 67.26, 90.0, 90.0, 90.0],
        "friedels_law": "TRUE",
        "untrusted_rectangles": [[513, 514, 0, 3262]],
        "refine_idxref": "CELL ORIENTATION AXIS  ! BEAM POSITION",
        "include_resolution_range": [50, 1.5],
        "beam_divergence": 0.17577,
        "beam_divergence_esd": 0.01758,
    }
)
```

Use `xds_extra` only for lines that are not already modelled as explicit task
inputs.