Beamlines API

General utilities

class nexgen.beamlines.beamline_utils.BeamlineAxes(gonio: List[Axis], det_axes: List[Axis], fast_axis: Point3D | Tuple[float, float, float], slow_axis: Point3D | Tuple[float, float, float])

Beamline specific axes for goniometer, detector and detector module.

class nexgen.beamlines.beamline_utils.PumpProbe(pump_status: bool = False, pump_exposure: float | None = None, pump_delay: float | None = None, pump_repeat: int | None = 0)

Define pump probe parameters.

Parameters:

• pump_status (bool) – Pump on/off

• pump_exposure (float, optional) – Pump exposure time, in s.

• pump_delay (float, optional) – Pump delay, in s.

• pump_repeat (int, optional) – Repeat mode.

I19-2

1. Directly from the python intepreter/ a python script …

The function

nexgen.beamlines.I19_2_nxs.nexus_writer(meta_file: Path | str, detector_name: str, exposure_time: float, scan_axis: str = 'phi', start_time: datetime | None = None, stop_time: datetime | None = None, **params)

Gather all parameters from the beamline and call the NeXus writers.

Parameters:

• meta_file (Path | str) – Path to _meta.h5 file.

• detector_name (str) – Detector in use.

• exposure_time (float) – Exposure time, in s.

• scan_axis (str, optional) – Name of the oscillation axis. Defaults to phi.

• start_time (datetime, optional) – Experiment start time. Defaults to None.

• stop_time (datetime, optional) – Experiment end time. Defaults to None.

Keyword Arguments:

• n_imgs (int) – Total number of images to be collected.

• transmission (float) – Attenuator transmission, in %.

• wavelength (float) – Wavelength of incident beam, in A.

• beam_center (List[float, float]) – Beam center position, in pixels.

• gonio_pos (List[axes]) – Name, start and end positions of the goniometer axes.

• det_pos (List[det_axes]) – Name, start and end positions of detector axes.

• outdir (str) – Directory where to save the file. Only specify if different from meta_file directory.

• serial (bool) – Specify whether it’s a serial crystallography dataset.

• det_dist (float) – Distance between sample and detector, in mm.

• use_meta (bool) – For Eiger, if True use metadata from meta.h5 file. Otherwise will require all other information to be passed manually.

can be called from python and depending on the specified detector type will run:

nexgen.beamlines.I19_2_nxs.tristan_writer(master_file: Path, TR: CollectionParams, timestamps: Tuple[str, str] = (None, None), axes_pos: List[axes] | None = None, det_pos: List[det_axes] | None = None)

A function to call the nexus writer for Tristan 10M detector.

Parameters:

• master_file (Path) – Path to nexus file to be written.

• TR (CollectionParams) – Parameters passed from the beamline.

• timestamps (Tuple[str, str], optional) – Collection start and end time. Defaults to (None, None).

• axes_pos (List[axes], optional) – List of (axis_name, start, end) values for the goniometer, passed from command line. Defaults to None.

• det_pos (List[det_axes], optional) – List of (axis_name, start) values for the detector, passed from command line. Defaults to None.

nexgen.beamlines.I19_2_nxs.eiger_writer(master_file: Path, TR: CollectionParams, timestamps: Tuple[str, str] = (None, None), use_meta: bool = False, n_frames: int | None = None, axes_pos: List[axes] | None = None, det_pos: List[det_axes] | None = None, vds_offset: int = 0)

A function to call the NXmx nexus file writer for Eiger 2X 4M detector. If use_meta is set to False, axes_pos and det_pos become required arguments. Otherwise, axes_pos and det_pos can be None but the code requires the information contained inside the meta file to work correctly.

Parameters:

• master_file (Path) – Path to nexus file to be written.

• TR (CollectionParams) – Parameters passed from the beamline.

• timestamps (Tuple[str, str], optional) – Collection start and end time. Defaults to (None, None).

• use_meta (bool, optional) – If True, metadata such as axes positions, wavelength etc. will be updated using the meta.h5 file. Defaults to False.

