Phasing API

cohere_core.phasing

Provides phasing capabilities for the Bragg CDI data. The software can run code utilizing different library, such as numpy and cupy. User configures the choice depending on hardware and installed software.

class cohere_core.phasing.Rec(params, data_file, pkg)

cohere_core.phasing.reconstruction(self, params, data_file)

Class, performs phasing using iterative algorithm.

paramsdict

parameters used in reconstruction. Refer to x for parameters description

data_filestr

name of file containing data to be reconstructed

cohere_core.phasing.reconstruction(datafile, **kwargs)

Reconstructs the image from experiment data in datafile according to given parameters. The results: image.npy, support.npy, and errors.npy are saved in ‘saved_dir’ defined in kwargs, or if not defined, in the directory of datafile.

example of the simplest kwargs parameters:

  • algorithm_sequence =’3*(20*ER+180*HIO)+20*ER’

  • shrink_wrap_trigger = [1, 1]

  • twin_trigger = [2]

  • progress_trigger = [0, 20]

Parameters:

  • datafile (str) – filename of phasing data. Must be either .tif format or .npy type

  • kwargs (keyword arguments) –

    save_dirstr

    directory where results of reconstruction are saved as npy files. If not present, the reconstruction outcome will be save in the same directory where datafile is.

    processingstr

    the library used when running reconstruction. When the ‘auto’ option is selected the program will use the best performing library that is available, in the following order: cupy, numpy. The ‘cp’ option will utilize cupy, and ‘np’ will utilize numpy. Default is auto.

    devicelist of int

    IDs of the target devices. If not defined, it will default to -1 for the OS to select device.

    algorithm_sequencestr

    Mandatory; example: “3* (20*ER + 180*HIO) + 20*ER”. Defines algorithm applied in each iteration during modulus projection (ER or HIO) and during modulus (error correction or partial coherence correction). The “*” character means repeat, and the “+” means add to the sequence. The sequence may contain single brackets defining a group that will be repeated by the preceding multiplier. The alphabetic entries: ‘ER’, ‘ERpc’, ‘HIO’, ‘HIOpc’ define algorithms used in iterations. If the defined algorithm contains ‘pc’ then during modulus operation a partial coherence correction is applied, but only if partial coherence (pc) feature is activated. If not activated, the phasing will use error correction instead.

    hio_betafloat

    multiplier used in hio algorithm

    twin_triggerlist

    example: [2]. Defines at which iteration to cut half of the array (i.e. multiply by 0s)

    twin_halveslist

    defines which half of the array is zeroed out in x and y dimensions. If 0, the first half in that dimension is zeroed out, otherwise, the second half.

    shrink_wrap_triggerlist

    example: [1, 1]. Defines when to update support array using the parameters below.

    shrink_wrap_typestr

    supporting “GAUSS” only. Defines which algorithm to use for shrink wrap.

    shrink_wrap_thresholdfloat

    only point with relative intensity greater than the threshold are selected

    shrink_wrap_gauss_sigmafloat

    used to calculate the Gaussian filter

    initial_support_arealist

    If the values are fractional, the support area will be calculated by multiplying by the data array dimensions. The support will be set to 1s to this dimensions centered.

    phc_triggerlist

    defines when to update support array using the parameters below by applaying phase constrain.

    phc_phase_minfloat

    point with phase below this value will be removed from support area

    phc_phase_maxfloat

    point with phase over this value will be removed from support area

    pc_intervalint

    defines iteration interval to update coherence.

    pc_typestr

    partial coherence algorithm. ‘LUCY’ type is supported.

    pc_LUCY_iterationsint

    number of iterations used in Lucy algorithm

    pc_LUCY_kernellist

    coherence kernel area.

    lowpass_filter_triggerlist

    defines when to apply lowpass filter using the parameters below.

    lowpass_filter_sw_thresholdfloat

    used in Gass type shrink wrap when applying lowpass filter.

    lowpass_filter_rangelist

    used when applying low resolution data filter while iterating. The values are linespaced for lowpass filter iterations from first value to last. The filter is gauss with sigma of linespaced value. If only one number given, the last value will default to 1.

    average_triggerlist

    defines when to apply averaging. Negative start means it is offset from the last iteration.

    progress_triggerlist of int

    defines when to print info on the console. The info includes current iteration and error.

    debugboolean

    if in debug mode the verifier will not stop the progress, only print message

