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

Implementation of beamline-specific classes.

API Reference

class bcdi.experiment.beamline.Beamline34ID(name, **kwargs)

Definition of APS 34ID-C beamline.

Parameters:

name – name of the beamline

property detector_hor

Horizontal detector orientation expressed in the laboratory frame.

We look at the detector from downstream, detector X is along the outboard direction. The laboratory frame convention is (z downstream, y vertical, x outboard).

property detector_ver

Vertical detector orientation expressed in the laboratory frame.

The origin is at the top, detector Y along vertical down. The laboratory frame convention is (z downstream, y vertical, x outboard).

goniometer_values(setup, **kwargs)

Retrieve goniometer motor positions for a BCDI rocking scan.

Parameters:

• setup – the experimental setup: Class Setup

• kwargs –

  • ‘scan_number’: the scan number to load

Returns:

a tuple of angular values in degrees (rocking angular step, grazing incidence angles, inplane detector angle, outofplane detector angle). The grazing incidence angles are the positions of circles below the rocking circle.

process_positions(setup, nb_frames, scan_number, frames_logical=None)

Load and crop/pad motor positions depending on the number of frames at 34ID-C.

The current number of frames may be different from the original number of frames if the data was cropped/padded, and motor values must be processed accordingly.

Parameters:

• setup – an instance of the class Setup

• nb_frames – the number of frames in the current dataset

• scan_number – the scan number to load

• frames_logical – array of length the number of measured frames. In case of cropping/padding the number of frames changes. A frame whose index is set to 1 means that it is used, 0 means not used, -1 means padded (added) frame

Returns:

a tuple of 1D arrays (sample circles, detector circles, energy)

transformation_matrix(wavelength, distance, pixel_x, pixel_y, inplane, outofplane, grazing_angle, tilt, rocking_angle, verbose=True)

Calculate the transformation matrix from detector frame to laboratory frame.

For the transformation in direct space, the length scale is in nm, for the transformation in reciprocal space, it is in 1/nm.

Parameters:

• wavelength – X-ray wavelength in nm

• distance – detector distance in nm

• pixel_x – horizontal detector pixel size in nm

• pixel_y – vertical detector pixel size in nm

• inplane – horizontal detector angle in radians

• outofplane – vertical detector angle in radians

• grazing_angle – angle or list of angles of the sample circles which are below the rotated circle

• tilt – angular step of the rocking curve in radians

• rocking_angle – “outofplane”, “inplane” or “energy”

• verbose – True to have printed comments

Returns:

a tuple of two numpy arrays

• the transformation matrix from the detector frame to the laboratory frame in reciprocal space (reciprocal length scale in 1/nm), as a numpy array of shape (3,3)

• the q offset (3D vector)

class bcdi.experiment.beamline.BeamlineBM02(name: str, **kwargs)

Definition of ESRF BM02 beamline.

Parameters:

name – name of the beamline

property detector_hor: str

Horizontal detector orientation expressed in the laboratory frame.

We look at the detector from upstream, detector X is along the inboard direction. The laboratory frame convention is (z downstream, y vertical, x outboard).

property detector_ver: str

Vertical detector orientation expressed in the laboratory frame.

The origin is at the top, detector Y along vertical down. The laboratory frame convention is (z downstream, y vertical, x outboard).

goniometer_values(setup: Setup, **kwargs) → Tuple[Any, ...]

Retrieve goniometer motor positions for a BCDI rocking scan.

Parameters:

• setup – the experimental setup: Class Setup

• kwargs –

  • ‘scan_number’: the scan number to load

Returns:

a tuple of angular values in degrees (rocking angular step, grazing incidence angles, inplane detector angle, outofplane detector angle). The grazing incidence angles are the positions of circles below the rocking circle.

process_positions(setup: Setup, nb_frames: int, scan_number: int, frames_logical: numpy.ndarray | None = None) → List[Any]

Load and crop/pad motor positions depending on the number of frames at BM02.

The current number of frames may be different from the original number of frames if the data was cropped/padded, and motor values must be processed accordingly.

Parameters:

• setup – an instance of the class Setup

• nb_frames – the number of frames in the current dataset

• scan_number – the scan number to load

• frames_logical – array of length the number of measured frames. In case of cropping/padding the number of frames changes. A frame whose index is set to 1 means that it is used, 0 means not used, -1 means padded (added) frame

Returns:

a tuple of 1D arrays (sample circles, detector circles, energy)

transformation_matrix(wavelength, distance, pixel_x, pixel_y, inplane, outofplane, grazing_angle, tilt, rocking_angle, verbose=True)

Calculate the transformation matrix from detector frame to laboratory frame.

For the transformation in direct space, the length scale is in nm, for the transformation in reciprocal space, it is in 1/nm.

Parameters:

• wavelength – X-ray wavelength in nm

• distance – detector distance in nm

• pixel_x – horizontal detector pixel size in nm

• pixel_y – vertical detector pixel size in nm

• inplane – horizontal detector angle in radians

• outofplane – vertical detector angle in radians

• grazing_angle – angle or list of angles of the sample circles which are below the rotated circle

• tilt – angular step of the rocking curve in radians

• rocking_angle – “outofplane”, “inplane” or “energy”

• verbose – True to have printed comments

Returns:

a tuple of two numpy arrays

• the transformation matrix from the detector frame to the laboratory frame in reciprocal space (reciprocal length scale in 1/nm), as a numpy array of shape (3,3)

• the q offset (3D vector)

class bcdi.experiment.beamline.BeamlineCRISTAL(name, **kwargs)

Definition of SOLEIL CRISTAL beamline.

Parameters:

name – name of the beamline

property detector_hor

Horizontal detector orientation expressed in the laboratory frame.

We look at the detector from downstream, detector X is along the outboard direction. The laboratory frame convention is (z downstream, y vertical, x outboard).

property detector_ver

Vertical detector orientation expressed in the laboratory frame.

The origin is at the top, detector Y along vertical down. The laboratory frame convention is (z downstream, y vertical, x outboard).

goniometer_values(setup, **kwargs)

Retrieve goniometer motor positions for a BCDI rocking scan.

Parameters:

setup – the experimental setup: Class Setup

Returns:

a tuple of angular values in degrees (rocking angular step, grazing incidence angles, inplane detector angle, outofplane detector angle). The grazing incidence angles are the positions of circles below the rocking circle.

process_positions(setup, nb_frames, scan_number, frames_logical=None)

Load and crop/pad motor positions depending on the number of frames at CRISTAL.

The current number of frames may be different from the original number of frames if the data was cropped/padded, and motor values must be processed accordingly.

Parameters:

• setup – an instance of the class Setup

• nb_frames – the number of frames in the current dataset

• scan_number – the scan number to load

• frames_logical – array of length the number of measured frames. In case of cropping/padding the number of frames changes. A frame whose index is set to 1 means that it is used, 0 means not used, -1 means padded (added) frame

Returns:

a tuple of 1D arrays (sample circles, detector circles, energy)

transformation_matrix(wavelength, distance, pixel_x, pixel_y, inplane, outofplane, grazing_angle, tilt, rocking_angle, verbose=True)

Calculate the transformation matrix from detector frame to laboratory frame.

For the transformation in direct space, the length scale is in nm, for the transformation in reciprocal space, it is in 1/nm.

Parameters:

• wavelength – X-ray wavelength in nm

• distance – detector distance in nm

• pixel_x – horizontal detector pixel size in nm

• pixel_y – vertical detector pixel size in nm

• inplane – horizontal detector angle in radians

• outofplane – vertical detector angle in radians

• grazing_angle – angle or list of angles of the sample circles which are below the rotated circle

• tilt – angular step of the rocking curve in radians

• rocking_angle – “outofplane” or “inplane”

• verbose – True to have printed comments

Returns:

a tuple of two numpy arrays

• the transformation matrix from the detector frame to the laboratory frame in reciprocal space (reciprocal length scale in 1/nm), as a numpy array of shape (3,3)

• the q offset (3D vector)

class bcdi.experiment.beamline.BeamlineID01(name, **kwargs)

Definition of ESRF ID01 beamline.

Parameters:

name – name of the beamline

property detector_hor

Horizontal detector orientation expressed in the laboratory frame.

We look at the detector from downstream, detector X is along the outboard direction. The laboratory frame convention is (z downstream, y vertical, x outboard).

property detector_ver

Vertical detector orientation expressed in the laboratory frame.

The origin is at the top, detector Y along vertical down. The laboratory frame convention is (z downstream, y vertical, x outboard).

goniometer_values(setup, **kwargs)

Retrieve goniometer motor positions for a BCDI rocking scan.

Parameters:

• setup – the experimental setup: Class Setup

• kwargs –

  • ‘scan_number’: the scan number to load

Returns:

a tuple of angular values in degrees (rocking angular step, grazing incidence angles, inplane detector angle, outofplane detector angle). The grazing incidence angles are the positions of circles below the rocking circle.

process_positions(setup, nb_frames, scan_number, frames_logical=None)

Load and crop/pad motor positions depending on the number of frames at ID01.

The current number of frames may be different from the original number of frames if the data was cropped/padded, and motor values must be processed accordingly.

Parameters:

• setup – an instance of the class Setup

• nb_frames – the number of frames in the current dataset

• scan_number – the scan number to load

• frames_logical – array of length the number of measured frames. In case of cropping/padding the number of frames changes. A frame whose index is set to 1 means that it is used, 0 means not used, -1 means padded (added) frame

Returns:

a tuple of 1D arrays (sample circles, detector circles, energy)

transformation_matrix(wavelength, distance, pixel_x, pixel_y, inplane, outofplane, grazing_angle, tilt, rocking_angle, verbose=True)

Calculate the transformation matrix from detector frame to laboratory frame.

For the transformation in direct space, the length scale is in nm, for the transformation in reciprocal space, it is in 1/nm.

Parameters:

• wavelength – X-ray wavelength in nm

• distance – detector distance in nm

• pixel_x – horizontal detector pixel size in nm

• pixel_y – vertical detector pixel size in nm

• inplane – horizontal detector angle in radians

• outofplane – vertical detector angle in radians

• grazing_angle – angle or list of angles of the sample circles which are below the rotated circle

• tilt – angular step of the rocking curve in radians

• rocking_angle – “outofplane”, “inplane” or “energy”

• verbose – True to have printed comments

Returns:

a tuple of two numpy arrays

• the transformation matrix from the detector frame to the laboratory frame in reciprocal space (reciprocal length scale in 1/nm), as a numpy array of shape (3,3)

• the q offset (3D vector)

class bcdi.experiment.beamline.BeamlineID27(name, **kwargs)

Definition of ID27 beamline for the high-energy BCDI setup.

The detector is not on a goniometer, its plane is always perpendiculat to the direct beam.

Parameters:

name – name of the beamline

property detector_hor

Horizontal detector orientation expressed in the laboratory frame.

We look at the detector from upstream, detector X is opposite to the outboard direction. The laboratory frame convention is (z downstream, y vertical, x outboard).

property detector_ver

Vertical detector orientation expressed in the laboratory frame.

The origin is at the top, detector Y along vertical down. The laboratory frame convention is (z downstream, y vertical, x outboard).

goniometer_values(setup, **kwargs)

Retrieve goniometer motor positions for a scan.

Parameters:

setup – the experimental setup: Class Setup

Returns:

a tuple of angular values in degrees (rocking angular step, grazing incidence angles, inplane detector angle, outofplane detector angle). The grazing incidence angles are the positions of circles below the rocking circle.

process_positions(setup, nb_frames, scan_number, frames_logical=None)

Load and crop/pad motor positions depending on the number of frames at ID27.

The current number of frames may be different from the original number of frames if the data was cropped/padded, and motor values must be processed accordingly.

Parameters:

• setup – an instance of the class Setup

• nb_frames – the number of frames in the current dataset

• scan_number – the scan number to load

• frames_logical – array of length the number of measured frames. In case of cropping/padding the number of frames changes. A frame whose index is set to 1 means that it is used, 0 means not used, -1 means padded (added) frame

Returns:

a tuple of 1D arrays (sample circles, detector circles, energy)

class bcdi.experiment.beamline.BeamlineNANOMAX(name, **kwargs)

Definition of MAX IV NANOMAX beamline.

Parameters:

name – name of the beamline

property detector_hor

Horizontal detector orientation expressed in the laboratory frame.

We look at the detector from downstream, detector X is along the outboard direction. The laboratory frame convention is (z downstream, y vertical, x outboard).

property detector_ver

Vertical detector orientation expressed in the laboratory frame.

The origin is at the top, detector Y along vertical down. The laboratory frame convention is (z downstream, y vertical, x outboard).

goniometer_values(setup, **kwargs)

Retrieve goniometer motor positions for a BCDI rocking scan.

Parameters:

setup – the experimental setup: Class Setup

Returns:

a tuple of angular values in degrees (rocking angular step, grazing incidence angles, inplane detector angle, outofplane detector angle). The grazing incidence angles are the positions of circles below the rocking circle.

