bcdi.experiment: Description of the experimental setup

This module provides classes and methods for the definition of the experimental setup. The following classes are implemented:

  • Beamline and corresponding child classes: calculations related to reciprocal or direct space transformation.

  • Detector and corresponding child classes: implementation of the 2D detectors.

  • Diffractometer and Geometry with corresponding child classes: implementation of the diffractometer geometry.

  • Loader and corresponding child classes: initialization of the file system and loading of data and motor positions.

  • RotationMatrix: used in methods from Diffractometer to generate rotation matrices

  • Setup: the manager of the analysis

classDiagram class Setup{ +name : beamline name +detector_name } class Beamline{ <<abstract>> +name } class Loader{ <<abstract>> +name +sample_offsets } class Diffractometer{ +name +sample_offsets } class Geometry{ +name } class Detector{ <<abstract>> +name } class RotationMatrix{ +angle +circle } Setup *-- Beamline : create_beamline() Setup *-- Detector : create_detector() Beamline *-- Diffractometer Diffractometer *-- Geometry : create_geometry() Beamline *-- Loader : create_loader() Diffractometer *-- RotationMatrix

In scripts, the initial step is to declare a setup instance with the related parameters (see the class documentation). The beamline and the detector are instantiated in the Setup instance. The Loader and Diffractometer are instantiated in the Beamline instance. However, you are free to instantiate these classes outside of a Setup instance if needed.

The geometry of the following beamlines is implemented:

  • ID01 (ESRF)

  • P10 (PETRA III): 6-circle and USAXS setups

  • CRISTAL (SOLEIL)

  • SIXS (SOLEIL)

  • NANOMAX (MAX IV)

  • 34ID-C (APS)

The following detectors are implemented:

  • Maxipix

  • Timepix

  • Merlin

  • Eiger2M

  • Eiger4M

  • Dummy (user-defined pixel size and pixel number)

beamline

General organization of the module:

classDiagram class Beamline{ <<abstract>> +name : beamline name } ABC <|-- Beamline Beamline <|-- BeamlineID01 Beamline <|-- BeamlineSIXS Beamline <|-- Beamline34ID Beamline <|-- BeamlineP10 BeamlineP10 <|-- BeamlineP10SAXS Beamline <|-- BeamlineCRISTAL Beamline <|-- BeamlineNANOMAX

detector

General organization of the module:

classDiagram class Detector{ <<abstract>> +name : detector_name } ABC <|-- Detector Detector <|-- Maxipix Detector <|-- Eiger2M Detector <|-- Eiger4M Detector <|-- Timepix Detector <|-- Merlin Detector <|-- Dummy

Implementation of the detector classes.

These classes handle the detector-dependent paths and data filenames, on top of the detector-dependent properties (e.g., number and size of the pixels, gaps between tiles…). Generic methods are implemented in the abstract base class Detector, and detector-dependent properties need to be implemented in each child class (they are decoracted by @abstractmethod in the base class, they are written in italic in the following diagram).

classDiagram class Detector{ <<abstract>> +str name +tuple binning +str datadir +int nb_pixel_x +int nb_pixel_y +float pixelsize_x +float pixelsize_y +dict params +tuple preprocessing_binning +tuple roi +str rootdir +str sample_name +str savedir +str scandir +tuple sum_roi +str template_file +str template_imagefile unbinned_pixel_number()* unbinned_pixel_size()* _background_subtraction() _flatfield_correction() _hotpixels_correction() _linearity_correction() _mask_gaps() _saturation_correction() counter() linearity_func() mask_detector() } ABC <|-- Detector

API Reference

class bcdi.experiment.detector.Detector(name, rootdir=None, datadir=None, savedir=None, template_imagefile=None, specfile=None, sample_name=None, roi=None, sum_roi=None, binning=(1, 1, 1), preprocessing_binning=(1, 1, 1), offsets=None, linearity_func=None, **kwargs)

Class to handle the configuration of the detector used for data acquisition.

