Data Class

SimExLite.SampleData

Sample Data APIs

class SimExLite.SampleData.SampleData.SampleData(key, data_dict=None, filename=None, file_format_class=None, file_format_kwargs=None)

Sample structure data mapper

property data_dict

The data_dict of the class instance for calculator usage

property expected_data

The expected_data of the class instance for calculator usage

property file_format_class

The FormatClass to map the file by this DataClass

property file_format_kwargs

The kwargs needed to map the file

property filename: str | None

The filename of the file to map by this DataClass.

classmethod from_dict(data_dict, key)

Create the data class by a python dictionary.

classmethod from_file(filename: str, format_class, key: str, **kwargs)

Create a Data Object mapping a file.

Parameters:

• filename (str, optional) – The filename of the file to map by this DataClass. It has to be None if a dict mapping was already set, defaults to None.

• file_format_class (class, optional) – The FormatClass to map the file by this DataClass, It has to be None if a dict mapping was already set, defaults to None

• file_format_kwargs (dict, optional) – The kwargs needed to map the file, defaults to None.

• key (str) – The key to identify the Data Object.

Returns:

A Data Object

Return type:

BaseData

get_data(**kwargs)

Return the data in a dictionary

property key: str

The key of the class instance for calculator usage

classmethod list_formats()

Print supported formats

property mapping_content

Returns an overview of the keys of the mapped dict or the filename of the mapped file

property mapping_type

If this data class is a file mapping or python dict mapping.

set_dict(data_dict: dict)

Set a mapping dict for this DataClass.

Parameters:

data_dict (dict) – The data dict to map

set_file(filename: str, format_class, **kwargs)

Set a mapping file for this DataClass.

Parameters:

• filename – The filename of the file to map.

• format_class (class) – The FormatClass to map the file

write(filename: str, format_class, key: str | None = None, **kwargs)

Write the data mapped by the Data Object into a file and return a Data Object mapping the file. It converts either a file or a python object to a file The behavior related to a file will always be handled by the format class. If it’s a python dictionary mapping, write with the specified format_class directly.

Parameters:

• filename (str) – The filename of the file to be written.

• file_format_class (class) – The FormatClass to write the file.

• key – The identification key of the new Data Object. When it’s None, a new key will

be generated with a suffix added to the previous identification key by the FormatClass. Defaults to None. :type key: str, optional :return: A Data Object :rtype: BaseData

module ASEFormat:

Module that holds the ASEFormat class.

class SimExLite.SampleData.ASEFormat.ASEFormat

Class that interfacing data format supported by ASE.

abstract classmethod convert(obj: BaseData, output: str, output_format_class: str, key, **kwargs)

Direct convert method, if the default converting would be too slow or not suitable for the output_format

classmethod read(filename: str, format=None) → dict

Read the data from the file with the filename to a dictionary.

classmethod write(object, filename: str, key: str | None = None, format=None)

Save the data with the filename.

SimExLite.PhotonBeamData

Photon Beam data APIs

class SimExLite.PhotonBeamData.BeamBase(pulse_energy=None, wavelength=None, focus_area=None)

The simplest description of a pulse of the beam.

Parameters:

• pulse_energy (float, optional) – The energy of the X-ray pulse in Joule.

• photons_per_pulse (int, optional) – The number of photons of this pulse.

• wavelength (float, optional) – The wavelength of this pulse in Angstrom.

• photon_energy (float, optional) – The photon energy of this pulse, in eV.

• focus_area (float, optional) – The focus area of this pulse, in m**2.

property pulse_energy

The pulse_energy property.

property wavelength

The wavelength property.

class SimExLite.PhotonBeamData.SimpleBeam(pulse_energy=None, photons_per_pulse=None, wavelength=None, wavelength_weights=None, photon_energy=None, photon_energy_weights=None, beam_size: ndarray | None = None, profile: str = 'gaussian', focus_area=None)

The simplest description of a pulse of the beam.

Parameters:

• pulse_energy (float, optional) – The energy of the X-ray pulse in Joule.

• photons_per_pulse (int, optional) – The number of photons of this pulse.