process_positions(setup, nb_frames, scan_number, frames_logical=None)

Load and crop/pad motor positions depending on the number of frames at NANOMAX.

The current number of frames may be different from the original number of frames if the data was cropped/padded, and motor values must be processed accordingly.

Parameters:

• setup – an instance of the class Setup

• nb_frames – the number of frames in the current dataset

• scan_number – the scan number to load

• frames_logical – array of length the number of measured frames. In case of cropping/padding the number of frames changes. A frame whose index is set to 1 means that it is used, 0 means not used, -1 means padded (added) frame

Returns:

a tuple of 1D arrays (sample circles, detector circles, energy)

transformation_matrix(wavelength, distance, pixel_x, pixel_y, inplane, outofplane, grazing_angle, tilt, rocking_angle, verbose=True)

Calculate the transformation matrix from detector frame to laboratory frame.

For the transformation in direct space, the length scale is in nm, for the transformation in reciprocal space, it is in 1/nm.

Parameters:

• wavelength – X-ray wavelength in nm

• distance – detector distance in nm

• pixel_x – horizontal detector pixel size in nm

• pixel_y – vertical detector pixel size in nm

• inplane – horizontal detector angle in radians

• outofplane – vertical detector angle in radians

• grazing_angle – angle or list of angles of the sample circles which are below the rotated circle

• tilt – angular step of the rocking curve in radians

• rocking_angle – “outofplane”, “inplane” or “energy”

• verbose – True to have printed comments

Returns:

a tuple of two numpy arrays

• the transformation matrix from the detector frame to the laboratory frame in reciprocal space (reciprocal length scale in 1/nm), as a numpy array of shape (3,3)

• the q offset (3D vector)

class bcdi.experiment.beamline.BeamlineP10(name, **kwargs)

Definition of PETRA III P10 beamline.

Parameters:

name – name of the beamline

property detector_hor

Horizontal detector orientation expressed in the laboratory frame.

We look at the detector from upstream, detector X is opposite to the outboard direction. The laboratory frame convention is (z downstream, y vertical, x outboard).

property detector_ver

Vertical detector orientation expressed in the laboratory frame.

The origin is at the top, detector Y along vertical down. The laboratory frame convention is (z downstream, y vertical, x outboard).

goniometer_values(setup, **kwargs)

Retrieve goniometer motor positions for a BCDI rocking scan.

Parameters:

setup – the experimental setup: Class Setup

Returns:

a tuple of angular values in degrees (rocking angular step, grazing incidence angles, inplane detector angle, outofplane detector angle). The grazing incidence angles are the positions of circles below the rocking circle.

process_positions(setup, nb_frames, scan_number, frames_logical=None)

Load and crop/pad motor positions depending on the number of frames at P10.

The current number of frames may be different from the original number of frames if the data was cropped/padded, and motor values must be processed accordingly.

Parameters:

• setup – an instance of the class Setup

• nb_frames – the number of frames in the current dataset

• scan_number – the scan number to load

• frames_logical – array of length the number of measured frames. In case of cropping/padding the number of frames changes. A frame whose index is set to 1 means that it is used, 0 means not used, -1 means padded (added) frame

Returns:

a tuple of 1D arrays (sample circles, detector circles, energy)

transformation_matrix(wavelength, distance, pixel_x, pixel_y, inplane, outofplane, grazing_angle, tilt, rocking_angle, verbose=True)

Calculate the transformation matrix from detector frame to laboratory frame.

For the transformation in direct space, the length scale is in nm, for the transformation in reciprocal space, it is in 1/nm.

Parameters:

• wavelength – X-ray wavelength in nm

• distance – detector distance in nm

• pixel_x – horizontal detector pixel size in nm

• pixel_y – vertical detector pixel size in nm

• inplane – horizontal detector angle in radians

• outofplane – vertical detector angle in radians

• grazing_angle – angle or list of angles of the sample circles which are below the rotated circle

• tilt – angular step of the rocking curve in radians

• rocking_angle – “outofplane”, “inplane” or “energy”

• verbose – True to have printed comments

Returns:

a tuple of two numpy arrays

• the transformation matrix from the detector frame to the laboratory frame in reciprocal space (reciprocal length scale in 1/nm), as a numpy array of shape (3,3)

• the q offset (3D vector)

class bcdi.experiment.beamline.BeamlineP10SAXS(name, **kwargs)

Definition of PETRA III P10 beamline for the USAXS setup.

Parameters:

name – name of the beamline

property detector_hor

Horizontal detector orientation expressed in the laboratory frame.

We look at the detector from upstream, detector X is opposite to the outboard direction. The laboratory frame convention is (z downstream, y vertical, x outboard).

property detector_ver

Vertical detector orientation expressed in the laboratory frame.

The origin is at the top, detector Y along vertical down. The laboratory frame convention is (z downstream, y vertical, x outboard).

goniometer_values(setup, **kwargs)

Retrieve goniometer motor positions for a CDI tomographic scan.

Parameters:

setup – the experimental setup: Class Setup

Returns:

a tuple of angular values in degrees (rocking angular step, grazing incidence angles, inplane detector angle, outofplane detector angle). The grazing incidence angles are the positions of circles below the rocking circle.

process_positions(setup, nb_frames, scan_number, frames_logical=None)

Load and crop/pad motor positions depending on the number of frames at P10.

The current number of frames may be different from the original number of frames if the data was cropped/padded, and motor values must be processed accordingly.

Parameters:

• setup – an instance of the class Setup

• nb_frames – the number of frames in the current dataset

• scan_number – the scan number to load

• frames_logical – array of length the number of measured frames. In case of cropping/padding the number of frames changes. A frame whose index is set to 1 means that it is used, 0 means not used, -1 means padded (added) frame

Returns:

a tuple of 1D arrays (sample circles, detector circles, energy)

class bcdi.experiment.beamline.BeamlineSIXS(name, **kwargs)

Definition of SOLEIL SIXS beamline.

Parameters:

name – name of the beamline

property detector_hor

Horizontal detector orientation expressed in the laboratory frame.

We look at the detector from downstream, detector X is along the outboard direction. The laboratory frame convention is (z downstream, y vertical, x outboard).

property detector_ver

Vertical detector orientation expressed in the laboratory frame.

The origin is at the top, detector Y along vertical down. The laboratory frame convention is (z downstream, y vertical, x outboard).

goniometer_values(setup, **kwargs)

Retrieve goniometer motor positions for a BCDI rocking scan at SIXS.

Parameters:

setup – the experimental setup: Class Setup

Returns:

a tuple of angular values in degrees (rocking angular step, grazing incidence angles, inplane detector angle, outofplane detector angle). The grazing incidence angles are the positions of circles below the rocking circle.

process_positions(setup, nb_frames, scan_number, frames_logical=None)

Load and crop/pad motor positions depending on the number of frames at SIXS.

The current number of frames may be different from the original number of frames if the data was cropped/padded, and motor values must be processed accordingly.

Parameters:

• setup – an instance of the class Setup

• nb_frames – the number of frames in the current dataset

• scan_number – the scan number to load

• frames_logical – array of length the number of measured frames. In case of cropping/padding the number of frames changes. A frame whose index is set to 1 means that it is used, 0 means not used, -1 means padded (added) frame

Returns:

a tuple of 1D arrays (sample circles, detector circles, energy)

transformation_matrix(wavelength, distance, pixel_x, pixel_y, inplane, outofplane, grazing_angle, tilt, rocking_angle, verbose=True)

Calculate the transformation matrix from detector frame to laboratory frame.

For the transformation in direct space, the length scale is in nm, for the transformation in reciprocal space, it is in 1/nm.

Parameters:

• wavelength – X-ray wavelength in nm

• distance – detector distance in nm

• pixel_x – horizontal detector pixel size in nm

• pixel_y – vertical detector pixel size in nm

• inplane – horizontal detector angle in radians

• outofplane – vertical detector angle in radians

• grazing_angle – angle or list of angles of the sample circles which are below the rotated circle

• tilt – angular step of the rocking curve in radians

• rocking_angle – “outofplane”, “inplane” or “energy”

• verbose – True to have printed comments

Returns:

a tuple of two numpy arrays

• the transformation matrix from the detector frame to the laboratory frame in reciprocal space (reciprocal length scale in 1/nm), as a numpy array of shape (3,3)

• the q offset (3D vector)

bcdi.experiment.beamline.create_beamline(name, sample_offsets=None, **kwargs) → Beamline

Create the instance of the beamline.

Parameters:

• name – str, 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 –

  • optional beamline-dependent parameters

  • ’logger’: an optional logger

Returns:

the corresponding beamline instance

beamline_factory

This module provides beamline abstract classes.

API Reference

Implementation of beamline abstract classes.

The class methods manage the calculations related to reciprocal or direct space transformation (interpolation in an orthonormal grid). Generic method are implemented in the abstract base classes Beamline and BeamlineSaxs; beamline-dependent methods need to be implemented in each child class (they are decorated by @abstractmethod in the base class; they are written in italic in the following diagram). These classes are not meant to be instantiated directly (although it is still possible) but via a Setup instance.

classDiagram class Beamline{ <<abstract>> +diffractometer +loader +name +sample_angles +detector_angles detector_hor()* detector_ver()* goniometer_values()* process_positions()* transformation_matrix()* exit_wavevector() find_inplane() find_outofplane() flatten_sample() init_qconversion() inplane_coeff() outofplane_coeff() process_tilt() } ABC <|-- Beamline

API Reference

class bcdi.experiment.beamline_factory.Beamline(name, sample_offsets=None, **kwargs)

Base class for defining a beamline.

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 –

  • optional beamline-dependent parameters

  • ’logger’: an optional logger

abstract property detector_hor

Horizontal detector orientation expressed in the laboratory frame.

The orientation is defined when the detector plane is perpendicular to the direct beam. This is beamline-dependent. The laboratory frame convention is (z downstream, y vertical, x outboard).

Returns:

“x+” or “x-”

abstract property detector_ver

Vertical detector orientation expressed in the laboratory frame.

The orientation is defined when the detector plane is perpendicular to the direct beam. This is beamline-dependent. The laboratory frame convention is (z downstream, y vertical, x outboard).

Returns:

“y+” or “y-”

flatten_sample(arrays, voxel_size, q_bragg, rocking_angle, central_angle=None, fill_value=0, is_orthogonal=True, reciprocal_space=False, debugging=False, **kwargs)

Send all sample circles to zero degrees.

Arrays are rotated such that all circles of the sample stage are at their zero position.

Parameters:

• arrays – tuple of 3D real arrays of the same shape.

• voxel_size – tuple, voxel size of the 3D array in z, y, and x (CXI convention)

• q_bragg – diffusion vector of the center of mass of the Bragg peak, expressed in an orthonormal frame x y z

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

• central_angle – if provided, angle to be used in the calculation of the rotation matrix for the rocking angle. If None, it will be defined as the angle value at the middle of the rocking curve.

• fill_value – tuple of numeric values used in the RegularGridInterpolator for points outside the interpolation domain. The length of the tuple should be equal to the number of input arrays.

• is_orthogonal – set to True is the frame is orthogonal, False otherwise. Used for plot labels.

• reciprocal_space – True if the data is in reciprocal space, False otherwise. Used for plot labels.

• debugging – tuple of booleans of the same length as the number of input arrays, True to see plots before and after rotation

• kwargs –

  • ‘cmap’: str, name of the colormap

  • ’title’: tuple of strings, titles for the debugging plots, same length as the number of arrays

  • ’scale’: tuple of strings (either ‘linear’ or ‘log’), scale for the debugging plots, same length as the number of arrays

  • width_z: size of the area to plot in z (axis 0), centered on the middle of the initial array

  • width_y: size of the area to plot in y (axis 1), centered on the middle of the initial array

  • width_x: size of the area to plot in x (axis 2), centered on the middle of the initial array

Returns:

a rotated array (if a single array was provided) or a tuple of rotated arrays (same length as the number of input arrays)

abstract goniometer_values(setup, **kwargs)

Retrieve goniometer values.

This method is beamline dependent. It must be implemented in the child classes.

Parameters:

• setup – the experimental setup: Class Setup

• kwargs – beamline_specific parameters

Returns:

a tuple of angular values in degrees (rocking angular step, grazing incidence angles, inplane detector angle, outofplane detector angle). The grazing incidence angles are the positions of circles below the rocking circle.

abstract inplane_coeff()

Coefficient related to the detector inplane orientation.

Define a coefficient +/- 1 depending on the detector inplane rotation direction (1 for clockwise, -1 for anti-clockwise) and the detector inplane orientation (1 for inboard, -1 for outboard).

For a SAXS Beamline it does not matter, the fixed detector inplane angle is 0.

Returns:

+1

abstract outofplane_coeff()

Coefficient related to the detector inplane orientation.

