|
GraceQ/tensor
A high-performance tensor computation framework for the quantum physics community
|
If it isn't fast, it isn't graceful
Note: For a complete list of the contributors, see CONTRIBUTORS.txt
In the following code blocks, if it is available, you can click the class or function name to jump to the detail documentation.
You can always get the latest usable version using git from the default branch on GitHub.
You can also download the release version from release page and uncompress the file to get the source code.
From now on, we suppose the root directory of the GraceQ/tensor source code is gqten. You can use CMake 3.12 or higher version to install it.
Where <your_gqten_installation_root> is the installation root directory which you have write access. For example, ~/.local is a good choice.
GraceQ/tensor depends hptt to perform dense tensor transpose on shared memory computing system and has integrated it at external/hptt. GraceQ/tensor build and install hptt library using the same CMake setting by default. If you want to use external hptt library, set GQTEN_USE_EXTERNAL_HPTT_LIB=ON. the hptt library will also be installed to <your_gqten_installation_root> if GQTEN_USE_EXTERNAL_HPTT_LIB is set to OFF (default value).
GraceQ/tensor also depends Intel's MKL to perform heavy dense vector and matrix numerical calculations on shared memory computing system. So you should also install it before using GraceQ/tensor.
It is easy to use the GraceQ/tensor.
When you compile your program, you can use following compile flags to gain the best performance.
GraceQ/tensor needs hptt and MKL during linking process. So you should use the following statements when you link the library.
We highly recommend that you use MKL Link Line Advisor to set <your_mkl_linking_flags>. A possible complete compiling command may looks like
The central object in GraceQ/tensor is its symmetry-blocked sparse tensor, GQTensor. It is designed as a class template, GQTensor<ElemT, QNT>. The first template parameter ElemT sets the type of the tensor element. Real number(GQTEN_Double) and complex number(GQTEN_Complex) are supported now. The second template parameter QNT (Quantum Number Type) sets the symmetry of the tensor. We will introduce how to define a quantum number later. Up to now, GraceQ/tensor supports the total symmetry \( G_{1} \otimes G_{2} \otimes G_{3} \otimes \cdots \), where \( G_{1} \), \( G_{2} \) ... are global Abelian symmetries the system has. For example, they may be the \( U(1) \) total particle number conservation or \( \mathbb{Z}_{n} \) discrete translational invariant.
The objects in quantum physics, like states and operators, are defined in the Hilbert space. If the system has some symmetry, the Hilbert space of the system will be split as a series of unconnected regions which labeled by quantum number. For example, a plain spinless Fermion tight-binding model keeps the \( U(1) \) total Fermion number \( N \) conservation; a plain Heisenberg model keeps the \( U(1) \) total spin at z direction \( S^{z} \) conservation; a model living on a n circumference cylinder with only nearest neighbor interactions keeps the \( \mathbb{Z}_{n} \) discrete translational invariant. And a system can also keeps several kinds symmetries. For example, a plain \( t \)- \( J \) model keeps \( U(1) \otimes U(1) \) total particle number and total z direction spin conservation.
In GraceQ/tensor, the quantum number value class gqten::QNVal represents a specific symmetry. User can inherit it and define their own symmetry. Only Abelian symmetries are supported now. GraceQ/tensor has offered \( U(1) \) quantum number value gqten::U1QNVal. For example, you can use this class to set a \( U(1) \) quantum number value labeled by the charge n:
The type of total symmetry of the system is represented by gqten::QN which take a series of quantum number value classes as the template parameters to support many symmetries case. For example, we can define the quantum number type as
and create a quantum number with specific name and quantum number value pairs by using gqten::QNCard as
We know the representation of the symmetry (groups) can label a specific linear space (i.e. the representation space). For example, A representation of the \( U(1) \) group with charge \( n \) label a one-dimensional representation space. The representations with different charges (degeneracy is allowed) can span a higher-dimensional linear space,
\[ \mathbb{V} = \bigoplus_{n} \mathbb{V}^{n} d_{n}~, \]
where \( \mathbb{V}^{n} \) is the representation space with charge \( n \) (for Abelian group, it is a one-dimensional space), and \( d_{n} \) is the degeneracy of this representation. So, for Abelian group, the dimension of \( \mathbb{V} \) is \( \sum_{n} d_{n}\). The combination of a representation space and its degeneracy \( \mathbb{V}^{n} d_{n} \) is called a quantum number sector. In GraceQ/tensor, quantum number sector is represented by gqten::QNSector
So, we can use a series of quantum number sectors to describe a linear space.
A rank \( k \) tensor can be seen as a linear mapping between \( k \) linear spaces. Each linear space is labeled by an index of the tensor, \( i_{0}, i_{1}, \cdots, i_{k-1} \). As a mapping, we can define the incoming spaces and outgoing spaces. And the tensor construct the mapping from incoming spaces to outgoing spaces. So a linear space can own a direction and be defined by an index of a tensor. In GraceQ/tensor, a linear space with a direction is described by gqten::Index
where you can use a vector of quantum number sectors gqten::QNSector and the direction of the space (also the direction of the index) gqten::GQTenIndexDirType to initialize a linear space (tensor index). You can use gqten::InverseIndex function to inverse the direction of an index.
Once we have constructed the mapping spaces, the mapping, i.e. a tensor, can be defined straightforwardly. In GraceQ/tensor, a tensor is described by gqten::GQTensor. This class template has two template parameters. The first one describes the type of the tensor elements, gqten::GQTEN_Double for real number, and gqten::GQTEN_Complex for complex number. The second one describes the type of the symmetry which needs be a gqten::QN.
Then, we can use mapping linear spaces, i.e. the tensor indexes, to initialize a tensor instance.
The following sample code shows how to get/set the tensor element, how to get the basic information of a tensor, and how to read/write a tensor from/to a file. You can compile and run it to see what will happened.
The following runnable sample code shows how to generate a random tensor by giving the quantum number variation, how to normalize a tensor, how to complex conjugate a tensor , and how to convert a real tensor to a complex tensor.
Up to now, following basic arithmetics are supported by gqten::GQTensor.
Since the data in memory are stored in a certain order, we need the indexes transpose manipulation. Because the cost of a tensor transpose is about O(N), the order of tensor indexes will influence the performance. In GraceQ/tensor, we can perform in-place tensor transpose by the member function of GQTensor, gqten::GQTensor::Transpose.
Tensor contraction is implemented as a numpy-like API in GraceQ/tensor gqten::Contract.
The truncated tensor singular value decomposition (SVD) is performed in GraceQ/tensor gqten::SVD.
The singular value spectrum truncation policies are
Dmin, keep all the spectrum.trunc_err first but its number is smaller than the Dmin, keep Dmin number of singular values.trunc_err first and its number is larger than the Dmin but smaller than the Dmax, keep number of singular values which satisfies the trunc_err.Dmax first but trunc_err not satisfied, keep Dmax number of singular values.To combine two indexes of a tensor, you can generate an index combiner according to these two indexes using gqten::IndexCombine
The combiner is a tensor initialized as GQTensor<TenElemT, QNT>( {InverseIndex(idx1), InverseIndex(idx2), new_idx} ) and only elements corresponding to index combination equal to 1. To combine two specific indexes of a tensor, you can create the corresponding combiner and contract the tensor with the combiner.
...
...
...
GraceQ/tensor is freely available under the LGPL v3.0 licence.
You can cite the GraceQ/tensor where you use it as a support to this project. Please cite GraceQ/tensor as
GraceQuantum.org . GraceQ/tensor: A high-performance tensor computation framework for the quantum physics community. For a complete list of the contributors, see CONTRIBUTORS.txt .
You can also choose to simply cite the whole GraceQ project as
GraceQ, www.gracequantum.org .
We highly acknowledge the following people, project(s) and organization(s) (sorted in alphabetical order):
ALPS project, Chunyu Sun, Donna Sheng, Grace Song, Hong-Chen Jiang, Hong-Hao Tu, Hui-Ke Jin, itensor.org, Le Zhao, Shuo Yang, Thomas P. Devereaux, Wayne Zheng, Xiaoyu Dong, Yi Zhou, Yifan Jiang, Yifeng Chen, Zheng-Yu Weng
You can not meet this project without anyone of them. And the basic part of this project (before version 0.1) was developed by Rong-Yang Sun and Cheng Peng, when Rong-Yang Sun was a visiting student at Stanford University. So R.-Y. Sun want to give special thanks to his co-advisors Hong-Chen Jiang, Prof. Thomas P. Devereaux and their postdoctors Yifan Jiang and Cheng Peng.
1.8.13