Welcome to numq’s documentation!

This project accelerates the simulation of quantum circuits through two backends: NumPy for CPU, and CuPy for GPU (CUDA based). A brief introduction is available from the project’s home page. Within this documentation, we list main functions exposed by this module.

Note

This project is a reserach project.

Note

Due to the singledispath mechanism, many functions are repeated, though with different signature, in this documentation. Only one of them is documented and other alternative implementations would perform the same calcualtion but on different type of inputs.

List of functions

numq.apply_isometry_to_density_matrices(...)

Applies the isometry to the density matrices.

numq.apply_kraus_ops_to_density_matrices()

Applies the Kraus operators to the density matrices.

numq.apply_unitary_transformation_to_density_matrices(...)

Applies the unitary transformation to the density matrices.

numq.commutator()

Returns the commutator of two matrices or operators.

numq.format_wavefunction()

Prints the components of the wavefunction visually. The argument reverse_qubitstr will reverse the sting representation of qubit's basis. For example, wf[1] will go from the |01> basis to the |10> basis.

numq.get_random_ru(np[, n])

Get a random unitary matrix of size n x n through QR decomposition of a random matrix with real and imaginary parts each sampled element-wise from a uniform distribution.

numq.get_random_wf(np, nqb[, nwf])

Get a random wavefunction distributed according to Haar measure on the complex unitary sphere.

numq.get_randu(np, nqb)

Generates a n qubit random unitary matrix, distributed uniformly according to the Haar measure.

numq.load_state_into_mqb_start_from_lqb()

Loads states (columns of wavefunctions) from the smaller, and initialise the new qubits to 0.

numq.load_states_into(states, total_qb, pos)

Loads the input states into the positions (pos), within a total qubits by total_qb.

numq.make_density_matrix()

Make a density matrix from a wavefunction, i.e., compute the "ket-bra".

numq.partial_trace()

Compute the partial trace of rho.

numq.partial_trace_wf()

Partial trace on wavefunctions.

numq.partial_trace_wf_keep_first()

Partial trace which keeps only the first n qubits

numq.rand_herm(np[, nqb, dim])

Generates a random Hermitian matrix.
numq.apply_isometry_to_density_matrices(isometry, density_matrices)

Applies the isometry to the density matrices.

Parameters:

  • isometry – The isometry to apply.

  • density_matrices – The density matrices to which the isometry is applied.

Returns:

The density matrices after applying the isometry.

numq.apply_kraus_ops_to_density_matrices(kraus_ops, density_matrices)
numq.apply_kraus_ops_to_density_matrices(unitary: ndarray, density_matrices)

Applies the Kraus operators to the density matrices.

Parameters:

  • kraus_ops – The Kraus operators to apply.

  • density_matrices – The density matrices to which the Kraus operators are applied.

Returns:

The density matrices after applying the Kraus operators.

numq.apply_unitary_transformation_to_density_matrices(unitary, density_matrices)

Applies the unitary transformation to the density matrices.

Parameters:

  • unitary – The unitary transformation to apply.

  • density_matrices – The density matrices to which the unitary transformation is applied.

Returns:

The density matrices after applying the unitary transformation.

numq.commutator(a, b)
numq.commutator(a: ndarray, b: ndarray)

Returns the commutator of two matrices or operators.

Parameters:

  • a – The first matrix or operator.

  • b – The second matrix or operator.

Returns:

The commutator [a, b] = ab - ba.

numq.format_wavefunction(wf, precision=8, skip_zeros=False, reverse_qubitstr=False)
numq.format_wavefunction(wf: ndarray, precision=8, skip_zeros=False, reverse_qubitstr=False)

Prints the components of the wavefunction visually. The argument reverse_qubitstr will reverse the sting representation of qubit’s basis. For example, wf[1] will go from the |01> basis to the |10> basis.

Parameters:

  • wf – The wavefunction to format.

  • precision – The number of decimal places to display.

  • skip_zeros – If True, skips the components that are close to zero.

  • reverse_qubitstr – If True, reverses the string representation of qubit’s basis. This is similar to reversing the endianness in binary representation.

Returns:

A formatted string representation of the wavefunction.

numq.get_random_ru(np, n=2)

