AbstractQuantumSystem

Abstract type for defining systems.

CompositeQuantumSystem <: AbstractQuantumSystem

A composite quantum system consisting of subsystems. Couplings between subsystems can be additionally defined. Subsystem drives are always appended to any new coupling drives.

OpenQuantumSystem <: AbstractQuantumSystem

A struct for storing open quantum dynamics.

Additional fields

• dissipation_operators::Vector{AbstractMatrix}: The dissipation operators.

See also QuantumSystem.

QuantumSystem <: AbstractQuantumSystem

A struct for storing quantum dynamics.

Fields

• H::Function: The Hamiltonian function, excluding dissipation: a -> H(a).
• G::Function: The isomorphic generator function, including dissipation, a -> G(a).
• levels::Int: The number of levels in the system.
• n_drives::Int: The number of drives in the system.

TimeDependentQuantumSystem <: AbstractQuantumSystem

A struct for storing time-dependent quantum dynamics.

Fields

• H::Function: The Hamiltonian function with time: (a, t) -> H(a, t).
• G::Function: The isomorphic generator function with time, (a, t) -> G(a, t).
• n_drives::Int: The number of drives in the system.
• levels::Int: The number of levels in the system.
• params::Dict{Symbol, Any}: A dictionary of parameters.

VariationalQuantumSystem <: AbstractQuantumSystem

A struct for storing variational quantum dynamics.

Additional fields

• G_vars::AbstractVector{<:Function}: Variational generator functions

See also QuantumSystem.

get_drift(sys::AbstractQuantumSystem)

Returns the drift Hamiltonian of the system.

get_drives(sys::AbstractQuantumSystem)

Returns the drive Hamiltonians of the system.

lift_operator(operator::AbstractMatrix{<:Number}, i::Int, subsystem_levels::Vector{Int})
lift_operator(operator::AbstractMatrix{<:Number}, i::Int, n_qubits::Int; kwargs...)
lift_operator(operators::AbstractVector{<:AbstractMatrix{T}}, indices::AbstractVector{Int}, subsystem_levels::Vector{Int})
lift_operator(operators::AbstractVector{<:AbstractMatrix{T}}, indices::AbstractVector{Int}, n_qubits::Int; kwargs...)
lift_operator(operator::AbstractMatrix{T}, indices::AbstractVector{Int}, subsystem_levels::AbstractVector{Int})
lift_operator(operator::AbstractMatrix{T}, indices::AbstractVector{Int}, n_qubits::Int; kwargs...)

Lift an operator acting on the i-th subsystem within subsystem_levels to an operator acting on the entire system spanning subsystem_levels.

A constant dictionary GATES containing common quantum gate matrices as complex-valued matrices. Each gate is represented by its unitary matrix.

• GATES[:I] - Identity: Leaves the state unchanged.
• GATES[:X] - Pauli-X (NOT): Flips the qubit state.
• GATES[:Y] - Pauli-Y: Rotates the qubit state around the Y-axis of the Bloch sphere.
• GATES[:Z] - Pauli-Z: Flips the phase of the qubit state.
• GATES[:H] - Hadamard: Creates superposition by transforming basis states.
• GATES[:CX] - Controlled-X (CNOT): Flips the 2nd qubit (target) if the first qubit (control) is |1⟩.
• GATES[:CZ] - Controlled-Z (CZ): Flips the phase of the 2nd qubit (target) if the 1st qubit (control) is |1⟩.
• GATES[:XI] - Complex: A gate for complex operations.
• GATES[:sqrtiSWAP] - Square root of iSWAP: Partially swaps two qubits with a phase.

The 2×2 Pauli matrics and identity.

AbstractPiccoloOperator

Union type for operators.

EmbeddedOperator

Embedded operator type to represent an operator embedded in a subspace of a larger quantum system.

Fields

• operator::Matrix{<:Number}: Embedded operator of size prod(subsystem_levels) x prod(subsystem_levels).
• subspace::Vector{Int}: Indices of the subspace the operator is embedded in.
• subsystem_levels::Vector{Int}: Levels of the subsystems in the composite system.