• wavelength (float or ndarray, optional) –

  The wavelength(s) of this pulse in Angstrom. Monchromatic beam: a scalar wavelength. Polychromatic beam (shot-to-shot-invariant):

  an array of length m of wavelengths.

  Polychromatic beam (shot-to-shot-variant):

  an array of np by m of wavelengths.

• wavelength_weights (ndarray, optional) –

  The relative weights of the corresponding wavelengths. Monchromatic beam: None Polychromatic beam (shot-to-shot-invariant):

  an array of length m of wavelengths.

  Polychromatic beam (shot-to-shot-variant):

  an array of np by m of wavelengths.

• photon_energy (float of ndarray, optional) –

  The photon energy(s) of this pulse, in eV. Monchromatic beam: a scalar. Polychromatic beam (shot-to-shot-invariant):

  an array of length m of photon energies.

  Polychromatic beam (shot-to-shot-variant):

  an array of np by m of photon energies.

• photon_energy_weights (ndarray, optional) –

  The relative weights of the corresponding photon energies. Monchromatic beam: None Polychromatic beam (shot-to-shot-invariant):

  an array of length m of photon energies.

  Polychromatic beam (shot-to-shot-variant):

  an array of np by m of photon energies.

• beam_size (array-like, optional) – Two-element array/list of FWHM (if Gaussian or Airy function) or diameters (if top hat) or widths (if rectangular) of the beam in the order x, y. The unit is meter.

• profile (str, optional) – The beam profile. It can be one of: gaussian|airy|top-hat|rectangular.

• focus_area (float, optional) – The focus area of this pulse, in m**2. It will be overridden by beam_size if both are provided.

SimExLite.PhotonBeamData.hcDivide(val)

h is the Plank constant and c is the speed of light. keV <-> Angstrom.

SimExLite.DiffractionData

Diffraction Data APIs

class SimExLite.DiffractionData.DiffractionData.DiffractionData(key, data_dict=None, filename=None, file_format_class=None, file_format_kwargs=None)

Diffraction data mapper

add_Gaussian_noise(mu, sigs_popt)

Add Gaussian noise to one diffraction pattern

Parameters:

• mu (float) – The averange ADU for one photon

• sigs_popt (list) – [slop, intercept]

add_beam_stop(stop_rad: float)

Add a beamstop in pixel radius (float) to the diffraction patterns.

Parameters:

stop_rad (float) – The radius of the beamstop in pixel unit

apply_geom_mask(geom)

Apply the mask from a detector geom to the data, detector gaps will be filled with -1.

Parameters:

geom (ExtraGeomDetectorGeometry) – extra_geom instance

property data_dict

The data_dict of the class instance for calculator usage

property expected_data

The expected_data of the class instance for calculator usage

property file_format_class

The FormatClass to map the file by this DataClass

property file_format_kwargs

The kwargs needed to map the file

property filename: str | None

The filename of the file to map by this DataClass.

classmethod from_dict(data_dict, key)

Create the data class by a python dictionary.

classmethod from_file(filename: str, format_class, key: str, **kwargs)

Create a Data Object mapping a file.

Parameters:

• filename (str, optional) – The filename of the file to map by this DataClass. It has to be None if a dict mapping was already set, defaults to None.

• file_format_class (class, optional) – The FormatClass to map the file by this DataClass, It has to be None if a dict mapping was already set, defaults to None

• file_format_kwargs (dict, optional) – The kwargs needed to map the file, defaults to None.

• key (str) – The key to identify the Data Object.

Returns:

A Data Object

Return type:

BaseData

get_data(**kwargs)

Return the data in a dictionary

property key: str

The key of the class instance for calculator usage

classmethod list_formats()

Print supported formats

property mapping_content

Returns an overview of the keys of the mapped dict or the filename of the mapped file

property mapping_type

If this data class is a file mapping or python dict mapping.

multiply(val, chunk_size=10000)

Multiply a number to the diffraction patterns.

Parameters:

• val (float) – The value to be multiplied.

• chunk (int) – The chunk size to conduct the operation

poissonize()

Poissonize the data array in this data class

set_array_data_type(data_type)

The the data numpy array dtype

Parameters:

data_type (numpy.dtype) – The numpy dtype to be set. E.g. ‘int32’

