dft_tools/doc/reference/determinant_manipulation/det_manip.rst

.. highlight:: c

The det_manip class
====================

Parameter & construction
------------------------

The template parameter is the **FunctionType**, the type of F,
which is completely general but has to model the concept

  * return_type: type returned by the function 
  * argument_type: type of the argument of the function (type of x and y).


Public types
-------------

+------------------+-----------------------------+
| name             | description                 |
+==================+=============================+
| xy_type          | ?                           |
+------------------+-----------------------------+
| value_type       | ?                           |
+------------------+-----------------------------+
| vector_type      | tqa::vector<value_type>     |
+------------------+-----------------------------+
| matrix_type      | tqa::matrix<value_type>     |
+------------------+-----------------------------+
| matrix_view_type | tqa::matrix_view<value_type |
+------------------+-----------------------------+


Public member functions
-----------------------

+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| return type                                   | member function                                                                                                                      | description                                                                                                                                                                |
+===============================================+======================================================================================================================================+============================================================================================================================================================================+
|                                               | det_manip(FunctionType F, size_t init_size)                                                                                          | constructor                                                                                                                                                                |
+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|                                               | det_manip(FunctionType F, ArgumentContainer1 const &X, ArgumentContainer2 const &Y)                                                  | constructor                                                                                                                                                                |
+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|                                               | det_manip(det_manip const &)                                                                                                         | constructor                                                                                                                                                                |
+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|                                               | det_manip(det_manip &&rhs) noexcept                                                                                                  | constructor                                                                                                                                                                |
+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| det_manip &                                   | operator=(const det_manip &)                                                                                                         |                                                                                                                                                                            |
+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| det_manip &                                   | operator=(det_manip && rhs) no except                                                                                                | ?                                                                                                                                                                          |
+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                          | clear()                                                                                                                              | put to size 0 (like a vector)                                                                                                                                              |
+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| size_t                                        | size() const                                                                                                                         | current size of the matrix                                                                                                                                                 |
+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| xy_type const &                               | get_x(size_t i) const                                                                                                                | returns the i-th values of x                                                                                                                                               |
+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| xy_type const &                               | get_y(size_t j) const                                                                                                                | returns the j-th values of y                                                                                                                                               |
+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| value_type                                    | determinant() const                                                                                                                  | determinant                                                                                                                                                                |
+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| value_type                                    | inverse_matrix(size_t i, size_t j) const                                                                                             | ?                                                                                                                                                                          |
+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| matrix_view_type                              | inverse_matrix() const                                                                                                               | Returns the inverse matrix. Warning: this is slow, since it create a new copy, and reorder the lines/cols.                                                                 |
+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| matrix_view_type                              | matrix() const                                                                                                                       | Rebuild the matrix. Warning: this is slow, since it create a new matrix and re-evaluate the function.                                                                      |
+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| value_type                                    | try_insert(size_t i, size_t j, xy_type const &x, xy_type const &y)                                                                   | returns determinant ratio corresponding to the insertion of an element x-y on line i, column j without actually doing it. In particular, does not change determinant size. |
+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| template<typename Fx, typename Fy> value_type | try_insert_from_function (size_t i, size_t j, Fx fx, Fy fy, value_type const ksi)                                                    | ?                                                                                                                                                                          |
+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| value_type                                    | try_insert2 (size_t i0, size_t i1, size_t j0, size_t j1, xy_type const &x0, xy_type const &x1, xy_type const &y0, xy_type const &y1) | ?                                                                                                                                                                          |
+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| value_type                                    | try_remove (size_t i, size_t j)                                                                                                      | ?                                                                                                                                                                          |
+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| value_type                                    | try_remove2 (size_t i0, size_t i1, size_t j0, size_t j1)                                                                             | ?                                                                                                                                                                          |
+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| value_type                                    | try_change_col (size_t j, xy_type const &y)                                                                                          | ?                                                                                                                                                                          |
+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| value_type                                    | try_change_row (size_t i, xy_type const &x)                                                                                          | ?                                                                                                                                                                          |
+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                          | complete_operation()                                                                                                                 | ?                                                                                                                                                                          |
+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| int                                           | roll_matrix (RollDirection roll)                                                                                                     | ?                                                                                                                                                                          |
+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

Synopsis
-----------

* The possible operations on the matrix M are: 

+------------+--------------------------------+
| Operation  | Effect                         |
+============+================================+
| insert     | adding a line and a column     |
+------------+--------------------------------+
| remove     | removing a line and a column   |
+------------+--------------------------------+
| insert2    | adding 2 lines and 2 columns   |
+------------+--------------------------------+
| remove2    | removing 2 lines and 2 columns |
+------------+--------------------------------+
| change_col | changing one *y*               |
+------------+--------------------------------+
| change_raw | changing one *x*               |
+------------+--------------------------------+


* Each operation *OP* is called in two steps: 

  * 
    .. code-block:: c

       value_type try_OP(arguments ...) 

    Returns the ratio 

    .. math:: \frac{det M'}{det M}

    where M' would be the matrix after the operation is completed.

    try_OP **does NOT** modify the matrix :math:`M`.

  * 
    .. code-block:: c
   
       void complete_operation() 

    Complete the last operation OP (the last called try_OP), by updating the list of x and y 
    and the inverse of the matrix to :math:`(M')^{-1}`.

* This structure is designed to write  Monte Carlo algorithms: 
  
  * the try part of the move calls some try_OP
  * if and only if the move is accepted, is the complete_operation called.

Under the hood ...
-------------------------

* All matrix algebra is made with BLAS calls.

* The storage is done in a compact way: when a column or row is added, 
  no data are shifted, it is added at the end of the matrix.
  However, the permutation of row and columns are handled by this class
  so that this is transparent for the user.


Doxygen documentation
-------------------------

The :doxy:`full C++ documentation<triqs::det_manip::det_manip>` is available here.

Example  
---------

.. triqs_example:: ./det_manip_0.cpp