The ITensor Software Library for Tensor Network Calculations

1 Introduction

• ITensor is inspired by tensor diagram notation: tensors with the same indices can be added in any order, with the library handling the details.Diagram notation depicts tensors as shapes and indices as lines, emphasizing connectivity without index ordering.Source: §1 · p. 3
• The design hides implementation details such as index ordering and offers access from sophisticated algorithms to moderately advanced routines and individual ITensors.This range of access is why ITensor is a library rather than a single executable program.Source: §1 · pp. 3–4
• Index objects can store conserved quantum-number subspaces to align contraction storage order, while dense and sparse ITensors share an interface that supports generic code..Source: §1 · p. 4
• Intelligent indices simplify tensor addition and MPS operator application, but can require property-manipulation code and limit low-level control; index order remains manually controllable when needed.Other tensor libraries expose index ordering for manual management [8], while ITensor provides functions such as permute and in-place contraction to specify ordering.Source: §1 · p. 4
• Persistent index labels let a collection of ITensors specify a graph and support higher-level network abstractions and planned automatic differentiation, unlike temporary-label or topology-based interfaces [9–11], [13]..Source: §1 · p. 4
• The article provides a high-level overview of ITensor’s design and features, with examples in Julia; its Julia and C++ interfaces are similar, and Julia is a full implementation.The article points readers to the ITensor website for documentation, code examples, and tutorials.Source: §1 · p. 5

2.1 Installing ITensor; 2.2 Obtaining Help; 2.9 Online Code Examples

• ITensor can be installed with Julia’s package manager, queried through Julia’s built-in documentation, and explored through code examples distributed with the source.The package manager command add ITensors downloads the package dependencies and ITensors.jl; the documentation system can look up functions and types.Source: §2.1 · p. 5, §2.2 · pp. 5–6, §2.9 · p. 10

2.3 Basic ITensor Usage

• ITensor indices have fixed dimensions and unique IDs, and the * operator contracts matching indices automatically, leaving unmatched indices on the result.Copies of an Index compare equal unless their tags differ; * also supports outer and scalar products.Source: §2.2 · p. 6, §2.3 · pp. 6–7

2.4 Setting ITensor Elements

• ITensor elements are assigned by index-value pairs, indices may be supplied in any order, and random constructors create real- or complex-valued tensors.The examples use Julia’s 1-indexing, and reordered index-value pairs have exactly the same effect.Source: §2.4 · p. 7

2.5 Matrix Example

• In the matrix example, A * B contracts the shared index and handles B’s transposition automatically, remaining correct when B’s indices are reversed.This behavior makes applications robust to code changes that alter index ordering or tensor memory layout.Source: §2.5 · pp. 7–8

2.6 Summing ITensors

• ITensors can be added or subtracted when they have the same indices, even in a different order, and can also be multiplied by scalars, including complex scalars.Source: §2.6 · p. 8

2.7 Priming Indices

• Priming an index changes its identity without changing tensor elements, allowing * to contract only the intended shared index while leaving other indices uncontracted.The example primes one i index so only j matches between the tensors.Source: §2.7 · pp. 8–9

2.8 Compiling ITensor

• ITensors.jl can be precompiled to reduce Julia startup times, though the initial compilation can take many minutes and is needed again after a library upgrade.Running Julia with the suggested arguments loads a precompiled system image; startup typically falls to a few seconds.Source: §2.8 · p. 9

3 Index Objects

• Index objects represent particular vector spaces, so equal dimensions do not imply equal indices: construction assigns a unique ID, and separately constructed indices compare unequal.Mathematically, an index labels a vector-space basis.Source: §3 · p. 10
• Tags help identify indices in print, group indices by shared labels, and prevent selected pairs from contracting; the example permits at most four tags of eight characters each.These limits are hard-coded and may be increased if use cases require it.Source: §3 · p. 10
• Random 64-bit IDs have highly improbable collisions and support parallel algorithms and mixing file-loaded ITensors with newly generated ones.The passage contrasts random ID generation with sequential IDs.Source: §3 · p. 10
• Index equality requires matching IDs and tags, while different prime levels also make copies unequal; these distinctions can prevent contraction by the * operator.Every Index has an integer prime level that defaults to zero.Source: §3 · pp. 10–11
• Prime levels suit temporary distinctions resettable with noprime(T), whereas application-specific tags can encode lattice positions and translationally invariant contexts.For a square lattice, tags such as x=-1 or y=1 can specify a unique position.Source: §3 · p. 11

