Systems and States

System(sites::Vector{<:AbstractSite})
System(n::Int, site::AbstractSite)

a quantum system, made of its sites. System(n, site) is made of n copies of site. Two systems of the same sites are equal, and have the same indices. Sites whose conserved quantities cannot live together on one system are refused.

Examples

System(10, Qubit())
System([Qubit(), Spin(1), Qubit(), Boson(5)])

length(::System)

the number of sites of the system, which system[i] and for site in system read.

::System ⊗ ::System
tensor(::System, ::System)

the system of the sites of the first followed by those of the second.

siteind(Pure, system, i)
siteind(Mixed, system, i)
siteinds(R, system)

the ITensor index of site i of system, for pure or for mixed representations, or those of all its sites.

Examples

siteind(Pure, system, 1)
siteinds(Mixed, system)

abstract type Representation

the supertype of the representations of a state: Pure, Mixed, and those an extension defines.

Pure

the representation of a state as a wave function, as in State{Pure}.

Mixed

the representation of a state as a density matrix, as in State{Mixed}.

Limits(; cutoff = nothing, maxdim = nothing, mindim = nothing)

the truncation limits of an MPS, a field left nothing taking the default of the function the limits are given to, which its docstring states.

• cutoff: the largest truncation error allowed, the sum of the squares of the discarded singular values relative to that of all, so that singular values up to √cutoff of the norm go: 1e-26 discards what rounding leaves, those below 1e-13 of the norm, 0 nothing
• maxdim: the maximum bond dimension
• mindim: the minimum bond dimension

For the evolutions and searches, any field may be a vector, one value per step or per sweep, continued with its last value.

Examples

Limits(cutoff = 1e-14, maxdim = 100)
Limits(maxdim = [10, 20, 50, 100])

State{R}(system, states)
State{R}(n::Int, site::AbstractSite, states)
State{R}(sites::Vector{<:AbstractSite}, states)
State(state, mps)

the state of a quantum system, as an MPS: a wave function for R = Pure, a density matrix for R = Mixed. The local states are given as a vector, one per site, or as a single one for every site: a name, A => λ, a vector of amplitudes, in mixed representation a density matrix, or a function of the site giving one of those. A vector of numbers is the amplitudes of one local state. State(state, mps) is a new state on the same system.

States can be added, subtracted, and multiplied or divided by numbers; a sum takes truncation limits as +(a, b; limits = Limits(maxdim = 100)), by default cutoff = 1e-26, which discards what rounding leaves.

Examples

State{Pure}(system, "Up")
State{Mixed}(system, ["Up", "Dn", "Up"])
State{Pure}(System(3, Qudit(4)), Level .=> [0, 3, 1])
State{Mixed}([Qubit(), Boson(4), Fermion()], ["Up", "2", "Occ"])

abstract type AbstractState

the supertype of the states a simulation holds: State, and the states of a representation an extension defines, which have a field system, the System of their physical sites.

length(::AbstractState)

the number of sites of the state.

maxlinkdim(::State)

the largest link dimension of the MPS of the state.

mix(::State; limits = Limits())

the state in mixed representation: the density matrix $|\psi\rangle\langle\psi|$ of a pure state, of the square of its bond dimension, or a mixed state unchanged; truncated to limits, see truncate, unless they are the default Limits().

Examples

ρ = mix(ψ; limits = Limits(maxdim = 100))

truncate(::State; limits::Limits)

the state with its MPS truncated to limits, by default cutoff = 1e-26, which discards what rounding leaves.

Examples

truncate(state; limits = Limits(cutoff = 1e-10, maxdim = 50))

trace(::State)

the trace of the density matrix, or the squared norm of a pure state, computed once and kept with the state.

tr(::AbstractState)

the trace of the state, trace under the name LinearAlgebra gives it

purity(::State)