set_dict(data_dict: dict)

Set a mapping dict for this DataClass.

Parameters:

data_dict (dict) – The data dict to map

set_file(filename: str, format_class, **kwargs)

Set a mapping file for this DataClass.

Parameters:

• filename – The filename of the file to map.

• format_class (class) – The FormatClass to map the file

write(filename: str, format_class, key: str | None = None, **kwargs)

Write the data mapped by the Data Object into a file and return a Data Object mapping the file. It converts either a file or a python object to a file The behavior related to a file will always be handled by the format class. If it’s a python dictionary mapping, write with the specified format_class directly.

Parameters:

• filename (str) – The filename of the file to be written.

• file_format_class (class) – The FormatClass to write the file.

• key – The identification key of the new Data Object. When it’s None, a new key will

be generated with a suffix added to the previous identification key by the FormatClass. Defaults to None. :type key: str, optional :return: A Data Object :rtype: BaseData

SimExLite.DiffractionData.DiffractionData.R_d(pix_range, img, img_ref, sa_array)

Get R factor for a certain q range. (See E et. al. 10.1038/s41598-021-97142-5). Here it assumes that the solid angles have already been applied to the input image and reference image, and the input solid angles are used to get the square root of intensity withtout solid angles.

Parameters:

• pix_range (ndarray) – A 1D array specifying the indices of pixels of the image for R factor calculation.

• img (ndarray) – A 2D array of the image for R factor analysis.

• img_ref (ndarray) – A 2D array of the reference image for R factor analysis.

• sa_array (ndarray) – The solid angle of each pixel for the diffraction image.

Returns:

The R factor for this certain pixel range.

Return type:

ndarray

SimExLite.DiffractionData.DiffractionData.addBeamStop(img, stop_rad)

Add the beamstop in pixel radius to diffraction pattern.

Parameters:

• img (ndarray) – Diffraction pattern

• stop_rad (float) – The radius of the beamstop in pixel unit (float)

Returns:

Beamstop masked 2D array

Return type:

ndarray

SimExLite.DiffractionData.DiffractionData.addGaussianNoise(diffr_data, mu, sigs_popt)

Add Gaussian noise to one diffraction pattern

Parameters:

• diffr_data (ndarray) – A diffraction pattern.

• mu (float) – The average ADU for one photon.

• sigs_popt (list) – [slop, intercept].

SimExLite.DiffractionData.DiffractionData.get_geom_mask(geom, img_size)

Get a 2D mask from a detector geom

Parameters:

• geom (ExtraGeomDetectorGeometry) – extra_geom instance.

• img_size ([nrow, ncol]) – The array size of the output mask.

SimExLite.DiffractionData.DiffractionData.get_q(Rs, distance, wavelength)

Rs is a collection of the radial distance of pixels. distance is the sample to detector distance in pixel unit (distance = real_distance/pixel_size).

SimExLite.DiffractionData.DiffractionData.get_radial_map(arr)

Get the radial map of a 2D array

SimExLite.DiffractionData.DiffractionData.get_rfactor(img, img_ref, sa_array, pixel_map=None, bin_range=None, bin_size: float = 1.0)

Get the residual factor between two reciprocal space volumes.

Parameters:

• img (ndarray) – A 3D array (num_snapshot, ny, nx).

• img_ref (ndarray) – A 3D reference array (num_snapshot, ny, nx).

• sa_array (ndarray) – A 2D array of the solid angle of each pixel for the detector.

• pixel_map (ndarray) – A 2D array defines the map the pixels, defaults to the array’s indices.

• bin_range (float) – The range of bins in the unit of the pixel map, defaults to cover the whole 2D pattern.

• bin_size (float) – The pixel interval between two bins, defaults to 1.0.

Returns:

A tuple of the r factors and their corresponding radial pixel indices.

Return type:

(bins, R_factors)

SimExLite.DiffractionData.DiffractionData.write_multiple_file_to_emc(in_file_list, in_file_format_class, filename: str, poissonize=False, stop_rad=None, multiply=None, fluct_sample_interval=None, background=None, geom=None, **kwargs)

Write multiple diffraction files to a single EMC h5 file