4 The ITensor Product Operator (∗)

• * computes outer products for tensors with no shared indices, inner products yielding scalar ITensors for identical indices, and contractions when only some indices overlap.Source: §4 · p. 12
• Users need only know which Indexes tensors share; ITensor performs the contraction without requiring manual tracking of the uncontracted result indices’ ordering.Source: §4 · p. 13
• Delta tensors replace an Index with one of the same dimension or duplicate an index, while diagonal-sparse storage saves memory and enables optimized contractions.Source: §4 · p. 13
• Combiners merge multiple indices into one, and multiplying by a conjugated combiner reverses the operation; their specialized storage and algorithms optimize both operations.Source: §4 · pp. 14–15
• For quantum-number-conserving or symmetric ITensors, combiners can group repeated quantum numbers in the combined Index and manage anticommutation properties for the upcoming fermion system.Source: §4 · p. 15

• ITensor automates converting tensors to matrices and back by grouping selected indices as rows and the rest as columns for matrix factorizations.Source: §5 · p. 15
• QR generates a shared Index linking Q and R, whose product recovers T without requiring users to know Index details; commonind retrieves it when needed.Source: §5 · pp. 15–16
• ITensor implements SVD, a key decomposition in tensor-network calculations.Source: §5 · p. 16
• By default, decompositions are untruncated (and thin when available); keyword-controlled truncation can stop at error 10^-8 while retaining at most 10 singular values.Source: §5 · p. 16

Tensor Storage Layer

• ITensor lets users mix dense and sparse tensors through the same interface, while Julia multiple dispatch specializes performance-critical operations for each storage type or combination.Distinct storage types can use optimal memory layouts, and users can contract tensors with the * operation without managing those optimizations.Source: §6 · pp. 16–17
• Storage types often arise automatically: SVD returns diagonal-sparse singular values, while indices with quantum number subspaces create block-sparse storage.Block sparsity can enforce symmetries or conservation laws; ITensor stores nonzero elements contiguously and maps block indices to array offsets.Source: §6 · pp. 16–17
• Dense storage is the default for regular indices; diagonal storage holds diagonal elements, while uniform diagonal storage stores one repeated value and enables specialized contractions.A uniform diagonal value of 1.0 can replace one index with another or act as a copy or delta tensor.Source: §6 · p. 17
• Combiner storage uses essentially no memory and merges two or more indices into a larger index when contracted with a tensor containing them.The combiner creates the combined index automatically.Source: §6 · p. 17
• Experimental GPU storage keeps tensor elements in GPU memory and uses specialized routines; GPU tensors can use the library’s high-level algorithms, with speedups ranging from two to a hundred times CPU calculations.The GPU feature is supported by the ITensorGPU.jl package.Source: §6 · p. 18
• EmptyStorage represents a numerically zero tensor without allocating memory and can serve as a universal zero when summing tensors with the same indices.Constructing an ITensor from indices produces empty storage.Source: §6 · p. 18
• Planned storage extensions include identity and unitary maps, lazy operations, and more explicit or optimized general sparsity; general sparsity is already representable as block sizes of one.The authors report observed speedups from representing sparse tensors in this limit.Source: §6 · p. 18
• Lower-precision floating-point data is supported, and exotic numerical types such as tropical numbers were supported through contributions by Jin-Guo Liu; systematic handling of integer, boolean, or nonnegative elements is planned.The authors also plan to document how users can define custom storage types outside the library and use them as first-class ITensor storage types.Source: §6 · pp. 18–19

7 High Level Features: MPS and MPO Algorithms

• ITensor supports MPS (also called tensor trains), MPOs, and algorithms for summing, truncating, optimizing, and multiplying them with customizable tradeoffs.MPS-by-MPO multiplication offers at least three algorithms, while DMRG can target ground or excited states and handle sums of MPOs.Source: §7 · p. 19

7.1 OpSum and AutoMPO

• OpSum expresses sums of products of local operators in a domain-specific language, and AutoMPO compiles them into MPOs, including terms with multiple operators at arbitrary distances.AutoMPO uses SVD-based compression to obtain a nearly optimal MPO bond dimension; its backend enhancement was based on Ref..Source: §7.1 · pp. 19–20
• Planned OpSum extensions include improved compression, quantum-circuit compilation, infinite systems, other network topologies, and fermionic mean-field approximations.The proposed directions include compression methods based on quantum-chemistry techniques, infinite-MPO truncation methods, TTNs and PEPOs, and Hartree-Fock approximations for interacting fermionic Hamiltonians.Source: §7.1 · p. 20