EmbeddedOperator(
    subspace_operator::AbstractMatrix{<:Number},
    subsystem_indices::AbstractVector{Int},
    subspaces::AbstractVector{<:AbstractVector{Int}},
    subsystem_levels::AbstractVector{Int}
)

Embed the subspace_operator into the provided subspaces of a composite system, where the subsystem_indices list the subspaces at which the operator is defined, and the subsystem_levels list the levels of the subsystems in which the operator is embedded.

EmbeddedOperator(
    subspace_operator::AbstractMatrix{<:Number},
    subsystem_indices::AbstractVector{Int},
    subspaces::AbstractVector{<:AbstractVector{Int}},
    composite_system::CompositeQuantumSystem
)

Embed the subspace_operator into the provided subspaces of a composite system.

EmbeddedOperator(subspace_operator::AbstractMatrix{<:Number}, system::QuantumSystem; kwargs...)

Embed the subspace_operator into a quantum system.

EmbeddedOperator(subspace_operator::Matrix{<:Number}, subspace::AbstractVector{Int}, subsystem_levels::AbstractVector{Int})

Create an embedded operator. The operator is embedded at the subspace of the system spanned by the subsystem_levels.

embed(subspace_operator::AbstractMatrix{<:Number}, embedded_operator::EmbeddedOperator)

Embed the subspace_operator in the subspace of a larger embedded_operator.

embed(operator::AbstractMatrix{<:Number}, subspace::AbstractVector{Int}, levels::Int)

Embed an operator in the subspace of a larger matrix of size levels x levels.

get_enr_subspace_indices(excitation_restriction::Int, subsystem_levels::AbstractVector{Int})

Get the indices for the subspace of the quantum system with an excitation restriction.

get_iso_vec_leakage_indices(subspace::AbstractVector{Int}, levels::Int)
get_iso_vec_leakage_indices(subspaces::AbstractVector{<:AbstractVector{Int}}, subsystem_levels::AbstractVector{Int})
get_iso_vec_leakage_indices(subsystem_levels::AbstractVector{Int}; subspace=1:2)
get_iso_vec_leakage_indices(op::EmbeddedOperator)

Get the indices for the leakage in the isomorphic vector space for operators.

get_iso_vec_subspace_indices(subspace::AbstractVector{Int}, subsystem_levels::AbstractVector{Int})
get_iso_vec_subspace_indices(op::EmbeddedOperator)

Get the indices for the subspace in the isomorphic vector space for operators.

get_leakage_indices(subspace::AbstractVector{Int}, levels::Int)
get_leakage_indices(subspaces::AbstractVector{<:AbstractVector{Int}}, subsystem_levels::AbstractVector{Int})
get_leakage_indices(subsystem_levels::AbstractVector{Int}; subspace=1:2)
get_leakage_indices(op::EmbeddedOperator)

Get the indices for the states that are outside of the provided subspace of the quantum system.

get_subspace_indices(subspace::AbstractVector{Int}, levels::Int)
get_subspace_indices(subspaces::Vector{<:AbstractVector{Int}}, subsystem_levels::AbstractVector{Int})
get_subspace_indices(subsystem_levels::AbstractVector{Int}; subspace=1:2)
get_subspace_indices(op::EmbeddedOperator)

Get the indices for the provided subspace of the quantum system.

unembed(matrix::AbstractMatrix{<:Number}, subspace::AbstractVector{Int})

Unembed a subspace operator from the matrix. This is equivalent to calling matrix[subspace, subspace].

unembed(op::AbstractMatrix, embedded_op::EmbeddedOperator)

Unembed a sub-matrix from the op at the subspace defined by embedded_op.

unembed(embedded_op::EmbeddedOperator)

Unembed an embedded operator, returning the original operator.

G(H::AbstractMatrix)::Matrix{Float64}

Returns the isomorphism of $-iH$, i.e. $G(H) = \text{iso}(-iH)$.

See also Isomorphisms.iso, Isomorphisms.H.