the purity $\mathrm{tr}(\rho^\dagger\rho) / (\mathrm{tr}\,\rho)^2$, which is $\mathrm{tr}(\rho^2)$ for a density matrix of trace one: 1 for a pure state, less for a mixed one, above 1 only for a matrix that is not positive or not Hermitian.

norm(::State)

the norm of the state: one for a normalized pure state, and on a mixed one the Hilbert-Schmidt norm $\sqrt{\mathrm{tr}(\rho^\dagger\rho)}$, not the trace.

normalize(::State)

the state rescaled to norm one on a pure representation, to a trace of real part one on a mixed one.

dag(::State)

the state whose density matrix is the adjoint of that of the state, computed once and kept with it. A pure representation is refused.

hermitianize(state; limits = Limits())

the state whose density matrix is the Hermitian part $(\rho + \rho^\dagger)/2$ of that of state, the sum truncated by limits. A pure representation is returned as it is.

hermiticity(::State)

how Hermitian the density matrix is, from 0 when it is anti-Hermitian to 1 when it is Hermitian, as it should be: $1/2 + \mathrm{Re}\,\mathrm{tr}(\rho^2)/(2\,\mathrm{tr}(\rho^\dagger\rho))$. 1 on a pure representation.

inner(a::State, b::State)
dot(a::State, b::State)

the inner product of two states of the same sites, taken on what both conserve, $\langle a | b \rangle$ on pure representations, $\mathrm{tr}(a^\dagger b)$ on mixed ones, not normalized.

inner(a::State, op, b::State)
dot(a::State, op, b::State)

$\langle a | op | b \rangle$ for the operator op, placed on sites, between two pure states of the same sites, taken on what both conserve, not normalised, through the MPO of op, an operator changing the charges by no definite amount being taken between the states conserving nothing, as by expect. Between two density matrices, for a channel or a generator, $\mathrm{tr}(a^\dagger\, op(b))$; a pure operator is ambiguous there, and refused.

fidelity(a, b)

the fidelity of two states of the same sites, taken on what both conserve, between 0 and 1, whatever their norms and traces: $|\langle a | b \rangle|^2$ on two pure representations, $\langle \psi | \rho | \psi \rangle$ on a pure and a mixed one, in either order. Two mixed representations are refused, their Uhlmann fidelity being out of reach for a matrix product state: use hs_fidelity.

Examples

fidelity(state, ground_state)

hs_fidelity(a::State{Mixed}, b::State{Mixed})

the normalised Hilbert-Schmidt overlap of two mixed states of the same sites, taken on what both conserve, $\mathrm{tr}(ab)/\sqrt{\mathrm{tr}(a^2)\mathrm{tr}(b^2)}$, 1 exactly when they are proportional. This is not the Uhlmann fidelity, see fidelity.

random_state(Pure, system, linkdims; rng, eltype = ComplexF64)
random_state(state, linkdims; rng, eltype = ComplexF64)
random_state(Mixed, system, linkdims; rng, eltype = ComplexF64)
random_state(Mixed, system, states, linkdims; rng, eltype = ComplexF64)

a random state of link dimension linkdims: a pure state, the pure state randomised in its sector, or a mixed state drawn as a purification on twice the system, of link dimension isqrt(linkdims)^2. On a system conserving something, a pure state is drawn by randomising one of the sector wanted, and a mixed one from the local states its purification starts from, written as for State; a mixed state cannot be drawn on a system conserving something strongly. rng is the random number generator, the global one by default; eltype = Float64 gives a real state, cheaper to contract, correct only if the whole computation stays real.

Examples

random_state(Pure, system, 20)
random_state(Mixed, system, 16; eltype = Float64)
random_state(State{Pure}(System(6, Fermion(conserve = N)), "Occ"), 8)

partial_trace(state; keep)
partial_trace(state; trace_out)

the mixed state reduced to the sites at the positions keep, in increasing order, or with those at trace_out traced out: a mixed state on the system of the sites kept, in the order of the chain, with the trace of state. An operator of the sites kept has on it the value it has on state, fermionic signs included; tracing out a fermionic site with fermionic sites kept on its right may double the bond dimension.