7.2 DMRG Algorithm

• DMRG computes low-energy states of Hermitian operators represented as MPOs, including quasi-two-dimensional systems and long-range interactions.For sums of MPOs, ITensor can loop over them internally rather than explicitly summing them; this can enable parallelization of environment construction and local effective-Hamiltonian diagonalization. Excited states are constrained to be orthogonal to previous states using energy-penalty projectors.Source: §7.2 · pp. 20–22

7.3 MPS and MPO Operations

• ITensor exposes MPS factor tensors and supports local expectation values, correlations, orthogonalization, and truncation with bond-dimension and error controls.MPS objects track known orthogonality to avoid repeated work, while a cutoff can adaptively reduce bond dimension while bounding truncation error.Source: §7.3 · pp. 22–23
• ITensor also supports MPS/MPO addition and approximate MPS-by-MPO or MPO-by-MPO products, with backend algorithms trading off cost, accuracy, and control.The described addition backend uses the density-matrix algorithm [28], and product operations can use different backend implementations.Source: §7.3 · pp. 23–24

8 Quantum Number Block Sparse ITensors

• ITensor stores quantum-number information on indices to determine block-sparse storage and propagate that information through tensor operations.Quantum-number conservation can reflect physical symmetries and improve memory use and runtime; ITensor currently supports Abelian symmetries such as U(1) and Zn, with non-Abelian support such as SU(2) planned.Source: §8 · pp. 24–25

8.1 QN Objects

• QN objects hold named integer-valued quantum numbers that can be combined, compared, or defined with modulo-N addition rules.Names let QNs with different components combine correctly when physical spaces are mixed; fermion parity is an example of a quantum number conserved modulo two.Source: §8.1 · pp. 25–26

8.2 QN Index

• QN indices represent direct-sum subspaces and carry arrow directions that govern contraction compatibility and the signs used to calculate tensor flux.Contracted QN indices must have opposite arrow directions; flux calculations add quantum numbers on Out indices and subtract them on In indices.Source: §8.2 · p. 27

8.3 QN ITensor

• QN ITensors store only blocks consistent with a well-defined flux, while dag reverses index arrows so correctly conjugated dense-tensor code also respects QN conservation.In the hard-core-boson example, the operator a has a single stored nonzero entry, at (1,2), with value 1.0; its flux is QN("N",-1), while n has flux zero.Source: §8.3 · pp. 27, 29
• Block-sparse operations achieved speedups of up to 5× in practical physics applications, with performance varying by application.Unallocated zero blocks can be skipped, and operations on nonzero blocks can run in parallel. Dense-tensor operations, including factorizations and MPS/MPO algorithms, retain the same interface for QN ITensors.Source: §8.3 · p. 29

9 NDTensors Library

• NDTensors separates low-level algorithms and storage from ITensor’s high-level logic, simplifying and modularizing the code to help prevent bugs.The authors also envision broader community contributions and eventual use of NDTensors as a backend for other software, with a separate release planned.Source: §9 · p. 30

9.1 Basic Interface

• NDTensors offers a standalone, traditional tensor interface that supports generic high-performance algorithms and varied sparse tensor types, while requiring users to track index ordering.Tensor contractions use temporary labels: matching labels indicate contracted indices, while unique labels indicate uncontracted indices.Source: §9.1 · pp. 30–31

9.2 Block Sparse Tensors

• Block-sparse tensors allocate only the blocks designated as potentially nonzero, with each block corresponding to a combination of index subspaces.The remaining zero blocks are assumed rather than allocated in memory.Source: §9.2 · p. 31

9.3 Generic Index Types

• NDTensors indices can be represented by any object that provides the required index interface, enabling ITensor interoperability and features such as slicing.For dense and diagonal storage, the interface requires that the dimension of an index can be queried.Source: §9.3 · p. 32

9.4 Tensor Contraction Backend

• Multi-core block-sparse contraction yielded 2−3× speedups for DMRG and related MPS calculations and up to 5× for tree tensor network calculations; Julia NDTensors later saw similar speedups.The dense backend permutes and reshapes tensors into matrices for BLAS multiplication, avoiding unnecessary permutations where possible; the best block-sparse contraction strategy depends on tensor and sparsity details.Source: §9.4 · pp. 32–33

10.1 Writing and Reading ITensor Objects with the HDF5 Format

