DOCSEARCHbyAlgolia
Submit Docs

TeNPy (Tensor Network Python) Documentation

repository·main·Indexed 19 days ago

https://github.com/tenpy/tenpy

A Python library for the simulation of strongly correlated quantum many-body systems using tensor network algorithms. TeNPy provides tools for working with Matrix Product States (MPS) and Matrix Product Operators (MPO), including implementations of TDVP, TEBD, and Variational Compression. It features a simulation layer for running and resuming tasks via the tenpy-run CLI or API, HDF5 support for data persistence, and a unified interface for time evolution algorithms.

Tokens
33.8K
Snippets
91
Records
166
Agent score
67%

What's inside TeNPy

  1. Explore TeNPy Submodules

    main

    TeNPy is organized into several core submodules that handle different aspects of tensor network physics:

    • algorithms: Implementation of various tensor network algorithms (e.g., DMRG, TEBD).
    • linalg: Linear algebra utilities and interfaces.
    • models: Definitions of physical models (Hamiltonians, etc.).
    • networks: Tensor network structures and manipulations.
    • simulations: The framework for running simulations, often driven by YAML files.
    • tools: General utility functions.
    • version: Version information.

  2. Explore the TeNPy main module structure

    main

    The tenpy module is the entry point for the Tensor Network Python library. It organizes functionality into several key submodules:

    • algorithms: Contains various tensor network algorithms (e.g., DMRG, TEBD).
    • linalg: Provides linear algebra utilities.
    • models: Contains physical models (e.g., spin chains, Hubbard models).
    • networks: Core tensor network data structures and operations.
    • tools: General utility functions.
    • version: Version information.

    Additionally, the module provides high-level command-line interfaces and utility functions for simulation management.

  3. Configure logging and verbosity

    main

    TeNPy uses Python's standard logging module for output. By default, you will only see error messages and warnings. To see simulation progress or other information, you must configure the logging level.

    • Command Line: Running via the command line typically defaults to the INFO level.
    • Python Code: To enable output in your scripts, configure the logging module to the INFO level.

    Deprecated Verbosity Patterns:

    • Do not use the verbose class argument in tenpy.tools.params.Config.
    • Do not use the verbose class attribute on TeNPy classes.
    • Use tenpy.tools.params.Config.log instead of the old print_if_verbose method.

  4. Understand the Jordan-Wigner transformation in TeNPy

    main

    The Jordan-Wigner transformation maps fermionic creation and annihilation operators to bosonic (spin) operators. In TeNPy, fermionic operators are treated as global operators.

    Even though a fermionic operator like $c_j$ has a site index $j$, it is composed of:

    1. A Jordan-Wigner (JW) string: The local operator JW (defined as $(-1)^{n_l}$) acting on all sites $l < j$.
    2. A local operator: The onsite operator C (annihilation) or Cd (creation) acting on site $j$.

    While onsite operators in FermionSite fulfill correct anti-commutation relations locally, the JW string is strictly necessary to ensure correct anti-commutation for operators acting on different sites.

  5. Access core TeNPy objects from the top-level namespace

    main

    As of v0.11.0, many important objects are exposed directly in the top-level tenpy namespace. This allows for cleaner imports. You can import major classes like MPS or utility functions like tensordot directly from tenpy instead of navigating deep subpackage paths.

    # Direct imports from top-level
from tenpy import MPS, tensordot, TwoSiteDMRGEngine

