Setting up the parameters
The MPR has several parameters that can be possibly set. Defining all of them manually each time is a tedius requirement, often not necessary as most of the default parameters are working out of the box.
For a better handling of the settings, the spring.Settings object is used as it follows
from spring import Settings
ss = Settings()
It provides a helper function spring.Settings.info() to get an overview on the algorithm’s parameters.
ss.info()
| Section | Name | Value | Type | Range | Description |
| :-----: | :----------: | :---: | :------: | :-------: | :------------------------------------------------: |
| global | generations | 100 | int | >1 | Total number of MPR generations. |
| | popsize | 128 | int | >8 | Population size. Total number of reconstructions |
| | | | | | that form the population. |
| | gpus | [0] | list/int | | Number of GPUs to use or, alternatively, list of |
| | | | | | specific GPU ids. If a number N is given, the |
| | | | | | current usage of the available GPUs is inspected |
| | | | | | and the N ones with lower computing load are |
| | | | | | selected. If N<=0, all available GPUs are |
| | | | | | selected. |
| | threads | 8 | int | >1 | Number of CPU threads per GPU. The total number of |
| | | | | | threads used for calculations is this value times |
| | | | | | the number of GPU in use |
| | bounds | 0 | int | >0 <1 | If set to 1, use the upper bound for the missing |
| | | | | | intensities in the diffraction data |
| | workdir | ./ | string | | Path where the results are saved |
| :-----: | :----------: | :---: | :------: | :-------: | :------------------------------------------------: |
| init | gamma | 0.5 | float | >0.0 <2.0 | Gamma value for the initizalization of the |
| | | | | | densities |
| | supportsize | 60 | int | >1 | Initial linear dimension of the support function. |
| | itemsize_min | 0.2 | float | >0.0 <1.0 | Minimum relative diameter of the spherical density |
| | | | | | profiles used to define the starting densities. |
| | | | | | The actual minimum size in pixels is calcualted as |
| | | | | | itemsize_min*supportsize |
| | itemsize_max | 0.9 | float | >0.0 <1.0 | Maximum relative diameter of the spherical density |
| | | | | | profiles used to define the starting densities. |
| | | | | | The actual maximum size in pixels is calcualted as |
| | | | | | itemsize_max*supportsize |
| | itemnum_min | 2 | int | >1 | Minimum number of spherical density profiles used |
| | | | | | to create the starting densities |
| | itemnum_max | 8 | int | >1 | Maximum number of spherical density profiles used |
| | | | | | to create the starting densities |
| | phaserange | 0 | float | >0.0 <1.0 | Range of phase values in real space for the |
| | | | | | initialized densities. If 0, densities are |
| | | | | | completely real-valued. In general, the phase |
| | | | | | values are initialized in the range |
| | | | | | [-phaserange*pi, phaserange*pi] |
| :-----: | :----------: | :---: | :------: | :-------: | :------------------------------------------------: |
| IA | alg | HIO | string | HIO RAAR | Iterative algorithm used for local optimization. |
| | it | 40 | int | >0 | Starting number of iterations of the iterative |
| | | | | | algorithm. |
| | beta | 0.95 | float | >0.0 <1.0 | Beta parameter of the iterative algorithm |
| | it_ER | 40 | int | >0 | Number of Error Reduction iterations executed |
| | | | | | after RAAR or HIO. |
| | it_eval | 40 | int | >0 | Number of Error Reduction iterations used for the |
| | | | | | evaluation of the reconstruction. |
| | it_stab | 0 | int | >0 | Number of Error Reduction iterations used for the |
| | | | | | stabilization of the reconstruction. |
| | sigma | 2.5 | float | >0.0 | Starting value of the smoothing for the Shrink- |
| | | | | | wrap algorithm. This value is then reduced to 0.5 |
| | | | | | at the end of the reconstruction. |
| | threshold | 0.03 | float | >0.0 | Starting threshold for the Shrink-wrap algorithm. |
| | | | | | This value is then reduced to 2/3 of its starting |
| | | | | | value at the end of the reconstruction. |
| | reality | 0.5 | float | >0.0 <1.0 | Reality constraint of the densities. Phases are |
| | | | | | constrained between -pi*(1-reality) and |
| | | | | | pi*(1-reality) during the execution of the IAs |
| | | | | | iterations |
| | repetitions | 3 | int | >3 | Number of repetitions of the IA algorithm sequence |
| | | | | | per iteration for each density. |
| :-----: | :----------: | :---: | :------: | :-------: | :------------------------------------------------: |
| GA | crossprob | 0.6 | float | >0.0 <1.0 | Probability of crossover |
| | crossweight | 0.4 | float | >0.0 <1.0 | Weight of the differential crossover |
| | crossaverage | 0 | float | >0.0 <2.0 | Weight assigned to the average intensities in the |
| | | | | | masked regions of the diffraction pattern during |
| | | | | | the crossover. If 0, average intensities are not |
| | | | | | used. If 1, the intensities of the new densities |
| | | | | | are completely replaced with the ones of the |
| | | | | | average. |
The parameters can be set by using the spring.Settings.set method, where the section and the name of the parameter must be specified along with the actual value. For example, a typical change in the settings involes the adjusting of the size of the initial support and of the number of iterations of the iterative algorithm. This can be accomplished with:
print("Default support size:", ss.get('init', 'supportsize') )
print("Default iterations", ss.get('IA', 'it') )
ss.set('init', 'supportsize', 100)
ss.set('IA', 'it', 60)
print("New support size:", ss.get('init', 'supportsize') )
print("New iterations", ss.get('IA', 'it') )
Default support size: 60
Default iterations 40
New support size: 100
New iterations 60
Here, the current value of the given parameter is inspected via the spring.Settings.get method.
Settings can be saved into a file and loaded at a later time, in case the user needs to save a specific configuration, for example to deal with a specific dataset. The current settings can be saved with the spring.Settings.save method. The output format is YAML, thus easily readable and editable as a text file.
ss.save('test_settings')
The saved settings can be loaded by creating a new setting object and passing the filename of the settings file to its constructor:
ss_loaded = Settings('test_settings')
print("Saved support size:", ss.get('init', 'supportsize') )
print("Saved iterations", ss.get('IA', 'it') )
Saved support size: 100
Saved iterations 60
The set() method returns a reference to the Settings object. Changes of the values can then be also performed in the following way:
ss_loaded.set('init', 'supportsize', 90).set('IA', 'threshold', 0.25)
print("New value", ss_loaded.get('IA', 'threshold') )
New value 0.25