Reference

Settings

class spring.Settings(fname=None)

Class to handle the settings of MPR. The settings are initialized with their default value. If fname is specified, then settings are loaded from the indicated file previously saved via the save() method.

get(section=None, name=None)

Get the value of the parameters, returned as a dictionary. If both section and name are specified, the parameter is directly returned as a value.

Parameters:

section (Optional[str]) – Section to which the parameter belongs.
name (Optional[str]) – Name of the parameter

info(section=None, name=None)

Print information about the current settings.

Parameters:

section (Optional[str]) – If given, it only prints information on parameters belonging to the given section.
name (Optional[str]) – If given along with section, it only prints information on that parameter.

load(fname)

Load settings from the YAML file fname.

Parameters:: fname (str) – name of the file from which the settings are loaded

print(section=None, name=None)

Print the current values of the parameters.

Parameters:

section (Optional[str]) – If given, it only prints the parameter values belonging to the given section.
name (Optional[str]) – If given along with section, it only prints the value of that parameter.

save(fname)

Save the current settings into the file fname. The file is in YAML format.

Parameters:: fname (str) – name of the file where the settings are saved

set(section, name, value)

Set the value of a parameter with name name belonging to the section section.

Parameters:

section (str) – Section to which the parameter belongs.
name (str) – Name of the parameter
value – Value to assign to the parameter

Pattern

class spring.Pattern(pattern, mask, center, cropsize=None, pid=[0], size=None, satvalue=None, metadata={})

Class for the handling of diffraction patterns.

Parameters:

pattern – 2D numpy array containing the diffraction pattern
mask – 2D numpy array containing the mask. Indexes where mask[i,j]=0 indicate good pixels. Indexes where mask[i,j]=1 are instead excluded. the mask and the pattern must have the same dimensions.
center (list[2]) – list of length 2 containing the y and x coordinates of the center of the pattern
cropsize (Optional[int]) – The pattern is cropped to a shape [cropsize,cropsize]. If cropsize = None, it is set equal to max(pattern.shape).
pid (list) – List of identifiers for the diffraction pattern. For example, if pattern has been acquired in run 34 with pulse-id 197843921, it is convenient to set pid=[34,197843921].
size (Optional[int]) – If not None, the pattern is rescaled to a final shape [size,size] after cropping.
satvalue (Optional[float]) – Indicate which is the saturation value of the detector. If different from None, pixels above this value are masked.
metadata – Additional experimental metadata that is convenient to save with the reconstruction, provided as a dictionary.

get(): Get the prepared pattern as a 2D numpy array.

plot(ax=None, cmap='inferno', circles=0, cropsize=-1)

Plot the diffraction pattern, in logarithmic colorscale.

Parameters:

ax (Optional[Axes]) – matplotlib axes where the pattern is plotted. If none, axes are created within the function and the data is automatically plotted.
cmap – colormap for the plot. It must be a valid matplotlib colormap
circles (int) – number of circles to draw on the pattern, centered in the central coordinates of the pattern matrix. It serves as a guide for the eyes to identify the correct pattern center.
cropsize (int) – The pattern is cropped to the given linear dimension for plotting.

plot_mask(ax=None, cmap='viridis')

Plot the mask of the pattern. Masked pixels get a value of 1, while saturated pixels get a value of 2. Valid pixels have a value of 0.

Parameters:

ax (Optional[Axes]) – matplotlib axes where the mask is plotted. If none, axes are created within the function and the data is automatically plotted.
cmap – colormap for the plot. It must be a valid matplotlib colormap

Result

class spring.Result(pid=None, workdir='./', tag='')

Handle a MPR result.

Parameters:

pid (Optional[list]) – If specified, load the reconstruction file corresponding to the given pid. Otherwise, an empty reconstruction is initialized.
workdir (str) – Specify the path of the folder where the reconstruction is saved
tag (str) – Specify a tag assigned to the reconstruction (given to the MPR.run method as parameter).

get_density(crop=True)

Get the reconstructed average density as numpy array.

Parameters:: crop (bool) – If True, crop the matrix to the support region.
Returns:: 2-D complex numpy array

get_density_best(crop=True)

Get the reconstructed best density as numpy array.