# Or using the package alias
import tenpy as tp
val = tp.tensordot(a, b)

  6. Understand the three Hamiltonian representation types in TeNPy

    main

    TeNPy provides three distinct ways to represent a Hamiltonian, each suited for different algorithms:

    1. NearestNeighborModel: The Hamiltonian is a sum of two-body terms stored explicitly as a list of np_conserved.Array objects. This structure is required for TEBD.
    2. MPOModel: The Hamiltonian is provided directly as an MPO (Matrix Product Operator). This structure is required for DMRG, ExpMPOEvolution, or TDVP.
    3. CouplingModel: The Hamiltonian is defined symbolically using terms (via tenpy.networks.terms). This is a convenient way to specify models and serves as a base to initialize the other two structures, but no current algorithms require this symbolic form directly.

    A custom model should inherit from all applicable classes (e.g., inheriting from both CouplingModel and MPOModel to support both symbolic definition and MPO-based algorithms).

  7. Handle dipole conservation and shift-symmetry

    main

    In TeNPy, most conserved charges follow the form $Q = \sum_i q_i$, where the local charge $q_i$ is independent of the site position $i$. However, some models (like DipolarSpinChain) possess a 'shift-symmetry' where the local charge depends on the site position, such as a dipole charge $P = \sum_i r_i q_i$.

    To handle these non-trivial symmetries, TeNPy uses the following mechanisms:

    • ChargeInfo: The base class for defining how charges transform under spatial translations. By default, ChargeInfo.trivial_shift is True (charges do not change). For non-trivial symmetries, you must implement a subclass (e.g., DipolarChargeInfo).
    • shift_charges / shift_charges_horizontal: Methods in ChargeInfo that define how local charges change when moved by a translation vector. shift_charges_horizontal is a specialized version for translations along the first dimension, used by MPS algorithms.
    • MPS Site Handling: When using non-trivial charges, the MPS sites are not just the lattice unit cell sites. TeNPy uses Lattice.mps_sites to account for the actual positions of sites, which affects the charge values on physical legs.
    • iMPS Shifting: In infinite MPS (iMPS) simulations, tensors in neighboring unit cells are not identical but are 'shifted' versions of each other. TeNPy handles this automatically in MPS.get_B, MPS.set_B, and similar methods for S.
    • Unit Cell Shifting: For iMPS algorithms, shifting is often performed by whole MPS unit cells. This is implemented via MPS.shift_Array_unit_cell, which utilizes the MPS.unit_cell_width attribute.

  8. Define models using onsite and coupling terms

    main

    While you can manually define an MPO by specifying its W tensors, TeNPy allows you to define models abstractly. This is more scalable for complex Hamiltonians and higher-dimensional lattices.

    By specifying onsite terms and coupling terms, TeNPy uses an internal finite state machine to automatically generate the corresponding MPO. This process can also automate the mapping of higher-dimensional lattices (like a 2D Kagome lattice) onto the 1D chain used by an MPS.

  9. Automate Hermitian conjugation in CouplingModels

    main

    When defining physical Hamiltonians, you can avoid manually adding Hermitian conjugate terms by using the plus_hc argument in coupling methods. This ensures that if you add a term like $c^{\dagger}_i c_j$, its conjugate $c^{\dagger}_j c_i$ is also included.

    Managing MPO Bond Dimension

    If you are using an MPOCouplingModel, you can optimize memory and computational efficiency using the explicit_plus_hc parameter in your model_params:

    1. explicit_plus_hc = False (Default): You must either add conjugate terms manually or use plus_hc=True. If you use plus_hc=True, the MPO will store both terms, increasing the bond dimension.
    2. explicit_plus_hc = True: The model and MPO will only store half the terms (the non-conjugate ones). At runtime during DMRG, TeNPy will compute and apply the Hermitian conjugate automatically. This reduces the MPO bond dimension and memory requirements.

    Important: To benefit from bond dimension reduction, you must set model_par['explicit_plus_hc'] = True and use plus_hc=True in your add_coupling or add_multi_coupling calls.

    # Case 1: Manual addition (High bond dimension)
model_params['explicit_plus_hc'] = False
self.add_coupling(-J, u1, 'Cd', u2, 'C', dx)
self.add_coupling(np.conj(-J), u2, 'Cd', u1, 'C', -dx)

# Case 2: Automatic addition, but still stores both terms (High bond dimension)
model_params['explicit_plus_hc'] = False
self.add_coupling(-J, u1, 'Cd', u2, 'C', dx, plus_hc=True)

# Case 3: Optimized (Reduced bond dimension)
model_params['explicit_plus_hc'] = True
self.add_coupling(-J, u1, 'Cd', u2, 'C', dx, plus_hc=True)

  10. Use MPSGeometry for linear tensor networks

    main

    TeNPy introduced MPSGeometry as a base class to abstract common properties and methods for tensor networks with linear geometry (such as MPS and MPO).

    Key features include:

    • MPO and Environments now subclass MPSGeometry.
    • The attribute unit_cell_width is available on MPSGeometry instances.
    • unit_cell_width is an argument to the __init__ method and most classmethods of MPS, MPO, etc. For backwards compatibility, it is optional and defaults to a value assuming a Chain lattice.

  11. Migrate from MultiCouplingModel to CouplingModel

    main
    In TeNPy (starting from version 0.7.2), tenpy.models.model.MultiCouplingModel has been deprecated. Its functionality is now fully merged into tenpy.models.model.CouplingModel. You should use CouplingModel directly instead of subclassing MultiCouplingModel to define your model's terms.

  12. Handle simulation abort signals gracefully

    main
    TeNPy now handles SIGINT signals during simulation runs. Instead of an immediate crash, the simulation will continue until the next algorithm checkpoint, save its state, and then exit gracefully by raising a KeyboardInterrupt. You can manage this behavior using Simulation.handle_abort_signal.