cohere_core.reconstruction_single

This module controls a single reconstruction process. Refer to cohere_core-ui suite for use cases. The reconstruction can be started from GUI or using command line scripts, see Using cohere with cohere-ui package.

cohere_core.reconstruction_single.reconstruction(pkg, conf_file, datafile, dir, dev=None)

Controls single reconstruction.

This script is typically started with cohere-ui helper functions. The ‘init_guess’ parameter in the configuration file defines whether it is a random guess, AI algorithm determined, or starting from some saved state. It will set the initial guess accordingly and start phasing process. The results will be saved in configured ‘save_dir’ parameter or in ‘results_phasing’ subdirectory if ‘save_dir’ is not defined.

Parameters:

  • pkg (str) – library acronym to use for reconstruction. Supported: np - to use numpy, cp - to use cupy,

  • conf_file (str) – configuration file name

  • datafile (str) – data file name

  • dir (str) – a parent directory that holds the reconstructions. For example experiment directory or scan directory.

  • dev (int) – id defining GPU the this reconstruction will be utilizing, or -1 if running cpu

cohere_core.reconstruction_multi

This module controls a multiple reconstructions. Refer to cohere_core-ui suite for use cases. The reconstruction can be started from GUI x or using command line scripts x.

cohere_core.reconstruction_multi.reconstruction(pkg, conf_file, datafile, dir, devices)

Controls multiple reconstructions, the reconstructions run concurrently.

This script is typically started with cohere_core-ui helper functions. The ‘init_guess’ parameter in the configuration file defines whether guesses are random, or start from some saved states. It will set the initial guesses accordingly and start phasing process, running each reconstruction in separate thread. The results will be saved in configured ‘save_dir’ parameter or in ‘results_phasing’ subdirectory if ‘save_dir’ is not defined.

Parameters:

  • pkg (str) – library acronym to use for reconstruction. Supported: np - to use numpy, cp - to use cupy,

  • conf_file (str) – configuration file name

  • datafile (str) – data file name

  • dir (str) – a parent directory that holds the reconstructions. For example experiment directory or scan directory.

  • devices (list) – list of GPUs available for this reconstructions

cohere_core.reconstruction_GA

This module controls a reconstructions using genetic algorithm (GA). Refer to cohere_core-ui suite for use cases. The reconstruction can be started from GUI x or using command line scripts x.

cohere_core.reconstruction_GA.reconstruction(pkg, conf_file, datafile, dir, devices)

Controls reconstruction that employs genetic algorith (GA).

This script is typically started with cohere_core-ui helper functions. The ‘init_guess’ parameter in the configuration file defines whether it is a random guess, AI algorithm determined (one reconstruction, the rest random), or starting from some saved state. It will set the initial guess accordingly and start GA algorithm. It will run multiple reconstructions for each generation in a loop. After each generation the best reconstruction, alpha is identified, and used for breeding. For each generation the results will be saved in g_x subdirectory, where x is the generation number, in configured ‘save_dir’ parameter or in ‘results_phasing’ subdirectory if ‘save_dir’ is not defined.

Parameters:

  • pkg (str) – library acronym to use for reconstruction. Supported: np - to use numpy, cp - to use cupy,

  • conf_file (str) – configuration file name

  • datafile (str) – data file name

  • dir (str) – a parent directory that holds the reconstructions. For example experiment directory or scan directory.

  • devices (list) – list of GPUs available for this reconstructions

cohere_core.reconstruction_coupled

This module controls a multipeak reconstruction process. Refer to cohere_core-ui suite for use cases. The reconstruction can be started from GUI or using command line scripts, see Using cohere with cohere-ui package.

cohere_core.reconstruction_coupled.reconstruction(lib, pars, peak_dirs, dev=None)

Controls multipeak reconstruction.

This script is typically started with cohere-ui helper functions. It will start based on the configuration. The config file must have multipeak parameter set to True. In addition the config_mp with the peaks parameters must be included. The results will be saved in configured ‘save_dir’ parameter or in ‘results_phasing’ subdirectory if ‘save_dir’ is not defined.

Parameters:

  • lib (str) – library acronym to use for reconstruction. Supported: np - to use numpy, cp - to use cupy, torch - to use pytorch,

  • pars (dict) – parameters reflecting configuration

  • peak_dirs (list) – list of directories with data taken at each peak

  • dev (int) – id defining GPU the this reconstruction will be utilizing