Create an XDS.INP file#

This tutorial shows how to use the CreateXDSInp task to generate an XDS.INP input file for XDS 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#

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:

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.