{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "68d52051-e8c7-46ba-847b-e54a635d0ec5",
   "metadata": {},
   "source": [
    "# Setting up the parameters\n",
    "\n",
    "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.\n",
    "\n",
    "For a better handling of the settings, the [spring.Settings](#spring.Settings) object is used as it follows"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "5a44cd38-cf2d-4a54-919f-069ddada0169",
   "metadata": {},
   "outputs": [],
   "source": [
    "from spring import Settings\n",
    "ss = Settings()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5e2fc71a-33bc-4b92-b432-7cf7d2b8df69",
   "metadata": {},
   "source": [
    "It provides a helper function `spring.Settings.info()` to get an overview on the algorithm's parameters."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "ce9f33d6-668e-4f69-b1ad-6d35595c3b32",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "| Section |     Name     | Value |   Type   |   Range   |                    Description                     |\n",
      "| :-----: | :----------: | :---: | :------: | :-------: | :------------------------------------------------: |\n",
      "|  global | generations  |  100  |   int    |    >1     |          Total number of MPR generations.          |\n",
      "|         |   popsize    |  128  |   int    |    >8     |  Population size. Total number of reconstructions  |\n",
      "|         |              |       |          |           |             that form the population.              |\n",
      "|         |     gpus     |  [0]  | list/int |           |  Number of GPUs to use or, alternatively, list of  |\n",
      "|         |              |       |          |           |   specific GPU ids. If a number N is given, the    |\n",
      "|         |              |       |          |           |  current usage of the available GPUs is inspected  |\n",
      "|         |              |       |          |           |    and the N ones with lower computing load are    |\n",
      "|         |              |       |          |           |     selected. If N<=0, all available GPUs are      |\n",
      "|         |              |       |          |           |                     selected.                      |\n",
      "|         |   threads    |   8   |   int    |    >1     | Number of CPU threads per GPU. The total number of |\n",
      "|         |              |       |          |           | threads used for calculations is this value times  |\n",
      "|         |              |       |          |           |              the number of GPU in use              |\n",
      "|         |    bounds    |   0   |   int    |   >0 <1   |  If set to 1, use the upper bound for the missing  |\n",
      "|         |              |       |          |           |        intensities in the diffraction data         |\n",
      "|         |   workdir    |   ./  |  string  |           |          Path where the results are saved          |\n",
      "| :-----: | :----------: | :---: | :------: | :-------: | :------------------------------------------------: |\n",
      "|   init  |    gamma     |  0.5  |  float   | >0.0 <2.0 |     Gamma value for the initizalization of the     |\n",
      "|         |              |       |          |           |                     densities                      |\n",
      "|         | supportsize  |   60  |   int    |    >1     | Initial linear dimension of the support function.  |\n",
      "|         | itemsize_min |  0.2  |  float   | >0.0 <1.0 | Minimum relative diameter of the spherical density |\n",
      "|         |              |       |          |           |  profiles used to define the starting densities.   |\n",
      "|         |              |       |          |           | The actual minimum size in pixels is calcualted as |\n",
      "|         |              |       |          |           |              itemsize_min*supportsize              |\n",
      "|         | itemsize_max |  0.9  |  float   | >0.0 <1.0 | Maximum relative diameter of the spherical density |\n",
      "|         |              |       |          |           |  profiles used to define the starting densities.   |\n",
      "|         |              |       |          |           | The actual maximum size in pixels is calcualted as |\n",
      "|         |              |       |          |           |              itemsize_max*supportsize              |\n",
      "|         | itemnum_min  |   2   |   int    |    >1     | Minimum number of spherical density profiles used  |\n",
      "|         |              |       |          |           |          to create the starting densities          |\n",
      "|         | itemnum_max  |   8   |   int    |    >1     | Maximum number of spherical density profiles used  |\n",
      "|         |              |       |          |           |          to create the starting densities          |\n",
      "|         |  phaserange  |   0   |  float   | >0.0 <1.0 |    Range of phase values in real space for the     |\n",
      "|         |              |       |          |           |     initialized densities. If 0, densities are     |\n",
      "|         |              |       |          |           |   completely real-valued. In general, the phase    |\n",
      "|         |              |       |          |           |        values are initialized in the range         |\n",
      "|         |              |       |          |           |          [-phaserange*pi, phaserange*pi]           |\n",
      "| :-----: | :----------: | :---: | :------: | :-------: | :------------------------------------------------: |\n",
      "|    IA   |     alg      |  HIO  |  string  | HIO RAAR  |  Iterative algorithm used for local optimization.  |\n",
      "|         |      it      |   40  |   int    |    >0     |   Starting number of iterations of the iterative   |\n",
      "|         |              |       |          |           |                     algorithm.                     |\n",
      "|         |     beta     |  0.95 |  float   | >0.0 <1.0 |     Beta parameter of the iterative algorithm      |\n",
      "|         |    it_ER     |   40  |   int    |    >0     |   Number of Error Reduction iterations executed    |\n",
      "|         |              |       |          |           |                 after RAAR or HIO.                 |\n",
      "|         |   it_eval    |   40  |   int    |    >0     | Number of Error Reduction iterations used for the  |\n",
      "|         |              |       |          |           |         evaluation of the reconstruction.          |\n",
      "|         |   it_stab    |   0   |   int    |    >0     | Number of Error Reduction iterations used for the  |\n",
      "|         |              |       |          |           |        stabilization of the reconstruction.        |\n",
      "|         |    sigma     |  2.5  |  float   |   >0.0    |  Starting value of the smoothing for the Shrink-   |\n",
      "|         |              |       |          |           | wrap algorithm. This value is then reduced to 0.5  |\n",
      "|         |              |       |          |           |         at the end of the reconstruction.          |\n",
      "|         |  threshold   |  0.03 |  float   |   >0.0    | Starting threshold for the Shrink-wrap algorithm.  |\n",
      "|         |              |       |          |           | This value is then reduced to 2/3 of its starting  |\n",
      "|         |              |       |          |           |      value at the end of the reconstruction.       |\n",
      "|         |   reality    |  0.5  |  float   | >0.0 <1.0 |  Reality constraint of the densities. Phases are   |\n",
      "|         |              |       |          |           |      constrained between -pi*(1-reality) and       |\n",
      "|         |              |       |          |           |   pi*(1-reality) during the execution of the IAs   |\n",
      "|         |              |       |          |           |                     iterations                     |\n",
      "|         | repetitions  |   3   |   int    |    >3     | Number of repetitions of the IA algorithm sequence |\n",
      "|         |              |       |          |           |          per iteration for each density.           |\n",
      "| :-----: | :----------: | :---: | :------: | :-------: | :------------------------------------------------: |\n",
      "|    GA   |  crossprob   |  0.6  |  float   | >0.0 <1.0 |              Probability of crossover              |\n",
      "|         | crossweight  |  0.4  |  float   | >0.0 <1.0 |        Weight of the differential crossover        |\n",
      "|         | crossaverage |   0   |  float   | >0.0 <2.0 | Weight assigned to the average intensities in the  |\n",
      "|         |              |       |          |           |  masked regions of the diffraction pattern during  |\n",
      "|         |              |       |          |           |  the crossover. If 0, average intensities are not  |\n",
      "|         |              |       |          |           |  used. If 1, the intensities of the new densities  |\n",
      "|         |              |       |          |           |    are completely replaced with the ones of the    |\n",
      "|         |              |       |          |           |                      average.                      |\n"
     ]
    }
   ],
   "source": [
    "ss.info()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "42ea5f50-0475-4aef-a2bd-b406389f8b63",
   "metadata": {},
   "source": [
    "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:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "b960e044-fce0-4a52-ad91-bfa94ba7f211",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Default support size: 60\n",
      "Default iterations 40\n",
      "New support size: 100\n",
      "New iterations 60\n"
     ]
    }
   ],
   "source": [
    "print(\"Default support size:\", ss.get('init', 'supportsize') )\n",
    "print(\"Default iterations\", ss.get('IA', 'it') )\n",
    "\n",
    "ss.set('init', 'supportsize', 100)\n",
    "ss.set('IA', 'it', 60)\n",
    "\n",
    "print(\"New support size:\", ss.get('init', 'supportsize') )\n",
    "print(\"New iterations\", ss.get('IA', 'it') )"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cc380908-5999-4422-b149-1cf871d16b00",
   "metadata": {},
   "source": [
    "Here, the current value of the given parameter is inspected via the `spring.Settings.get` method."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f5d052e1-44b6-4d63-bbcd-f3cc7838a08b",
   "metadata": {},
   "source": [
    "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."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "81a0ca30-3081-4691-ae79-11e0bc61b587",
   "metadata": {},
   "outputs": [],
   "source": [
    "ss.save('test_settings')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c6358b7b-6595-4d85-b857-ef71d8baf18a",
   "metadata": {},
   "source": [
    "The saved settings can be loaded by creating a new setting object and passing the filename of the settings file to its constructor:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "c27e9cf4-6c52-4493-b49b-9a5ae0bc500b",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Saved support size: 100\n",
      "Saved iterations 60\n"
     ]
    }
   ],
   "source": [
    "ss_loaded = Settings('test_settings')\n",
    "print(\"Saved support size:\", ss.get('init', 'supportsize') )\n",
    "print(\"Saved iterations\", ss.get('IA', 'it') )"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "aeaca87c-62d8-43a8-8a23-b33b494dec2c",
   "metadata": {},
   "source": [
    "The `set()` method returns a reference to the `Settings` object. Changes of the values can then be also performed in the following way:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "9fa980cf-d658-4643-b28f-4f6f3cb08729",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "New value 0.25\n"
     ]
    }
   ],
   "source": [
    "ss_loaded.set('init', 'supportsize', 90).set('IA', 'threshold', 0.25)\n",
    "print(\"New value\", ss_loaded.get('IA', 'threshold') )"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}