Define a coefficient +/- 1 depending on the detector inplane rotation direction (1 for clockwise, -1 for anti-clockwise) and the detector inplane orientation (1 for inboard, -1 for outboard).

For a SAXS Beamline it does not matter, the fixed detector inplane angle is 0.

Returns:

+1

abstract process_positions(setup: Setup, nb_frames: int, scan_number: int, frames_logical: numpy.ndarray | None = None) → Any

Load and crop/pad motor positions depending on the current number of frames.

The current number of frames may be different from the original number of frames if the data was cropped/padded, and motor values must be processed accordingly.

Parameters:

• setup – an instance of the class Setup

• nb_frames – the number of frames in the current dataset

• scan_number – the scan number to load

• frames_logical – array of length the number of measured frames. In case of cropping/padding the number of frames changes. A frame whose index is set to 1 means that it is used, 0 means not used, -1 means padded (added) frame

Returns:

a tuple of 1D arrays (sample circles, detector circles, energy)

static process_tilt(array, nb_steps, nb_frames, step_size)

Crop or pad array depending on how compare two numbers.

Cropping or padding depends on the number of current frames compared to the number of motor steps. For pading it assumes that array is linear in the angular_step.

Parameters:

• array – a 1D numpy array of motor values

• nb_steps – int, the number of motor positions

• nb_frames – int, the number of frames

• step_size – float, the angular tilt of the rocking curve

Returns:

the cropped/padded array

property sample_angles

Tuple of goniometer angular values for the sample stages.

class bcdi.experiment.beamline_factory.BeamlineGoniometer(name, **kwargs)

Base class for defining a beamline where the detector is on a goniometer.

Parameters:

• name – name of the beamline

• kwargs –

  • optional beamline-dependent parameters

  • ’logger’: an optional logger

property detector_angles

Tuple of goniometer angular values for the detector stages.

exit_wavevector(wavelength: float, inplane_angle: float, outofplane_angle: float) → numpy.ndarray

Calculate the exit wavevector kout.

It uses the setup parameters. kout is expressed in 1/m in the laboratory frame (z downstream, y vertical, x outboard).

Parameters:

• wavelength – float, X-ray wavelength in meters.

• inplane_angle – float, horizontal detector angle, in degrees.

• outofplane_angle – float, vertical detector angle, in degrees.

Returns:

kout vector as a numpy array of shape (3)

find_inplane() → int

Find the index of the detector inplane circle.

It looks for the index of the detector inplane rotation in the detector_circles property of the diffractometer (“y+” or “y-”) . The coordinate convention is the laboratory frame (z downstream, y vertical up, x outboard).

Returns:

int, the index. None if not found.

find_outofplane()

Find the index of the detector out-of-plane circle.

It looks for the index of the detector out-of-plane rotation in the detector_circles property of the diffractometer (typically “x-”) . The coordinate convention is the laboratory frame (z downstream, y vertical up, x outboard). This is useful only for SIXS where there are two out-of-plane detector rotations due to the beta circle. We need the index of the most inner circle, not beta.

Returns:

int, the index. None if not found.

init_qconversion(conversion_table, beam_direction, offset_inplane)

Initialize the qconv object for xrayutilities depending on the setup parameters.

The convention in xrayutilities is x downstream, z vertical up, y outboard. Note: the user-defined motor offsets are applied directly when reading motor positions, therefore do not need to be taken into account in xrayutilities apart from the detector inplane offset determined by the area detector calibration.

Parameters:

• conversion_table – dictionary where keys are axes in the laboratory frame (z downstream, y vertical up, x outboard) and values are the corresponding axes in the frame of xrayutilities (x downstream, y outboard, z vertical up). E.g. {“x+”: “y+”, “x-”: “y-”, “y+”: “z+”, “y-”: “z-”, “z+”: “x+”, “z-”: “x-“}

• beam_direction – direction of the incident X-ray beam in the frame of xrayutilities.

• offset_inplane – inplane offset of the detector defined as the outer angle in xrayutilities area detector calibration.

Returns:

a tuple containing:

• the qconv object for xrayutilities

• a tuple of motor offsets used later for q calculation

inplane_coeff()

Coefficient related to the detector inplane orientation.

Define a coefficient +/- 1 depending on the detector inplane rotation direction (1 for clockwise, -1 for anti-clockwise) and the detector inplane orientation (1 for inboard, -1 for outboard).

See scripts/postprocessing/correct_angles_detector.py for a use case.

Returns:

+1 or -1

outofplane_coeff()

Coefficient related to the detector vertical orientation.

Define a coefficient +/- 1 depending on the detector out of plane rotation direction (1 for clockwise, -1 for anti-clockwise) and the detector out of plane orientation (1 for downward, -1 for upward).

See scripts/postprocessing/correct_angles_detector.py for a use case.

Returns:

+1 or -1

abstract transformation_matrix(wavelength, distance, pixel_x, pixel_y, inplane, outofplane, grazing_angle, tilt, rocking_angle, verbose=True)

Calculate the transformation matrix from detector frame to laboratory frame.

For the transformation in direct space, the length scale is in nm, for the transformation in reciprocal space, it is in 1/nm.

Parameters:

• wavelength – X-ray wavelength in nm

• distance – detector distance in nm

• pixel_x – horizontal detector pixel size in nm

• pixel_y – vertical detector pixel size in nm

• inplane – horizontal detector angle in radians

• outofplane – vertical detector angle in radians

• grazing_angle – angle or list of angles of the sample circles which are below the rotated circle

• tilt – angular step of the rocking curve in radians

• rocking_angle – “outofplane”, “inplane” or “energy”

• verbose – True to have printed comments

Returns:

a tuple of two numpy arrays

• the transformation matrix from the detector frame to the laboratory frame in reciprocal space (reciprocal length scale in 1/nm), as a numpy array of shape (3,3)

• the q offset (3D vector)

class bcdi.experiment.beamline_factory.BeamlineSaxs(name, sample_offsets=None, **kwargs)

Base class for defining a beamline in the SAXS geometry.

The detector is fixed and its plane is always perpendicular to the direct beam, independently of its position.

static cartesian2polar(nb_pixels, pivot, offset_angle, debugging=False)

Find the corresponding polar coordinates of a cartesian 2D grid.

The grid is assumed perpendicular to the rotation axis.

Parameters:

• nb_pixels – number of pixels of the axis of the squared grid

• pivot – position in pixels of the origin of the polar coordinates system

• offset_angle – reference angle for the angle wrapping

• debugging – True to see more plots

Returns:

the corresponding 1D array of angular coordinates, 1D array of radial coordinates

inplane_coeff()

Coefficient related to the detector inplane orientation.

Define a coefficient +/- 1 depending on the detector inplane rotation direction (1 for clockwise, -1 for anti-clockwise) and the detector inplane orientation (1 for inboard, -1 for outboard).

For a SAXS Beamline it does not matter, the fixed detector inplane angle is 0.

Returns:

+1

outofplane_coeff()

Coefficient related to the detector inplane orientation.

Define a coefficient +/- 1 depending on the detector inplane rotation direction (1 for clockwise, -1 for anti-clockwise) and the detector inplane orientation (1 for inboard, -1 for outboard).

For a SAXS Beamline it does not matter, the fixed detector inplane angle is 0.

Returns:

