source_localization package

Submodules

source_localization.adjoint_convection_diffusion_2D module

class source_localization.adjoint_convection_diffusion_2D.AdjointDiffusionConvectionReaction2DEquation(U, K, coeff_depot, msh, time_discretization='semi-implicit', tol_inversion=1e-14)[source]

Bases: object

Class containing the adjoint model of the 2D diffusion-convection-reaction PDE model and its solvers

__init__(U, K, coeff_depot, msh, time_discretization='semi-implicit', tol_inversion=1e-14)[source]

Instanciation of the class.

  • input:

    • msh: object of the class mesh_rect_2D

    • U: object of the class velocity

    • K: object of the class diffusion_tensor

    • coeff_depot: array of shape (msh.y, msh.x) containing the deposition coefficient

    • obs: object of the class Obs, contains the observation operator and its derivative wrt the state variable

    • msh: object of the class mesh_rect_2D

    • time_discretization:

      string, describes the type of time discretization by default is ‘semi-implicit’, can also be ‘implicit’

  • attributes:

    • msh: object of the class mesh_rect_2D

    • A: object of the class Advection, if the time discretization is semi-implicit, contains the convection linear operator

    • A_adjoint:

      object of the class Advection, if the time discretization is implicit, contains the adjoint of the convection linear operator

    • D: oject of the class Diffusion, contains the diffusion linear operator

    • R: object of the class Reaction, contains the reaction linear operator

    • ID: object of the class Id, contains the identity operator

    • obs: object of the class Obs, contains the observation operator and its derivative wrt the state variable

    • negative_divU_advection_term:

      object of the class Reaction, if the time discretization is semi-implicit, contains negative part of the reaction term in div U coming from the splitting of the adjoint of the advection term into a advection flux part and a reaction part

    • positive_divU_advection_term:

      object of the class Reaction, if the time discretization is semi-implicit, contains positive part of the reaction term in div U coming from the splitting of the adjoint of the advection term into a advection flux part and a reaction part

    • time_discretization: string, describes the type of time discretization

at_current_time(tc)[source]

Update the linear operators of the PDE at a given time, i.e. update the attributes D and S of the class if the time discretization is semi-implicit, A, positive_divU_advection_term, negative_divU_advection_term, if the time discretization is implicit, A_adjoint, and the derivative of the observation operator of the attribute obs.

  • input:

    • tc: the current time

init_inverse_matrix(path_to_matrix=None, matrix_file_name=None)[source]
solver(adjoint_derivative_obs_operator, cost, display_flag=True)[source]

solve the PDE on the whole time window

  • input:
    • cost:

      object of the class Cost, contains especially a method that compute the gradient of the objectif wrt the observed variable for the current optimization iteration and estimation of the observed variable

    • display_flag: boolean, True by default, print the evolution in time of the solver if True

  • output:
    • p:

      numpy array of shape (msh.t_array.size * msh.y.size * msh.x.size,), contains the adjoint state everywhere and at all time step concatenated in a vector

source_localization.control module

class source_localization.control.Control(background_source, msh, exclusion_domain=None, log_barrier_threshold=1e-10, population_dynamique_death_rate=None)[source]

Bases: object

Class containing the control, its current and background value, and the background error covariance matrix

__init__(background_source, msh, exclusion_domain=None, log_barrier_threshold=1e-10, population_dynamique_death_rate=None)[source]

Instanciation of the class.

  • TO DO:

    • add exceptions in case the death rate is not defined

  • input:

    • background_source: object of the class Source, contains the background value of the source term

    • msh: object of the class MeshRect2D

  • attributes:
    • background_value:

      array of shape (t.size * msh.y.size * msh.x.size,), contains the background value of the source term the background values of control each time step of the direct model are concatenated

    • value:

      array of shape (t.size * msh.y.size * msh.x.size,), contains the current value of the control and is initialized with the background value

    • C_inv:

      array of shape (t.size * msh.y.size * msh.x.size, t.size * msh.y.size * msh.x.size), contains inverse of the background error covariance matrix, by default the identity

apply_control(direct_model)[source]

apply the current value of the control to an direct model

  • input:

    • direct_model: object of the class DiffusionConvectionReaction2DEquation, contains the direct model

  • do:

    • set the source terme of direct_model as the current value of the control

set_C_inv_to_id_on_initial_time(msh)[source]

source_localization.cost module

source_localization.gradient_descent module

source_localization.gradient_descent.gradient_descent(fun, x0, args=(), options=None, callback=None, f_old=numpy.inf)[source]