Parameters

  • name – name of the detector in {‘Maxipix’, ‘Timepix’, ‘Merlin’, ‘MerlinSixS’, ‘Eiger2M’, ‘Eiger4M’, ‘Dummy’}

  • datadir – directory where the data files are located

  • savedir – directory where to save the results

  • template_imagefile –

    beamline-dependent template for the data files

    • ID01: ‘data_mpx4_%05d.edf.gz’ or ‘align_eiger2M_%05d.edf.gz’

    • SIXS_2018: ‘align.spec_ascan_mu_%05d.nxs’

    • SIXS_2019: ‘spare_ascan_mu_%05d.nxs’

    • Cristal: ‘S%d.nxs’

    • P10: ‘_master.h5’

    • NANOMAX: ‘%06d.h5’

    • 34ID: ‘Sample%dC_ES_data_51_256_256.npz’

  • specfile – template for the log file or the data file depending on the beamline

  • roi – region of interest of the detector used for analysis

  • sum_roi – region of interest of the detector used for calculated an integrated intensity

  • binning – binning factor of the 3D dataset (stacking dimension, detector vertical axis, detector horizontal axis)

  • preprocessing_binning – tuple of the three binning factors used in a previous preprocessing step

  • offsets – tuple or list, sample and detector offsets corresponding to the parameter delta in xrayutilities hxrd.Ang2Q.area method

  • linearity_func – function to apply to each pixel of the detector in order to compensate the deviation of the detector linearity for large intensities.

  • kwargs –

    • ‘logger’: an optional logger

property binning

Binning factor of the dataset.

Tuple of three positive integers corresponding to the binning of the data used in phase retrieval (stacking dimension, detector vertical axis, detector horizontal axis). To declare an additional binning factor due to a previous preprocessing step, use the kwarg ‘preprocessing_binning’ instead.

counter(beamline)

Name of the counter in the log file for the image number.

Parameters

beamline – str, name of the beamline

property current_binning

Display the current binning factor of the dataset.

Tuple of three positive integers corresponding to the current binning of the data in the processing pipeline.

property datadir

Name of the data directory.

property linearity_func

Correction of the non-linearity of the detector with high incoming flux.

mask_detector(data, mask, nb_frames=1, flatfield=None, background=None, hotpixels=None)

Mask data measured with a 2D detector.

It can apply flatfield correction, background subtraction, masking of hotpixels and detector gaps.

Parameters

  • data – the 2D data to mask

  • mask – the 2D mask to be updated

  • nb_frames – number of frames summed to yield the 2D data (e.g. in a series measurement), used when defining the threshold for hot pixels

  • flatfield – the 2D flatfield array to be multiplied with the data

  • background – a 2D array to be subtracted to the data

  • hotpixels – a 2D array with hotpixels to be masked (1=hotpixel, 0=normal pixel)

Returns

the masked data and the updated mask

property name

Name of the detector.

property nb_pixel_x

Horizontal number of pixels of the detector.

It takes into account an eventual preprocessing binning (useful when reloading a already preprocessed file).

property nb_pixel_y

Vertical number of pixels of the detector.

It takes into account an eventual preprocessing binning (useful when reloading a already preprocessed file).

property params

Return a dictionnary with all parameters.

property pixelsize_x

Horizontal pixel size of the detector after taking into account binning.

property pixelsize_y

Vertical pixel size of the detector after taking into account binning.

property preprocessing_binning

Preprocessing binning factor of the data.

Tuple of three positive integers corresponding to the binning factor of the data used in a previous preprocessing step (stacking dimension, detector vertical axis, detector horizontal axis).

property roi

Region of interest of the detector to be used.

Convention: [y_start, y_stop, x_start, x_stop]

property rootdir

Name of the root directory, which englobes all scans.

property sample_name

Name of the sample.

property savedir

Name of the saving directory.

property scandir

Path of the scan, typically it is the parent folder of the data folder.

property sum_roi

Region of interest of the detector used for integrating the intensity.

Convention: [y_start, y_stop, x_start, x_stop]

property template_imagefile

Name of the data file.

abstract property unbinned_pixel_number

Define the number of pixels of the unbinned detector.

Convention: (vertical, horizontal)

abstract property unbinned_pixel_size

Pixel size (vertical, horizontal) of the unbinned detector in meters.

class bcdi.experiment.detector.Dummy(name, **kwargs)

Implementation of the Dummy detector.

Parameters

kwargs –

  • ‘custom_pixelnumber’: (V, H) number of pixels of the unbinned dummy detector, as a tuple of two positive integers.

  • ’custom_pixelsize’: float, pixel size of the dummy detector in m.

property unbinned_pixel_number

Define the number of pixels of the unbinned detector.

Convention: (vertical, horizontal)

property unbinned_pixel_size

Pixel size (vertical, horizontal) of the unbinned detector in meters.

class bcdi.experiment.detector.Eiger2M(name, **kwargs)

Implementation of the Eiger2M detector.

