Skip to content

Latest commit

 

History

History
144 lines (119 loc) · 11.8 KB

CONTRIBUTING.org

File metadata and controls

144 lines (119 loc) · 11.8 KB

CONTRIBUTING

How to contribute to TNSP project

If you have/implemented an idea or find/fixed a bug, use GitHub issues or pull requests. Providing a minimum working example for bugs would be helpful. Any questions about using TNSP can be put in GitHub discussion. And feel free to submit a pull request for completing documentation or adding descriptions of new models into tetraku.

Code structure

The code structure of TNSP is organized into subprojects, with each subproject placed in its respective directory. The TNSP framework includes:

  • =TAT= contains the core tensor library written in C++17, known as TAT.
  • =PyTAT= contains a wrapper over TAT using pybind11, known as PyTAT or the Python interface for TAT.
  • =lazy_graph= contains a utility library for lazy evaluation, known as lazy_graph , utilized in tetragono.
  • =PyScalapack= contains a utility library for directly calling ScaLAPACK in python, known as PyScalapack , utilized in tetragono.
  • =tetragono= contains a library tetragono , which provides high-level tensor network state operations, including exact diagonalization, simple update and sampling methods on PEPS.
  • =tetraku= contains a library tetraku , which provides some physics models that can be used with tetragono .
  • =tnsp_bridge= contains a library tnsp_bridge , which is used to migrate tensors in the old TNSP format to the PyTAT format.

whereas lazy_graph, PyScalapack, and tnsp_bridge are all single-file, pure Python packages. The directory structure of other subprojects is presented below.

tetraku

The tetraku contains physics model information in their respective directories. Every model contains a function abstract_state to define its physics edge and Hamiltonian, and abstract_lattice to define its virtual edges. When adding a new physics model to tetraku, please include a short README, even a single line containing its Hamiltonian is acceptable. Please note that for models you want to optimize within a subspace of the Hamiltonian, typically a Hamiltonian hopping script, configuration initializer script, or even a subspace restrictor is needed. And most of the time, you may also want to add some measurements for the model. The scripts for these models can be referenced if you want to add new models: =J1J2=, =rydberg= and =free_fermion=.

tetragono

The tetragono first defines AbstractState in =abstract_state.py=, which includes customized Hamiltonian and physical edges on a virtual square lattice, accommodating multiple orbits on a single site. Subsequently, =abstract_lattice.py= defines AbstractLattice. This component details the virtual edges within the tensor network on the square lattice, known as the projected entangled pair states (PEPS). For non-symmetry tensors, users only need to provide the dimension as edge information, while non-fermion symmetric tensors need complete segment information, and fermion symmetry tensors require an additional fermi-arrow. Following these definitions, exact diagonalization is realized in =exact_state.py= ,and =simple_update_lattice.py= implements a simple update algorithm.

Since there are various sampling methods, the related functions are categorized under the =sampling_lattice= subdirectory. Within this directory, =lattice.py= specifies the lattice type for containing data and configuration type for individual sampling results, while =sampling.py= encompasses several methods such as ergodic, sweep, and direct sampling. The =observer.py= is designed to facilitate measurements and calculate gradients from sampling results. Finally, all these functionalities are integrated and executed through the driver functions outlined in =gradient.py=.

The =utility.py= file comprises various utility functions. The =auxiliaries= directory, utilizing lazy_graph, used in the configuration type, contains several auxiliary systems designed to minimize redundant calculations in tensor network contractions, particularly when several sites are removed or replaced. The =tensor_element.py= script is dedicated to sparsifying the Hamiltonian, a critical component in sampling methods. In =conversion.py=, functions are defined for converting between ExactState, SimpleUpdateLattice, and SamplingLattice. Finally, =shell.py= offers a high-level, user-friendly interface for accessing all functions within tetragono.

PyTAT

The PyTAT serves as a wrapper for TAT, utilizing pybind11. It comprises three files:

TAT

Within the directory =structure=, the organization of files is as follows:

  • =name.hpp= is responsible for defining names used to label tensor edges, referred to as edge names.
  • =symmetry.hpp= outlines the generic symmetry type Symmetry. This can be instantiated as various symmetries such as NoSymmetry, BoseU1Symmetry, BoseZ2Symmetry, FermiZ2Symmetry, FermiU1Symmetry, among others.
  • =edge.hpp= details the structure of a tensor edge, which includes segments and a fermi-arrow. Here, segments are represented as a vector comprising pairs of Symmetry and dimension.
  • =core.hpp= is designed to define everything in a tensor except for the edge names.
  • =tensor.hpp= describes the tensor structure, encompassing a shared_ptr<Core> and a vector<Name>. Additionally, this file declares numerous tensor-related functions, the implementations of which are found in the corresponding files within the =implement= directory.

Furthermore, several utilities are defined in the =utility= directory. The file =io.hpp= is dedicated to defining I/O functions for tensors, =scalar.hpp= handles scalar arithmetic for tensors, and =mpi.hpp= focuses on various MPI functions for tensors. It is important to note that in PyTAT, functions from mpi.hpp are not utilized.

Thanks! ❤️ ❤️ ❤️

USTC-TNS Group