A pure state is refused (mix it first), so is a state conserving something strongly (weaken it first), and so are tracing out every site, a site given twice and keep out of increasing order, which permute_sites gives once the trace is taken.

Examples

partial_trace(ρ; keep = 3:5)
partial_trace(ρ; trace_out = [1, 2])

mps_state(system, tensors)

the pure state of system, normalized, whose MPS has the tensors tensors, each an array A[l, s, r] in the basis of its site, the first of left dimension 1 and the last of right dimension 1. On a system carrying charges, a state of no definite charge is refused.

Examples

# the cluster state of a chain of qubits, each link carrying the state of the site on its
# left, and a sign when both sites are in "Dn"
A = zeros(2, 2, 2)
for l in 1:2, s in 1:2
    A[l, s, s] = l == s == 2 ? -1 : 1
end
mps_state(System(10, Qubit()), [ A[1:1, :, :], fill(A, 8)..., sum(A; dims = 3) ])

dense_state(system, ψ; limits = Limits())
dense_state(system, ρ; limits = Limits())

the pure state of system of vector ψ, or the mixed state of density matrix ρ, normalized, on the basis of product states ordered as kron orders them, the first site varying the slowest. Its MPS is decomposed from the whole array and truncated to limits, by default cutoff = 1e-26. On a system carrying charges, a state of no definite charge is refused.

Examples

dense_state(System(2, Qubit()), [1, 0, 0, 1])               # (|↑↑⟩ + |↓↓⟩)/√2
dense_state(System(2, Qubit()), [1 0 0 0 ; 0 0 0 0 ; 0 0 0 0 ; 0 0 0 1])

Vector(state::State{Pure})

the vector of the pure state, not normalized, on the basis of the product states ordered as kron orders them, the first site varying the slowest, as dense_state takes it and matrix(op, system) acts on it. It is refused beyond dense_max^2 elements, as many as the largest dense matrix TMS builds. The density matrix of a mixed state is given by reduced_density_matrix(ρ, 1:n).

Examples

Vector(State{Pure}(System(2, Qubit()), "+"))      # [0.5, 0.5, 0.5, 0.5]

superposition(system, terms; limits = Limits())

the pure state $\sum_k c_k |s^k_1 s^k_2 \dots s^k_n\rangle$ of terms, pairs c => states of a coefficient and the local pure states of a product state, given by their names or their vectors, one for every site or one for all of them, normalized. It is exact, of bond dimension the number of terms of nonzero coefficient, truncated to limits when they are given, by default cutoff = 0. On a system conserving something, the product states of these terms must have the same charge.

Examples

superposition(System(4, Qubit()),
              [1 => ["Up", "Dn", "Up", "Dn"], -1 => ["Dn", "Up", "Dn", "Up"]])
superposition(System(6, Qubit()), [1 => "Up", 1 => "Dn"])     # the GHZ state

mixture(system, terms; limits = Limits())

the mixed state $\sum_k p_k \rho^k_1 \otimes \dots \otimes \rho^k_n$ of terms, pairs p => states of a weight, real and not negative, and the local states of a product state, pure or mixed, given by their names, their vectors or their density matrices, one for every site or one for all of them, normalized to trace one. It is exact, of bond dimension the number of terms of nonzero weight, truncated to limits when they are given, by default cutoff = 0.

Examples

mixture(System(4, Qubit()), [0.5 => ["Up", "Dn", "Up", "Dn"], 0.5 => ["Dn", "Up", "Dn", "Up"]])

ghz_state(system, states...)

the GHZ state of states, local pure states given by their names or their vectors: the superposition with equal weights of the product states in which every site is in the same one, $(|aa\dots a\rangle + |bb\dots b\rangle + \dots)/\sqrt{m}$ for orthonormal states, normalized in any case. It is exact, of bond dimension the number of states. On sites conserving something, the product states must have the same charge.

