source_localization.cost module

class source_localization.cost.Cost(msh, obs, ctrl, regularization_types=None, alpha=None)[source]

Bases: object

Class containing the cost function \(j\) to minimize with respect to the quantity of pheromone emitted by the insects \(s\), also refered to as the control variable. The cost function is of the following form:

\[j(s)=\|m\left(c(s)\right)-m_{obs}\|_{\mathbf{R}^{-1}}^2 + \sum_{i} \alpha_{reg,i} j_{reg,i}(s)\]

with \(\|m\left(c(s)\right)-m_{obs}\|_{\mathbf{R}^{-1}}^2\) the term of discrepancy between the data \(m_{obs}\) and the estimate computed using the pheromone propagation model \(m\left(c(s)\right)\), \(j_{reg,i}\) some regularization terms based on biological information and \(\alpha_{reg,i}\) the associated weight coefficient.

This class contains several features to construct such cost function and to solve the optimization such as:

  • the observation and regularization terms,

  • methods to add, modify and remove regularization terms,

  • methods to compute the gradient of each differentiable parts,

  • methods to compute the proximal operator of each non-differentiable parts,

  • a method to minimize the cost function.

msh

The geometry of the domain.

Type:

MeshRect2D

obs

Object containing all the features related to the observations and estimation of the observed variables.

Type:

Obs

ctrl

Object containing the control variable \(s\), its value and all its features.

Type:

Control

j_obs

The current value of the observations term of the cost function \(\|m\left(c(s)\right)-m_{obs}\|_{\mathbf{R}^{-1}}^2\).

Type:

float

implemented_regularization_types

The list of the keywords of the implemented type of regularization terms. This list of keyword is [‘Tikhonov’, ‘Population dynamic’, ‘LASSO’, ‘time group LASSO’, ‘logarithm barrier’].

Let us note that the regularization terms ‘Tikhonov’, ‘Population dynamic’ and ‘logarithm barrier’ are differentiable, while the regularization terms ‘LASSO’ and ‘time group LASSO’ are non-differentiable with respect to the control variable \(s\).

Type:

list of str

regularization_types

The list of the keywords of the type of regularization terms considered. If no regularization terms are considered, initialized to an empty list.

Type:

list of str

alpha

The weight coefficients of the regularization terms \(\alpha_{reg,i}\). This dictionnary links the keywords of the type of regularization considered to the associated weight coefficient. If no regularization terms are considered, initialized to an empty dictionnary.

Type:

dict of float

j_reg

The current value of the regularization terms \(j_{reg,i}\). This dictionnary links the keywords of the type of regularization considered to the value of the regularization term. If no regularization terms are considered, initialized to an empty dictionnary.

Type:

dict of float

__init__(msh, obs, ctrl, regularization_types=None, alpha=None)[source]

Constructor method

Parameters:

  • msh (MeshRect2D) – The geometry of the domain.

  • obs (Obs) – Object containing all the features related to the observations and estimation of the observed variables.

  • ctrl (Control) – Object containing the control variable \(s\) and all its features.

  • regularization_types (list of string, string or None, optional, default: None) – The keyword or list of the keywords of the type of regularization terms considered. If None, no regularization terms are considered.

  • alpha (dic of float, float or None, optional, default: None) – The weight coefficient or dictionnary of weight coefficients \(\alpha_{reg,i}\). If None, no regularization terms are considered.

Raises:

ValueError – if the keywords of the type of regularization terms considered do not coincide with the keywords of the dictionnary of weight coefficients or are not in the list of the keywords of the implemented type of regularization terms.

add_reg(regularization_type, alpha)[source]

Add a regularization term \(j_{reg,i}\) to the cost function \(j\).

The addition of a regularization term is done in the following steps:

  • update the attribute regularization_types by stacking the keyword of the type of regularization to add,

  • update the attribute alpha by adding the additional keyword and the associated weight coefficient,

  • update the attribute j_reg by adding the additional keyword and initialize the associated value with 0.

Parameters:

  • regularization_type (string) – The keyword of the type of regularization to add.

  • alpha (float) – The associated weight coefficient \(\alpha_{reg,i}\).

Raises:

ValueError – if the keyword of the type of regularization terms to additionnaly considered is not in the list of the keywords of the implemented type of regularization terms.

Notes

If the weight coefficient of the additional regularization term is 0 (\(\alpha_{reg,i}=0\)), then the regularization term is not added and nothing is done.

