.. _api-askadam-optimisation:
.. role::  raw-html(raw)
    :format: html

askadam.optmisation
===================

Usage
-----

.. code-block::

    obj = askadam;
    out = obj.optimisation( data, mask, weights, parameters, fitting, FWDfunc, varargin);

I/O overview
------------

+---------------------------+--------------------------------------------------------------------------------------------------------------+
| Input                     | Description                                                                                                  |
+===========================+==============================================================================================================+
| data                      | (Masked) N-D (imaging) data                                                                                  |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| mask                      | (1-3)D signal mask applied on FWDfunc, **NOTE this mask does NOT apply on data**                             |
+---------------------------+--------------------------------------------------------------------------------------------------------------+ 
| weights                   | N-D wieghts, same dimension as 'data' (optional)                                                             |
+---------------------------+--------------------------------------------------------------------------------------------------------------+ 
| parameters                | structure variable containing starting points of all model parameters to be estimated (optional)             |
+---------------------------+--------------------------------------------------------------------------------------------------------------+ 
| fitting                   | structure contains fitting algorithm parameters                                                              |
+---------------------------+--------------------------------------------------------------------------------------------------------------+ 
| fitting.optimiser         | Algorithm for parameter update, 'adam' (default) | 'sgdm' | 'rmsprop'                                        |
+---------------------------+--------------------------------------------------------------------------------------------------------------+ 
| fitting.model_params      | 1xM cell variable,    name of the model parameters, e.g. {'S0','R2star'};                                    |
+---------------------------+--------------------------------------------------------------------------------------------------------------+ 
| fitting.lb                | 1xM numeric variable, fitting lower bound, same order as field 'model_params', e.g. [0.5, 0];                |
+---------------------------+--------------------------------------------------------------------------------------------------------------+ 
| fitting.ub                | 1xM numeric variable, fitting upper bound, same order as field 'model_params', e.g. [2, 1];                  |
+---------------------------+--------------------------------------------------------------------------------------------------------------+ 
| fitting.isdisplay         | boolean, display optimisation process in graphic plot                                                        |
+---------------------------+--------------------------------------------------------------------------------------------------------------+ 
| fitting.convergenceValue  | tolerance in loss gradient to stop the optimisation, set to -inf to disable checking the gradient;           |
|                           | +ve: decreasing loss; -ve: increasing loss                                                                   |
+---------------------------+--------------------------------------------------------------------------------------------------------------+ 
| fitting.convergenceWindow | #iterations in which 'convergenceValue' is computed                                                          |
+---------------------------+--------------------------------------------------------------------------------------------------------------+ 
| fitting.patience          | #iterations to wait before stopping then optimisation when the loss does not improve                         |
+---------------------------+--------------------------------------------------------------------------------------------------------------+ 
| fitting.iteration         | maximum # of optimisation iterations                                                                         |
+---------------------------+--------------------------------------------------------------------------------------------------------------+ 
| fitting.initialLearnRate  | (initial) learn rate of Adam optimiser                                                                       |
+---------------------------+--------------------------------------------------------------------------------------------------------------+ 
| fitting.tol               | tolerance in loss                                                                                            |
+---------------------------+--------------------------------------------------------------------------------------------------------------+ 
| fitting.lambda            | regularisation parameter(s)                                                                                  |
+---------------------------+--------------------------------------------------------------------------------------------------------------+ 
| fitting.regmap            | model parameter(s) in which regularisation is applied                                                        |
+---------------------------+--------------------------------------------------------------------------------------------------------------+ 
| fitting.TVmode            | Mode for total variation (TV) regularisation, '2D' | '3D'                                                    |
+---------------------------+--------------------------------------------------------------------------------------------------------------+ 
| fitting.lossFunction      | loss function, 'L1' | 'L2' | 'huber' | 'mse'                                                                 |
+---------------------------+--------------------------------------------------------------------------------------------------------------+ 
| fitting.randomness        | randomness of starting point; value between [0,1] 0 (fixed point) > somewhere inbetween >1 completely random |
+---------------------------+--------------------------------------------------------------------------------------------------------------+ 
| fitting.debug             | Dispay extra messages for debugging                                                                          |
+---------------------------+--------------------------------------------------------------------------------------------------------------+ 
| FWDfunc                   | function handle for forward signal generation; size of the output must match size of 'data'                  |
+---------------------------+--------------------------------------------------------------------------------------------------------------+ 
| varargin                  | additional input for FWDfunc other than 'parameter' and 'mask' (same order as FWDfunc)                       |
+---------------------------+--------------------------------------------------------------------------------------------------------------+ 

+-------------------------------+--------------------------------------------------------------------------------------------------------------+
| Output                        | Description                                                                                                  |
+===============================+==============================================================================================================+
| out                           | structure contains optimisation result                                                                       |
+-------------------------------+--------------------------------------------------------------------------------------------------------------+
| out.final                     | output structure at final iteration                                                                          |
+-------------------------------+--------------------------------------------------------------------------------------------------------------+
| out.final.loss                | total loss = loss_fidelity + loss_reg                                                                        |
+-------------------------------+--------------------------------------------------------------------------------------------------------------+
| out.final.loss_fidelity       | loss of data consistency term                                                                                |
+-------------------------------+--------------------------------------------------------------------------------------------------------------+
| out.final.loss_reg            | loss of regularisation term                                                                                  |
+-------------------------------+--------------------------------------------------------------------------------------------------------------+
| out.final.(model_params{k})   | estimated model parameter(s)                                                                                 |
+-------------------------------+--------------------------------------------------------------------------------------------------------------+
| out.min                       | output structure at loss is minimum                                                                          |
+-------------------------------+--------------------------------------------------------------------------------------------------------------+

See also :ref:`gettingstarted-askadam_basic_tutorial`.