Mininize a function using the gradient descent method

  • input:

    • fun: callable, method that given an x return the evaluation in x of the function to minimize and its gradient

    • x0: the initial point from which the iterative optimization algorithm will starts

    • args: tuple, arguments that should be given to the callable fun besides x

    • options:

      dictionnary, by default None, contains several options that can be given to customize the gradient descent method and its stopping criteria these options are: the step size, or learning rate, of the gradient descent ‘step size’, constant for now, by default step_size=1 the maximal number of iteration ‘nit_max’, by default nit_max=50, the tolerance on two consecutive evaluation of the function to minimize ‘ftol’, by default ftol=1e-7, the tolerance on the gradient ‘gtol, by default gtol=1e-7.

    • callback: A AJOUTER

    • f_old:

      float, by default np.inf, if the optimization processe is restarted, enable to store the previous value of the cost function

  • output:

    • the optimal value of x

    • the evaluation of the function to minimize at the optimal value of x

    • the evaluation of the gradient of the function to minimize at the optimal value of x

    • the number of iteration needed to converge

  • TO DO:

    • ameliorer le critere d arret

    • ameliorer la doc

    • ajouter exception pour vérifier que les types en entrees sont les bons

source_localization.obs module

class source_localization.obs.Obs(t_obs, X_obs, d_obs, msh, index_sensor=None, dt_obs_operator=0.0)[source]

Bases: object

Class containing: - the observations: its value, the time and space location of the observations, - the corresponding estimation of the observed variable (accumulation of pheromone over a time window) computed by the direction model - the observations error covariance matrix - the observation operator and the adjoint operator of its derivative with respect of the state variable

__init__(t_obs, X_obs, d_obs, msh, index_sensor=None, dt_obs_operator=0.0)[source]

Instanciation of the class.

  • TO DO:

    • update the documentation and comments for the new observation operator

    • add an exception to make sure that the accumulation time window does not overlapp for a given sensor

    • add an exception to make sure that no observations are made after

  • input:

    • t_obs: array of the shape (N_obs,), contains the observations times

    • X_obs: array of the shape (N_obs,2), contains the locations of the observations

    • d_obs: array of the shape (N_obs,), contains the values of the observations

    • msh: object of the class MeshRect2D

  • attributes:

    • msh: object of the class MeshRect2D

    • t_obs: array of the shape (N_obs,), contains the observations times

    • X_obs: array of the shape (N_obs,2), contains the locations of the observations

    • d_obs: array of the shape (N_obs,), contains the values of the observations

    • N_obs: int, contains the number of observations

    • X_sensors: array of tuple, contains the position of the sensors

    • nb_sensors: int, contains the number of sensors

    • dt_obs_operator: float, contains the length of the time window of accumulation

    • nb_dt_in_obs_time_window: int, contains the number of time steps covering the time window of accumulation

    • c_est:

      array of the shape (N_obs, nb_dt_in_obs_time_window), contains the estimation of the state variable (concentration) computed by the direct model at the time and space location required to estimate the observed variable at the time and space location of the observations

    • d_est:

      array of the shape (N_obs,), contains the estimation of the observed variable (accumulation of pheromone) computed by the direct model at the time and space location of the observations

    • R_inv:

      array of shape (N_obs, N_obs), contains the inverse of the observations error covariance matrix, by default the identity

    • index_obs_to_index_time_est:

      array of shape (N_obs, nb_dt_in_obs_time_window), contains the indexes of the times at which the state variable is required to compute the observation variable given the index of an observation

    • index_time_est_to_index_obs:

      dictionnary, for a time as key, contains the array of index of the observations that require the estimate of the state variable at this time to estimate the observed variable

adjoint_derivative_obs_operator(t, delta_c)[source]

compute the spatial map of the adjoint of the derivative of the observation operator with respect to the state variable at a given time

  • input:

    • t: the current time

    • delta_c: numpy array of shape (N_obs, ), element of the space of the concentration (state variable)

  • output:
    • numpy array of shape (msh.x.size*msh.y.size, ),

      evaluation of the adjoint of the derivative of the observation operator in delta_c

obs_operator()[source]

the observation operator i.e. integration of the state variable of the direct model over the time window [t_obs-dt_obs_operator; t_obs] assuming that the integration time window for different data of a same sensor are not overlapping

  • do:

    • compute an estimation of the observed variable given an estimation of the state variable of the direct model

    • store the estimation of the observed variable in the attribute d_est

onesensor_adjoint_derivative_obs_operator(t, delta_c, index_sensor)[source]

compute the spatial map of the adjoint of the derivative of the observation operator with respect to the state variable at a given time

  • input:

    • t: the current time

    • delta_c: numpy array of shape (N_obs, ), element of the space of the concentration (state variable)

    • index_sensor:

      int, index of the sensor to consider in the solving the one-sensor adjoint model

  • output:
    • numpy array of shape (msh.x.size*msh.y.size, ),

      evaluation of the adjoint of the derivative of the observation operator in delta_c