If the regularization term was already considered, then the method only updates the associated weight coefficient \(\alpha_{reg,i}\).

cost_and_gradient(s, direct_model, adjoint_model, display=False)[source]

Compute the cost function \(j\) and its gradient \(\nabla j\) for a given value of the control variable \(s\).

Parameters:

  • s (ndarray) – The value of the control variable \(s\) in which \(j\) and \(\nabla j\) are evaluated.

  • direct_model (DiffusionConvectionReaction2DEquation) – The pheromone propagation model that enables to estimate the observed variable \(m\left(c(s)\right)\).

  • adjoint_model (AdjointDiffusionConvectionReaction2DEquation) – The adjoint model that enables to compute the adjoint state \(c^*(s)\).

  • display (boolean, optional, default: False) – If True, print the progress of the computations throught the different steps

Returns:

  • j (float) – The evaluation of the cost function \(j(s)\).

  • grad_j (ndarray) – The evaluation of the gradient of the cost function \(\nabla j(s)=\sum_{i} \alpha_{reg,i} \nabla j_{reg,i}(s)-c^*(s)\).

gradient_objectif_wrt_S()[source]

Compute the gradient of the differentiable part objectif function \(J(s,m) =\|m-m_{obs}\|_{\mathbf{R}^{-1}}^2 + \sum_{i} \alpha_{reg,i} j_{reg,i}(s)\) with respect to the control variable \(s\) for the current value of the control variable:

\[\nabla_s J(s,m) = \sum_{i} \alpha_{reg,i} \nabla j_{reg,i}(s)\]
Returns:

evaluation of the gradient \(\nabla_s J(s,m)\)

Return type:

ndarray

Raises:

ValueError – if a regularization term is considered but can not be computed due to parameters with incorrect or missing parameters.

gradient_objectif_wrt_d()[source]

Compute the gradient of the objectif function \(J(s,m) =\|m-m_{obs}\|_{\mathbf{R}^{-1}}^2 + \sum_{i} \alpha_{reg,i} j_{reg,i}(s)\) with respect to the observed variable \(m\) for the current estimate of the observed variable:

\[\nabla_m J(s,m) =2 R^{-1}(m-m_{obs})\]
Returns:

evaluation of the gradient \(\nabla_m J(s,m)\)

Return type:

ndarray

Raises:

ValueError – if the observed variable has not been estimated.

minimize(direct_model, adjoint_model, method, j_obs_threshold=-1, s_init=None, options={}, path_save=None, restart_flag=False)[source]

Minimize the cost function \(j\)

Parameters:

  • direct_model (DiffusionConvectionReaction2DEquation) – The pheromone propagation used to compute the estimate of the observation variable \(m\left(c(s)\right)\).

  • adjoint_model (AdjointDiffusionConvectionReaction2DEquation) – The adjoint model associated to the pheromone propagation model and used to compute the gradient \(\nabla j\).

  • method (str) –

    keyword of the method used to minimize the cost function. Can be either ‘gradient descent’, ‘proximal gradient’, or ‘L-BFGS-B’.

    • With the ‘gradient descent’ keyword, the method uses the algorithm implemented in the module gradient_descent. This method should be used only when \(j\) is differentiable.

    • With ‘proximal gradient’ keyword, the method uses the algorithm implemented in the module proximal_gradient. This method should be used only when \(j\) is non-differentiable.

    • With the ‘L-BFGS-B’ keyword, the method uses the L-BFGS-B algorithm implemented in the function minimize() of the module optimize. This method should be used only when \(j\) is differentiable.

  • j_obs_threshold (float, optional, default: -1) – Threshold \(\epsilon\) such that the algorithm terminates successfully when \(\|m-m_{obs}\|_{\mathbf{R}^{-1}}^2<\epsilon\). If has a negative value, this termination criteria is not considered as \(\|m-m_{obs}\|_{\mathbf{R}^{-1}}^2\) is always positive.

  • s_init (ndarray, optional, default: None) – Value for the control \(s_0\) used as starting point of the iterative optimization algorithm. If no initial value are provided, the optimization algorithm starts with \(s_0=0\).

  • options (dict, optional, default: {}) – Dictionary containing several options to customize the optimization method.

  • path_save (str or None, optional, default: None) – Path to the folder in which the results are saved. If None, the results are not saved.

  • restart_flag (bool, optional, default: False) – If True, then the optimization algorithm is restarted (hot start) using the results found in the folder which path is given by path_save.

