Python programming API

This chapter describes the programming interface of pyRS, and the implementation of methods for the reduction of raw neutron event data.

import pyRS

The most important class is AzimuthalIntegrator which is an object containing both the geometry (it inherits from Geometry, another class) and exposes important methods (functions) like integrate1d and `integrate2d.

pyRS package

Event Nexus Conversion Module

class pyrs.core.nexus_conversion.NeXusConvertingApp(nexus_file_name, mask_file_name=None, extra_logs=[])

Convert NeXus file to Hidra project file

Parameters

• nexus_file_name (str) – Name of NeXus file

• mask_file_name (str, optional) – Name of masking file

• extra_logs (list, optional) – list of string with no default logs to keep in project file

pyrs.core.nexus_conversion.NeXusConvertingApp.convert(self, use_mantid=False)

Main method to convert NeXus file to HidraProject File by

1. split the workspace to sub runs

2. for each split workspace, aka a sub run, get the total counts for each spectrum and save to a 1D array

Returns

HidraWorkspace for converted data

Return type

pyrs.core.workspaces.HidraWorkspace

pyrs.core.nexus_conversion.NeXusConvertingApp.save(self, projectfile)

Save workspace to Hidra project file

Parameters

projectfile (str) – output filename

Data Reduction Manager Module

class pyrs.core.reduction_manager.HB2BReductionManager

Bases: object

A data reduction manager of HB2B

1. It can work with both PyHB2BReduction and MantidHB2BReduction seamlessly

2. It can always compare the results between 2 reduction engines

3. It shall provide an API to calibration optimization

convert_counts_to_diffraction(reduction_engine, two_theta_range, num_bins, delta_2theta, mask_array, vanadium_array)

Histogram detector counts for a defined 2theta range

Parameters

• reduction_engine (object) – object containing information about the instrument geometry

• two_theta_range (tuple, [float, optional]) – tuple with the min and max 2theta range

• num_bins (int, optional) – number of bins in 2theta vector

• delta_2theta (float, optional) – 2theta increment in the reduced diffraction data

• mask_array (numpy.ndarray, optional) – mask: 1 to keep, 0 to mask (exclude)

• vanadium_array (numpy.ndarray, optional) – detector pixels’ vanadium for efficiency and normalization. If vanadium duration is recorded, the vanadium counts are normalized by its duration in seconds

Returns

2theta bins, histogram of counts, variances of counts

Return type

numpy.ndarray

static generate_2theta_histogram_vector(min_2theta: Optional[float], max_2theta: Optional[float], num_bins: int, pixel_2theta_array, mask_array, step_2theta=None)

Generate a 1-D array for histogram 2theta bins

Parameters

• min_2theta (float, optional) – minimum 2theta to use for generating vector

• max_2theta (float, optional) – maximum 2theta to use for generating vector

• num_bins (int) – number of bins in 2theta vector

• pixel_2theta_array (numpy.ndarray) – 2theta of each detector pixel

• mask_array (numpy.ndarray, optional) – vector for pixel mask

Returns

2theta values serving as bin boundaries, such its size is 1 larger than num_bins

Return type

numpy.ndarray

generate_eta_roi_vector(eta_step, eta_min, eta_max)

Generate vector of out-of-plane angle centers

Determines list of out-of-plane centers for texture reduction generated list is centered at eta of 0

e.g.; 0, +/-step, +/-2step, +/-3step, …

Parameters

• eta_step (float) – angular step size for out-of-plane reduction

• eta_min (float) – min angle for out-of-plane reduction

• eta_max (float) – max angle for out-of-plane reduction

Returns

eta_roi_vector

Return type

numpy.ndarray

get_detector_counts(session_name, sub_run: int)

Get the raw counts from detector of the specified sub run

Parameters

• session_name (str) – name of the session for locating workspace

• sub_run (int) – sub run number

Returns

array of detector counts

Return type

numpy.ndarray

get_mask_vector(mask_id)

Get the detector mask

Parameters

mask_id (str) – String as ID

Returns

a 1D array (0: mask, 1: keep)

Return type

numpy.ndarray

get_reduced_diffraction_data(session_name, sub_run=None, mask_id=None)

Get the reduce data

Parameters

• session_name (str) – name of the session for locating workspace

• sub_run (int) – sub-run index

• mask_id (str, optional) – mask used to reduce diffraction data (default is None)

Returns

2-vectors: 2theta and intensity

Return type

numpy.ndarray

get_sample_log_value(session_name, log_name, sub_run)

Get an individual sample log’s value for a sub run

Parameters

• session_name (str) – name of the session for locating workspace

• log_name (str) – Name of the sample log

• sub_run (int) – sub-run index

Returns

vector of sample log values

Return type

numpy.ndarray

get_sample_logs_names(session_name)

Get the names of all sample logs in the workspace

Parameters

session_name (str) – name of the session for locating workspace

Returns

list of sample logs

Return type

list

get_sub_run_2theta(session_name, sub_run)

Get the detector arm’s 2theta position of a sub run

Parameters

• session_name (str) – name of the session for locating workspace

• sub_run (int) – sub-run index

Returns

2theta vector for the sub-run

Return type

numpy.ndarray

get_sub_runs(session_name)

Get sub runs from a workspace belonged to a session

Parameters

session_name (str) – name of the session for locating workspace

Returns

return a list of sub-runs in the workspace

Return type

list

init_session(session_name, hidra_ws=None)

Initialize a new session of reduction and thus to store data according to session name

load_hidra_project(project_file_name, load_calibrated_instrument, load_detectors_counts, load_reduced_diffraction)

Load hidra project file

Parameters

• project_file_name (str) – filename for the Hidra project file

• load_calibrated_instrument (bool) –

• load_detectors_counts (bool) – Flag to load detector counts

• load_reduced_diffraction (bool) – Flag to reduced diffraction data

Returns

HidraWorkspace instance

load_mask_file(mask_file_name)

Load mask file to 1D array and auxiliary information

Parameters

mask_file_name (str) – mask filename

Returns

two_theta, note, mask_id

load_vanadium(van_project_file)

Load vanadium from HiDRA project file or NeXus file

Parameters

van_project_file (str) – vanadium HiDRA project file or NeXus file

Returns

• van_array (numpy.ndarray) - 1D array as vanadium counts

• van_duration (numpy.ndarray) - duration of vanadium run (second)

reduce_diffraction_data(session_name, apply_calibrated_geometry, num_bins, sub_run_list, mask, mask_id, vanadium_counts=None, van_duration=None, normalize_by_duration=True, eta_step=None, eta_min=None, eta_max=None, min_2theta=None, max_2theta=None, delta_2theta=None)

Reduce ALL sub runs in a workspace from detector counts to diffraction data

Parameters

• session_name (str) – Name for the reduction session

• apply_calibrated_geometry (DENEXDetectorShift, bool) –

  1. user-provided DENEXDetectorShift

  2. True (use calibrated geometry in workspace)

  3. False (no calibration)

• num_bins (int) – 2theta resolution/step

• mask – 1D array for masking (1 to keep, 0 to mask out)

• mask_id (str, optional) – ID for mask. If mask ID is None, then it is the default universal mask applied to all data

• sub_run (integer) – sub run number in workspace to reduce

• vanadium_counts (numpy.ndarray, optional) – detector pixels’ vanadium for efficiency and normalization. If vanadium duration is recorded, the vanadium counts are normalized by its duration in seconds

• eta_step (float, optional) – angular step size for out-of-plane reduction

• eta_min (float, optional) – min angle for out-of-plane reduction

• eta_max (float, optional) – max angle for out-of-plane reduction

• min_2theta (float, optional) – min 2theta

• max_2theta (float, optional) – max 2theta

• delta_2theta (float, optional) – 2theta increment in the reduced diffraction data

Returns

None

reduce_sub_run_diffraction(workspace, sub_run, geometry_calibration, mask_vec_tuple, min_2theta=None, max_2theta=None, num_bins=1000, sub_run_duration=None, vanadium_counts=None, van_duration=None, delta_2theta=None)

Reduce import data (workspace or vector) to 2-theta ~ I

The binning of 2theta is linear in range (min, max) with given resolution

1. 2-theta range:

   If nothing is given, then the default range is from detector arm’s 2theta value going up and down with half of default_two_theta_range

2. 2-theta resolution/step size:

   If 2theta resolution is not given, num_bins will be used to determine resolution with 2-theta range; Otherwise, use resolution

Normalization to time/duration

If both sub run duration and vanadium duration are given normalized intensity = raw histogram / vanadium histogram * vanadium duration / sub run duration

Parameters

• workspace (HidraWorkspace) – workspace with detector counts and position

• sub_run (integer) – sub run number in workspace to reduce

• geometry_calibration (DENEXDetectorShift) – instrument geometry to calculate diffraction pattern

• mask_vec_tuple (tuple, [str, numpy.ndarray]) – mask ID and 1D array for masking (1 to keep, 0 to mask out)

• min_2theta (float, optional) – min 2theta

• max_2theta (float, optional) – max 2theta

• num_bins (int) – 2theta resolution/step

• num_bins – number of bins

• delta_2theta (float, optional) – 2theta increment in the reduced diffraction data

• sub_run_duration (float, optional) – If None, then no normalization to time (duration) will be done. Otherwise, intensity will be normalized by time (duration)

• vanadium_counts (numpy.ndarray, optional) – detector pixels’ vanadium for efficiency and normalization. If vanadium duration is recorded, the vanadium counts are normalized by its duration in seconds

Returns

None

reduce_sub_run_texture(workspace, sub_run, geometry_calibration, mask_vec_tuple, min_2theta=None, max_2theta=None, num_bins=1000, sub_run_duration=None, vanadium_counts=None, van_duration=None, eta_step=None, eta_min=None, eta_max=None, delta_2theta=None)

Reduce import data (workspace or vector) to 2-theta ~ I

The binning of 2theta is linear in range (min, max) with given resolution

1) 2-theta range: If nothing is given, then the default range is from detector arm’s 2theta value going up and down with half of default_two_theta_range 2) 2-theta resolution/step size: If 2theta resolution is not given, num_bins will be used to determine resolution with 2-theta range; Otherwise, use resolution

Normalization to time/duration If both sub run duration and vanadium duration are given normalized intensity = raw histogram / vanadium histogram * vanadium duration / sub run duration

Parameters

• workspace (HidraWorkspace) – workspace with detector counts and position

• sub_run (integer) – sub run number in workspace to reduce

• geometry_calibration (DENEXDetectorShift) – instrument geometry to calculate diffraction pattern

• mask_vec_tuple (tuple, [str, numpy.ndarray]) – mask ID and 1D array for masking (1 to keep, 0 to mask out)

• min_2theta (float, optional) – min 2theta

• max_2theta (float, optional) – max 2theta

• num_bins (int) – 2theta resolution/step

• num_bins – number of bins

• delta_2theta (float, optional) – 2theta increment in the reduced diffraction data

• sub_run_duration (float, optional) – If None, then no normalization to time (duration) will be done. Otherwise, intensity will be normalized by time (duration)

• vanadium_counts (numpy.ndarray, optional) – detector pixels’ vanadium for efficiency and normalization. If vanadium duration is recorded, the vanadium counts are normalized by its duration in seconds

• eta_step (float) – angular step size for out-of-plane reduction

• eta_min (float) – min angle for out-of-plane reduction

• eta_max (float) – max angle for out-of-plane reduction

Returns

None

save_reduced_diffraction(session_name, output_name)

Save the reduced diffraction data to file

Parameters

• session_name (str) – name of the session for locating workspace

• output_name (str) – output filename

Returns

setup_reduction_engine(workspace, sub_run, geometry_calibration)

Setup reduction engine to reduce data (workspace or vector) to 2-theta ~ I

Builds a new 2theta pixel map if none is present or if the detector has moved

Parameters

• workspace (HidraWorkspace) – workspace with detector counts and position

• sub_run (int) – sub run number in workspace to reduce

• geometry_calibration (DENEXDetectorShift) – instrument geometry to calculate diffraction pattern

Returns

None

Data Reduction Module

class pyrs.core.reduce_hb2b_pyrs.PyHB2BReduction(instrument, wave_length=None)

Bases: object

A class to reduce HB2B data in pure Python and numpy

build_instrument(calibration)

Build an instrument for each pixel’s position in cartesian coordinate

Parameters

calibration (DENEXDetectorShift) – DENEXDetectorShift from geometry calibration

Returns

2D numpy array

build_instrument_prototype(two_theta, arm_length, arm_length_shift, center_shift_x, center_shift_y, rot_x_flip, rot_y_flip, rot_z_spin, two_theta_shift)

build an instrument definition from calibration inputs

Parameters

• two_theta (float) – 2theta position of the detector panel. It shall be negative to sample log value

• arm_length (float) – Distance of detector from center of rotation

• arm_length_shift (float) – shift along Z-direction (arm length)

• center_shift_x (float) – shift along X-direction

• center_shift_y (float) – shift along Y-direction

• rot_x_flip (float) – rotation of the detector panel about the X-direction

• rot_y_flip (float) – rotation of the detector panel about the Y-direction

• rot_z_spin (float) – rotation of the detector panel about the Z-direction

• two_theta_shift (float) – 2theta offset

Returns

2D numpy array

get_eta_value()

Get vector of solid angles for each pixel

Return type

numpy.ndarray

get_pixel_positions(is_matrix=False, corner_center=False)

Get pixels’ positions

Return the pixel matrix of the instrument

Parameters

• is_matrix (boolean) – flag to output pixels in matrix. Otherwise, 1D array in order of pixel IDs

• corner_center (boolean) – only return 5 positions

Return pixel_array

array of pixel positions

Return type

numpy.ndarray

static histogram_by_numpy(pixel_2theta_array, pixel_count_array, two_theta_bins, is_point_data, vanadium_counts)

Histogram a data set (X, Y) by numpy histogram algorithm

Assumption: 1. pixel_2theta_array[i] and vec_counts[i] correspond to the same detector pixel

Parameters

• pixel_2theta_array (numpy.ndarray) – 2theta (1D) array for each pixel

• pixel_count_array (numpy.ndarray) – count array (1D) for each pixel and paired to pixel_2theta_array

• pixel_2theta_array – 2-theta bin boundaries

• is_point_data (bool) – Output shall be point data; otherwise, histogram data

• vanadium_counts (None or numpy.ndarray) – Vanadium counts for normalization and efficiency calibration. It is allowed to be None

Returns

bins, data_hist, data_var

Return type

numpy.ndarray

property instrument

Return instrument geometry/calculation instance :return:

reduce_to_2theta_histogram(two_theta_bins, mask_array, is_point_data=True, vanadium_counts_array=None)

Reduce the previously added detector raw counts to 2theta histogram (i.e., diffraction pattern)

Parameters

• two_theta_bins (numpy.ndarray) – 2theta bin boundaries

• mask_array (numpy.ndarray) – mask: 1 to keep, 0 to mask (exclude)

• is_point_data (bool) – Flag whether the output is point data (numbers of X and Y are same)

• vanadium_counts_array (numpy.ndarray, optional) – Vanadium counts array for normalization and efficiency calibration

Returns

two_theta_bins, intensity_vector, variances_vector

Return type

numpy.ndarray

rotate_two_theta(two_theta_0, two_theta_1)

Rotate instrument about Y

Parameters

• two_theta_0 – inital 2theta position of the detector panel.

• two_theta_1 – final 2theta position of the detector panel.

set_experimental_data(two_theta: float, l2: Optional[float], raw_count_vec)

Set experimental data (for a sub-run)

Parameters

• two_theta (float) – detector position

• l2 (float) – detector distance from center of rotation

• raw_count_vec (numpy.ndarray) – detector raw counts

Returns

set_raw_counts(raw_count_vec)

Set experimental data (for a sub-run)

Parameters

raw_count_vec (numpy.ndarray) – detector raw counts

Returns

Detector Definition Module

class pyrs.core.instrument_geometry.DENEXDetectorGeometry(num_rows: int, num_columns: int, pixel_size_x: float, pixel_size_y: float, arm_length: float, calibrated: bool)

Bases: object

A class to handle and save instrument geometry setup

apply_shift(geometry_shift)

Apply detector Calibration :param geometry_shift: DENEXDetectorShift :return:

property arm_length

Return float

sample to detector distance

property detector_size

Detector size (number of pixels) :return: number of rows, number of columns

property pixel_dimension

Each pixel’s linear size at X (across columns) and Y (across rows) direction :return: size along X-axis, size along Y-axis in unit of meter

class pyrs.core.instrument_geometry.DENEXDetectorShift(shift_x, shift_y, shift_z, rotation_x, rotation_y, rotation_z, two_theta_0=0.0)

Bases: object

A class to handle and save instrument geometry calibration information

property center_shift_x

Return float

detector shift along x

property center_shift_y

Return float

detector shift along y

property center_shift_z

Return float

detector shift along z

convert_error_to_dict()

Convert instrument geometry calibration to a dictionary if this shift is shift error :return:

convert_to_dict()

Convert instrument geometry calibration to a dictionary :return:

from_json(file_name)

Convert from a Json string (dictionary) and set to parameters :param file_name: json file name :return:

property rotation_x

Return float

detector rotation about z

property rotation_y

Return float

detector rotation about y

property rotation_z

Return float

detector rotation about z

set_from_dict(geometry_shift_dict)

Set geometry shift parameters from a dictionary, which may miss some parameters :param geometry_shift_dict: :return:

set_from_dict_error()

to_json(file_name)

Convert to a dictionary and convert to Json string :return:

property two_theta_0

Return float

Shift of the 2theta zero point

Instrument Definition Module

class pyrs.core.instrument_geometry.HidraSetup(detector_setup)

Bases: object

A class to work with instrument geometry calculation

Handle anything to do with HB2B (HiDRA) including geometry, wavelength and calibration

get_instrument_geometry(calibrated)

Get instrument geometry parameters Get HB2B geometry setup, raw or calibrated optionally :param calibrated: Bool :return GeometrySetup: Geometry setup parameters

get_wavelength(wave_length_tag)

Get wave length Get wave length for only calibrated :param wave_length_tag: str

user tag (as 111, 222) for wave length. None for single wave length

Return float

wave length in A

get_wavelength_shift()

property name

class pyrs.core.reduce_hb2b_pyrs.ResidualStressInstrument(instrument_setup)

Bases: object

This is a class to define HB2B instrument geometry and related calculation

build_instrument(two_theta: float, l2: Optional[float] = None, instrument_calibration=None)

Build instrument considering calibration step 1: rotate instrument according to the calibration step 2: rotate instrument about 2theta

Parameters

• two_theta (float) – 2theta position of the detector arm

• l2 (float) – distance of detector from the center of rotation

• instrument_calibration (DENEXDetectorShift) – DENEXDetectorShift or None (no calibration)

Returns

generate_rotation_matrix(rot_x_rad, rot_y_rad, rot_z_rad)

Build a ration matrix with 3 orthogonal directions

Parameters

• rot_x_rad (float) – rotation about X-axis in rad (flip forward/backward)

• rot_y_rad (float) – rotation about Y-axis in rad (vertical rotation)

• rot_z_rad (float) – rotation about Z-axis in rad (spin)

Returns

get_dspacing_value(dimension=1)

get the dspacing value for all pixels

Parameters

dimension (int) – 1 for array, 2 for matrix

Returns

get_eta_values(dimension)

get the 2theta values for all the pixels

Parameters

dimension (int) – 1 for array, 2 for matrix

Returns

get_pixel_array()

return the 1D array of pixels’ coordination in the order of pixel IDs :return: 2D array ((N x M) x 3)

get_pixel_matrix()

return the 2D matrix of pixels’ coordination

Returns

3D array (2D of 1-D array) (N x M x 3)

get_pixels_2theta(dimension)

get the 2theta values for all the pixels

Parameters

dimension (int) – 1 for array, 2 for matrix

Returns

rotate_detector_2theta(det_2theta)

Rotate detector, i.e., change 2theta value of the detector

Parameters

det_2theta (float) – detector’s 2theta (motor) position in degree

Returns

multiple dimensional array for detector positions

set_wavelength(w_l)

Parameters

w_l – Neutron wavelength

Instrument Calibration Module

class pyrs.calibration.peakfit_calibration.PeakFitCalibration(hb2b_inst=None, powder_engine=None, pin_engine=None, powder_lines=None, single_material=True, wavelength=None)

Bases: object

Calibrate by grid searching algorithm using Brute Force or Monte Carlo random walk

Peak Fitting Methods Module

class pyrs.peaks.peak_fit_engine.PeakFitEngine(hidraworkspace, peak_function_name, background_function_name, wavelength, out_of_plane_angle)

This is the virtual base class as the fitting frame

Parameters

• hidraworkspace (str) – hidraworkspace with detector counts and position

• peak_function_name (str) – peak shape function for peak fitting (Gaussian, PseudoVoigt, or Voigt)

• background_function_name (str) – background function for peak fitting (Linear)

• wavelength (float) – neutron wavelength used to measure diffraction data

• out_of_plane_angle (float, optional) – out-of-plane angle used for texture analysis

pyrs.peaks.peak_fit_engine.PeakFitEngine.fit_multiple_peaks(self, peak_tags, x_mins, x_maxs)

Fit multiple peaks across subruns. This will return a FitResult Concrete instances may instantiate this as needed

Parameters

• peak_tag (str) – Id to define peak

• x_min (float) – min 2theta for peak fitting window

• x_max (float) – max 2theta for peak fitting window

Returns

peaks collections of fitting results

Return type

FitResult