H(G::AbstractMatrix{<:Real})

Returns the inverse of $G(H) = iso(-iH)$, i.e. returns H.

See also Isomorphisms.iso, Isomorphisms.G.

ad_vec(H::AbstractMatrix{ℂ}; anti::Bool=false) where ℂ <: Number

Returns the vectorized adjoint action of a matrix H:

\[\text{ad_vec}(H) = \mqty(1 & 0 \\ 0 & 1) \otimes H - (-1)^{\text{anti}} \mqty(0 & 1 \\ 1 & 0) \otimes H^*\]

density_to_iso_vec(ρ::AbstractMatrix{<:Number})

Returns the isomorphism ρ⃗̃ = ket_to_iso(vec(ρ)) of a density matrix ρ

iso(H::AbstractMatrix{<:Number})

Returns the isomorphism of $H$:

\[iso(H) = \widetilde{H} = \mqty(1 & 0 \\ 0 & 1) \otimes \Re(H) + \mqty(0 & -1 \\ 1 & 0) \otimes \Im(H)\]

where $\Im(H)$ and $\Re(H)$ are the imaginary and real parts of $H$ and the tilde indicates the standard isomorphism of a complex valued matrix:

\[\widetilde{H} = \mqty(1 & 0 \\ 0 & 1) \otimes \Re(H) + \mqty(0 & -1 \\ 1 & 0) \otimes \Im(H)\]

See also Isomorphisms.G, Isomorphisms.H.

iso_D(L::AbstractMatrix{ℂ}) where ℂ <: Number

Returns the isomorphic representation of the Lindblad dissipator L.

iso_operator_to_iso_vec(Ũ::AbstractMatrix{ℝ}) where ℝ <: Real

Convert a real matrix Ũ representing an isomorphism operator into a real vector.

iso_operator_to_operator(Ũ)

iso_to_ket(ψ̃::AbstractVector{<:Real})

Convert a real isomorphism vector ψ̃ into a ket vector.

iso_vec_to_density(ρ⃗̃::AbstractVector{<:Real})

Returns the density matrix ρ from its isomorphism ρ⃗̃

iso_vec_to_iso_operator(Ũ⃗::AbstractVector{ℝ}) where ℝ <: Real

Convert a real vector Ũ⃗ into a real matrix representing an isomorphism operator.

iso_vec_to_operator(Ũ⃗::AbstractVector{ℝ}) where ℝ <: Real

Convert a real vector Ũ⃗ into a complex matrix representing an operator.

ket_to_iso(ψ::AbstractVector{<:Number})

Convert a ket vector ψ into a complex vector with real and imaginary parts.

mat(x::AbstractVector)

Convert a vector x into a square matrix. The length of x must be a perfect square.

operator_to_iso_operator(U)

operator_to_iso_vec(U::AbstractMatrix{ℂ}) where ℂ <: Number

Convert a complex matrix U representing an operator into a real vector.

var_G(G::AbstractMatrix{<:Real}, G_vars::AbstractVector{<:AbstractMatrix{<:Real}})

Returns the variational generator of G with variational derivatives, G_vars.

The variational generator is

\[\text{var}_G(G, [G_a, G_b]) = \mqty( G & 0 & 0 \\ G_a & G & 0 \\ G_b & 0 & G )\]

where G is the isomorphism of a Hamiltonian and G_a and G_b are the variational derivatives of G for parameters a and b, respectively.

annihilate(levels::Int)

Get the annihilation operator for a system with levels.

create(levels::Int)

Get the creation operator for a system with levels.

haar_identity(n::Int, radius::Number)

Generate a random unitary matrix close to the identity matrix using the Haar measure for an n-dimensional system with a given radius. The smaller the radius, the closer the matrix will be to the identity.

haar_random(n::Int)

Generate a random unitary matrix using the Haar measure for an n-dimensional system.

ket_from_bitstring(ket::String)

Get the state vector for a qubit system given a ket string ket of 0s and 1s.