source_localization.population_dynamique module

class source_localization.population_dynamique.PopulationDynamicModel(*args: Any, **kwargs: Any)[source]

Bases: LinearOperator

Class containing the time derivative operator of the control Subclass of the scipy.sparse.linalg.LinearOperator class, see https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.linalg.LinearOperator.html

__init__(msh, death_rate=0.1)[source]

Instanciation of the class.

  • input:

  • attributes:

    • shape: tuple of integers, shape of the matrix of the linear operator

    • dtype: data type object, data type of the element of the matrix of the linear operator

_matvec(x_out)[source]

Compute the image (matrix-vector product) of the time derivative operator for a given vector of source

  • input:
    • x_out:

      numpy array of shape (msh.x.size*msh.y.size*msh.t_array.size, ), contains the source raveled into a vector to match the format of the LinearOperator class

  • output:
    • numpy array of shape (msh.x.size*msh.y.size*msh.t_array.size, ),

      the image of the time derivative operator for a given source

_rmatvec(x_out)[source]

Compute the image (matrix-vector product) of the adjoint of the time derivative operator for a given vector of source

  • input:
    • x_out:

      numpy array of shape (msh.x.size*msh.y.size*msh.t_array.size, ), contains the source raveled into a vector to match the format of the LinearOperator class

  • output:
    • numpy array of shape (msh.x.size*msh.y.size*msh.t_array.size, ),

      the image of the adjoint of the time derivative operator for a given source

class source_localization.population_dynamique.StationnaryPopulationDynamicModel(*args: Any, **kwargs: Any)[source]

Bases: LinearOperator

Class containing the time derivative operator of the control Subclass of the scipy.sparse.linalg.LinearOperator class, see https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.linalg.LinearOperator.html

__init__(msh)[source]

Instanciation of the class.

  • input:

  • attributes:

    • shape: tuple of integers, shape of the matrix of the linear operator

    • dtype: data type object, data type of the element of the matrix of the linear operator

_matvec(x_out)[source]

Compute the image (matrix-vector product) of the time derivative operator for a given vector of source

  • input:
    • x_out:

      numpy array of shape (msh.x.size*msh.y.size*msh.t_array.size, ), contains the source raveled into a vector to match the format of the LinearOperator class

  • output:
    • numpy array of shape (msh.x.size*msh.y.size*msh.t_array.size, ),

      the image of the time derivative operator for a given source

_rmatvec(x_out)[source]

Compute the image (matrix-vector product) of the adjoint of the time derivative operator for a given vector of source

  • input:
    • x_out:

      numpy array of shape (msh.x.size*msh.y.size*msh.t_array.size, ), contains the source raveled into a vector to match the format of the LinearOperator class

  • output:
    • numpy array of shape (msh.x.size*msh.y.size*msh.t_array.size, ),

      the image of the adjoint of the time derivative operator for a given source

source_localization.proximal_gradient module

source_localization.proximal_gradient.proximal_gradient(x0, fun1, proximal_fun2, args=(), options=None, callback=None)[source]

Uses accelerated proximal gradient (FISTA) to solve : argmin f(x) + g(x) with f a differentiable function and g a fonction whose proximal operator is known in the present context : f is the L2 norm terms of the cost function (cost of the observations and Tikhonov regularization terms) g is the L1 norm / LASSO regularization term

  • input:

    • x0: the initial point from which the iterative optimization algorithm will starts

    • fun1: callable, method that given an x return the evaluation of the differentiable function f and its gradient

    • proximal_fun2: callable, method that given an x return the evaluation of proximal operator of the function g

    • algorithm: string, by default ‘ISTA’, the type of algorithm used, ISTA and FISTA are implemented

    • args: tuple, arguments that should be given to the callable fun1 besides x

    • options:

      dictionnary, by default None, contains several options that can be given to customize the gradient descent method and its stopping criteria these options are: the step size of the gradient descent by default step_size=1, for FISTA, should be 1/L with L the Lipschitz constant the maximal number of iteration ‘nit_max’, by default nit_max=50, the tolerance on two consecutive evaluation of the function to minimize ‘ftol’, by default ftol=1e-7, the tolerance on the gradient ‘gtol, by default gtol=1e-7.

    • callback: A AJOUTER

  • output:

    • the optimal value of x

    • the evaluation of the function f at the optimal value of x

    • the evaluation of the gradient of the function f at the optimal value of x

    • the number of iteration needed to converge

Module contents