Get a random unitary matrix of size n x n through QR decomposition of a random matrix with real and imaginary parts each sampled element-wise from a uniform distribution.

Parameters:

  • np – The X-py module to use (NumPy or CuPy).

  • n – The size of the unitary matrix to generate.

Returns:

A random unitary matrix of size n x n.

numq.get_random_wf(np, nqb, nwf=1)

Get a random wavefunction distributed according to Haar measure on the complex unitary sphere.

Parameters:

  • np – The X-py module to use (NumPy or CuPy).

  • nqb – The number of qubits.

  • nwf – The number of wavefunctions to generate. Default is 1.

Returns:

A random wavefunction of one-dimension or an array of random wavefunctions of two dimensions, with the second (i.e. last) dimension indexing the wavefunction.

numq.get_randu(np, nqb)

Generates a n qubit random unitary matrix, distributed uniformly according to the Haar measure. This is based on http://www.dr-qubit.org/matlab/randU.m.

Parameters:

  • np – The X-py module to use (NumPy or CuPy).

  • nqb – The number of qubits.

Returns:

A random unitary matrix of size 2^nqb x 2^nqb.

numq.load_state_into_mqb_start_from_lqb(states, m, l: int = 0)
numq.load_state_into_mqb_start_from_lqb(states: ndarray, m: int, l: int = 0)

Loads states (columns of wavefunctions) from the smaller, and initialise the new qubits to 0.

Note: l is 0-based. m is 1-based. For example, you can load state into 1 qb starts from 0 qubit.

Parameters:

  • states – The input states to load.

  • m – The number of qubits in the target state.

  • l – The starting qubit index (0-based) from which to load the states.

Returns:

The states loaded into the specified qubits.

numq.load_states_into(states, total_qb: int, pos: List[int])

Loads the input states into the positions (pos), within a total qubits by total_qb.

Parameters:

  • states – The input states to load, which should be

  • total_qb – The total number of qubits in the system.

  • pos – The positions (0-based) in which to load the states.

Returns:

The states loaded into the specified positions.

numq.make_density_matrix(wf)
numq.make_density_matrix(wf: ndarray)

Make a density matrix from a wavefunction, i.e., compute the “ket-bra”.

Parameters:

wf – The wavefunction to convert into a density matrix.

Returns:

The density matrix corresponding to the wavefunction.

numq.partial_trace(rho, retain_qubits: Iterable[int])
numq.partial_trace(rho: ndarray, retain_qubits) → ndarray

Compute the partial trace of rho.

Parameters:

  • rho – The density matrix to perform the partial trace on.

  • return_qubits – the qubits which we want to keep after partial trace.

Returns:

The reduced density matrix after performing the partial trace.

numq.partial_trace_wf(iwf, retain_qubits: Iterable[int])
numq.partial_trace_wf(iwf: ndarray, retain_qubits)

Partial trace on wavefunctions. See partial_trace for an explanation.

numq.partial_trace_wf_keep_first(iwf, n: int)
numq.partial_trace_wf_keep_first(iwf: ndarray, n: int)

Partial trace which keeps only the first n qubits

Parameters:

  • iwf – The input wavefunction to perform the partial trace on.

  • n – The number of qubits to keep after the partial trace. If n is 0, it returns a shape (1,1) array of value 1.

Notes

We keep the least significant bit on the left. That is, inside the bit string of \(n_0n_1\cdots n_m\), \(n_0\) is the first qubit.

In this way, for a iwf of indices \(i_1\cdots i_n j_{n+1}j_{n+2}\cdots\), the \(j\) indices needs to be summed, which should be close together on the memory since we assume that iwf is c-ordered (although the code would work even if iwf is f-ordered)

numq.rand_herm(np, nqb=None, dim=None)

Generates a random Hermitian matrix. Based on http://www.dr-qubit.org/matlab/randH.m .

Parameters:

  • np – The X-py module to use (NumPy or CuPy).

  • nqb – The number of qubits. If provided, will override the dim parameter.

  • dim – The dimension of the Hermitian matrix. If not provided, it is set to 2^nqb.

Returns:

A random Hermitian matrix of size dim x dim.

Indices and tables