ket_from_string(
    ket::String,
    levels::Vector{Int};
    level_dict=Dict(:g => 0, :e => 1, :f => 2, :h => 3, :i => 4, :j => 5, :k => 6, :l => 7),
    return_states=false
)

Construct a quantum state from a string ket representation.

operator_from_string(operator::String; lookup=PAULIS)

Reduce the string (each character is one key) via operators from a dictionary.

is_linearly_dependent(M::AbstractMatrix; eps=eps(Float32), verbose=true)

Check if the columns of the matrix M are linearly dependent.

is_reachable(gate::AbstractMatrix{<:Number}, system::AbstractQuantumSystem; kwargs...)

Check if the gate is reachable using the given system.

Keyword Arguments

• use_drift::Bool=true: include drift Hamiltonian in the generators
• kwargs...: keyword arguments for is_reachable

is_reachable(gate, hamiltonians; kwargs...)

Check if the gate is reachable using the given hamiltonians.

Arguments

• gate::AbstractMatrix: target gate
• hamiltonians::AbstractVector{<:AbstractMatrix}: generators of the Lie algebra

Keyword Arguments

• subspace::AbstractVector{<:Int}=1:size(gate, 1): subspace indices
• compute_basis::Bool=true: compute the basis or use the Hamiltonians directly
• remove_trace::Bool=true: remove trace from generators
• verbose::Bool=true: print information about the operator algebra
• atol::Float32=eps(Float32): absolute tolerance

See also QuantumSystemUtils.operator_algebra.

operator_algebra(generators; kwargs...)

Compute the Lie algebra basis for the given generators.

Arguments

• generators::Vector{<:AbstractMatrix}: generators of the Lie algebra

Keyword Arguments

• return_layers::Bool=false: return the Lie tree layers
• normalize::Bool=false: normalize the basis
• verbose::Bool=false: print information
• remove_trace::Bool=true: remove trace from generators

direct_sum(A::AbstractMatrix, B::AbstractMatrix)

Returns the direct sum of two matrices.

direct_sum(Ã⃗::AbstractVector, B̃⃗::AbstractVector)

Returns the direct sum of two iso_vec operators.

direct_sum(sys1::QuantumSystem, sys2::QuantumSystem)

Returns the direct sum of two QuantumSystem objects.

direct_sum(A::SparseMatrixCSC, B::SparseMatrixCSC)

Returns the direct sum of two sparse matrices.

fidelity(ρ::AbstractMatrix{<:Number}, ρ_goal::AbstractMatrix{<:Number})

Calculate the fidelity between two density matrices ρ and ρ_goal.

fidelity(ψ::AbstractVector{<:Number}, ψ_goal::AbstractVector{<:Number})

Calculate the fidelity between two quantum states ψ and ψ_goal.

free_phase(phases::AbstractVector{<:Real}, phase_operators::AbstractVector{<:AbstractMatrix{<:ℂ}})

Rotate the phase_operators by the phases and return the Kronecker product.

infer_is_evp(integrator::Function)

Infer whether the integrator is a exponential-vector product (EVP) function.

If true, the integrator is expected to have a signature like the exponential action, expv. Otherwise, it is expected to have a signature like exp.

open_rollout(
    ρ⃗₁::AbstractVector{<:Complex},
    controls::AbstractMatrix{<:Real},
    Δt::AbstractVector,
    system::OpenQuantumSystem;
    kwargs...
)

Rollout a quantum state ρ⃗₁ under the control controls for a time Δt

Arguments

• ρ⃗₁::AbstractVector{<:Complex}: Initial state vector
• controls::AbstractMatrix{<:Real}: Control matrix
• Δt::AbstractVector: Time steps
• system::OpenQuantumSystem: Quantum system

Keyword Arguments

• show_progress::Bool=false: Show progress bar
• integrator::Function=expv: Integrator function
• exp_vector_product::Bool: Infer whether the integrator is an exponential-vector product

open_rollout(
    ρ₁::AbstractMatrix{<:Complex},
    controls::AbstractMatrix{<:Real},
    Δt::AbstractVector,
    system::OpenQuantumSystem;
    kwargs...
)