+1

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[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: Tuple[Real, ...] | List[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: Tuple[float, ...] | None = None, **kwargs) → FullDiffractometer | 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.

default_offsets

Alias for field number 2

detector_circles

Alias for field number 1

sample_circles

Alias for field number 0

user_offsets

Alias for field number 3

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

default_offsets

Alias for field number 2

detector_axes

Alias for field number 1

sample_circles

Alias for field number 0

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

Implementation of beamline-dependent data loading classes.

The class methods manage the initialization of the file system and loading of data and motor positions. Generic method are implemented in the abstract base class Loader, and beamline-dependent methods need to be implemented in each child class (they are decorated by @abstractmethod in the base class; they are written in italic in the following diagram).

classDiagram class Loader{ <<abstract>> +name +sample_offsets create_logfile()* init_paths()* load_data()* motor_positions()* read_device()* read_monitor()* init_data_mask() init_monitor() load_check_dataset() } ABC <|-- Loader

API Reference

class bcdi.experiment.loader.Loader(name: str, sample_offsets: tuple[float, ...], **kwargs)

Base class for data loading.

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

abstract create_logfile(datadir: str, name: str, root_folder: str, scan_number: int, filename: str | None = None, template_imagefile: str | None = None)

Create the logfile, which can be a log/spec file or the data itself.

The nature of this file is beamline dependent.

Parameters:

• datadir – str, the data directory

• name – str, the name of the beamline, e.g. ‘SIXS_2019’

• root_folder – str, the root directory of the experiment

• scan_number – the scan number to load

• filename – str, absolute path to the spec/fio/alias file when it exists

• template_imagefile – str, template for the data file name

Returns:

an instance of a context manager ContextFile

init_data_mask(detector, setup, normalize, nb_frames, bin_during_loading, **kwargs)

Initialize data, mask and region of interest for loading a dataset.

Parameters:

• detector – an instance of the class Detector

• setup – an instance of the class Setup

• normalize – ‘monitor’ to return the default monitor values, ‘sum_roi’ to return a monitor based on the integrated intensity in the region of interest defined by detector.sum_roi, ‘skip’ to do nothing

• nb_frames – number of data points (not including series at each point)

• bin_during_loading – if True, the data will be binned in the detector frame while loading. It saves a lot of memory space for large 2D detectors.

• kwargs –

  • ‘scan_number’: int, the scan number to load

Returns:

• the empty 3D data array

• the 2D mask array initialized with 0 values

• the initialized monitor as a 1D array

• the region of interest use for loading the data, as a list of 4 integers

init_monitor(normalize, nb_frames, setup, **kwargs)

Initialize the monitor for normalization.

Parameters:

• normalize – ‘monitor’ to return the default monitor values, ‘sum_roi’ to return a monitor based on the integrated intensity in the region of interest defined by detector.sum_roi, ‘skip’ to do nothing

• nb_frames – number of data points (not including series at each point)

• setup – an instance of the class Setup

• kwargs –

  • ‘scan_number’: int, the scan number to load

Returns:

the initialized monitor as a 1D array

abstract static init_paths(root_folder, sample_name, scan_number, template_imagefile, **kwargs)

Initialize paths used for data processing and logging.

Parameters:

• root_folder – folder of the experiment, where all scans are stored

• sample_name – string in front of the scan number in the data folder name.

• scan_number – int, the scan number

• 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’

• kwargs –

  dictionnary of the setup parameters including the following keys:

  • ’specfile_name’: beamline-dependent string:

    • ID01: name of the spec file without ‘.spec’

    • SIXS_2018 and SIXS_2019: None or full path of the alias dictionnary (e.g. root_folder+’alias_dict_2019.txt’)

    • empty string for all other beamlines

Returns:

a tuple of strings:

• homedir: the path of the scan folder

• default_dirname: the name of the folder containing images / raw data

• specfile: the name of the specfile if it exists

• template_imagefile: the template for data/image file names

load_check_dataset(scan_number, setup, frames_pattern=None, flatfield=None, hotpixels=None, background=None, normalize='skip', bin_during_loading=False, debugging=False)

Load data, apply filters and concatenate it for phasing.

Parameters:

• scan_number – the scan number to load

• setup – an instance of the class Setup

• frames_pattern – user-provided list which can be: - a binary list of length nb_images - a list of the indices of frames to be skipped

• flatfield – the 2D flatfield array

• hotpixels – the 2D hotpixels array. 1 for a hotpixel, 0 for normal pixels.

• background – the 2D background array to subtract to the data

• normalize – ‘monitor’ to return the default monitor values, ‘sum_roi’ to return a monitor based on the integrated intensity in the region of interest defined by detector.sum_roi, ‘skip’ to do nothing

• bin_during_loading – if True, the data will be binned in the detector frame while loading. It saves a lot of memory for large detectors.

• debugging – set to True to see plots

Returns:

• the 3D data array in the detector frame

• the 3D mask array

• the monitor values for normalization

• frames_logical: 1D array of length equal to the number of measured frames. In case of cropping the length of the stack of frames changes. A frame whose index is set to 1 means that it is used, 0 means not used.

abstract load_data(setup, flatfield=None, hotpixels=None, background=None, normalize='skip', bin_during_loading=False, debugging=False, **kwargs)

Load data including detector/background corrections.

Parameters:

• setup – an instance of the class Setup

• flatfield – the 2D flatfield array

• hotpixels – the 2D hotpixels array

• background – the 2D background array to subtract to the data

• normalize – ‘monitor’ to return the default monitor values, ‘sum_roi’ to return a monitor based on the integrated intensity in the region of interest defined by detector.sum_roi, ‘skip’ to do nothing

• bin_during_loading – if True, the data will be binned in the detector frame while loading. It saves a lot of memory space for large 2D detectors.

• debugging – set to True to see plots

• kwargs –

  beamline_specific parameters, which may include part of the totality of the following keys:

  • ’scan_number’: the scan number to load (e.g. for ID01)

Returns:

in this order

• the 3D data array in the detector frame

• the 2D mask array

• the monitor values for normalization as a 1D array of length data.shape[0]

• frames_logical as a 1D array of length the original number of 2D frames, 0 if a frame was removed, 1 if it wasn’t. It can be used later to crop goniometer motor values accordingly.

abstract motor_positions(setup, **kwargs)

Retrieve motor positions.

This method is beamline dependent. It must be implemented in the child classes.

Parameters:

• setup – an instance of the class Setup

• kwargs – beamline_specific parameters, see the documentation for the child class.

Returns:

the diffractometer motors positions for the particular setup. The energy (1D array or number) and the sample to detector distance are expected to be the last elements of the tuple in this order.

abstract read_device(setup, device_name: str, **kwargs)

Extract the scanned device positions/values.

Parameters:

• setup – an instance of the class Setup

• device_name – name of the scanned device

• kwargs –

  beamline_specific parameters, which may include part of the totality of the following keys:

  • ’scan_number’: int, number of the scan (e.g. for ID01)

Returns:

the positions/values of the device as a numpy 1D array

abstract read_monitor(setup: Setup, **kwargs) → np.ndarray

Load the default monitor for intensity normalization of the considered beamline.

Parameters:

• setup – an instance of the class Setup

• kwargs –

  beamline_specific parameter

  • ’scan_number’: int, number of the scan (e.g. for ID01)

Returns:

the default monitor values

class bcdi.experiment.loader.Loader34ID(name: str, sample_offsets: tuple[float, ...], **kwargs)

Loader for APS 34ID-C beamline.

create_logfile(datadir: str, name: str, root_folder: str, scan_number: int, filename: str | None = None, template_imagefile: str | None = None) → ContextFile

Create the logfile, which is the spec file for 34ID-C.

Parameters:

• datadir – str, the data directory

• name – str, the name of the beamline, e.g. ‘34ID’

• root_folder – str, the root directory of the experiment

• scan_number – the scan number to load

• filename – str, absolute path to the spec/fio/alias file when it exists

• template_imagefile – str, template for the data file name

Returns:

an instance of a context manager ContextFile

static init_paths(root_folder, sample_name, scan_number, template_imagefile, **kwargs)

Initialize paths used for data processing and logging at 34ID-C.

Parameters:

• root_folder – folder of the experiment, where all scans are stored

• sample_name – string in front of the scan number in the data folder name.

• scan_number – int, the scan number

• template_imagefile – template for the data files, e.g. ‘Sample%dC_ES_data_51_256_256.npz’.

• kwargs –

  • ‘specfile_name’: name of the spec file without ‘.spec’

Returns:

a tuple of strings:

• homedir: the path of the scan folder

• default_dirname: the name of the folder containing images / raw data

• specfile: the name of the specfile if it exists

• template_imagefile: the template for data/image file names

load_data(setup: Setup, flatfield: np.ndarray | None = None, hotpixels: np.ndarray | None = None, background: np.ndarray | None = None, normalize: str = 'skip', bin_during_loading: bool = False, debugging: bool = False, **kwargs) → tuple[np.ndarray, np.ndarray, np.ndarray, list]

Load 34ID-C data including detector/background corrections.

Parameters:

• setup – an instance of the class Setup

• flatfield – the 2D flatfield array

• hotpixels – the 2D hotpixels array

• background – the 2D background array to subtract to the data

• normalize – ‘monitor’ to return the default monitor values, ‘sum_roi’ to return a monitor based on the integrated intensity in the region of interest defined by detector.sum_roi, ‘skip’ to do nothing

• bin_during_loading – if True, the data will be binned in the detector frame while loading. It saves a lot of memory space for large 2D detectors.

• debugging – set to True to see plots

motor_positions(setup: Setup, **kwargs) → tuple[float | list | np.ndarray, ...]

Load the scan data and extract motor positions.

Parameters:

setup – an instance of the class Setup

Returns:

(theta, phi, delta, gamma, energy) values

read_device(setup: Setup, device_name: str, **kwargs) → np.ndarray

Extract the scanned device positions/values at 34ID-C beamline.

Parameters:

• setup – an instance of the class Setup

• device_name – name of the scanned device

Returns:

the positions/values of the device as a numpy 1D array

read_monitor(setup: Setup, **kwargs: dict[str, Any]) → np.ndarray

Load the default monitor for a dataset measured at 34ID-C.

Parameters:

• setup – an instance of the class Setup

• kwargs –

  • ‘scan_number’: int, the scan number to load

Returns:

the default monitor values

class bcdi.experiment.loader.LoaderBM02(name: str, sample_offsets: tuple[float, ...], **kwargs)

Loader for ESRF BM02 beamline before the deployement of BLISS.

create_logfile(datadir: str, name: str, root_folder: str, scan_number: int, filename: str | None = None, template_imagefile: str | None = None) → ContextFile

Create the logfile, which is the spec file for BM02.

Parameters:

• datadir – str, the data directory

• name – str, the name of the beamline, e.g. ‘BM02’

• root_folder – str, the root directory of the experiment, where is e.g. the specfile file.

• scan_number – the scan number to load

• filename – str, name of the spec file or full path of the spec file

• template_imagefile – str, template for the data file name

Returns:

an instance of a context manager ContextFile

static init_paths(root_folder: str, sample_name: str, scan_number: int, template_imagefile: str, **kwargs) → tuple[str, str, str | None, str]

Initialize paths used for data processing and logging at BM02.

Parameters:

• root_folder – folder of the experiment, where all scans are stored

• sample_name – string in front of the scan number in the data folder name.

• scan_number – int, the scan number

• template_imagefile – template for the data files, e.g. ‘PtYSZ_%04d.edf’.

• kwargs –

  • ‘specfile_name’: name of the spec file without ‘.spec’

Returns:

a tuple of strings:

• homedir: the path of the scan folder

• default_dirname: the name of the folder containing images / raw data

• specfile: the name of the specfile if it exists

• template_imagefile: the template for data/image file names

load_data(setup: Setup, flatfield: np.ndarray | None = None, hotpixels: np.ndarray | None = None, background: np.ndarray | None = None, normalize: str = 'skip', bin_during_loading: bool = False, debugging: bool = False, **kwargs) → tuple[np.ndarray, np.ndarray, np.ndarray, list]

Load BM02 data, apply filters and concatenate it for phasing.

Parameters:

• setup – an instance of the class Setup

• flatfield – the 2D flatfield array

• hotpixels – the 2D hotpixels array

• background – the 2D background array to subtract to the data

• normalize – ‘monitor’ to return the default monitor values, ‘sum_roi’ to return a monitor based on the integrated intensity in the region of interest defined by detector.sum_roi, ‘skip’ to do nothing

• bin_during_loading – if True, the data will be binned in the detector frame while loading. It saves a lot of memory space for large 2D detectors.

• debugging – set to True to see plots

Returns:

• the 3D data array in the detector frame

• the 2D mask array

• the monitor values for normalization

• the detector region of interest used for loading the data

motor_positions(setup: Setup, **kwargs) → tuple[float | list | np.ndarray, ...]

Load the scan data and extract motor positions.

Parameters:

setup – an instance of the class Setup

Returns:

(mu, th, chi, phi, nu, tth, energy) values

read_device(setup: Setup, device_name: str, **kwargs) → np.ndarray

Extract the scanned device positions/values at BM02 beamline.

Parameters:

• setup – an instance of the class Setup

• device_name – name of the scanned device

Returns:

the positions/values of the device as a numpy 1D array

read_monitor(setup: Setup, **kwargs: dict[str, Any]) → np.ndarray

Load the default monitor for a dataset measured at BM02.

Parameters:

setup – an instance of the class Setup

Returns:

the default monitor values

class bcdi.experiment.loader.LoaderCRISTAL(name: str, sample_offsets: tuple[float, ...], **kwargs)

Loader for SOLEIL CRISTAL beamline.

create_logfile(datadir: str, name: str, root_folder: str, scan_number: int, filename: str | None = None, template_imagefile: str | None = None) → ContextFile

Create the logfile, which is the data itself for CRISTAL.

Parameters:

• datadir – str, the data directory

• name – str, the name of the beamline, e.g. ‘CRISTAL’

• root_folder – str, the root directory of the experiment

• scan_number – the scan number to load

• filename – str, absolute path to the spec/fio/alias file when it exists

• template_imagefile – str, template for data file name, e.g. ‘S%d.nxs’

Returns:

an instance of a context manager ContextFile

cristal_load_motor(setup: Setup, root: str, actuator_name: str, field_name: str, **kwargs) → float | list[float] | np.ndarray

Try to load the dataset at the defined entry and returns it.

Patterns keep changing at CRISTAL.

Parameters:

• setup – an instance of the class Setup

• root – string, path of the data up to the last subfolder (not included). This part is expected to not change over time

• actuator_name – string, name of the actuator (e.g. ‘I06-C-C07-EX-DIF-KPHI’). Lowercase and uppercase will be tested when trying to load the data.

• field_name – name of the field under the actuator name (e.g. ‘position’)

Returns:

the dataset if found or 0

find_detector(setup: Setup, root: str, data_path: str = 'scan_data', pattern: str = '^data_[0-9][0-9]$', **kwargs)

Look for the entry corresponding to the detector data in CRISTAL dataset.

Parameters:

• setup – an instance of the class Setup

• root – root folder name in the data file

• data_path – string, name of the subfolder when the scan data is located

• pattern – string, pattern corresponding to the entries where the detector data could be located

Returns:

numpy array of the shape of the detector dataset

static init_paths(root_folder, sample_name, scan_number, template_imagefile, **kwargs)

Initialize paths used for data processing and logging at CRISTAL.

Parameters:

• root_folder – folder of the experiment, where all scans are stored

• sample_name – string in front of the scan number in the data folder name.

• scan_number – int, the scan number

• template_imagefile – template for the data files, e.g. ‘S%d.nxs’

Returns:

a tuple of strings:

• homedir: the path of the scan folder

• default_dirname: the name of the folder containing images / raw data

• specfile: not used at CRISTAL

• template_imagefile: the template for data/image file names

load_data(setup: Setup, flatfield: np.ndarray | None = None, hotpixels: np.ndarray | None = None, background: np.ndarray | None = None, normalize: str = 'skip', bin_during_loading: bool = False, debugging: bool = False, **kwargs) → tuple[np.ndarray, np.ndarray, np.ndarray, list]

Load CRISTAL data including detector/background corrections.

It will look for the correct entry ‘detector’ in the dictionary ‘actuators’, and look for a dataset with compatible shape otherwise.

Parameters:

• setup – an instance of the class Setup

• flatfield – the 2D flatfield array

• hotpixels – the 2D hotpixels array

• background – the 2D background array to subtract to the data

• normalize – ‘monitor’ to return the default monitor values, ‘sum_roi’ to return a monitor based on the integrated intensity in the region of interest defined by detector.sum_roi, ‘skip’ to do nothing

• bin_during_loading – if True, the data will be binned in the detector frame while loading. It saves a lot of memory space for large 2D detectors.

• debugging – set to True to see plots

Returns:

• the 3D data array in the detector frame

• the 2D mask array

• the monitor values for normalization

• the detector region of interest used for loading the data

motor_positions(setup: Setup, **kwargs) → tuple[float | list | np.ndarray, ...]

Load the scan data and extract motor positions.

It will look for the correct entry ‘rocking_angle’ in the dictionary Setup.actuators, and use the default entry otherwise.

Parameters:

setup – an instance of the class Setup

Returns:

(mgomega, mgphi, gamma, delta, energy) values

read_device(setup: Setup, device_name: str, **kwargs) → np.ndarray

Extract the scanned device positions/values at CRISTAL beamline.

Parameters:

• setup – an instance of the class Setup

• device_name – name of the scanned device

Returns:

the positions/values of the device as a numpy 1D array

read_monitor(setup: Setup, **kwargs: dict[str, Any]) → np.ndarray

Load the default monitor for a dataset measured at CRISTAL.

Parameters:

setup – an instance of the class Setup

Returns:

the default monitor values

class bcdi.experiment.loader.LoaderID01(name: str, sample_offsets: tuple[float, ...], **kwargs)

Loader for ESRF ID01 beamline before the deployement of BLISS.

create_logfile(datadir: str, name: str, root_folder: str, scan_number: int, filename: str | None = None, template_imagefile: str | None = None) → ContextFile

Create the logfile, which is the spec file for ID01.

Parameters:

• datadir – str, the data directory

• name – str, the name of the beamline, e.g. ‘SIXS_2019’

• root_folder – str, the root directory of the experiment, where is e.g. the specfile file.

• scan_number – the scan number to load

• filename – str, name of the spec file or full path of the spec file

• template_imagefile – str, template for the data file name

Returns:

an instance of a context manager ContextFile

static init_paths(root_folder: str, sample_name: str, scan_number: int, template_imagefile: str, **kwargs) → tuple[str, str, str | None, str]

Initialize paths used for data processing and logging at ID01.

Parameters:

• root_folder – folder of the experiment, where all scans are stored

• sample_name – string in front of the scan number in the data folder name.

• scan_number – int, the scan number

• template_imagefile – template for the data files, e.g. ‘data_mpx4_%05d.edf.gz’ or ‘align_eiger2M_%05d.edf.gz’

• kwargs –

  • ‘specfile_name’: name of the spec file without ‘.spec’

Returns:

a tuple of strings:

• homedir: the path of the scan folder

• default_dirname: the name of the folder containing images / raw data

• specfile: the name of the specfile if it exists

• template_imagefile: the template for data/image file names

load_data(setup: Setup, flatfield: np.ndarray | None = None, hotpixels: np.ndarray | None = None, background: np.ndarray | None = None, normalize: str = 'skip', bin_during_loading: bool = False, debugging: bool = False, **kwargs) → tuple[np.ndarray, np.ndarray, np.ndarray, list]

Load ID01 data, apply filters and concatenate it for phasing.

Parameters:

• setup – an instance of the class Setup

• flatfield – the 2D flatfield array

• hotpixels – the 2D hotpixels array

• background – the 2D background array to subtract to the data

• normalize – ‘monitor’ to return the default monitor values, ‘sum_roi’ to return a monitor based on the integrated intensity in the region of interest defined by detector.sum_roi, ‘skip’ to do nothing

• bin_during_loading – if True, the data will be binned in the detector frame while loading. It saves a lot of memory space for large 2D detectors.

• debugging – set to True to see plots

Returns:

• the 3D data array in the detector frame

• the 2D mask array

• the monitor values for normalization

• the detector region of interest used for loading the data

motor_positions(setup: Setup, **kwargs) → tuple[float | list | np.ndarray, ...]

Load the scan data and extract motor positions.

Stages names for data previous to ?2017? start with a capital letter.

Parameters:

setup – an instance of the class Setup

Returns:

(mu, eta, phi, nu, delta, energy) values

read_device(setup: Setup, device_name: str, **kwargs) → np.ndarray

Extract the scanned device positions/values at ID01 beamline.

Parameters:

• setup – an instance of the class Setup

• device_name – name of the scanned device

Returns:

the positions/values of the device as a numpy 1D array

read_monitor(setup: Setup, **kwargs: dict[str, Any]) → np.ndarray

Load the default monitor for a dataset measured at ID01.

Parameters:

setup – an instance of the class Setup

Returns:

the default monitor values

retrieve_distance(filename: str, default_folder: str) → float | None

Load the spec file and retrieve the detector distance if it has been calibrated.

Parameters:

• filename – name of the spec file

• default_folder – folder where the spec file is expected

Returns:

the detector distance in meters or None

class bcdi.experiment.loader.LoaderID01BLISS(name: str, sample_offsets: tuple[float, ...], **kwargs)

Loader for ESRF ID01 beamline after the deployement of BLISS.

create_logfile(datadir: str, name: str, root_folder: str, scan_number: int, filename: str | None = None, template_imagefile: str | None = None) → ContextFile

Create the logfile, which is the h5 file for ID01BLISS.

Parameters:

• datadir – str, the data directory

• name – str, the name of the beamline, e.g. ‘ID01BLISS’

• root_folder – str, the root directory of the experiment

• scan_number – the scan number to load

• filename – not used at ID01BLISS

• template_imagefile – str, template for data file name, e.g. ‘ihhc3715_sample5.h5’

Returns:

an instance of a context manager ContextFile

static init_paths(root_folder, sample_name, scan_number, template_imagefile, **kwargs)

Initialize paths used for data processing and logging at ID01 BLISS.

Parameters:

• root_folder – folder of the experiment, where all scans are stored

• sample_name – string in front of the scan number in the data folder name.

• scan_number – int, the scan number

• template_imagefile – template for the data files, e.g. ‘S%d.h5’

Returns:

a tuple of strings:

• homedir: the path of the scan folder

• default_dirname: the name of the folder containing images / raw data

• specfile: not used at ID01BLISS

• template_imagefile: the template for data/image file names

load_data(setup: Setup, flatfield: np.ndarray | None = None, hotpixels: np.ndarray | None = None, background: np.ndarray | None = None, normalize: str = 'skip', bin_during_loading: bool = False, debugging: bool = False, **kwargs) → tuple[np.ndarray, np.ndarray, np.ndarray, list]

Load ID01 BLISS data, apply filters and concatenate it for phasing.

Parameters:

• setup – an instance of the class Setup

• flatfield – the 2D flatfield array

• hotpixels – the 2D hotpixels array

• background – the 2D background array to subtract to the data

• normalize – ‘monitor’ to return the default monitor values, ‘sum_roi’ to return a monitor based on the integrated intensity in the region of interest defined by detector.sum_roi, ‘skip’ to do nothing

• bin_during_loading – if True, the data will be binned in the detector frame while loading. It saves a lot of memory space for large 2D detectors.

• debugging – set to True to see plots

Returns:

• the 3D data array in the detector frame

• the 2D mask array

• the monitor values for normalization

• the detector region of interest used for loading the data

motor_positions(setup: Setup, **kwargs) → tuple[float | list | np.ndarray, ...]

Load the scan data and extract motor positions.

Parameters:

setup – an instance of the class Setup

Returns:

(mu, eta, phi, nu, delta, energy) values

read_device(setup: Setup, device_name: str, **kwargs) → np.ndarray

Extract the scanned device values at ID01 BLISS beamline.

Parameters:

• setup – an instance of the class Setup

• device_name – name of the scanned device

Returns:

the positions/values of the device as a numpy 1D array

read_monitor(setup: Setup, **kwargs: dict[str, Any]) → np.ndarray

Load the default monitor for a dataset measured at ID01 BLISS.

Parameters:

setup – an instance of the class Setup

Returns:

the default monitor values

class bcdi.experiment.loader.LoaderID27(name: str, sample_offsets: tuple[float, ...], **kwargs)

Loader for ESRF ID27 beamline.

create_logfile(datadir: str, name: str, root_folder: str, scan_number: int, filename: str | None = None, template_imagefile: str | None = None) → ContextFile

Create the logfile, which is the h5 file for ID27.

Parameters:

• datadir – str, the data directory

• name – str, the name of the beamline, e.g. ‘ID27’

• root_folder – str, the root directory of the experiment

• scan_number – the scan number to load

• filename – str, absolute path to the spec/fio/alias file when it exists

• template_imagefile – str, template for data file name, e.g. ‘Ptx7_0007.h5’

Returns:

an instance of a context manager ContextFile

static init_paths(root_folder, sample_name, scan_number, template_imagefile, **kwargs)

Initialize paths used for data processing and logging at ID27.

Parameters:

• root_folder – folder of the experiment, where all scans are stored

• sample_name – string in front of the scan number in the data folder name.

• scan_number – int, the scan number

• template_imagefile – template for the data files, e.g. ‘S%d.h5’

Returns:

a tuple of strings:

• homedir: the path of the scan folder

• default_dirname: the name of the folder containing images / raw data

• specfile: not used at ID27

• template_imagefile: the template for data/image file names

load_data(setup: Setup, flatfield: np.ndarray | None = None, hotpixels: np.ndarray | None = None, background: np.ndarray | None = None, normalize: str = 'skip', bin_during_loading: bool = False, debugging: bool = False, **kwargs) → tuple[np.ndarray, np.ndarray, np.ndarray, list]

Load ID27 data, apply filters and concatenate it for phasing.

Parameters:

• setup – an instance of the class Setup

• flatfield – the 2D flatfield array

• hotpixels – the 2D hotpixels array

• background – the 2D background array to subtract to the data

• normalize – ‘monitor’ to return the default monitor values, ‘sum_roi’ to return a monitor based on the integrated intensity in the region of interest defined by detector.sum_roi, ‘skip’ to do nothing

• bin_during_loading – if True, the data will be binned in the detector frame while loading. It saves a lot of memory space for large 2D detectors.

• debugging – set to True to see plots

Returns:

• the 3D data array in the detector frame

• the 2D mask array

• the monitor values for normalization

• the detector region of interest used for loading the data

motor_positions(setup: Setup, **kwargs) → tuple[float | list | np.ndarray, ...]

Load the scan data and extract motor positions.

Parameters:

setup – an instance of the class Setup

Returns:

(nath, energy) values

read_device(setup: Setup, device_name: str, **kwargs) → np.ndarray

Extract the scanned device values at ID27 beamline.

Parameters:

• setup – an instance of the class Setup

• device_name – name of the scanned device

Returns:

the positions/values of the device as a numpy 1D array

read_monitor(setup: Setup, **kwargs: dict[str, Any]) → np.ndarray

Load the default monitor for a dataset measured at ID27.

Parameters:

setup – an instance of the class Setup

Returns:

the default monitor values

class bcdi.experiment.loader.LoaderNANOMAX(name: str, sample_offsets: tuple[float, ...], **kwargs)

Loader for MAX IV NANOMAX beamline.

create_logfile(datadir: str, name: str, root_folder: str, scan_number: int, filename: str | None = None, template_imagefile: str | None = None) → ContextFile

Create the logfile, which is the data itself for Nanomax.

Parameters:

• datadir – str, the data directory

• name – str, the name of the beamline, e.g. ‘Nanomax’

• root_folder – str, the root directory of the experiment

• scan_number – the scan number to load

• filename – str, absolute path to the spec/fio/alias file when it exists

• template_imagefile – str, template for data file name, e.g. ‘%06d.h5’

Returns:

an instance of a context manager ContextFile

static init_paths(root_folder, sample_name, scan_number, template_imagefile, **kwargs)

Initialize paths used for data processing and logging at Nanomax.

Parameters:

• root_folder – folder of the experiment, where all scans are stored

• sample_name – string in front of the scan number in the data folder name.

• scan_number – int, the scan number

• template_imagefile – template for the data files, e.g. ‘%06d.h5’

Returns:

a tuple of strings:

• homedir: the path of the scan folder

• default_dirname: the name of the folder containing images / raw data

• specfile: the name of the specfile if it exists

• template_imagefile: the template for data/image file names

load_data(setup: Setup, flatfield: np.ndarray | None = None, hotpixels: np.ndarray | None = None, background: np.ndarray | None = None, normalize: str = 'skip', bin_during_loading: bool = False, debugging: bool = False, **kwargs) → tuple[np.ndarray, np.ndarray, np.ndarray, list]

Load NANOMAX data, apply filters and concatenate it for phasing.

Parameters:

• setup – an instance of the calss Setup

• flatfield – the 2D flatfield array

• hotpixels – the 2D hotpixels array

• background – the 2D background array to subtract to the data

• normalize – ‘monitor’ to return the default monitor values, ‘sum_roi’ to return a monitor based on the integrated intensity in the region of interest defined by detector.sum_roi, ‘skip’ to do nothing

• bin_during_loading – if True, the data will be binned in the detector frame while loading. It saves a lot of memory space for large 2D detectors.

• debugging – set to True to see plots

Returns:

• the 3D data array in the detector frame

• the 2D mask array

• the monitor values for normalization

• the detector region of interest used for loading the data

motor_positions(setup: Setup, **kwargs) → tuple[float | list | np.ndarray, ...]

Load the scan data and extract motor positions.

Parameters:

setup – an instance of the class Setup

Returns:

(theta, phi, gamma, delta, energy) values

read_device(setup: Setup, device_name: str, **kwargs) → np.ndarray

Extract the scanned device positions/values at Nanomax beamline.

Parameters:

• setup – an instance of the class Setup

• device_name – name of the scanned device

Returns:

the positions/values of the device as a numpy 1D array

read_monitor(setup: Setup, **kwargs: dict[str, Any]) → np.ndarray

Load the default monitor for a dataset measured at NANOMAX.

Parameters:

setup – an instance of the class Setup

Returns:

the default monitor values

class bcdi.experiment.loader.LoaderP10(name: str, sample_offsets: tuple[float, ...], **kwargs)

Loader for PETRAIII P10 beamline.

create_logfile(datadir: str, name: str, root_folder: str, scan_number: int, filename: str | None = None, template_imagefile: str | None = None) → ContextFile

Create the logfile, which is the .fio file for P10.

Parameters:

• datadir – str, the data directory

• name – str, the name of the beamline, e.g. ‘P10’

• root_folder – str, the root directory of the experiment

• scan_number – the scan number to load

• filename – str, name of the .fio file or full path of the .fio file

• template_imagefile – str, template for the data file name

Returns:

an instance of a context manager ContextFile

static init_paths(root_folder, sample_name, scan_number, template_imagefile, **kwargs)

Initialize paths used for data processing and logging at P10.

Parameters:

• root_folder – folder of the experiment, where all scans are stored

• sample_name – string in front of the scan number in the data folder name.

• scan_number – int, the scan number

• template_imagefile – template for the data files, e.g. ‘_master.h5’

• kwargs –

  • ‘specfile_name’: optional, full path of the .fio file

Returns:

a tuple of strings:

• homedir: the path of the scan folder

• default_dirname: the name of the folder containing images / raw data

• specfile: the name of the specfile if it exists

• template_imagefile: the template for data/image file names

load_data(setup: Setup, flatfield: np.ndarray | None = None, hotpixels: np.ndarray | None = None, background: np.ndarray | None = None, normalize: str = 'skip', bin_during_loading: bool = False, debugging: bool = False, **kwargs) → tuple[np.ndarray, np.ndarray, np.ndarray, list]

Load P10 data, apply filters and concatenate it for phasing.

Parameters:

• setup – an instance of the class Setup

• flatfield – the 2D flatfield array

• hotpixels – the 2D hotpixels array

• background – the 2D background array to subtract to the data

• normalize – ‘monitor’ to return the default monitor values, ‘sum_roi’ to return a monitor based on the integrated intensity in the region of interest defined by detector.sum_roi, ‘skip to do nothing’

• bin_during_loading – if True, the data will be binned in the detector frame while loading. It saves a lot of memory space for large 2D detectors.

• debugging – set to True to see plots

Returns:

• the 3D data array in the detector frame

• the 2D mask array

• the monitor values for normalization

• the detector region of interest used for loading the data

motor_positions(setup: Setup, **kwargs) → tuple[float | list | np.ndarray, ...]

Load the .fio file from the scan and extract motor positions.

Parameters:

setup – an instance of the class Setup

Returns:

(om, phi, chi, mu, gamma, delta, energy) values

read_device(setup: Setup, device_name: str, **kwargs) → np.ndarray

Extract the scanned device positions/values at P10 beamline.

Parameters:

• setup – an instance of the class Setup

• device_name – name of the scanned device

Returns:

the positions/values of the device as a numpy 1D array

read_monitor(setup: Setup, **kwargs: dict[str, Any]) → np.ndarray

Load the default monitor for a dataset measured at P10.

Parameters:

setup – an instance of the class Setup

Returns:

the default monitor values

class bcdi.experiment.loader.LoaderP10SAXS(name: str, sample_offsets: tuple[float, ...], **kwargs)

Loader for PETRAIII P10 SAXS beamline.

motor_positions(setup: Setup, **kwargs) → tuple[float | list | np.ndarray | Any, ...]

Load the .fio file from the scan and extract motor positions.

The detector positions are returned in the laboratory frame z, y, x

Parameters:

setup – an instance of the class Setup

Returns:

(phi, det_z, det_y, det_x, energy, detector_distance) values

class bcdi.experiment.loader.LoaderSIXS(name: str, sample_offsets: tuple[float, ...], **kwargs)

Loader for SOLEIL SIXS beamline.

create_logfile(datadir: str, name: str, root_folder: str, scan_number: int, filename: str | None = None, template_imagefile: str | None = None) → ContextFile

Create the logfile, which is the data itself for SIXS.

Parameters:

• datadir – str, the data directory

• name – str, the name of the beamline, e.g. ‘SIXS_2019’

• root_folder – str, the root directory of the experiment

• scan_number – the scan number to load

• filename – str, absolute path of ‘alias_dict.txt’

• template_imagefile –

  str, template for data file name:

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

  • SIXS_2019: ‘spare_ascan_mu_%05d.nxs’

Returns:

an instance of a context manager ContextFile

static init_paths(root_folder, sample_name, scan_number, template_imagefile, **kwargs)

Initialize paths used for data processing and logging at SIXS.

Parameters:

• root_folder – folder of the experiment, where all scans are stored

• sample_name – string in front of the scan number in the data folder name.

• scan_number – int, the scan number

• template_imagefile – template for the data files, e.g. ‘align.spec_ascan_mu_%05d.nxs’ (SIXS_2018), ‘spare_ascan_mu_%05d.nxs’ (SIXS_2019).

• kwargs –

  • ‘specfile_name’: None or full path of the alias dictionnary (e.g. root_folder+’alias_dict_2019.txt’)

Returns:

a tuple of strings:

• homedir: the path of the scan folder

• default_dirname: the name of the folder containing images / raw data

• specfile: the name of the specfile if it exists

• template_imagefile: the template for data/image file names

load_data(setup: Setup, flatfield: np.ndarray | None = None, hotpixels: np.ndarray | None = None, background: np.ndarray | None = None, normalize: str = 'skip', bin_during_loading: bool = False, debugging: bool = False, **kwargs) → tuple[np.ndarray, np.ndarray, np.ndarray, list]

Load data, apply filters and concatenate it for phasing at SIXS.

Parameters:

• setup – an instance of the class Setup

• flatfield – the 2D flatfield array

• hotpixels – the 2D hotpixels array

• background – the 2D background array to subtract to the data

• normalize – ‘monitor’ to return the default monitor values, ‘sum_roi’ to return a monitor based on the integrated intensity in the region of interest defined by detector.sum_roi, ‘skip’ to do nothing

• bin_during_loading – if True, the data will be binned in the detector frame while loading. It saves a lot of memory space for large 2D detectors.

• debugging – set to True to see plots

Returns:

• the 3D data array in the detector frame

• the 2D mask array

• the monitor values for normalization

• the detector region of interest used for loading the data

motor_positions(setup: Setup, **kwargs) → tuple[float | list | np.ndarray, ...]

Load the scan data and extract motor positions at SIXS.

Parameters:

setup – an instance of the class Setup

Returns:

(beta, mu, gamma, delta, energy) values

read_device(setup: Setup, device_name: str, **kwargs) → np.ndarray

Extract the scanned device positions/values at SIXS beamline.

Parameters:

• setup – an instance of the class Setup

• device_name – name of the scanned device

Returns:

the positions/values of the device as a numpy 1D array

read_monitor(setup: Setup, **kwargs: dict[str, Any]) → np.ndarray

Load the default monitor for a dataset measured at SIXS.

Parameters:

setup – an instance of the class Setup

Returns:

the default monitor values

bcdi.experiment.loader.check_empty_frames(data, mask=None, monitor=None, frames_logical=None, **kwargs)

Check if there is intensity for all frames.

In case of beam dump, some frames may be empty. The data and optional mask will be cropped to remove those empty frames.

Parameters:

• data – a numpy 3D array

• mask – a numpy 3D array of 0 (pixel not masked) and 1 (masked pixel), same shape as data

• monitor – a numpy 1D array of shape equal to data.shape[0]

• frames_logical – 1D array of length equal to the number of measured frames. In case of cropping the length of the stack of frames changes. A frame whose index is set to 1 means that it is used, 0 means not used.

• kwargs – an optional logger

Returns:

• cropped data as a numpy 3D array

• cropped mask as a numpy 3D array

• cropped monitor as a numpy 1D array

• updated frames_logical

bcdi.experiment.loader.check_pixels(data, mask, debugging=False, **kwargs)

Check for hot pixels in the data using the mean value and the variance.

Parameters:

• data – 3D diffraction data

• mask – 2D or 3D mask. Mask will summed along the first axis if a 3D array.

• debugging (bool) – set to True to see plots

• kwargs – an optional logger

Returns:

the filtered 3D data and the updated 2D mask.

bcdi.experiment.loader.create_loader(name, sample_offsets, **kwargs)

Create the instance of the loader.

Parameters:

• name – str, 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:

the corresponding beamline instance

bcdi.experiment.loader.load_filtered_data(detector, frames_pattern: list[int] | None) → tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray]