Parameters:: crop (bool) – If True, crop the matrix to the support region.
Returns:: 2-D complex numpy array

get_filename(pid, tag='')

Get the filename for a specific pid.

Parameters:

pid (list) – list of integers specifing the pid
tag – tag to add to the filename

get_pattern(): Get the diffraction pattern used for the reconstruction as a 2D numpy array.

get_prtf()

Calculate the Phase Retrieval Transfer Function on the current reconstructed density.

Returns:: a tuple of two arrays. The first is the array of q values, normalized between 0 and 1. To get the actual corresponding q values, one should multiply this array by q_max. The second array contains the PRTF values.

get_rec_pattern(): Get the retrieved pattern calculated from the reconstruction.

get_residuals(): Get the residuals of the reconstruction, i.e. the difference between the experimental and reconstructed pattern.

get_settings(): Get the settings with which the reconstruction was performed. Returns a spring.Settings object.

get_stats(): Get the statistics of the reconstruction process as a nested dictionary.

get_support(crop=True)

Get the reconstructed average support as numpy array.

Parameters:: crop (bool) – If True, crop the matrix to the support region.
Returns:: 2-D numpy array

get_support_best(crop=True)

Get the reconstructed best support as numpy array.

Parameters:: crop (bool) – If True, crop the matrix to the support region.
Returns:: 2-D numpy array

loadfile(fname)

Load a reconstruction with the specified filename.

Parameters:: fname (str) – name of the reconstruction file

plot(stats=False, cmap='bone', cmap_pattern='inferno')

Plot an overview of the reconstruction in a Matplotlib figure.

Parameters:

stats (bool) – If true, plot also the behavior of relevant parameters and statistics during the reconstruction process.
cmap (str) – A valid matplotlib colormap to assign to the density module.
cmap_pattern (str) – A valid matplotlib colormap to assign to the diffraction pattern.

plot_density(ax, cmap='bone', energy=None, angle=None)

Plot the retrieved density module on the given input axes (instance of matplotlib.axes.Axes).

Parameters:

ax – matplotlib.axes.Axes object on which the data is plotted.
cmap – a valid matplotlib colormap
energy – photon energy in eV. If both energy and angle are given, a scale-bar is shown.
angle – maximum scattering angle at the edge of the detector, in degrees. If both energy and angle are given, a scale-bar is shown.

plot_pattern(ax, cmap='inferno')

Plot the diffraction pattern on the given input axes (instance of matplotlib.axes.Axes).

Parameters:

ax – matplotlib.axes.Axes object on which the data is plotted.
cmap – a valid matplotlib colormap

plot_phase(ax)

Plot the retrieved density phase on the given input axes (instance of matplotlib.axes.Axes).

Parameters:: ax – matplotlib.axes.Axes object on which the data is plotted.

plot_prtf(ax=None)

Plot the Phase Retrieval Transfer Function, calculated on the reconstructed density.

Parameters:: ax – matplotlib.axes.Axes object on which the PRTF is plotted. If None, a new figure and new axes are created and the data is plotted.

plot_rec_pattern(ax, cmap='inferno')

Plot the reconstructed diffraction pattern on the given input axes (instance of matplotlib.axes.Axes).

Parameters:

ax – matplotlib.axes.Axes object on which the data is plotted.
cmap – a valid matplotlib colormap

plot_residuals(ax, cmap='inferno')

Plot the residuals (difference between experimental and reconstructed pattern) on the given input axes (instance of matplotlib.axes.Axes).

Parameters:

ax – matplotlib.axes.Axes object on which the data is plotted.
cmap – a valid matplotlib colormap

plot_support(ax, cmap='viridis')

Plot the retrieved support function on the given input axes (instance of matplotlib.axes.Axes).

Parameters:

ax – matplotlib.axes.Axes object on which the data is plotted.
cmap – a valid matplotlib colormap

print_status(): Print textual information about the reconstruction status.

save(workdir='./', tag='')

Save the reconstruction on disk.

Parameters:

workdir (str) – path to the ourput folder
tag (str) – tag to add to the filename

savefile(fname)

Save the reconstruction with the specified filename.

Parameters:: filename – name of the output file.

MPR

class spring.MPR(pattern, settings, tag='')