property unbinned_pixel_number

Define the number of pixels of the unbinned detector.

Convention: (vertical, horizontal)

property unbinned_pixel_size

Pixel size (vertical, horizontal) of the unbinned detector in meters.

class bcdi.experiment.detector.Eiger4M(name, **kwargs)

Implementation of the Eiger4M detector.

property unbinned_pixel_number

Define the number of pixels of the unbinned detector.

Convention: (vertical, horizontal)

property unbinned_pixel_size

Pixel size (vertical, horizontal) of the unbinned detector in meters.

class bcdi.experiment.detector.Eiger9M(name, **kwargs)

Implementation of the Eiger9M detector.

property unbinned_pixel_number

Define the number of pixels of the unbinned detector.

Convention: (vertical, horizontal)

property unbinned_pixel_size

Pixel size (vertical, horizontal) of the unbinned detector in meters.

class bcdi.experiment.detector.Lambda(name, **kwargs)

Implementation of the Lambda detector.

property unbinned_pixel_number

Define the number of pixels of the unbinned detector.

Convention: (vertical, horizontal)

property unbinned_pixel_size

Pixel size (vertical, horizontal) of the unbinned detector in meters.

class bcdi.experiment.detector.Maxipix(name, **kwargs)

Implementation of the Maxipix detector.

property unbinned_pixel_number

Define the number of pixels of the unbinned detector.

Convention: (vertical, horizontal)

property unbinned_pixel_size

Pixel size (vertical, horizontal) of the unbinned detector in meters.

class bcdi.experiment.detector.Merlin(name, **kwargs)

Implementation of the Merlin detector.

property unbinned_pixel_number

Define the number of pixels of the unbinned detector.

Convention: (vertical, horizontal)

property unbinned_pixel_size

Pixel size (vertical, horizontal) of the unbinned detector in meters.

class bcdi.experiment.detector.MerlinSixS(name, **kwargs)

Implementation of the Merlin detector for SixS.

property unbinned_pixel_number

Define the number of pixels of the unbinned detector.

Convention: (vertical, horizontal)

property unbinned_pixel_size

Pixel size (vertical, horizontal) of the unbinned detector in meters.

class bcdi.experiment.detector.Timepix(name, **kwargs)

Implementation of the Timepix detector.

property unbinned_pixel_number

Define the number of pixels of the unbinned detector.

Convention: (vertical, horizontal)

property unbinned_pixel_size

Pixel size (vertical, horizontal) of the unbinned detector in meters.

bcdi.experiment.detector.create_detector(name, **kwargs)

Create a Detector instance depending on the detector.

Parameters

name – str, name of the detector

Returns

the corresponding detector instance

diffractometer

Diffractometer class.

This class holds the definition of the geometry for the sample and detector circles. The beamline-specific geometry is defined via a named tuple.

classDiagram class Diffractometer{ +detector_circles +name +sample_circles +tuple sample_offsets -_geometry add_circle() get_circles() get_rocking_circle() remove_circle() rotation_matrix() valid_name() }

‘sample_offsets’ is a list or tuple of angles in degrees, corresponding to the offsets of each of the sample circles (the offset for the most outer circle should be at index 0). The number of circles is beamline dependent, as indicated below with default values in degrees:

  • ID01: (mu=0, eta=0, phi=0,)

  • SIXS: (beta=0, mu=0,)

  • 34ID-C: (theta=0, chi=90, phi=0,)

  • P10: (mu=0, om=0, chi=90, phi=0,)

  • P10_SAXS: (phi=0,)

  • CRISTAL: (mgomega=0, mgphi=0,)

  • NANOMAX: (theta=0, phi=0,)

API Reference

class bcdi.experiment.diffractometer.Diffractometer(name: str, sample_offsets=None, **kwargs)

Base class for defining diffractometers.

The frame used is the laboratory frame with the CXI convention (z downstream, y vertical up, x outboard).

Parameters

  • name – name of the beamline

  • sample_offsets – list or tuple of angles in degrees, corresponding to the offsets of each of the sample circles (the offset for the most outer circle should be at index 0). The number of circles is beamline dependent. Convention: the sample offsets will be subtracted to measurement the motor values.

  • kwargs –

    • ‘logger’: an optional logger

add_circle(stage_name: str, index: int, circle: str) → None

Add a circle to the list of circles.

The most outer circle should be at index 0.