• num_frames (int, optional) – Number of images for the nexus file. Not necessary if same as the tot_num_images from the CollectionParameters. If different, the VDS will onlu contain the number of frames specified here. Defaults to None.

• axes_pos (List[axes], optional) – List of (axis_name, start, inc) values for the goniometer, passed from command line. Defaults to None.

• det_pos (List[det_axes], optional) – List of (axis_name, start) values for the detector, passed from command line. Defaults to None.

• vds_offset (int, optional) – Start index for the vds writer. Defaults to 0.

Raises:

• ValueError – If use_meta is set to False but axes_pos and det_pos haven’t been passed.

• IOError – If the axes positions can’t be read from the metafile (missing config or broken links).

Some useful type definitions to use with these methods:

class nexgen.beamlines.I19_2_nxs.axes(id=None, start=0.0, inc=0.0, end=0.0)

Goniometer axis name, start and end position, increment.

end

Axis end position. Defaults fo 0.0. Only really needed for Tristan collections.

id

Axis name.

inc

Axis increment value. Defaults fo 0.0. Only needed for the scan axis.

start

Axis start position. Defaults fo 0.0.

class nexgen.beamlines.I19_2_nxs.det_axes(id=None, start=0.0)

Detector axis name and position.

id

Axis name.

start

Axis position. Defaults to 0.0.

Collection parameters schema for I19-2

pydantic model nexgen.beamlines.I19_2_nxs.CollectionParams

Parameters passed as input from the beamline.

Parameters:

• metafile – Path to _meta.h5 file.

• detector_name – Name of the detector in use for current experiment.

• exposure_time – Exposure time, in s.

• beam_center – Beam center (x,y) position, in pixels.

• wavelength – Incident beam wavelength, in A.

• transmission – Attenuator transmission, in %.

• tot_num_images – Total number of frames in a collection.

• scan_axis – Rotation scan axis. Must be passed for Tristan.

Show JSON schema

{
   "title": "CollectionParams",
   "description": "Parameters passed as input from the beamline.\n\nArgs:\n    metafile: Path to _meta.h5 file.\n    detector_name: Name of the detector in use for current experiment.\n    exposure_time: Exposure time, in s.\n    beam_center: Beam center (x,y) position, in pixels.\n    wavelength: Incident beam wavelength, in A.\n    transmission: Attenuator transmission, in %.\n    tot_num_images: Total number of frames in a collection.\n    scan_axis: Rotation scan axis. Must be passed for Tristan.",
   "type": "object",
   "properties": {
      "metafile": {
         "title": "Metafile",
         "anyOf": [
            {
               "type": "string",
               "format": "path"
            },
            {
               "type": "string"
            }
         ]
      },
      "detector_name": {
         "title": "Detector Name",
         "type": "string"
      },
      "exposure_time": {
         "title": "Exposure Time",
         "type": "number"
      },
      "beam_center": {
         "title": "Beam Center",
         "type": "array",
         "items": {
            "type": "number"
         }
      },
      "wavelength": {
         "title": "Wavelength",
         "type": "number"
      },
      "transmission": {
         "title": "Transmission",
         "type": "number"
      },
      "tot_num_images": {
         "title": "Tot Num Images",
         "type": "integer"
      },
      "scan_axis": {
         "title": "Scan Axis",
         "type": "string"
      }
   },
   "required": [
      "metafile",
      "detector_name",
      "exposure_time",
      "beam_center"
   ]
}

Fields:

• beam_center (Sequence[float])

• detector_name (str)

• exposure_time (float)

• metafile (pathlib.Path | str)

• scan_axis (str | None)

• tot_num_images (int | None)

• transmission (float | None)

• wavelength (float | None)

field beam_center: Sequence[float] [Required]

field detector_name: str [Required]

field exposure_time: float [Required]

field metafile: Path | str [Required]

field scan_axis: str | None = None

field tot_num_images: int | None = None

field transmission: float | None = None

field wavelength: float | None = None