Initialise the class to handle the reconstruction process.

Parameters:

pattern (Pattern) – A spring.Pattern object initialized with the diffraction pattern.
settings (Settings) – A spring.Settings object initialized with the desired settings for the MPR parameters.
tag (str) – If tag is given, the final part of the reconstruction file is formatted as ...pid[n]_tag_rec.h5

run(save_every=-1)

Start the reconstruction process. The reconstruction is saved in a file, that is updated along the reconstruction. The name of the file that contains the reconstruction is formed by using the pid parameter of the spring.Pattern, with the form pid[0]_pid[1]_ ... pid[n]_rec.h5.

Parameters:: save_every (int) – The current status of the reconstruction is saved every save_every generations. If <0, only the final result at the last generation is saved.
Returns:: spring.Result

runasync(save_every=-1)

Start the reconstruction process asynchronously. The reconstruction is saved in a file, that is updated along the reconstruction. The name of the file that contains the reconstruction is formed by using the pid parameter of the spring.Pattern, with the form pid[0]_pid[1]_ ... pid[n]_rec.h5.

Parameters:: save_every (int) – The current status of the reconstruction is saved every save_every generations. If <0, only the final result at the last generation is saved.
Returns:: None

Hypervisor

spring.hypervisor: Hypervisor object to handle asynchronous execution. It is a global instance of spring._Hypervisor. Use this instance to access its methods.

class spring._Hypervisor

Object for handling asynchronous executions.

Warning

A new instance of this class shouldn’t be created by the user. Use the global instance spring.hypervisor to use the class methods.

Note

All class methods are non-blocking, apart those explicitly made for this scope like wait.

append(mpr, save_every=-1)

Append a spring.MPR at the back of the execution queue. It behaves like spring.MPR.runasync(). If the execution queue is empty and no reconstruction process is currently running, the execution of the reconstruction is immediately started.

Parameters:

mpr – an instance of spring.MPR for which the execution via the spring.MPR.run() has to be scheduled.
save_every (int) – The current status of the reconstruction is saved every save_every generations. If <0, only the final result at the last generation is saved.

Returns:

None

get()

Get the reconstruction result at the current status.

Returns:: spring.Result

info(): Print information on the running process and the execution queue. Job names are formatted as "pid[0]-pid[1]- .. -pid[n]-tag".

kill()

Empty the execution queue and interrupt the currently running one. Equivalent to the execution of spring._Hypervisor.remove("*")() (which empties the whole execution queue) and spring._Hypervisor.stop() (which interrupts the currently running process).

Returns:: None

livelog(): Start/stop the live logging of the reconstruction status

liveplot(cmap='bone', cmap_pattern='inferno'): Start/stop the live plotting of the reconstruction status

prepend(mpr, save_every=-1)

Similar to spring._Hypervisor.append(), but the reonstruction on the given spring.MPR is put at the front of the execution queue (i.e. it is started at latest right after the one currently running).

Parameters:

mpr – an instance of spring.MPR for which the execution via the spring.MPR.run() has to be scheduled.
save_every (int) – The current status of the reconstruction is saved every save_every generations. If <0, only the final result at the last generation is saved.

Returns:

None

remove(item)

Remove spring.MPR objects submitted with spring.MPR.runasync() from the execution queue. The given item parameter can be either:

An integer type: the element at the corresponding position in the execution queue (given by spring._Hypervisor.info()) is removed.

A string: the element with the corresponding name (give by spring._Hypervisor.info()) is removed from the list. Simple regular expressions allowed by fnmatch can be used (Unix shell-style wildcards).

Note

The operation may affect more than one queued job. For example item='190*' will remove all jobs whose pid starts with 190. The value item='*' will remove all queued jobs.

Warning

Using the position in the queue list is inherently unsafe, as the queue position may change in the meanwhile.

Parameters:: item (Union[int, str]) – An integer, representing the current position in the execution queue (as given by spring._Hypervisor.info()) or a string with the job name (as given by spring._Hypervisor.info()). Simple regular expressions with the wildcards *, ? and [] are allowed to remove multiple items at once.
Returns:: None

stop(): Stop the currently running MPR reconstruction.

wait(): Block until the currently running reconstruction is complete.