Function createComplexMatrixN

pub unsafe extern "C" fn createComplexMatrixN(
    numQubits: c_int,
) -> ComplexMatrixN

Allocate dynamic memory for a square complex matrix of any size, which can be passed to functions like multiQubitUnitary() and applyMatrixN().

The returned matrix will have dimensions \f[ 2^{\text{numQubits}} \times 2^{\text{numQubits}}, \f] stored as nested arrays ComplexMatrixN.real and ComplexMatrixN.imag, initialised to zero.

If your matrix will ultimately be diagonal, use createSubDiagonalOp() instead to save quadratic memory and runtime.

Unlike a ::Qureg, the memory of a ::ComplexMatrixN is always stored in RAM, and non-distributed. Hence, elements can be directly accessed and modified:

int numQubits = 5;
int dim = (1 << numQubits);
ComplexMatrixN m = createComplexMatrixN(numQubits);

for (int r=0; r<dim; r++) {
    for (int c=0; c<dim; c++) {
        m.real[r][c] = rand();
        m.imag[r][c] = rand();
    }
}

\n A ::ComplexMatrixN can be initialised in bulk using initComplexMatrixN(), though this is not C++ compatible.

Like ::ComplexMatrix2 and ::ComplexMatrix4 (which are incidentally stored in the stack), the returned ::ComplexMatrixN is safe to return from functions.

The ::ComplexMatrixN must eventually be freed using destroyComplexMatrixN(), since it is created in the dynamic heap. One can instead use getStaticComplexMatrixN() to create a ComplexMatrixN struct in the stack (which doesn’t need to be later destroyed), though this may cause a stack overflow if the matrix is too large (approx 10+ qubits).

@see

• destroyComplexMatrixN()
• getStaticComplexMatrixN()
• initComplexMatrixN()
• applyMatrixN()
• multiQubitUnitary()
• mixMultiQubitKrausMap()
• createSubDiagonalOp()

@ingroup type @param[in] numQubits the number of qubits of which the returned ComplexMatrixN will correspond @returns a dynamic ComplexMatrixN struct, that is one where the .real and .imag fields are arrays kept in the heap and must be later destroyed. @throws invalidQuESTInputError()

• if \p numQubits <= 0
• if the memory was not allocated successfully @author Tyson Jones