2. Interface with GDA …

class nexgen.beamlines.I19_2_gda_nxs.tr_collect(meta_file, xml_file, detector_name, exposure_time, wavelength, beam_center, start_time, stop_time, geometry_json, detector_json)

Information extracted from GDA containing collection parameters.

beam_center

Beam center (x,y) position, in pixels.

detector_json

Path to GDA-generated JSON file describing the detector.

detector_name

Name of the detector in use for current experiment.

exposure_time

Exposure time, in s.

geometry_json

Path to GDA-generated JSON file describing the beamline geometry.

meta_file

Path to _meta.h5 file.

start_time

Collection start time.

stop_time

Collection end time.

wavelength

Incident beam wavelength, in A.

xml_file

Path to GDA-generated xml file.

nexgen.beamlines.I19_2_gda_nxs.tristan_writer(master_file: Path, TR: namedtuple, axes_params: BeamlineAxes, det_params: EigerDetector | TristanDetector | SinglaDetector | JungfrauDetector | CetaDetector, timestamps: Tuple[str, str] = (None, None))

A function to call the nexus writer for Tristan 10M detector.

Parameters:

• master_file (Path) – Path to nexus file to be written.

• TR (namedtuple) – Parameters passed from the beamline.

• axes_params (BeamlineAxes) – Axes for goniometer, detector and detector module.

• det_params (DetectorType) – Detector definition for Tristan.

• timestamps (Tuple[str, str], optional) – Collection start and end time. Defaults to None.

nexgen.beamlines.I19_2_gda_nxs.eiger_writer(master_file: ~pathlib.Path, TR: ~collections.namedtuple, axes_params: ~nexgen.beamlines.beamline_utils.BeamlineAxes, det_params: ~nexgen.nxs_utils.detector.EigerDetector | ~nexgen.nxs_utils.detector.TristanDetector | ~nexgen.nxs_utils.detector.SinglaDetector | ~nexgen.nxs_utils.detector.JungfrauDetector | ~nexgen.nxs_utils.detector.CetaDetector, timestamps: ~typing.Tuple[str, str] = (None, None), vds_dtype: ~numpy.dtype[~typing.Any] | None | type[~typing.Any] | ~numpy._typing._dtype_like._SupportsDType[~numpy.dtype[~typing.Any]] | str | tuple[~typing.Any, int] | tuple[~typing.Any, ~typing.SupportsIndex | ~collections.abc.Sequence[~typing.SupportsIndex]] | list[~typing.Any] | ~numpy._typing._dtype_like._DTypeDict | tuple[~typing.Any, ~typing.Any] = <class 'numpy.uint16'>)

A function to call the nexus writer for Eiger 2X 4M detector.

Parameters:

• master_file (Path) – Path to nexus file to be written.

• TR (namedtuple) – Parameters passed from the beamline.

• axes_params (BeamlineAxes) – Axes for goniometer, detector and detector module.

• det_params (DetectorType) – Detector definition for Eiger.

• timestamps (Tuple[str, str], optional) – Collection start and end time. Defaults to (None, None).

• vds_dtype (DtypeLike) – Data type for vds as np.uint##.

Serial crystallography: Eiger writers

nexgen.beamlines.SSX_Eiger_nxs.ssx_eiger_writer(visitpath: Path | str, filename: str, beamline: str, num_imgs: int, expt_type: str = 'fixed-target', pump_status: bool = False, **ssx_params)

Gather all collection parameters and write the NeXus file for SSX using Eiger detector.

Parameters:

• visitpath (Path | str) – Collection directory.

• filename (str) – Filename root.

• beamline (str) – Beamline on which the experiment is being run.

• num_imgs (int) – Total number of images collected.

• expt_type (str, optional) – Experiment type, accepted values: extruder, fixed-target, 3Dgridscan. Defaults to “fixed-target”.

• pump_status (bool, optional) – True for pump-probe experiment. Defaults to False.

Keyword Arguments:

• exp_time (float) – Exposure time, in s.