Rollout a density matrix ρ₁ under the control controls and timesteps Δt

open_rollout_fidelity(
    ρ⃗₁::AbstractVector{<:Complex},
    ρ⃗₂::AbstractVector{<:Complex},
    controls::AbstractMatrix{<:Real},
    Δt::AbstractVector,
    system::OpenQuantumSystem
)
open_rollout_fidelity(
    ρ₁::AbstractMatrix{<:Complex},
    ρ₂::AbstractMatrix{<:Complex},
    controls::AbstractMatrix{<:Real},
    Δt::AbstractVector,
    system::OpenQuantumSystem
)
open_rollout_fidelity(
    traj::NamedTrajectory,
    system::OpenQuantumSystem;
    state_name::Symbol=:ρ⃗̃,
    control_name::Symbol=:a,
    kwargs...
)

Calculate the fidelity between the final state of an open quantum system rollout and a goal state.

rollout(
    ψ̃_init::AbstractVector{<:Real},
    controls::AbstractMatrix{<:Real},
    Δt::AbstractVector,
    system::AbstractQuantumSystem
)
rollout(
    ψ_init::AbstractVector{<:Complex},
    controls::AbstractMatrix{<:Real},
    Δt::AbstractVector,
    system::AbstractQuantumSystem
)
rollout(
    inits::AbstractVector{<:AbstractVector},
    controls::AbstractMatrix{<:Real},
    Δt::AbstractVector,
    system::AbstractQuantumSystem
)

Rollout a quantum state ψ̃_init under the control controls for a time Δt using the system system.

If exp_vector_product is true, the integrator is expected to have a signature like the exponential action, expv. Otherwise, it is expected to have a signature like exp.

Types should allow for autodifferentiable controls and times.

rollout_fidelity(
    ψ̃_init::AbstractVector{<:Real},
    ψ̃_goal::AbstractVector{<:Real},
    controls::AbstractMatrix{<:Real},
    Δt::AbstractVector,
    system::AbstractQuantumSystem
)
rollout_fidelity(
    ψ_init::AbstractVector{<:Complex},
    ψ_goal::AbstractVector{<:Complex},
    controls::AbstractMatrix{<:Real},
    Δt::AbstractVector,
    system::AbstractQuantumSystem
)
rollout_fidelity(
    trajectory::NamedTrajectory,
    system::AbstractQuantumSystem
)

Calculate the fidelity between the final state of a rollout and a goal state.

unitary_fidelity(U::AbstractMatrix{<:Number}, U_goal::AbstractMatrix{<:Number})

Calculate the fidelity between unitary operators U and U_goal in the subspace.

unitary_free_phase_fidelity(
    U::AbstractMatrix,
    U_goal::AbstractMatrix,
    phases::AbstractVector{<:Real},
    phase_operators::AbstractVector{<:AbstractMatrix};
    subspace::AbstractVector{Int}=axes(U, 1)
)

Calculate the fidelity between unitary operators U and U_goal in the subspace, including the phase rotations about the phase_operators.

unitary_rollout(
    Ũ⃗_init::AbstractVector{<:Real},
    controls::AbstractMatrix{<:Real},
    Δt::AbstractVector,
    system::AbstractQuantumSystem;
    kwargs...
)

Rollout a isomorphic unitary operator Ũ⃗_init under the control controls for a time Δt using the system system.

Arguments

• Ũ⃗_init::AbstractVector{<:Real}: Initial unitary vector
• controls::AbstractMatrix{<:Real}: Control matrix
• Δt::AbstractVector: Time steps
• system::AbstractQuantumSystem: Quantum system

Keyword Arguments

• show_progress::Bool=false: Show progress bar
• integrator::Function=expv: Integrator function
• exp_vector_product::Bool: Infer whether the integrator is an exponential-vector product