Examples

ghz_state(System(10, Qubit()), "Up", "Dn")
ghz_state(System(6, Qudit(3)), "0", "1", "2")

dicke_state(system, k, a, b)

the Dicke state of k sites in the local pure state b and the others in a, given by their names or their vectors: the superposition with equal weights of the product states that place b on k sites and a on the others, $\binom{n}{k}^{-1/2} \sum |a\dots b \dots a\rangle$ for orthonormal states, normalized in any case. It is exact, of bond dimension k + 1 at most, and holds the charge of its product states, which share it.

Examples

dicke_state(System(10, Qubit()), 3, "Up", "Dn")
dicke_state(System(10, Qubit(conserve = N)), 5, "Up", "Dn")

w_state(system, a, b)
w_state(system, a, b, amplitudes)

the W state, the Dicke state of one site in b and the others in a, see dicke_state. With amplitudes, one for each site, the superposition $\sum_j \phi_j |a \dots a b_j a \dots a\rangle$ of the states in which site j alone is in b, normalized: a wave packet of a single excitation, of bond dimension 2.

Examples

w_state(System(10, Qubit()), "Up", "Dn")
w_state(System(40, Qubit()), "Up", "Dn",
        [ exp(-(j - 10)^2 / 8 + im * π / 2 * j) for j in 1:40 ])

dimer_state(system, pairs, a, b; others, limits = Limits())

the state of a singlet $(|ab\rangle - |ba\rangle)/\sqrt{2}$ on each pair (i, j) of pairs, a on i in the first term, of the local pure states a and b, given by their names or their vectors and orthonormal: "Up" and "Dn" for spins one half. The sites in no pair take the local state others, one for all of them or a vector of one for each, which they then need. On fermionic sites, when a and b are of different parities, $|ba\rangle$ is $|ab\rangle$ with the fermion moved from one site of the pair to the other by a hopping $c^\dagger c$, whose string gives it the sign of the occupied sites between: the singlet of fermions, which differs from that of the products of local vectors when the pair spans occupied sites.

The pairs need not be neighbours: pairs of neighbours give the Majumdar-Ghosh state, of bond dimension 2, and nested pairs (i, n + 1 - i) the rainbow state, of bond dimension $2^{n/2}$ in the middle. limits constrains the truncations made as the singlets are applied.

Examples

dimer_state(System(10, Qubit()), [ (i, i + 1) for i in 1:2:9 ], "Up", "Dn")
dimer_state(System(9, Spin(1/2)), [ (i, i + 1) for i in 1:2:7 ], "1/2", "-1/2";
            others = "1/2")

fully_mixed(system, quantities...)

the fully mixed state of the sector given by quantities, pairs op => value where the sum of op over the sites takes the value: the projector on the basis states of the sector divided by their number, from which Thermalize gives the canonical thermal state of a Hamiltonian conserving these quantities. Each op must be diagonal on the basis of every site, as a number of particles or an $S^z$, but the sites need not conserve it. Without quantities, it is the fully mixed state of the system, which a system conserving something strongly refuses: give a sector fixing what it conserves strongly. It is exact, of bond dimension N + 1 at most for N => N.

Examples

fully_mixed(System(10, Fermion()), N => 4)
fully_mixed(System(8, Electron(conserve = (strong(Ntot), 2Sz))), Ntot => 8, Sz => 0)

slater_state(system, orbitals...; others, limits = Limits())

the Slater determinant of orbitals, one matrix $\Phi$ for each species of fermions of the sites, in the order the species first appear along them (C for a Fermion, Cup then Cdn for an Electron). The matrix of a species has a row for each site holding it, in their order, and a column for each fermion of that species: column k holds the amplitudes of orbital k, the columns being orthonormal. The state is $\prod_k \left(\sum_i \Phi_{ik} c_i^\dagger\right) |0\rangle$, up to a global phase, so that $\langle c_i^\dagger c_j \rangle = \sum_k \overline{\Phi_{ik}} \Phi_{jk}$, $|0\rangle$ being the vacuum of every site holding fermions.