Parameters

  • stage_name – supported stage name, ‘sample’ or ‘detector’

  • index – index where to put the circle in the list

  • circle – valid circle in {‘x+’, ‘x-’, ‘y+’, ‘y-’, ‘z+’, ‘z-‘}. + for a counter-clockwise rotation, - for a clockwise rotation.

get_circles(stage_name: str) → List[str]

Return the list of circles for the stage.

Parameters

stage_name – supported stage name, ‘sample’ or ‘detector’

get_rocking_circle(rocking_angle, stage_name, angles)

Find the index of the circle which corresponds to the rocking angle.

Parameters

  • rocking_angle – angle which is tilted during the rocking curve in {‘outofplane’, ‘inplane’}

  • stage_name – supported stage name, ‘sample’ or ‘detector’

  • angles – tuple of angular values in degrees, one for each circle of the sample stage

Returns

the index of the rocking circles in the list of angles

remove_circle(stage_name: str, index: int) → None

Remove the circle at index from the list of sample circles.

Parameters

  • stage_name – supported stage name, ‘sample’ or ‘detector’

  • index – index of the circle to be removed from the list

rotation_matrix(stage_name: str, angles: List[numbers.Real]) → numpy.ndarray

Calculate a 3D rotation matrix given rotation axes and angles.

Parameters

  • stage_name – supported stage name, ‘sample’ or ‘detector’

  • angles – list of angular values in degrees for the stage circles during the measurement

Returns

the rotation matrix as a numpy ndarray of shape (3, 3)

property sample_circles: List[str]

List of sample circles.

The sample circles should be listed from outer to inner (e.g. mu eta chi phi), expressed using a valid pattern within {‘x+’, ‘x-’, ‘y+’, ‘y-’, ‘z+’, ‘z-‘}. For example: [‘y+’ ,’x-’, ‘z-’, ‘y+’]. Convention: CXI convention (z downstream, y vertical up, x outboard), + for a counter-clockwise rotation, - for a clockwise rotation.

property sample_offsets: Union[Tuple[numbers.Real, ...], List[numbers.Real]]

List or tuple of sample angular offsets in degrees.

These angles correspond to the offsets of each f the sample circles (the offset for the most outer circle should be at index 0). Convention: the sample offsets will be subtracted to measurement the motor values.

valid_name(stage_name: str) → None

Check if the stage is defined.

Parameters

stage_name – supported stage name, e.g. ‘sample’

class bcdi.experiment.diffractometer.DiffractometerFactory

Create a diffractometer depending on the beamline name.

static create_diffractometer(name: str, sample_offsets: Optional[Tuple[float, ...]] = None, **kwargs) → Union[bcdi.experiment.diffractometer.FullDiffractometer, bcdi.experiment.diffractometer.DiffractometerSAXS]

Create a diffractometer instance of the corresponding class.

Parameters

  • name – name of the beamline

  • sample_offsets – list or tuple of angles in degrees, corresponding to the offsets of each of the sample circles (the offset for the most outer circle should be at index 0). The number of circles is beamline dependent. Convention: the sample offsets will be subtracted to measurement the motor values.

  • kwargs –

    • ‘logger’: an optional logger

Returns

an instance of the corresponding class

class bcdi.experiment.diffractometer.DiffractometerSAXS(name, **kwargs)

Class for defining diffractometers where the detector is not on a circle.

The detector plane is always perpendicular to the direct beam, independently of its position. The frame used is the laboratory frame with the CXI convention (z downstream, y vertical up, x outboard).

Parameters

  • name – name of the beamline

  • sample_offsets – list or tuple of angles in degrees, corresponding to the offsets of each of the sample circles (the offset for the most outer circle should be at index 0). The number of circles is beamline dependent. Convention: the sample offsets will be subtracted to measurement the motor values.

  • kwargs –

    • ‘logger’: an optional logger

property detector_axes: List[str]

List of detector axes.

The axes are expressed in the order [z, y, x], the sign corresponding to the translation direction using a valid pattern within {‘x+’, ‘x-’, ‘y+’, ‘y-’, ‘z+’, ‘z-‘}. For example: [‘z+’ ,’y-’, ‘x-‘]. Convention: CXI convention (z downstream, y vertical up, x outboard).

class bcdi.experiment.diffractometer.FullDiffractometer(name: str, **kwargs)

Class for defining diffractometers including detector circles.

The frame used is the laboratory frame with the CXI convention (z downstream, y vertical up, x outboard).