unitary_rollout_fidelity(
    Ũ⃗_init::AbstractVector{<:Real},
    Ũ⃗_goal::AbstractVector{<:Real},
    controls::AbstractMatrix{<:Real},
    Δt::AbstractVector,
    system::AbstractQuantumSystem;
    kwargs...
)
unitary_rollout_fidelity(
    Ũ⃗_goal::AbstractVector{<:Real},
    controls::AbstractMatrix{<:Real},
    Δt::AbstractVector,
    system::AbstractQuantumSystem;
    kwargs...
)
unitary_rollout_fidelity(
    U_init::AbstractMatrix{<:Complex},
    U_goal::AbstractMatrix{<:Complex},
    controls::AbstractMatrix{<:Real},
    Δt::AbstractVector,
    system::AbstractQuantumSystem;
    kwargs...
)
unitary_rollout_fidelity(
    U_goal::AbstractMatrix{<:Complex},
    controls::AbstractMatrix{<:Real},
    Δt::AbstractVector,
    system::AbstractQuantumSystem;
    kwargs...
)
unitary_rollout_fidelity(
    U_goal::EmbeddedOperator,
    controls::AbstractMatrix{<:Real},
    Δt::AbstractVector,
    system::AbstractQuantumSystem;
    subspace::AbstractVector{Int}=U_goal.subspace,
    kwargs...
)
unitary_rollout_fidelity(
    traj::NamedTrajectory,
    sys::AbstractQuantumSystem;
    kwargs...
)

Calculate the fidelity between the final state of a unitary rollout and a goal state. If the initial unitary is not provided, the identity operator is assumed. If phases and phase_operators are provided, the free phase unitary fidelity is calculated.

variational_rollout(
    ψ̃_init::AbstractVector{<:Real},
    controls::AbstractMatrix{<:Real},
    Δt::AbstractVector{<:Real},
    system::VariationalQuantumSystem;
    show_progress::Bool=false,
    integrator::Function=expv,
    exp_vector_product::Bool=infer_is_evp(integrator)
)
variational_rollout(ψ::Vector{<:Complex}, args...; kwargs...)
variational_rollout(inits::AbstractVector{<:AbstractVector}, args...; kwargs...)
variational_rollout(
    traj::NamedTrajectory, 
    system::AbstractQuantumSystem; 
    state_name::Symbol=:ψ̃,
    drive_name::Symbol=:a,
    kwargs...
)

Simulates the variational evolution of a quantum state under a given control trajectory.

Returns

• Ψ̃::Matrix{<:Real}: The evolved quantum state at each timestep.
• Ψ̃_vars::Vector{<:Matrix{<:Real}}: The variational derivatives of the quantum state with respect to the variational parameters.

Notes

This function computes the variational evolution of a quantum state using the variational generators of the system. It supports autodifferentiable controls and timesteps, making it suitable for optimization tasks. The variational derivatives are computed alongside the state evolution, enabling sensitivity analysis and gradient-based optimization.

variational_unitary_rollout(
    Ũ⃗_init::AbstractVector{<:Real},
    controls::AbstractMatrix{<:Real},
    Δt::AbstractVector{<:Real},
    system::VariationalQuantumSystem;
    show_progress::Bool=false,
    integrator::Function=expv,
    exp_vector_product::Bool=infer_is_evp(integrator)
)
variational_unitary_rollout(
    controls::AbstractMatrix{<:Real},
    Δt::AbstractVector,
    system::VariationalQuantumSystem;
    kwargs...
)
variational_unitary_rollout(
    traj::NamedTrajectory,
    system::VariationalQuantumSystem;
    unitary_name::Symbol=:Ũ⃗,
    drive_name::Symbol=:a,
    kwargs...
)

Simulates the variational evolution of a quantum state under a given control trajectory.

Returns

• Ũ⃗::Matrix{<:Real}: The evolved unitary at each timestep.
• Ũ⃗_vars::Vector{<:Matrix{<:Real}}: The variational derivatives of the unitary with respect to the variational parameters.

Notes

This function computes the variational evolution of a unitary using the variational generators of the system. It supports autodifferentiable controls and timesteps, making it suitable for optimization tasks. The variational derivatives are computed alongside the state evolution, enabling sensitivity analysis and gradient-based optimization.