The sites holding no fermions take the local state others, one for all of them or a vector of one for each, which they then need.

It is built by a circuit of rotations of neighbouring modes (Fishman and White, 2015), exact to 1e-12 on the correlations; limits constrains the truncations made as it is applied, the entanglement of a determinant growing with the size of the system. The sites may conserve the number of fermions of each species, weakly or strongly.

Examples

slater_state(System(10, Fermion()), orbitals)
slater_state(System(10, Electron(conserve = (Ntot, 2Sz))), up, down;
             limits = Limits(cutoff = 1e-12))
slater_state(System([Fermion(), Fermion(), Qubit(), Fermion()]), orbitals; others = "Up")

fermi_sea(system, hamiltonian, nparticles...; others, limits = Limits())

the ground state of nparticles free fermions of each species of the sites, in the order they first appear, under hamiltonian, a quadratic Hamiltonian conserving the number of each, $E_0 + \sum_{ij} h_{ij} c_i^\dagger c_j$ for each species: the Slater determinant of the nparticles lowest orbitals of h, see slater_state, whose others and limits it takes.

A Hamiltonian of another form is refused, as one with an interaction, a term mixing species or a term acting on the sites holding no fermions, and so is a number of fermions filling a degenerate level in part: the message gives the nearest numbers that fill it, and a small term added to the Hamiltonian lifts the degeneracy.

Examples

sea = fermi_sea(System(20, Fermion()), -sum(dag(C)(i) * C(i + 1) + dag(C)(i + 1) * C(i)
                                            for i in 1:19), 7)
ring = -sum(dag(C)(i) * C(j) + dag(C)(j) * C(i) for (i, j) in circle_graph(10))
fermi_sea(System(10, Fermion()), ring + 1e-3 * N(1), 4)    # 4 alone fills a level in part
hop(c) = -sum(dag(c)(i) * c(i + 1) + dag(c)(i + 1) * c(i) for i in 1:7)
fermi_sea(System(8, Electron()), hop(Cup) + hop(Cdn), 3, 3)

a ⊗ b
tensor(a, b)

the product of the states a and b, on the system a.system ⊗ b.system, the sites of b following those of a: exact, its bond dimension the larger of theirs, its norm or its trace the product of theirs. A pure state with a mixed one is mixed, see mix. On fermions, the operators of a stand on the left of those of b: the fermionic product of two states of definite parity.

Examples

ψ ⊗ State{Pure}(System(2, Qubit()), "Up")       # two qubits more
left ⊗ right                                     # two halves made apart

permute_sites(state, p; limits = Limits())

the state with its sites moved, site k to position p[k], p a permutation of the positions: an operator measures on it what map_sites(k -> p[k], op) measures on state. The sites are moved by exchanges of neighbours, each truncated by limits, by default cutoff = 1e-26, as many as the pairs of sites p puts in the other order. The bond dimension may grow: two states interleaved, a ⊗ b with the sites of b moved between those of a, have the product of their bond dimensions. On fermions, two odd states exchanged give a sign, as Swap.

Examples

permute_sites(ψ, [1, 3, 5, 2, 4, 6])        # the halves of a chain of 6 sites interleaved
permute_sites(ψ, n:-1:1)                    # a chain of n sites reversed

save_state(filename, statename, state)

save the state in the HDF5 file filename under the name statename, replacing a state saved under that name. Every field of every site must be a number, a boolean, a symbol, a string, nothing or a Conservation.

Examples

save_state("myfile.h5", "ground_state", state)

load_state(filename, statename)

the state saved under the name statename in the file filename by save_state, on the system of its sites. The modules defining its site types, and the state type of an extension, must be loaded.

Examples

load_state("myfile.h5", "ground_state")