Load a filtered dataset and the corresponding mask.

In that case

Parameters:

• detector – an instance of the class Detector

• frames_pattern – user-provided list which can be: - a binary list of length nb_images - a list of the indices of frames to be skipped

Returns:

the data and the mask array

bcdi.experiment.loader.load_frame(frame, mask2d, monitor, frames_per_point, detector, loading_roi, flatfield=None, background=None, hotpixels=None, normalize='skip', bin_during_loading=False, debugging=False)

Load a frame and apply correction to it.

Parameters:

• frame – the frame to be loaded

• mask2d – a numpy array of the same shape as frame

• monitor – the volue of the intensity monitor for this frame

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

• detector – an instance of the class Detector

• loading_roi – user-defined region of interest, it may be larger than the physical size of the detector

• flatfield – the 2D flatfield array

• hotpixels – the 2D hotpixels array

• background – the 2D background array to subtract to the data

• normalize – ‘monitor’ to return the default monitor values, ‘sum_roi’ to return a monitor based on the integrated intensity in the region of interest defined by detector.sum_roi, ‘skip’ to do nothing

• bin_during_loading – if True, the data will be binned in the detector frame while loading. It saves a lot of memory space for large 2D detectors.

• debugging – set to True to see plots

Returns:

bcdi.experiment.loader.normalize_dataset(array, monitor, savedir=None, norm_to_min=True, debugging=False, **kwargs)