Returns:

  • direct_model (DiffusionConvectionReaction2DEquation) – The pheromone propagation model with the optimal source term.

  • j_obs (ndarray) – The values of the observation term \(\|m\left(c(s)\right)-m_{obs}\|_{\mathbf{R}^{-1}}^2\) at each iterations of the optimization process.

  • j_reg (dic of ndarray) – The dictionnary containing the values of the regularization terms \(j_{reg,i}\) at each iterations of the optimization process.

  • s_a (ndarray) – The optimal value of the control.

Raises:

  • ValueError – If the directory corresponding to the given path and needed to restart the optimization process does not exist.

  • ValueError – If one of the files needed to restart the optimization process does not exist in the given directory.

  • ValueError – If method is ‘L-BFGS-B’ or ‘gradient descent’ and the cost function has a LASSO or group-LASSO regularization term, making the cost function non-differentiable.

  • ValueError – If method is ‘proximal gradient’ and no LASSO or group LASSO regularization terms are present, making the cost function differentiable.

  • ValueError – If method is not the keyword of one of the implemented methods (‘gradient descent’, ‘proximal gradient’, ‘L-BFGS-B’).

modify_weight_reg(regularization_type, alpha)[source]

Modify the weight coefficient \(\alpha_{reg,i}\) for a given type of regularization term \(j_{reg,i}\).

Parameters:

  • regularization_type (string) – The keyword of the type of regularization whose weigth coefficient needs to be changed.

  • alpha (float) – The new value of the weight coefficient \(\alpha_{reg,i}\).

Raises:

  • ValueError – if the keyword of the type of regularization terms whose weigth coefficient needs to be changed is not in the list of the keywords of the implemented type of regularization terms.

  • ValueError – if the keyword of the type of regularization terms whose weigth coefficient needs to be changed is not in the list of the keywords of the type of regularization terms considered.

Notes

If the new value of the weight coefficient is 0 (\(\alpha_{reg,i}=0\)), then the regularization term is removed.

objectif()[source]

Evaluate the cost objectif function

\[J(s,m) =\|m-m_{obs}\|_{\mathbf{R}^{-1}}^2 + \sum_{i} \alpha_{reg,i} j_{reg,i}(s)\]

for the current value of the control \(s\) and of the observed variable \(m\)

Call the methods obs_cost() and reg_cost() and update the attribute j accordingly.

obs_cost()[source]

Compute the observation term \(\|m\left(c(s)\right)-m_{obs}\|_{\mathbf{R}^{-1}}^2\) of the cost function and update the attribute j_obs accordingly.

Raises:

ValueError – if the observed variable has not been estimated.

reg_cost()[source]

Compute the regularization terms \(j_{reg,i}\) of the cost function and update the attribute j_reg accordingly.

Raises:

ValueError – if a regularization term is considered but can not be computed due to parameters with incorrect or missing parameters.

reg_proximal_operator(s, lam)[source]

Evaluate the proximal operator \(prox_\lambda\) of the non-differentiable part objectif function \(J(s,m) =\|m-m_{obs}\|_{\mathbf{R}^{-1}}^2 + \sum_{i} \alpha_{reg,i} j_{reg,i}(s)\) for a given value of the control variable \(s\) and a given parameter of the proximal operator \(\lambda\).

Parameters:

  • s (ndarray) – The value of the control variable \(s\) in which the proximal operator is evaluated.

  • lam (float) – The parameter of the proximal operator \(\lambda\).

Returns:

prox – The evaluation of the proximal operator raveled into a vector.

Return type:

ndarray

Notes

For now, only one non-differentiable regularization term can be considered at a time.

Raises:

ValueError – if no regularization terms are non-differentiable.

remove_reg(regularization_type)[source]

Remove a regularization term \(j_{reg,i}\) from the cost function \(j\).

The addition of a regularization term is done in the following steps:

  • update the attribute regularization_types by removing the keyword of the type of regularization to remove,

  • update the attribute alpha by deleting the keyword and the associated weight coefficient,

  • update the attribute j_reg by deleting the keyword and the associated value of \(j_{reg,i}\).

Parameters:

regularization_type (string) – The keyword of the type of regularization to remove.

Raises:

ValueError – if the keyword of the type of regularization terms to remove is not in the list of the keywords of the implemented type of regularization terms.

Notes

If the regularization term to remove was not considered, then the method does nothing.