• Nearly all ITensor network objects can be read from and written to HDF5, enabling portable storage and exchange between the C++ and Julia libraries.HDF5 also supports metadata, file-system organization, and efficient memory use, including numerical-data compression.Source: §10.1 · p. 33

10.2 Defining Custom Local Hilbert Spaces

• Julia site types let users define tagged custom Hilbert spaces and operator overloads that work through OpSum and MPS/MPO constructors, including mixed-site models.This streamlines customization compared with the cumbersome process described for C++ users.Source: §10.2 · pp. 35–36

10.3 DMRG Observer System

• DMRG observer hooks let users customize each algorithm step through measure! and checkdone!, enabling state monitoring and stopping before all requested sweeps.measure! can inspect the current sweep, optimized site locations, and MPS; checkdone! can apply a convergence criterion or respond to an external signal.Source: §10.3 · p. 36

11.1 Equilibrium Quantum Systems

• Equilibrium applications include ground-state studies, where Keselman and Berg used ITensor DMRG to support a topological state in a one-dimensional superconducting-electron model.Their finite-size study included quantities at the edges of open systems and found evidence for the state even without a gap in the excitation spectrum.Source: §11.1 · p. 37
• In two dimensions, ITensor DMRG studies found a p-wave-to-d-wave superconductivity transition in the triangular-lattice hole-doped Hubbard model and proposed universal corner-entanglement scaling.The corner-scaling conjecture was later supported by field-theoretic methods.Source: §11.1 · p. 37
• Other equilibrium applications include hydrogen-chain quantum chemistry, finite-temperature studies using METTS [48–51], and PEPS calculations [53].The section also identifies ab initio systems, including quantum chemistry, as an important area of development for DMRG and MPS methods.Source: §11.1 · p. 37

11.2 Dynamics of Quantum Systems

• ITensor’s flexibility and customizability suit quantum dynamics research, where time-evolution algorithms require care across varied systems, evolution methods, and measurements.Studies may involve closed or open systems and Hamiltonian- or circuit-based evolution.Source: §11.2 · p. 37
• For integrable systems such as the XXZ chain, Alba and Calabrese showed that entanglement entropy can be accurately predicted at short and long times.Source: §11.2 · pp. 37–38
• ITensor simulations supported KPZ-class entanglement growth in random unitary circuits, matched cold-atom observations, and demonstrated a fork-state DMFT solver.The solver enables greater resolution for electron spectral functions and other benefits.Source: §11.2 · p. 38

11.3 Other Application Areas

• Beyond physics, tensor networks have been applied to holographic dualities and high-dimensional integration; PastaQ uses ITensor for quantum-device simulation and related tasks.PastaQ also supports quantum-circuit optimization and tomography of quantum systems and processes; tensor networks can offer linear scaling with qubit count.Source: §11.3 · p. 38
• Applied mathematics and machine-learning uses include neural-network weight compression, corrupted-data recovery, and supervised and unsupervised learning with tensor-network models.ITensor has also been used to study generalization of these models on synthetic data.Source: §11.3 · p. 38

12 Benchmarks of ITensor Performance

• Julia is very competitive with C++ for tensor-network algorithms, and recent optimization efforts put it ahead in several cases, especially block-sparse operations.The C++ implementation is also highly optimized and nearing state-of-the-art performance.Source: §12 · p. 39, §12.1 · p. 44

12.1 Comparison of Julia and C++ Implementations of ITensor

• TRG performance is similar across C++ and Julia: C++ is slightly faster at bond dimension 40, Julia at 50, and BLAS/LAPACK threading speeds the contraction-dominated calculations.The comparison uses dense tensors and 1, 4, or 8 BLAS threads.Source: §12.1 · pp. 39–40
• Julia is consistently faster for CTMRG at larger boundary bond dimensions; four BLAS threads help, while eight add little speedup.The passage attributes Julia’s relative performance likely to improved dense tensor permutation libraries, specifically Strided.jl, and notes that BLAS multithreading effectiveness depends on the system and algorithm.Source: §12.1 · pp. 40–41
• For block-sparse DMRG, Julia handles tensors much more efficiently than C++; BLAS multithreading is less effective because many blocks produce smaller matrix multiplications.The optimizations include storing nonzero-block locations in a dictionary rather than an array and improving contractions of small blocks. Dense-chain DMRG shows relative Julia performance similar to CTMRG.Source: §12.1 · pp. 41–42
• For cylinder Hubbard-model DMRG, Julia also outperforms C++, with similar single-threaded performance in one case; additionally conserving ky reduces total time and increases Julia’s advantage.With block-sparse contraction threading, timings improve by 1.5x to 2x over no such threading; multithreading is more effective in C++ than Julia in these calculations.Source: §12.1 · pp. 43–44

12.2 Benchmarks of ITensor Versus Other Software

• ITensor and TeNPy perform comparably when algorithmic details and external dependencies are made as similar as possible.TeNPy’s default sparse Hamiltonian representation typically speeds up DMRG, prompting ITensor’s splitblocks capability, though whether it improves performance depends on the system; TeNPy’s DMRG default also uses more Lanczos steps per step than ITensor’s. Benchmarks are hosted online because both libraries and their implementations continue to change.Source: §12.2 · pp. 44–45

13 Future Directions

• Automatic differentiation is a high-priority direction, with prototypes for optimizing MPS, variational circuits, and PEPS and plans to broaden operation coverage and higher-order derivatives.The proposed system uses ChainRules.jl rules with Julia source-to-source AD frameworks; planned work includes better differentiation through factorizations and MPS/MPO operations and support for unitary constraints.Source: §13 · p. 45
• ITensor is developing fermionic index semantics so index permutations can apply parity signs, aiming to make fermionic calculations use the same code as bosonic ones.Current automatic fermion support is limited to OpSum/AutoMPO lookup tables, so some calculations require manually inserted Jordan–Wigner strings.Source: §13 · pp. 45–46
• After fermion support, ITensor plans to add non-Abelian symmetries such as SU(2) for Heisenberg and Hubbard variants and quantum-chemistry electronic-structure Hamiltonians.Source: §13 · p. 46
• ITensor is extending contraction-sequence optimization and developing network visualization, with planned alternative backends for larger networks and approximate contraction algorithms.The current optimizer can choose sequences for expressions such as A*B*C*D; visualization is planned through a macro with text and interactive outputs.Source: §13 · p. 46
• First-class infinite MPS/MPO support is planned, including eigenvalue and eigenvector algorithms, canonical forms, infinite MPO application, and an infinite OpSum/AutoMPO.The work is in the separate ITensorInfiniteMPS.jl package, with preliminary development nearly completed.Source: §13 · p. 46
• GPU support is planned to expand from dense operations to block-sparse tensors, with a goal of high-performance GPU execution for most CPU code with minimal user effort.The eventual goal includes code that uses automatic differentiation.Source: §13 · p. 46
• ITensor plans high-level PEPS algorithms, leveraging its developing general tensor-network interface, automatic differentiation, and contraction-sequence optimization.The passage identifies variational iPEPS and fixed-point environment methods as established approaches for which algorithms may be provided.Source: §13 · p. 47

A Full Code Examples · A.1 Contraction Example

• The code examples section points to a growing source-distribution collection and presents a working contraction example with a complex index structure and a diagram.The example uses hasinds to check that the resulting ITensor C has indices a, b, c, i, and j; index tags are for readability when printed, not required for the code to function.Source: A Full Code Examples · p. 48, §A.1 · pp. 48–49

A.2 DMRG Example

• The Julia example builds a 100-site S=1/2 Heisenberg chain Hamiltonian as an MPO and applies DMRG to a random bond-dimension-10 MPS.The calculation returns the ground-state energy and wavefunction MPS.Source: §A.2 · pp. 49–51
• The five-sweep DMRG example ends with G.S. energy = -44.127739882501665.The reported sweep energies converge to this final ground-state energy.Source: §A.2 · p. 50
• Its five sweeps use maximum bond dimensions 10, 20, 100, 100, and 200 with a truncation cutoff of 10^-11.Source: §A.2 · pp. 50–51

B ITensor Implementation and Interface in the C++ Language

• The C++ appendix provides code examples to show similarities to and differences from the Julia version.Source: B ITensor Implementation and Interface… · p. 51

B.1 C++ Contraction Example

• The C++ contraction example mirrors Julia’s, differing in header includes, auto declarations, semicolon-terminated statements, and ITensor’s Print macro.Source: §B.1 · p. 51

B.2 C++ DMRG Example

• The C++ DMRG example parallels Julia’s, disables default site-set quantum-number information, and uses {"Quiet=",true} within ITensor’s custom named-argument system.The authors plan to release the named-argument system as a separate library.Source: §B.2 · pp. 52–53