• det_dist (float) – Distance between sample and detector, in mm.

• beam_center (List[float, float]) – Beam center position, in pixels.

• transmission (float) – Attenuator transmission, in %.

• wavelength (float) – Wavelength of incident beam, in A.

• flux (float) – Total flux.

• start_time (datetime) – Experiment start time.

• stop_time (datetime) – Experiment end time.

• chip_info (Dict) – For a grid scan, dictionary containing basic chip information. At least it should contain: x/y_start, x/y number of blocks and block size, x/y number of steps and number of exposures.

• chipmap (Path | str) – Path to the chipmap file corresponding to the experiment, if None for a fixed target experiment, it indicates that the fullchip is being scanned.

• pump_exp (float) – Pump exposure time, in s.

• pump_delay (float) – Pump delay time, in s.

• osc_axis (str) – Oscillation axis. Always omega on I24. If not passed it will default to phi for I19-2.

• outdir (str) – Directory where to save the file. Only specify if different from meta_file directory.

Raises:

• ValueError – If an invalid beamline name is passed.

• ValueError – If an invalid experiment type is passed.

Serial crystallography: Tristan writers

nexgen.beamlines.SSX_Tristan_nxs.ssx_tristan_writer(visitpath: Path | str, filename: str, beamline: str, **ssx_params)

Gather all parameters from the beamline and call the NeXus writers.

Parameters:

• visitpath (Path | str) – Path to colection directory.

• filename (str) – Root of the filename.

• beamline (str) – Beamline on which the experiment is being run.

Keyword Arguments:

• exp_time (float) – Exposure time, in s.

• det_dist (float) – Distance between sample and detector, in mm.

• beam_center (List[float, float]) – Beam center position, in pixels.

• transmission (float) – Attenuator transmission, in %.

• wavelength (float) – Wavelength of incident beam, in A.

• flux (float) – Total flux.

• start_time (datetime) – Experiment start time.

• stop_time (datetime) – Experiment end time.

• chip_info (Dict) – For a grid scan, dictionary containing basic chip information. At least it should contain: x/y_start, x/y number of blocks and block size, x/y number of steps and number of exposures.

• chipmap (Path | str) – Path to the chipmap file corresponding to the experiment, or ‘fullchip’ indicating that the whole chip is being scanned.

Serial crystallography: chip tools

Tools to read a chip and compute the coordinates of a Serial Crystallography collection.

class nexgen.beamlines.SSX_chip.Chip(name: str, num_steps: List[int, int] | Tuple[int, int], step_size: List[float, float] | Tuple[float, float], num_blocks: List[int, int] | Tuple[int, int], block_size: List[float, float] | Tuple[float, float], start_pos: List[float, float, float] = <factory>)

Define a fixed target chip.

Parameters:

• name (str) – Description of the chip.

• num_steps (List[int] | Tuple[int]) – Number of windows in each block.

• step_size (List[float] | Tuple[float]) – Size of each window (distance between the centers in x and y direction).

• num_blocks (List[int] | Tuple[int]) – Total number of blocks in the chip.

• block_size (List[int] | Tuple[int]) – Size of each block.

• start_pos (List[float]) – Start coordinates (x,y,z)

nexgen.beamlines.SSX_chip.compute_goniometer(chip: Chip, blocks: Dict | None = None, full: bool = False, ax1: str = 'sam_y', ax2: str = 'sam_x') → Dict[Dict[str | Tuple, float | int]]

Compute the start coordinates of each block in a chip scan.

The function returns a dictionary associating a list of axes start values and a scan direction to each scanned block. If full is True, the blocks argument will be overridden and coordinates will be calculated for every block in the chip.

Parameters:

• chip (Chip) – General description of the chip schematics: number and size of blocks, size and step of each window, start positions.

• blocks (Dict | None, optional) – Scanned blocks. Defaults to None.

• full (bool, optional) – True if all blocks have been scanned. Defaults to False.

• ax1 (str, optional) – Axis name corrsponding to slow varying axis. Defaults to “sam_y”.