Normalize array using the monitor values.

Parameters:

• array – the 3D array to be normalized

• monitor – the monitor values

• savedir – path where to save the debugging figure

• norm_to_min – bool, True to normalize to min(monitor) instead of max(monitor), avoid multiplying the noise

• debugging – bool, True to see plots

• kwargs – an optional logger

Returns:

• normalized dataset

• updated monitor

• a title for plotting

bcdi.experiment.loader.select_frames(data: numpy.ndarray, frames_logical: numpy.ndarray) → numpy.ndarray

Select frames, update the monitor and create a logical array.

Override this method in the child classes of you want to implement a particular behavior, for example if two frames were taken at a same motor position and you want to delete one or average them…

Parameters:

• data – a 3D data array

• frames_logical – 1D array of length equal to the number of measured frames. In case of cropping the length of the stack of frames changes. A frame whose index is set to 1 means that it is used, 0 means not used.

Returns:

• the updated 3D data, eventually cropped along the first axis

• a 1D array of length the original number of 2D frames, 0 if a frame was removed, 1 if it wasn’t. It can be used later to crop goniometer motor values accordingly.

rotation_matrix

This class is used to define 3D rotation matrices.

API Reference

RotationMatrix class.

class bcdi.experiment.rotation_matrix.RotationMatrix(circle: str, angle: 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

Setup class that defines the experimental geometry.

You can think of it as the public interface for the Beamline and Diffractometer child classes. A script would call a method from Setup, which would then retrieve the required beamline-dependent information from the child classes.

class bcdi.experiment.setup.Setup(parameters: Dict[str, Any], scan_index: int = 0, **kwargs)

Class for defining the experimental geometry.

Parameters:

• parameters – dictionary of parameters

• scan_index – index of the scan to analyze

• kwargs –

  • ‘logger’: an optional logger

property actuators

Define motors names in the data file.

This optional dictionary can be used to define the entries corresponding to actuators in data files (useful at CRISTAL where the location of data keeps changing)

apply_frames_logical() → None

Crop setup attributes where data frames have been excluded.

property beam_direction: numpy.ndarray

Direction of the incident X-ray beam.

Frame convention: (z downstream, y vertical up, x outboard).

property beam_direction_xrutils: numpy.ndarray

Direction of the incident X-ray beam in xrayutilities frame.

xrayutilities frame convention: (x downstream, y outboard, z vertical up).

calc_qvalues_xrutils(hxrd, nb_frames, **kwargs)

Calculate the 3D q values of the BCDI scan using xrayutilities.

Parameters:

• hxrd – an initialized xrayutilities HXRD object used for the orthogonalization of the dataset

• nb_frames – length of axis 0 in the 3D dataset. If the data was cropped or padded, it may be different from the original length len(frames_logical)

• kwargs –

  • ‘scan_number’: the scan number to load

Returns:

• qx, qz, qy components for the dataset. xrayutilities uses the xyz crystal frame: for incident angle = 0, x is downstream, y outboard, and z vertical up. The output of hxrd.Ang2Q.area is qx, qy, qz is this order. If q values seem wrong, check if diffractometer angles have default values set at 0, otherwise use the parameter setup.diffractometer.sample_offsets to correct it

• updated frames_logical

check_setup(grazing_angle: Tuple[Real, ...] | None, inplane_angle: Real, outofplane_angle: Real | numpy.ndarray, tilt_angle: numpy.ndarray, detector_distance: Real, energy: Real | numpy.ndarray) → None

Check if the required parameters are correctly defined.

This method is called in Diffractometer.goniometer_value, which is used only for the geometric transformation using the linearized transformation matrix. Hence, arrays for detector angles and the energy are not allowed.

Parameters:

• grazing_angle – tuple of motor positions for the goniometer circles below the rocking angle. Leave None if there is no such circle.

• inplane_angle – detector inplane angle in degrees

• outofplane_angle – detector out-of-plane angle in degrees

• tilt_angle – ndarray of shape (N,), values of the rocking angle

• detector_distance – sample to detector distance in meters

• energy – X-ray energy in eV

check_setup_cdi(grazing_angle: Tuple[Real, ...] | None, detector_position: Tuple[Real, Real, Real], tilt_angle: numpy.ndarray, detector_distance: Real, energy: Real) → None

Check if the required parameters are correctly defined.

This method is called in Diffractometer.goniometer_value, which is used only for the geometric transformation using the linearized transformation matrix. Hence, arrays for detector angles and the energy are not allowed.

Parameters:

• grazing_angle – tuple of motor positions for the goniometer circles below the rocking angle. Leave None if there is no such circle.

• detector_position – detector positions [det_z, det_y, det_x]

• tilt_angle – ndarray of shape (N,), values of the rocking angle

• detector_distance – sample to detector distance in meters

• energy – X-ray energy in eV

correct_detector_angles(bragg_peak_position: List[int] | None, verbose: bool = True) → None

Correct the detector angles given the direct beam position.

The detector angles for the direct beam measurement can be non-zero.

Parameters:

• bragg_peak_position – [vertical, horizontal] position of the Bragg peak in the unbinned, full detector

• verbose – True to self.logger.info more comments

correct_direct_beam() → Tuple[Real, ...] | None

Calculate the direct beam position in pixels at zero detector angles.

Returns:

a tuple representing the direct beam position at zero detector angles

create_logfile(scan_number: int, root_folder: str, filename: str) → None

Create the logfile, which can be a log/spec file or the data itself.

The nature of this file is beamline dependent.

Parameters:

• scan_number – the scan number to load

• root_folder – the root directory of the experiment, where is the specfile/.fio file

• filename – the file name to load, or the absolute path of ‘alias_dict.txt’ for SIXS

property custom_images

List of images numbers.

It can be used for scans which don’t follow the beamline’s usual directory format (e.g. manual scan).

property custom_monitor

List of monitor values.

It can be used for scans which don’t follow the beamline’s usual directory format (e.g. manual scan). The number of values should be equal to the number of elements in custom_images.

property custom_motors

List of motor values.

It can be used for scans which don’t follow the beamline’s usual directory format (e.g. manual scan).

property custom_scan

Define is a scan follows the standard directory format or not.

Boolean, True is the scan does not follow the beamline’s usual directory format.

property detector

Define a valid Detector instance.

detector_frame(obj, voxel_size, width_z=None, width_y=None, width_x=None, debugging=False, **kwargs)

Interpolate the orthogonal object back into the non-orthogonal detector frame.

Parameters:

• obj – real space object, in the orthogonal laboratory frame

• voxel_size – voxel size of the original object, number of list/tuple of three numbers

• width_z – size of the area to plot in z (axis 0), centered on the middle of the initial array

• width_y – size of the area to plot in y (axis 1), centered on the middle of the initial array

• width_x – size of the area to plot in x (axis 2), centered on the middle of the initial array

• debugging – True to show plots before and after interpolation

• kwargs –

  • ‘title’: title for the debugging plots

Returns:

object interpolated on an orthogonal grid

property detector_hor_xrutil

Convert the detector horizontal orientation to xrayutilities frame.

The laboratory frame convention is (z downstream, y vertical, x outboard). The frame convention of xrayutilities is (x downstream, y outboard, z vertical up).

Returns:

“x+” or “x-” depending on the detector horizontal orientation

property detector_ver_xrutil

Convert the detector vertical orientation to xrayutilities frame.

The laboratory frame convention is (z downstream, y vertical, x outboard). The frame convention of xrayutilities is (x downstream, y outboard, z vertical up).

Returns:

“z+” or “z-” depending on the detector vertical orientation

property diffractometer

Public interface to access the diffractometer instance.

property dirbeam_detector_angles

Detector angles in degrees for the measurement of the direct beam.

[outofplane, inplane]

property dirbeam_detector_position

Detector position for the measurement of the direct beam.

[z, y, x] in the laboratory frame

property direct_beam

Direct beam position in pixels.

Tuple of two real numbers indicating the position of the direct beam in pixels.

property distance

Sample to detector distance, in m.

property energy

Energy setting of the beamline, in eV.

ewald_curvature_saxs(array_shape, cdi_angle)

Calculate q values taking into account the curvature of Ewald sphere.

Based on the CXI detector geometry convention: Laboratory frame: z downstream, y vertical up, x outboard. Detector axes: Y vertical and X horizontal.

Parameters:

• array_shape – tuple of three integers, shape of the dataset to be gridded

• cdi_angle – 1D array of measurement angles in degrees

Returns:

qx, qz, qy values in the laboratory frame (downstream, vertical up, outboard). Each array has the shape: nb_pixel_x * nb_pixel_y * nb_angles

property exit_wavevector: numpy.ndarray

Calculate the exit wavevector kout.

It uses the setup instance parameters. kout is expressed in 1/m in the laboratory frame (z downstream, y vertical, x outboard).

Returns:

kout vector

property filtered_data

Define if data was already preprocessed.

Boolean, True if the data and the mask to be loaded were already preprocessed.

property frames_logical: numpy.ndarray | None

Specify invalid frames using a logical array.

1D array of length equal to the number of measured frames. In case of cropping the length of the stack of frames changes. A frame whose index is set to 1 means that it is used, 0 means not used.

get_detector_offset() → Tuple[float, float]

Calculate the offset in pixels in the detector frame.

The offset is calculated by comparing the detector position for the direct beam measurement and the detector position during the BCDI data collection.

Returns:

(offset_y, offset_x) in unbinned pixels in the detector frame.

get_offseted_beam(detector_offsets: Tuple[float, float] = (0, 0)) → Tuple[int, int]

Calculate the position of the direct beam compared to the origin of the frame.

It takes into account an eventual shift of the detector between the direct beam measurement and the detector position during the BCDI data collection, an eventual user-defined region of interest when loading the data, and binning.

Parameters:

detector_offsets – a tuple of two floats indicating the offset in unbinned pixels due to the detector shift. Orientation convention: Y vertical down, X inboard

Returns:

a tuple of int, position of the offseted direct beam compare to the origin of indices.

get_transfer_matrix_crystal_frame(current_shape: Tuple[int, int, int], q_bragg: numpy.ndarray, reference_axis: numpy.ndarray | Tuple[int, int, int] = (0, 1, 0), initial_shape: Tuple[int, int, int] | None = None, voxel_size: Tuple[float, float, float] | None = None, verbose: bool = True) → Tuple[numpy.ndarray, Tuple[float, float, float]]

Calculate the transformation matrix in direct space, in crystal frame.

Parameters:

• current_shape – shape of the output of phase retrieval. It could be smaller than the shape used in phase retrieval, if the object was cropped around the support.

• q_bragg – tuple of 3 vector components for the q values of the center of mass of the Bragg peak, expressed in an orthonormal frame x y z

• reference_axis – 3D vector along which q will be aligned, expressed in an orthonormal frame x y z

• initial_shape – shape of the FFT used for phasing

• voxel_size – number or list of three user-defined voxel sizes for the interpolation, in nm. If a single number is provided, the voxel size will be identical in all directions.

• verbose – True to have printed comments

Returns:

• the transformation matrix as a numpy array of shape (3, 3)

• a tuple of 3 voxels size for the interpolated arrays

get_transfer_matrix_labframe(current_shape: Tuple[int, int, int], initial_shape: Tuple[int, int, int] | None = None, voxel_size: Tuple[float, float, float] | None = None, verbose: bool = True) → Tuple[numpy.ndarray, Tuple[float, float, float]]

Calculate the transformation matrix in direct space, in the laboratory frame.

Parameters:

• current_shape – shape of the output of phase retrieval. It could be smaller than the shape used in phase retrieval, if the object was cropped around the support.

• initial_shape – shape of the FFT used for phasing

• voxel_size – number or list of three user-defined voxel sizes for the interpolation, in nm. If a single number is provided, the voxel size will be identical in all directions.

• verbose – True to have printed comments

Returns:

• the transformation matrix as a numpy array of shape (3, 3)

• a tuple of 3 voxels size for the interpolated arrays

property grazing_angle

Motor positions for the goniometer circles below the rocking angle.

None if there is no such circle.

grid_cylindrical(array, rotation_angle, direct_beam, interp_angle, interp_radius, fill_value=numpy.nan, comment='', multiprocessing=False)

Interpolate a tomographic dataset onto cartesian coordinates.

The initial 3D array is in cylindrical coordinates. There is no benefit from multiprocessing, the data transfers are the limiting factor.

Parameters:

• array – 3D array of intensities measured in the detector frame

• rotation_angle – array, rotation angle values for the rocking scan

• direct_beam – position in pixels of the rotation pivot in the direction perpendicular to the rotation axis

• interp_angle – 2D array, polar angles for the interpolation in a plane perpendicular to the rotation axis

• interp_radius – 2D array, polar radii for the interpolation in a plane perpendicular to the rotation axis

• fill_value – real number (np.nan allowed), fill_value parameter for the RegularGridInterpolator

• comment – a comment to be printed

• multiprocessing – True to use multiprocessing

Returns:

the 3D array interpolated onto the 3D cartesian grid

property incident_wavevector: numpy.ndarray

Calculate the incident wavevector kout.

It uses the setup instance parameters. kin is expressed in 1/m in the laboratory frame (z downstream, y vertical, x outboard).

Returns:

kin vector

init_paths(sample_name, scan_number, root_folder, save_dir, specfile_name=None, template_imagefile=None, data_dir=None, save_dirname='result')

Init paths used for data processing and logging.

Update the detector instance with initialized paths and template for filenames depending on the beamline.

Parameters:

• sample_name – string in front of the scan number in the data folder name.

• scan_number – the scan number

• root_folder – folder of the experiment, where all scans are stored

• save_dir – path of the directory where to save the analysis results, can be None

• specfile_name –

  beamline-dependent string

  • ID01: name of the spec file without ‘.spec’

  • SIXS_2018 and SIXS_2019: None or full path of the alias dictionnary (e.g. root_folder+’alias_dict_2019.txt’)

  • None for all other beamlines

• 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’

• data_dir – if None it will use the beamline default, otherwise it will look for the data directly into that directory

• save_dirname – name of the saving folder, by default ‘save_dir/result/’ will be created

init_qconversion()

Initialize the qconv object for xrayutilities depending on the setup parameters.

The convention in xrayutilities is x downstream, z vertical up, y outboard. Note: the user-defined motor offsets are applied directly when reading motor positions, therefore do not need to be taken into account in xrayutilities apart from the detector inplane offset determined by the area detector calibration.

Returns:

a tuple containing:

• the qconv object for xrayutilities

• a tuple of motor offsets used later for q calculation

initialize_analysis() → None

Initialize the paths, logfile and load motor positions.

property inplane_angle

Horizontal detector angle, in degrees.

property inplane_coeff

Expose the inplane_coeff beamline property to the outer world.

Return a coefficient +/- 1 depending on the detector inplane rotation direction and the detector inplane orientation.

Returns:

+1 or -1

static interp_2dslice(array, slice_index, rotation_angle, direct_beam, interp_angle, interp_radius, fill_value)

Interpolate a 2D slice from a tomographic dataset onto cartesian coordinates.

The initial 3D array is in cylindrical coordinates.

Parameters:

• array – 3D array of intensities measured in the detector frame

• slice_index – the index along the rotation axis of the 2D slice in array to interpolate

• rotation_angle – array, rotation angle values for the rocking scan

• direct_beam – position in pixels of the rotation pivot in the direction perpendicular to the rotation axis

• interp_angle – 2D array, polar angles for the interpolation in a plane perpendicular to the rotation axis

• interp_radius – 2D array, polar radii for the interpolation in a plane perpendicular to the rotation axis

• fill_value – real number (np.nan allowed), fill_value parameter for the RegularGridInterpolator

Returns:

the interpolated slice, the slice index

interpolate_direct_space(arrays: numpy.ndarray | Tuple[numpy.ndarray, ...], current_shape: Tuple[int, ...], transfer_matrix: numpy.ndarray, voxel_size: Tuple[float, float, float], fill_value: Tuple[float, ...], verbose: bool, debugging: bool | Tuple[bool, ...], **kwargs) → Tuple[numpy.ndarray | List[numpy.ndarray], Tuple[float, float, float], numpy.ndarray]

Interpolate arrays using the transfer matrix.

Parameters:

• arrays – tuple of 3D arrays of the same shape (output of the phase retrieval), in the detector frame

• current_shape – shape of the output of phase retrieval. It could be smaller than the shape used in phase retrieval, if the object was cropped around the support.

• transfer_matrix – the transformation matrix, numpy array of shape (3, 3)

• voxel_size – number or list of three user-defined voxel sizes for the interpolation, in nm. If a single number is provided, the voxel size will be identical in all directions.

• fill_value – tuple of real numbers, fill_value parameter for the RegularGridInterpolator, same length as the number of arrays

• verbose – True to have printed comments

• debugging – tuple of booleans of the same length as the number of input arrays, True to show plots before and after interpolation

• kwargs –

  • ‘cmap’: str, name of the colormap

  • ’title’: tuple of strings, titles for the debugging plots, same length as the number of arrays

  • width_z: size of the area to plot in z (axis 0), centered on the middle of the initial array

  • width_y: size of the area to plot in y (axis 1), centered on the middle of the initial array

  • width_x: size of the area to plot in x (axis 2), centered on the middle of the initial array

Returns:

• an array (if a single array was provided) or a tuple of arrays interpolated on an orthogonal grid (same length as the number of input arrays)

• a tuple of 3 voxels size for the interpolated arrays

• a numpy array of shape (3, 3): transformation matrix from the detector frame to the laboratory/crystal frame

property is_series

Set to true for series measurement at P10 (several frames per point).

property loader

Public interface to access the beamline data loader instance.

property name

Name of the beamline.

ortho_cdi(arrays, cdi_angle, fill_value=0, correct_curvature=False, debugging=False)

Interpolate forward CDI data in the laboratory frame.

Parameters:

• arrays – tuple of 3D arrays of the same shape (e.g.: reciprocal space diffraction pattern and mask), in the detector frame

• cdi_angle – 1D array of measurement angles in degrees

• fill_value – tuple of real numbers (np.nan allowed), fill_value parameter for the RegularGridInterpolator, same length as the number of arrays

• correct_curvature – bool, True to take into account the curvature of the Ewald sphere (uses griddata, very slow)

• debugging – bool, True to see more plots

Returns:

• an array (if a single array was provided) or a tuple of arrays interpolated on an orthogonal grid (same length as the number of input arrays)

• a tuple of three 1D arrays for the q values (qx, qz, qy) where qx is downstream, qz is vertical up and qy is outboard.

• a tuple of two integersfor the corrected position of the direct beam (V, H)

ortho_directspace(arrays: numpy.ndarray | Tuple[numpy.ndarray, ...], q_bragg: numpy.ndarray, initial_shape: Tuple[int, int, int] | None = None, voxel_size: Tuple[float, float, float] | None = None, fill_value: Tuple[float, ...] = (0,), reference_axis: numpy.ndarray | Tuple[int, int, int] = (0, 1, 0), verbose: bool = True, debugging: bool = False, **kwargs) → Tuple[numpy.ndarray | List[numpy.ndarray], Tuple[float, float, float], numpy.ndarray]

Geometrical transformation in direct space, into the crystal frame.

Interpolate arrays (direct space output of the phase retrieval) in the orthogonal reference frame where q_bragg is aligned onto the array axis reference_axis.

Parameters:

• arrays – tuple of 3D arrays of the same shape (output of the phase retrieval), in the detector frame

• q_bragg – array of 3 vector components for the q values of the center of mass of the Bragg peak, expressed in an orthonormal frame x y z

• initial_shape – shape of the FFT used for phasing

• voxel_size – number or list of three user-defined voxel sizes for the interpolation, in nm. If a single number is provided, the voxel size will be identical in all directions.

• fill_value – tuple of real numbers, fill_value parameter for the RegularGridInterpolator, same length as the number of arrays

• reference_axis – 3D vector along which q will be aligned, expressed in an orthonormal frame x y z

• verbose – True to have printed comments

• debugging – tuple of booleans of the same length as the number of input arrays, True to show plots before and after interpolation

• kwargs –

  • ‘cmap’: str, name of the colormap

  • ’title’: tuple of strings, titles for the debugging plots, same length as the number of arrays

  • width_z: size of the area to plot in z (axis 0), centered on the middle of the initial array

  • width_y: size of the area to plot in y (axis 1), centered on the middle of the initial array

  • width_x: size of the area to plot in x (axis 2), centered on the middle of the initial array

Returns:

• an array (if a single array was provided) or a tuple of arrays interpolated on an orthogonal grid (same length as the number of input arrays)

• a tuple of 3 voxels size for the interpolated arrays

• a numpy array of shape (3, 3): transformation matrix from the detector frame to the laboratory/crystal frame

ortho_directspace_labframe(arrays: numpy.ndarray | Tuple[numpy.ndarray, ...], initial_shape: Tuple[int, int, int] | None = None, voxel_size: Tuple[float, float, float] | None = None, fill_value: Tuple[float, ...] = (0,), verbose: bool = True, debugging: bool = False, **kwargs) → Tuple[numpy.ndarray | List[numpy.ndarray], Tuple[float, float, float], numpy.ndarray]

Geometrical transformation in direct space, into the laboratory frame.

Interpolate arrays (direct space output of the phase retrieval) in the orthogonal laboratory frame.

Parameters:

• arrays – tuple of 3D arrays of the same shape (output of the phase retrieval), in the detector frame

• initial_shape – shape of the FFT used for phasing

• voxel_size – number or list of three user-defined voxel sizes for the interpolation, in nm. If a single number is provided, the voxel size will be identical in all directions.

• fill_value – tuple of real numbers, fill_value parameter for the RegularGridInterpolator, same length as the number of arrays

• verbose – True to have printed comments

• debugging – tuple of booleans of the same length as the number of input arrays, True to show plots before and after interpolation

• kwargs –

  • ‘cmap’: str, name of the colormap

  • ’title’: tuple of strings, titles for the debugging plots, same length as the number of arrays

  • width_z: size of the area to plot in z (axis 0), centered on the middle of the initial array

  • width_y: size of the area to plot in y (axis 1), centered on the middle of the initial array

  • width_x: size of the area to plot in x (axis 2), centered on the middle of the initial array

Returns:

• an array (if a single array was provided) or a tuple of arrays interpolated on an orthogonal grid (same length as the number of input arrays)

• a tuple of 3 voxels size for the interpolated arrays

• a numpy array of shape (3, 3): transformation matrix from the detector frame to the laboratory/crystal frame

ortho_reciprocal(arrays, fill_value=0, align_q=False, reference_axis=(0, 1, 0), verbose=True, debugging=False, **kwargs)

Geometrical transformation in reciprocal (Fourier) space.

Interpolate arrays in the orthogonal laboratory frame (z/qx downstream, y/qz vertical up, x/qy outboard) or crystal frame (q aligned along one array axis). The ouput shape will be increased in order to keep the same range in q in each direction. The sampling in q is defined as the norm of the rows of the transformation matrix.

Parameters:

• arrays – tuple of 3D arrays of the same shape (e.g.: reciprocal space diffraction pattern and mask), in the detector frame

• fill_value – tuple of real numbers, fill_value parameter for the RegularGridInterpolator, same length as the number of arrays

• align_q – boolean, if True the data will be rotated such that q is along reference_axis, and q values will be calculated in the pseudo crystal frame.

• reference_axis – 3D vector along which q will be aligned, expressed in an orthonormal frame x y z

• verbose – True to have printed comments

• debugging – tuple of booleans of the same length as the number of input arrays, True to show plots before and after interpolation

• kwargs –

  • ‘title’: tuple of strings, titles for the debugging plots, same length as the number of arrays

  • ’scale’: tuple of strings (either ‘linear’ or ‘log’), scale for the debugging plots, same length as the number of arrays

  • width_z: size of the area to plot in z (axis 0), centered on the middle of the initial array

  • width_y: size of the area to plot in y (axis 1), centered on the middle of the initial array

  • width_x: size of the area to plot in x (axis 2), centered on the middle of the initial array

Returns:

• an array (if a single array was provided) or a tuple of arrays interpolated on an orthogonal grid (same length as the number of input arrays)

• a tuple of three 1D vectors of q values (qx, qz, qy)

• a numpy array of shape (3, 3): transformation matrix from the detector frame to the laboratory/crystal frame

orthogonalize_vector(vector, array_shape, tilt_angle, pixel_x, pixel_y, verbose=False)

Calculate the coordinates of the vector in the laboratory frame.

Parameters:

• vector – tuple of 3 coordinates, vector to be transformed in the detector frame

• array_shape – shape of the 3D array to orthogonalize

• tilt_angle – angular step during the rocking curve, in degrees

• pixel_x – horizontal pixel size, in meters

• pixel_y – vertical pixel size, in meters

• verbose – True to have printed comments

Returns:

tuple of 3 numbers, the coordinates of the vector expressed in the laboratory frame

property outofplane_angle

Vertical detector angle, in degrees.

property outofplane_coeff

Expose the outofplane_coeff beamline property to the outer world.

Return a coefficient +/- 1 depending on the detector out of plane rotation direction and the detector out of plane orientation.

Returns:

+1 or -1

property params

Return a dictionnary with all parameters.

property q_laboratory: numpy.ndarray | None

Calculate the diffusion vector in the laboratory frame.

Frame convention: (z downstream, y vertical up, x outboard). The unit is 1/A.

Returns:

ndarray of three vectors components.

read_logfile(**kwargs)

Extract values of interest for the geometric transformation from the logfile.

This is the public interface of Diffractometer.goniometer_values

Parameters:

kwargs –

beamline_specific parameters

• ’scan_number’: int, the scan number to load

Returns:

a tuple of angular values in degrees (rocking angular step, grazing incidence angles, inplane detector angle, outofplane detector angle). The grazing incidence angles are the positions of circles below the rocking circle.

property rocking_angle

Angle which is tilted during the rocking curve.

Valid values: {‘outofplane’, ‘inplane’}

property tilt_angle

Angular step of the rocking curve, in degrees.

transformation_bcdi(array_shape, tilt_angle, pixel_x, pixel_y, direct_space, verbose=True)

Calculate the transformation matrix from detector frame to laboratory frame.

For the transformation in direct space, the length scale is in nm, for the transformation in reciprocal space, it is in 1/nm.

Parameters:

• array_shape – shape of the 3D array to orthogonalize

• tilt_angle – angular step during the rocking curve, in degrees

• pixel_x – horizontal pixel size, in meters

• pixel_y – vertical pixel size, in meters

• direct_space – True in order to return the transformation matrix in direct space

• verbose – True to have printed comments

Returns:

• the transformation matrix from the detector frame to the laboratory frame

• the q offset (3D vector) if direct_space is False.

transformation_cdi(arrays, cdi_angle, fill_value, debugging)

Calculate the transformation matrix from detector frame to laboratory frame.

For the transformation in direct space, the length scale is in nm, for the transformation in reciprocal space, it is in 1/nm.

Parameters:

• arrays – tuple of 3D arrays of the same shape (e.g.: reciprocal space diffraction pattern and mask), in the detector frame

• cdi_angle – 1D array of measurement angles in degrees

• fill_value – tuple of real numbers (np.nan allowed), fill_value parameter for the RegularGridInterpolator, same length as the number of arrays

• debugging – bool, True to see more plots

Returns:

• a tuple of arrays interpolated on an orthogonal grid (same length as the number of input arrays)

• a tuple of three 1D arrays for the q values (qx, qz, qy) where qx is downstream, qz is vertical up and qy is outboard.

• a tuple of 2 floats: position of the direct beam after taking into accout the region of interest and binning.

transformation_cdi_ewald(arrays, cdi_angle, fill_value)

Interpolate forward CDI data considering the curvature of the Ewald sphere.

Parameters:

• arrays – tuple of 3D arrays of the same shape (e.g.: reciprocal space diffraction pattern and mask), in the detector frame

• cdi_angle – 1D array of measurement angles in degrees

• fill_value – tuple of real numbers (np.nan allowed), fill_value parameter for the RegularGridInterpolator, same length as the number of arrays

Returns:

voxel_sizes(array_shape, tilt_angle, pixel_x, pixel_y, verbose=False)

Calculate the direct space voxel sizes in the laboratory frame.

Frame convention: (z downstream, y vertical up, x outboard).

Parameters:

• array_shape – shape of the 3D array to orthogonalize

• tilt_angle – angular step during the rocking curve, in degrees

• pixel_x – horizontal pixel size, in meters

• pixel_y – vertical pixel size, in meters

• verbose – True to have printed comments

Returns:

the direct space voxel sizes in nm, in the laboratory frame (voxel_z, voxel_y, voxel_x)

voxel_sizes_detector(array_shape, tilt_angle, pixel_x, pixel_y, verbose=False)

Calculate the direct space voxel sizes in the detector frame.

Frame convention: (z rocking angle, y detector vertical axis, x detector horizontal axis).

Parameters:

• array_shape – shape of the 3D array used in phase retrieval

• tilt_angle – angular step during the rocking curve, in degrees

• pixel_x – horizontal pixel size, in meters

• pixel_y – vertical pixel size, in meters

• verbose – True to have printed comments

Returns:

the direct space voxel sizes in nm, in the detector frame (voxel_z, voxel_y, voxel_x)

property wavelength: float | None

Wavelength in meters.

bcdi.experiment.setup.get_mean_tilt(angles: float | int | numpy.ndarray | List[float | int] | None) → float | None

Calculate the mean tilt depending on the array of incident angles.

E.g., for input angles of [0, 0.25, 0.5, 0.75], the mean tilt is 0.25.