qlat_utils¶

Qlattice utility package

Usage:

import qlat_utils as q

Will also be loaded by import qlat as q together with other qlat functions.

Message¶

`get_verbose_level`()	Return the current verbosity level as integer.
`set_verbose_level`([level])	Set the current verbosity level as integer.
`displayln`(level, *args)	Print all the arguments and then print a newline.
`displayln_info`(*args)	Same as `displayln` but only print if `get_id_node() == 0`.
`get_fname`()	Return the function name of the current function `fname`

Timer¶

`timer`(func)	Timing functions.
`timer_verbose`(func)	Timing functions.
`timer_flops`(func)	Timing functions with flops.
`timer_verbose_flops`(func)	Timing functions with flops.
`timer_display`(unicode tag=u)
`timer_display_stack`()
`timer_fork`(...)
`timer_merge`()
`get_time`()	Return current time in seconds since epoch.
`get_start_time`()	Return start time in seconds since epoch.

Random number¶

`RngState`([x, y])
`get_data_sig`(x, RngState rs)	Return a signature (a floating point number, real or complex) of data viewed as a 1-D array of numbers.

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¶

`rel_mod`(x, size)	Return `x % size` or `x % size - size`
`rel_mod_sym`(x, size)	Return `x % size` or `x % size - size` or `0`
`rel_mod_arr`(x, size)	Return `x % size` or `x % size - size` where `x` and `size` are np.array of same shape
`rel_mod_sym_arr`(x, size)	Return `x % size` or `x % size - size` or `0` where `x` and `size` are np.array of same shape
`Coordinate`
`Coordinate.to_list`()	Return a list composed of the 4 components of the coordinate.
`Coordinate.to_tuple`()	Return a tuple composed of the 4 components of the coordinate.
`Coordinate.to_numpy`()	Return a np.ndarray composed of the 4 components of the coordinate.
`Coordinate.from_list`(x)	set value based on a list composed of the 4 components of the coordinate.
`Coordinate.sqr`()	Return the square sum of all the components as `cc.Long`.
`Coordinate.r_sqr`()	get spatial distance square as int
`Coordinate.volume`()	get product of all components
`Coordinate.spatial_volume`()	get product of all components
`Coordinate.from_index`(index, size)
`Coordinate.to_index`(size)
`CoordinateD`
`CoordinateD.to_list`()	Return a list composed of the 4 components of the coordinate.
`CoordinateD.to_tuple`()	Return a tuple composed of the 4 components of the coordinate.
`Coordinate.to_numpy`()	Return a np.ndarray composed of the 4 components of the coordinate.
`Coordinate.from_list`(x)	set value based on a list composed of the 4 components of the coordinate.

Cache system¶

