Phasing API

Provides phasing capabilities for the Bragg CDI data.

The reconstruction is based on known iterative algorithm, oscillating between direct and reciprocal space and applying projection algorithms. Cohere supports the following projection algorithms: ER (error reduction), HIO (hybrid input-output), SF (solvent flipping), and RAAR (relaxed averaged alternating reflectors). The algorithms are described in this publication: https://pubs.aip.org/aip/rsi/article/78/1/011301/349838/Invited-Article-A-unified-evaluation-of-iterative

The cohere reconstruction can be tuned to specific cases. Typically every few iteration steps a shrink wrap is applied. And typically a twin blocking is performed after a few first iterations. Other factors differentiating reconstruction and supported by cohere are: low pass filter, phase constrain, averaging amplitudes. These are direct space methods. Each of these features owns parameters that can be tuned to the projection algorithm. Cohere supports partial coherence feature that is performed in reciprocal space and is used to mitigate coherence of the light source.

The software can run code on GPU or CPU, utilizing different library, such as cupy, numpy or torch. User configures the choice depending on hardware and installed software.

The reconstruction is utilized by the GA algorithm, where each generation creates multiple Rec objects, and executes parallel reconstructions.

In addition two subclasses provide functionality for different types of reconstruction. The CoupleRec class supports multipeak reconstruction. The TeRec class supports reconstruction of time-evolving samples with improved temporal resolution.

class cohere_core.controller.phasing.Rec(params, data_file, pkg, **kwargs)

Performs phasing using iterative algorithm.

The Rec object must have a device set, either to GPU id or set as CPU. The functions executed in each iteration are determined at the beginning, during iteration loop initialization. It is based on the reconstruction parameters and the order of functions internally defined in 'iter_functions' field. A factory for this class, 'create_rec' returns initialized Rec object. The object is then called to run iterations. The results can be retrieved with getters or saved.

__init__(params, data_file, pkg, **kwargs)

Constructor. Sets / initializes reconstruction parameters.

Parameters:

  • params -- dictionary containing configuration parameters

  • data_file -- path to the data file

  • pkg -- an acronym of the package that will be utilized for reconstruction: "np" for numpy, "cp" for cupy, and "torch" for torch

  • kwargs -- can contain "debug" parameter. When activated, it will throw exception, if one happens. Otherwise, an error code of -1 is returned and error printed. The handling of the exception is needed in GA reconstruction.

get_coherence()

returns coherence array, if exists.

get_image()

Returns image array.

get_metric()

Returns metrics such as: chi (the error after last iteration), summed phase, area, sharpness of the ds_image array that holds reconstructed image.

get_support()

Returns support array.

init_dev(device_id)

This function initializes GPU device that will be used for reconstruction. When running on CPU, the device_id is set to -1, and the initialization is omitted. After the device is set, the data array is loaded on that device or cpu memory. The data file can be in tif or npy format.

Parameters:

device_id -- device id or -1 if cpu

Returns:

0 if successful, -1 otherwise. In debug mode will re-raise exception instead of returning -1.

init_iter_loop(dir=None, gen=None)

Initializes the iteration loop.

Parameters:

  • dir -- directory containing 'image.npy' file that contains reconstructed object, if the reconstruction is continuation. It defaults to None.

  • gen -- generation number, only used when running GA algorithm. It defaults to None.

Returns:

0 if successful, -1 otherwise. In debug mode will re-raise exception instead of returning -1.

iterate()

It iterates over function order that was determined during loop initialization.

During iteration execution an exception can happen. The exception is handled in non debug mode and thrown otherwise.

Returns:

0 if successful, -1 otherwise. In debug mode will throw exception instead of returning -1.

save_res(save_dir, only_image=False)

Saves reconstruction results.

It centers the maximum of image array and saves this array, support array, coherence if present, and errors. This function is typically called after iterations.

Parameters:

  • save_dir -- directory where results will be saved

  • only_image -- will save only image if True, otherwise all the results are saved. By default all results are saved.

Returns:

cohere_core.controller.phasing.create_rec(params, datainfo, pkg, dev, **kwargs)

Factory for creating Rec object.

If the rec_type is "mp", it will create CoupledRec object used for multipeak reconstruction, otherwise base Rec object. After the object is instantiated it will be set to a given device. This operation can fail, in which case no object is returned. The function continues with initialization of iteration loop. If successful, the Rec object is returned, otherwise None.

Parameters:

  • params -- dict, contains reconstruction parameters

  • datainfo -- for 'basic' datainfo is data file name, and for 'mp' reconstruction it is a list of peak directories

  • pkg -- python package that will be used to run the reconstruction: 'cp' for cupy, 'np' for numpy, 'torch' for torch

  • dev -- GPU device id or -1

  • kwargs -- var parameters: rec_type: 'mp' for multipeak, debug : if True the exceptions are not handled

Returns:

created and initialized object if success, None if failure

cohere_core.controller.phasing.set_lib_from_pkg(pkg)

Imports package specified in input and sets the device library to this package.

Parameters:

pkg -- supported values: 'cp' for cupy, 'np' for numpy, and 'torch' for torch

Returns: