ITensors.jl

The Expose module is designed to unwrap complex types to facilitate generic programming for type-based functions. It is primarily used to intercept workflows and prevent unexpected behavior that can occur when functions interact with arbitrary type wrappers.

Use Expose when you are developing generic algorithms that need to access the underlying data or structure of wrapped types without being blocked by the wrapper itself.

To merge multiple indices into a single index (where the new dimension is the product of the original dimensions), use the combiner function. This is done by contracting the original ITensor with a 'combiner' ITensor.

1. Create a combiner: C = combiner(i, k; tags="...").
2. Contract: CT = C * T.
3. To undo the process (uncombine), contract with the conjugate: UT = dag(C) * CT.

You can retrieve the new combined index using combinedind(C).

# Setup indices
i = Index(4,"i"); j = Index(3,"j"); k = Index(2,"k")
T = random_itensor(i,j,k)

# Create and apply combiner
C = combiner(i, k; tags="c")
CT = C * T

# Access the new index
ci = combinedind(C)
@show inds(CT)

# Uncombine
UT = dag(C) * CT
@show inds(UT)

In v0.2, plain ITensor constructors (e.g., ITensor(i, j, k)) return an ITensor with EmptyStorage instead of Dense or BlockSparse storage filled with zeros.

Behavioral Notes

• Contracting two EmptyStorage ITensors results in another EmptyStorage ITensor.
• To allocate actual storage, set an element: A[i' => 1, i => 1] = 0.0.
• The ITensor will adopt the element type of the first value you set (e.g., setting a ComplexF64 value will convert the storage to ComplexF64).

i = Index(2)
A = ITensor(i', dag(i)) # Returns EmptyStorage

# Allocate storage by setting a value
A[i' => 1, i => 1] = 1.0 + 0.0im
# A is now Dense{ComplexF64, ...}

The ITensor type now directly wraps a tensor and no longer has separate .inds and .store fields.

Task: Update Field Access Do not access A.inds or A.store directly. Instead, use the following functions:

• Use inds(A) to get the indices (now returns a Tuple of Index instead of an IndexSet).
• Use storage(A) to access the underlying storage.

Example of the change:

# Instead of:
A.inds

# Use:
inds(A)

i = Index(2)
j = Index(3)
A = random_itensor(i, j)

# Returns a Tuple of Indices
inds(A) # ((dim=2|id=770), (dim=3|id=272))

To use the ITensors.compile() function, you must install PackageCompiler.jl and include it in your code alongside ITensors. This is necessary because compile() relies on running MPS/MPO functionality as example code for Julia to compile.

using Pkg; Pkg.add("PackageCompiler")

using PackageCompiler
using ITensors

You can persist ITensors to disk using the HDF5 format. This requires the HDF5.jl package (install via using Pkg; Pkg.add("HDF5")).

Writing to HDF5 Use h5open in write mode ("w") and call write(f, "key", ITensor).

Reading from HDF5 Use h5open in read mode ("r") and call read(f, "key", ITensor). Note that you must explicitly pass the ITensor type to the read function so Julia knows how to interpret the data.

using ITensors, HDF5

# Writing
i = Index(2)
T = random_itensor(i)
f = h5open("myfile.h5", "w") do f
    write(f, "T", T)
end

# Reading
T_loaded = h5open("myfile.h5", "r") do f
    read(f, "T", ITensor)
end

You can persist ITensors and other ITensors types to HDF5 files using the HDF5.jl library. Use write(f, "name", object) to save and read(f, "name", Type) to load. You can also apply compression during the write process using the compress keyword argument.

Note that the HDF5 format used by ITensors.jl is designed for interoperability with the C++ version of ITensor.

using ITensors, HDF5
i = Index(2)
T = random_itensor(i)

# Writing to HDF5 with optional compression
f = h5open("myfile.h5","w") do f
    write(f,"T",T; compress=3)
end

# Reading from HDF5
T2 = h5open("myfile.h5","r") do f
    read(f,"T",ITensor)
end

T == T2