• ax2 (str, optional) – Axis name corrsponding to fast varying axis. Defaults to “sam_x”.

Returns:

Axes start coordinates and scan direction of each block. eg. {

‘01’/(0,0): {

‘ax1’: 0.0, ‘ax2’: 0.0, ‘direction’: 1,

}

}

Return type:

Dict[Dict[str | Tuple, float | int]]

nexgen.beamlines.SSX_chip.fullchip_conversion_table(chip: Chip) → Dict

Associate block coordinates to block number for a full chip.

Parameters:

chip (Chip) – General description of the chip.

Returns:

Conversion table, keys are block numbers, values are coordinates.

Return type:

Dict

nexgen.beamlines.SSX_chip.read_chip_map(mapfile: Path | str, x_blocks: int, y_blocks: int) → Dict

Read the .map file for the current collection on a chip.

Parameters:

• mapfile (Path | str) – Path to .map file. If None, assumes fullchip.

• x_blocks (int) – Total number of blocks in x direction in the chip.

• y_blocks (int) – Total number of blocks in y direction in the chip.

Returns:

A dictionary whose values indicate either the coordinates on the chip of the scanned blocks, or a string indicating that the whole chip is being scanned.

Return type:

Dict

Serial crystallography: experiment types

nexgen.beamlines.SSX_expt.run_extruder(goniometer_axes: List[Axis], num_imgs: int, pump_probe: PumpProbe, osc_axis: str = 'omega') → Tuple[List, Dict, Dict]

Run the goniometer computations for an extruder experiment.

Parameters:

• goniometer_axes (List[Axis]) – List of goniometer axes for current beamline.

• num_imgs (int) – Total number of images.

• pump_probe (PumpProbe) – Pump probe parameters.

• osc_axis – Defines which axis is considered the “moving” one. Defaults to omega.

Returns:

goniometer_axes: updated goniometer_axes list with actual values from the scan. SCAN: dictionary with oscillation scan axis values. pump_info: updated pump probe information.

Return type:

Tuple[List, Dict, Dict]

nexgen.beamlines.SSX_expt.run_fixed_target(goniometer_axes: List[Axis], chip_info: Dict[str, List], chipmap: Path | str, pump_probe: PumpProbe, scan_axes: List[str, str] = ['sam_y', 'sam_x']) → Tuple[Dict, Dict]

Run the goniometer computations for a fixed-target experiment.

Parameters:

• goniometer_axes (List[Axis]) – List of goniometer axes for current beamline.

• chip_info (Dict[str, List]) – General information about the chip: number and size of blocks, size and step of each window, start positions, number of exposures.

• chipmap (Path | str) – Path to .map file. If None is passed, assumes a fullchip.

• pump_probe (PumpProbe) – Pump probe parameters.

• scan_axes (List[str, str], optional) – List of scan axes, in order slow,fast. Defaults to [“sam_y”, “sam_x”].

Raises:

• ValueError – If one or both of the axes names passed as input are not part of the goniometer axes.

• ValueError – if chip_info hasn’t been passed or is an empty dictionary.

Returns:

SCAN: Dictionary with grid scan values. pump_info: Updated pump probe information.

Return type:

Tuple[Dict, Dict]

Electron diffraction: Singla writer

nexgen.beamlines.ED_singla_nxs.singla_nexus_writer(master_file: ~pathlib.Path | str, det_distance: float, exp_time: float, ED_cs: ~typing.Dict = {'convention': 'ED', 'origin': (0, 0, 0), 'x': Axis(name='x', depends='.', transformation_type=<TransformationType.TRANSLATION: 'translation'>, vector=(0, 1, 0), start_pos=0.0, increment=0.0, num_steps=0, offset=(0.0, 0.0, 0.0)), 'y': Axis(name='y', depends='x', transformation_type=<TransformationType.TRANSLATION: 'translation'>, vector=(-1, 0, 0), start_pos=0.0, increment=0.0, num_steps=0, offset=(0.0, 0.0, 0.0)), 'z': Axis(name='z', depends='y', transformation_type=<TransformationType.TRANSLATION: 'translation'>, vector=(0, 0, 1), start_pos=0.0, increment=0.0, num_steps=0, offset=(0.0, 0.0, 0.0))}, datafiles: ~typing.List[~pathlib.Path | str] | None = None, convert2mcstas: bool = False, **params)

