qlat_utils
==========

.. automodule:: qlat_utils
   :members:

Message
-------

.. autosummary::
   :toctree: generated
 
   get_verbose_level
   set_verbose_level

   displayln
   displayln_info

   get_fname

Timer
-----

.. autosummary::
   :toctree: generated

   timer
   timer_verbose
   timer_flops
   timer_verbose_flops

   timer_display
   timer_display_stack

   timer_fork
   timer_merge

   get_time
   get_start_time

Random number
-------------

.. autosummary::
   :toctree: generated

   RngState
   get_data_sig

Algorithm of the random number generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The state of the generator is effectively composed of the history of the generator encoded as a string.

To generate random numbers, one computes the SHA-256 hash of the string.  The hash result is viewed as a `8` 32-bit unsigned integers.

The ``8`` 32-bit unsigned integers are merged into ``4`` 64-bit unsigned integers. These ``4`` numbers are treated as the random numbers generated by this random number generator.

Relevant source files: ``qlat-utils/include/qlat-utils/rng-state.h`` and ``qlat-utils/lib/rng-state.cpp``

Coordinate
----------

.. autosummary::
   :toctree: generated

   rel_mod
   rel_mod_sym

   rel_mod_arr
   rel_mod_sym_arr

   Coordinate
   Coordinate.to_list
   Coordinate.to_tuple
   Coordinate.to_numpy
   Coordinate.from_list
   Coordinate.sqr
   Coordinate.r_sqr
   Coordinate.volume
   Coordinate.spatial_volume
   Coordinate.from_index
   Coordinate.to_index

   CoordinateD
   CoordinateD.to_list
   CoordinateD.to_tuple
   Coordinate.to_numpy
   Coordinate.from_list

Cache system
------------

.. autosummary::
   :toctree: generated

   Cache
   mk_cache
   clean_cache
   list_cache
   rm_cache
   get_all_caches_info
   clear_all_caches

Example code::

    Usage:
    cache_x = q.mk_cache("xx")
    q.clean_cache(cache_x)
    cache_x[key] = value
    val = cache_x[key]
    key in cache_x
    val = cache_x.get(key)
    val = cache_x.pop(key, None)

Matrix for QCD
--------------

.. autosummary::
   :toctree: generated

   WilsonMatrix
   SpinMatrix
   ColorMatrix

   get_gamma_matrix
   wilson_matrix_g5_herm
   mat_tr_sm
   mat_tr_cm
   mat_tr_wm
   mat_tr_wm_wm
   mat_tr_wm_sm
   mat_tr_sm_wm
   mat_tr_sm_sm
   mat_tr_wm_cm
   mat_tr_cm_wm
   mat_tr_cm_cm
   mat_mul_wm_wm
   mat_mul_wm_sm
   mat_mul_sm_wm
   mat_mul_sm_sm
   mat_mul_wm_cm
   mat_mul_cm_wm
   mat_mul_cm_cm

   as_wilson_matrix
   as_wilson_matrix_g5_herm

ElemType
--------

.. autosummary::
   :toctree: generated

   ElemType
   ElemTypeInt8t
   ElemTypeInt32t
   ElemTypeInt64t
   ElemTypeChar
   ElemTypeInt
   ElemTypeLong
   ElemTypeRealD
   ElemTypeRealF
   ElemTypeComplexD
   ElemTypeComplexF

   ElemTypeSpinMatrix
   ElemTypeWilsonMatrix
   ElemTypeColorMatrix
   ElemTypeIsospinMatrix
   ElemTypeNonRelWilsonMatrix
   ElemTypeWilsonVector

Data analysis
-------------

.. autosummary::
   :toctree: generated

   get_chunk_list

Spatial distance list
^^^^^^^^^^^^^^^^^^^^^

.. autosummary::
   :toctree: generated

   mk_r_sq_list
   mk_r_list
   mk_interp_tuple
   mk_r_sq_interp_idx_coef_list

Jackknife method
^^^^^^^^^^^^^^^^

.. autosummary::
   :toctree: generated

   g_jk
   g_rejk
   g_mk_jk_val
   g_jk_avg
   g_jk_err
   g_jk_avg_err
   g_jk_size
   g_jk_blocking_func

Example for the random Super-Jackknife method: ``examples-py/jackknife-random.py``

.. literalinclude:: ../examples-py/jackknife-random.py

Example for the conventional Super-Jackknife method: ``examples-py/jackknife-super.py``

.. literalinclude:: ../examples-py/jackknife-super.py

Plotting
^^^^^^^^

.. autosummary::
   :toctree: generated

   plot_save
   plot_view

Example code to make a plot: ``examples-py/qplot.py``

.. literalinclude:: ../examples-py/qplot.py