Parameters

  • name – name of the beamline

  • sample_offsets – list or tuple of angles in degrees, corresponding to the offsets of each of the sample circles (the offset for the most outer circle should be at index 0). The number of circles is beamline dependent. Convention: the sample offsets will be subtracted to measurement the motor values.

  • kwargs –

    • ‘logger’: an optional logger

property detector_circles: List[str]

List of detector circles.

The circles should be listed from outer to inner (e.g. gamma delta), expressed using a valid pattern within {‘x+’, ‘x-’, ‘y+’, ‘y-’, ‘z+’, ‘z-‘}. For example: [‘y+’ ,’x-’, ‘z-’, ‘y+’]. Convention: CXI convention (z downstream, y vertical up, x outboard), + for a counter-clockwise rotation, - for a clockwise rotation.

class bcdi.experiment.diffractometer.Geometry(sample_circles, detector_circles, default_offsets, user_offsets)

Describe the geometry of the diffractometer with a detector not on a circle.

The detector plane is always perpendicular to the direct beam, independently of its position. The frame used is the laboratory frame with the CXI convention (z downstream, y vertical up, x outboard).

Parameters

  • sample_circles – list of sample circles from outer to inner (e.g. mu eta chi phi), expressed using a valid pattern within {‘x+’, ‘x-’, ‘y+’, ‘y-’, ‘z+’, ‘z-‘}. For example: [‘y+’ ,’x-’, ‘z-’, ‘y+’]

  • detector_axes – list of the translation direction of detector axes for a detector not sitting on a goninometer, expressed in the laboratory frame. For example: [‘z+’, ‘y+’, ‘x-‘]

  • default_offsets – tuple, default sample offsets of the diffractometer, same length as sample_circles.

  • user_offsets – tuple, user-defined sample offsets of the diffractometer, same length as sample_circles.

property default_offsets

Alias for field number 2

property detector_circles

Alias for field number 1

property sample_circles

Alias for field number 0

property user_offsets

Alias for field number 3

class bcdi.experiment.diffractometer.Geometry_SAXS(sample_circles, detector_axes, default_offsets, user_offsets)
property default_offsets

Alias for field number 2

property detector_axes

Alias for field number 1

property sample_circles

Alias for field number 0

property user_offsets

Alias for field number 3

bcdi.experiment.diffractometer.create_geometry(beamline, sample_offsets=None)

Create a Diffractometer instance depending on the beamline.

Parameters

  • beamline – str, name of the

  • sample_offsets – list or tuple of angles in degrees, corresponding to the offsets of each of the sample circles (the offset for the most outer circle should be at index 0). The number of circles is beamline dependent. Convention: the sample offsets will be subtracted to measurement the motor values.

Returns

the corresponding Geometry named tuple

loader

General organization of the module:

classDiagram class Loader{ <<abstract>> +name +sample_offsets } ABC <|-- Loader Loader <|-- LoaderID01 Loader <|-- LoaderID01BLISS Loader <|-- LoaderSIXS Loader <|-- Loader34ID Loader <|-- LoaderP10 LoaderP10 <|-- LoaderP10SAXS Loader <|-- LoaderCRISTAL Loader <|-- LoaderNANOMAX

rotation_matrix

This class is used to define 3D rotation matrices.

API Reference

RotationMatrix class.

class bcdi.experiment.rotation_matrix.RotationMatrix(circle: str, angle: numbers.Real, **kwargs)

Class defining a rotation matrix given the rotation axis and the angle.

This considers a right-handed orthonormal frame (x, y, z).

Parameters

  • circle – circle in {‘x+’, ‘x-’, ‘y+’, ‘y-’, ‘z+’, ‘z-‘}. The letter represents the rotation axis. + for a counter-clockwise rotation, - for a clockwise rotation.

  • angle – angular value in degrees to be used in the calculation of the rotation matrix

  • kwargs –

    • ‘logger’: an optional logger

property angle

Angular value to be used in the calculation of the rotation matrix.

property circle

Circle definition used for the calculation of the rotation matrix.

Allowed values: {‘x+’, ‘x-’, ‘y+’, ‘y-’, ‘z+’, ‘z-‘}. + for a counter-clockwise rotation, - for a clockwise rotation.

get_matrix()

Calculate the rotation matric for a given circle and angle.

Returns

a numpy ndarray of shape (3, 3)

setup

This class is the “manager” or public interface of the analysis workflow. Access to the instances of the child classes inheriting from Beamline, Diffractometer and Detector is realized through Setup.

API Reference