Gather all collection parameters and write the NeXus file for an electron diffraction collectio using SINGLA detector.

Parameters:

• master_file (Path | str) – Singla master file.

• det_distance (float) – Sample-detector distance, in mm.

• exp_time (float) – Exposure time, in s.

• ED_cs (Dict, optional) – Definition of the ED coordinate system in use. Defaults to {“convention”: “ED”, “origin”: (0, 0, 0), “x”: Axis(“x”, “.”, “translation”, [0, 1, 0]), “y”: Axis(“y”, “x”, “translation”, [-1, 0, 0]), “z”: Axis(“z”, “y”, “translation”, [0, 0, 1]),}

• datafiles (List[Path | str], optional) – List of data files. Defaults to None.

• convert2mcstas (bool, optional) – Convert vectors to mcstas if required. Defaults to False.

Keyword Arguments:

• n_imgs (int) – Total number of images in collection.

• scan_axis (List[str, float, float]) – Rotation axis name, start and increment.

• outdir (Path | str) – Directory where to save the file. Only specify if different from meta_file directory.

• beam_center (List[float, float]) – Beam center position, in pixels.

• wavelength (float) – Wavelength of incident beam, in A.

• start_time (datetime) – Experiment start time.

• new_source_info (Dict) – Information about Source that might differ from the default. eg. {“facility_id”: “MICROSCOPE”, “name”: “Not Diamond”}

• vds_writer (str) – Write dataset or external file.

GDA integration tools

Read geometry and detector parameters from GDA-generated JSON files

Tools to extract goniometer and detector parameters from GDA JSON files.

class nexgen.beamlines.GDAtools.GDAjson2params.JSONParamsIO(json_file: Path | str)

Read JSON file and exctract parameters.

get_coordinate_frame() → str

Get the coordinate frame from geometry json file.

get_detector_axes_from_file() → List[Axis]

Read the detector axes information from the GDA-supplied json file.

get_detector_params_from_file() → EigerDetector | TristanDetector | SinglaDetector | JungfrauDetector | CetaDetector

Read the detector parameters from the GDA-supplied json file.

get_fast_and_slow_direction_vectors_from_file(det_type: str) → Tuple[Point3D, Point3D]

Read detector fast and slow axes from the GDA-supplied json file.

get_goniometer_axes_from_file() → List[Axis]

Read the axes information from the GDA-supplied json file.

Gather beamline and collection information from GDA-generated xml file

IO tool to gather beamline and collection information from xml file.

class nexgen.beamlines.GDAtools.ExtendedRequest.ExtendedRequestIO(xmlfile: Path | str)

Define an ExtendedRequest object which in GDA gathers all the information regarding beamline and collection into an xml file.

nexgen.beamlines.GDAtools.ExtendedRequest.read_det_position_from_xml(ecr: ExtendedRequestIO, det_description: str) → List[float]

Extract the detector position contained in the xml file.

Parameters:

• ecr (ExtendedRequestIO) – XML tree parser.

• det_description (str) – Detector description

Returns:

Detector axes positions in the order [2theta, det_z]

Return type:

List[float]

nexgen.beamlines.GDAtools.ExtendedRequest.read_scan_from_xml(ecr: ExtendedRequestIO)

Extract information about the scan contained in the xml file.

Parameters:

• ecr (ExtendedRequestIO) – XML tree parser.

• xmlfile (Path | str) – Path to xml file.

Returns:

Name of the rotation scan axis pos (Dict): Dictionary containing the (start,end,increment) values for each goniometer axis. num (int): Number of images written.

Return type:

scan_axis (str)