`Cache`(*keys)
`mk_cache`(*keys[, ca])	make cache if it does not exist, otherwise return existing elements
`clean_cache`([ca])	Remove values of cache, but keep all the structures
`list_cache`([ca])
`rm_cache`(*keys[, ca])	remove cache if it exist
`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¶

`WilsonMatrix`
`SpinMatrix`
`ColorMatrix`
`get_gamma_matrix`(int mu)
`wilson_matrix_g5_herm`(WilsonMatrix x)
`mat_tr_sm`(SpinMatrix v)
`mat_tr_cm`(ColorMatrix v)
`mat_tr_wm`(WilsonMatrix v)
`mat_tr_wm_wm`(WilsonMatrix v1, WilsonMatrix v2)
`mat_tr_wm_sm`(WilsonMatrix v1, SpinMatrix v2)
`mat_tr_sm_wm`(SpinMatrix v1, WilsonMatrix v2)
`mat_tr_sm_sm`(SpinMatrix v1, SpinMatrix v2)
`mat_tr_wm_cm`(WilsonMatrix v1, ColorMatrix v2)
`mat_tr_cm_wm`(ColorMatrix v1, WilsonMatrix v2)
`mat_tr_cm_cm`(ColorMatrix v1, ColorMatrix v2)
`mat_mul_wm_wm`(WilsonMatrix v1, WilsonMatrix v2)
`mat_mul_wm_sm`(WilsonMatrix v1, SpinMatrix v2)
`mat_mul_sm_wm`(SpinMatrix v1, WilsonMatrix v2)
`mat_mul_sm_sm`(SpinMatrix v1, SpinMatrix v2)
`mat_mul_wm_cm`(WilsonMatrix v1, ColorMatrix v2)
`mat_mul_cm_wm`(ColorMatrix v1, WilsonMatrix v2)
`mat_mul_cm_cm`(ColorMatrix v1, ColorMatrix v2)
`as_wilson_matrix`(x)
`as_wilson_matrix_g5_herm`(x)

ElemType¶

`ElemType`
`ElemTypeInt8t`
`ElemTypeInt32t`
`ElemTypeInt64t`
`ElemTypeChar`
`ElemTypeInt`
`ElemTypeLong`
`ElemTypeRealD`
`ElemTypeRealF`
`ElemTypeComplexD`
`ElemTypeComplexF`
`ElemTypeSpinMatrix`
`ElemTypeWilsonMatrix`
`ElemTypeColorMatrix`
`ElemTypeIsospinMatrix`
`ElemTypeNonRelWilsonMatrix`
`ElemTypeWilsonVector`

Data analysis¶

get_chunk_list(total_list, *[, chunk_size, ...])

Split total_list into chunk_number chunks or chunks with chunk_size. One (and only one) of chunk_size and chunk_number should not be None. # Returns a list of chunks. Number of chunks is less or equal to chunk_number. Chunk sizes are less or equal to chunk_size. if rng_state is None: Do not randomly permute the list.

Spatial distance list¶

`mk_r_sq_list`(r_sq_limit[, dimension])
`mk_r_list`(r_limit, *[, r_all_limit, ...])	Make a list of r values from 0 up to r_limit.
`mk_interp_tuple`(x, x0, x1, x_idx)	Returns (x_idx_low, x_idx_high, coef_low, coef_high,)
`mk_r_sq_interp_idx_coef_list`(r_list)	Return a list of tuples:

Jackknife method¶

`g_jk`(data_list, , eps, *_kwargs)	Perform initial Jackknife for the original data set.
`g_rejk`(jk_list, jk_idx_list, *, jk_type, ...)	Perform (randomized) Super-Jackknife for the Jackknife data set.
`g_mk_jk_val`(rs_tag, val, err, *, jk_type, ...)	Create a jackknife sample with random numbers based on central value `val` and error `err`.
`g_jk_avg`(jk_list)	Return `avg` of the `jk_list`.
`g_jk_err`(jk_list, , eps, jk_type, *_kwargs)	Return `err` of the `jk_list`.
`g_jk_avg_err`(jk_list, **kwargs)	Return `(avg, err,)` of the `jk_list`.
`g_jk_size`(**kwargs)	Return number of samples for the (randomized) Super-Jackknife data set.
`g_jk_blocking_func`(idx, *, jk_blocking_func, ...)	Return `jk_blocking_func(idx)`.

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

#!/usr/bin/env python3

import qlat as q
import numpy as np
import functools

q.begin_with_mpi()

q.default_g_jk_kwargs["jk_type"] = "rjk"
q.default_g_jk_kwargs["n_rand_sample"] = 1024
q.default_g_jk_kwargs["rng_state"] = q.RngState("rejk")
q.default_g_jk_kwargs["jk_blocking_func"] = None
q.default_g_jk_kwargs["is_normalizing_rand_sample"] = True

@functools.lru_cache
def get_trajs(job_tag):
    return list(range(25))

rs = q.RngState("seed")
job_tag = "test1"
trajs = get_trajs(job_tag)

data_arr = rs.g_rand_arr((len(trajs), 5,)) # can be list or np.array
jk_arr = q.g_jk(data_arr)
jk_idx_list = [ "avg", ] + [ (job_tag, traj) for traj in trajs ]
jk_arr = q.g_rejk(jk_arr, jk_idx_list)
avg, err = q.g_jk_avg_err(jk_arr)

q.displayln_info(f"CHECK: {avg}")
q.displayln_info(f"CHECK: {err}")

json_results = []
check_eps = 1e-10

for i in range(len(avg)):
    json_results.append((f"avg[{i}]", avg[i],))
for i in range(len(avg)):
    json_results.append((f"err[{i}]", err[i],))

q.check_log_json(__file__, json_results)

q.end_with_mpi()

q.displayln_info(f"CHECK: finished successfully.")

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

#!/usr/bin/env python3

import qlat as q
import numpy as np
import functools

q.begin_with_mpi()

job_tags = [ 'test1', 'test2', ]

q.default_g_jk_kwargs["jk_type"] = "super"
@functools.lru_cache
def get_all_jk_idx():
    jk_idx_list = [ 'avg', ]
    for job_tag in job_tags:
        trajs = get_trajs(job_tag)
        for traj in trajs:
            jk_idx_list.append((job_tag, traj,))
    return jk_idx_list
q.default_g_jk_kwargs["get_all_jk_idx"] = get_all_jk_idx

@functools.lru_cache
def get_trajs(job_tag):
    return list(range(25))

rs = q.RngState("seed")
job_tag = "test1"
trajs = get_trajs(job_tag)

data_arr = rs.g_rand_arr((len(trajs), 5,)) # can be list or np.array
jk_arr = q.g_jk(data_arr)
jk_idx_list = [ "avg", ] + [ (job_tag, traj) for traj in trajs ]
jk_arr = q.g_rejk(jk_arr, jk_idx_list)
avg, err = q.g_jk_avg_err(jk_arr)

q.displayln_info(f"CHECK: {avg}")
q.displayln_info(f"CHECK: {err}")

json_results = []
check_eps = 1e-10

for i in range(len(avg)):
    json_results.append((f"avg[{i}]", avg[i],))
for i in range(len(avg)):
    json_results.append((f"err[{i}]", err[i],))

q.check_log_json(__file__, json_results)

q.end_with_mpi()

q.displayln_info(f"CHECK: finished successfully.")

Plotting¶

`plot_save`([fn, dts, cmds, lines, ...])	fn is full name of the plot or None dts is dict_datatable, e.g. { "table.txt" : [ [ 0, 1, ], [ 1, 2, ], ], } cmds is plot_cmds, e.g. [ "set key rm", "set size 1.0, 1.0 ", ] lines is plot_lines, e.g. [ "plot", "x", ].
`plot_view`([fn, dts, cmds, lines, ...])

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

#!/usr/bin/env python3

import numpy as np
import qlat as q

q.begin_with_mpi()

q.qremove_all_info("results")
q.qmkdir_info("results")

q.qplot.plot_save_display_width = 500

x = np.arange(31) * (6 / 30) - 3
y = np.cos(x)
yerr = 0.1 / (1 + x**2)
dts = {
    "table.txt": q.azip(x, y, yerr),
}

if q.get_id_node() == 0:
    q.plot_save(
        fn = "results/plot.png",
        dts = dts,
        cmds = [
            "set size 0.8, 1.0",
            "set key tm",
            "set xlabel '$x$'",
            "set ylabel '$y$'",
        ],
        lines = [
            "plot [-3:3] [-1.5:1.5]",
            "0 not",
            "sin(x) w l t '$y = \\sin(x)$'",
            "'table.txt' w yerrorb t '$y = \\cos(x)$'",
        ],
    )

q.timer_display()

q.end_with_mpi()

q.displayln_info(f"CHECK: finished successfully.")