State API Documentation

HadaMAG.jl: StateVec

A lightweight container for a pure quantum state of n q-dits (q = qudit dimension, 2 for qubits) stored in the computational basis |0 ... 00⟩, |0 ... 01⟩, ..., |q−1 ... (q−1)⟩.

StateVec(vec::AbstractVector{<:Complex}; q::Int = 2)

Create a StateVec from an existing amplitude vector vec. Throws ArgumentError if length(vec) is not an exact power of q.

Arguments

• vec: Vector of complex amplitudes.
• q: Dimension of each qudit (default = 2 for qubits).

Returns

• A StateVec containing a copy of vec and inferred n & q.

Example

julia> ψ = randn(ComplexF64, 2^4);
julia> StateVec(ψ) # defaults to qubits
StateVec{Float64,2}(n=4, q=2)

apply_2gate!(state::AbstractVector{Complex{T}}, gate::AbstractMatrix{Complex{T}}, q1::Int, q2::Int)

Apply in-place a two-qubit gate (4×4 matrix) to qubits q1,q2 (1-based) on state. state must have length 2^n and contain amplitude data in computational basis.

apply_2gate!(sv::StateVec{T,2}, gate::AbstractMatrix{T}, q1::Int, q2::Int)

Apply a two-qubit gate directly on a StateVec{T,2}.

apply_brick_wall_haar!(state::AbstractVector{ComplexF64}, nqubits::Integer, depth::Integer; rng::AbstractRNG = Random.GLOBAL_RNG)

Apply an in-place “brick-wall” of Haar-random 2-qubit unitaries to state. The circuit has depth layers; odd layers act on qubits (1,2),(3,4),...; even on (2,3),(4,5),...

Arguments

• state: length-2^nqubits state vector (will be mutated).
• nqubits: number of qubits.
• depth: number of alternating layers.
• rng: keyword RNG (defaults to GLOBAL_RNG).

apply_brick_wall_haar!(ψ::StateVec{T,q}, L::Int, depth::Int, rng::AbstractRNG = Random.GLOBAL_RNG)

Apply a brick-wall Haar-random circuit to a state vector vec in-place. The circuit consists of depth layers of random unitary 2-qudit gates, alternating between even and odd qudit pairs.

Arguments

• ψ: StateVec to be modified.
• depth: Number of layers of gates.
• rng: Random number generator (default = Random.GLOBAL_RNG).

load_state(path::AbstractString; q::Int = 2) -> StateVec

Load a state vector from disk into a StateVec. The loaded vector is not renormalized; ensure it has unit norm if required.

Supported formats (by file extension):

• .jld2: Reads dataset "state" via JLD2.jl.
• .npy: Reads NumPy array via NPZ.jl.
• Otherwise: Whitespace-delimited real and imaginary parts.

Arguments

• path: Path to the file containing state amplitudes.
• q: Dimension of each qudit (default = 2).

Returns

• A StateVec constructed from the loaded data.

rand_haar(n::Int, depth::Int; rng::AbstractRNG = Random.GLOBAL_RNG)

Generate a Haar-random state on n qubits of local dimension 2, normalized to unit norm.

Arguments

• depth::Int: number of layers of random 2-qudit gates (brick-wall pattern) to apply to a state vector initialized with iid complex Gaussian entries.
• q::Int: dimension of each qudit (default = 2).

Keyword Arguments

• rng::AbstractRNG: random number generator (default = Random.GLOBAL_RNG).

HadaMAG.jl: DensityMatrix

A lightweight container for a mixed quantum state of n q-dits (q = qudit dimension, 2 for qubits) stored in the computational basis |0 ... 00⟩, |0 ... 01⟩, ..., |q−1 ... (q−1)⟩.

DensityMatrix(mat::AbstractMatrix{<:Complex}; q::Int = 2)

Create a DensityMatrix from an existing density matrix mat. Throws ArgumentError if mat is not square or if its size is not an exact power of q.

Arguments

• mat: Square matrix of complex amplitudes.
• q: Dimension of each qudit (default = 2 for qubits).

Returns

• A DensityMatrix containing a copy of mat and inferred n & q.

reduced_density_matrix(ψ, NA; q=3, side=:right)

Compute the reduced density matrix ρA = Tr_B(|ψ⟩⟨ψ|) for a contiguous bipartition of an N-site qudit state (with local dimension q), where dimA = q^NA and dimB = q^(N-NA).

The keyword argument side selects which end of the chain is kept as subsystem A (assuming the usual convention in this library that site 1 is the least-significant digit in the linear index, consistent with using q^(s-1) for site s):

• side = :left keeps sites 1:NA (least-significant): ρA[iA,jA] = ∑_{kB=0}^{dimB-1} ψ[iA + dimA*kB] * conj(ψ[jA + dimA*kB]).

• side = :right keeps sites (N-NA+1):N (most-significant). ρA[iA,jA] = ∑_{kB=0}^{dimB-1} ψ[iA*dimB + kB] * conj(ψ[jA*dimB + kB]).

Returns a DensityMatrix(ρA; q) of size q^NA × q^NA.