dqcs_handle_t dqcs_mat_new(
    size_t num_qubits,
    const double *matrix
)

num_qubits must be set to the number of qubits mutated by this matrix. It must be greater than or equal to zero. matrix must point to an appropriately sized array of doubles. The matrix is specified in row-major form, using pairs of doubles for the real vs. imaginary component of each entry. The size must be 4**num_qubits complex numbers = 2*4**num_qubits doubles = 16*4**num_qubits bytes, representing a 2**num_qubits by 2**num_qubits matrix. This function returns the constructed matrix handle, or 0 if an error occurs.

While not enforced at this level, the matrix is normally unitary, or approximately so within some floating-point error margin.

This function returns the handle to the matrix, or 0 to indicate failure.

ssize_t dqcs_mat_len(dqcs_handle_t mat)

This function returns -1 when an error occurs.

ssize_t dqcs_mat_dimension(dqcs_handle_t mat)

This function returns -1 when an error occurs.

ssize_t dqcs_mat_num_qubits(dqcs_handle_t mat)

This function returns -1 when an error occurs.

double *dqcs_mat_get(dqcs_handle_t mat)

If this function succeeds, the matrix is returned in row-major form, using pairs of doubles for the real vs. imaginary component of each entry. The size will be 4**num_qubits complex numbers = 2*4**num_qubits doubles = 16*4**num_qubits bytes. A newly allocated matrix is returned; free it with free() when you're done with it to avoid memory leaks. On failure, this function returns NULL.

dqcs_bool_return_t dqcs_mat_approx_eq(
    dqcs_handle_t a,
    dqcs_handle_t b,
    double epsilon,
    bool ignore_gphase
)

a and b are borrowed matrix handles. epsilon specifies the maximum element-wise root-mean-square error between the matrices that results in a positive match. ignore_gphase specifies whether the check should ignore global phase.

If ignore_gphase is set, this checks that the following holds for some x:

\[ A \cdot e^{ix} \approx B \]

This function returns DQCS_TRUE if the matrices match according to the aforementioned criteria, or DQCS_FALSE if not. DQCS_BOOL_ERROR is used when either handle is invalid or not a matrix. If the matrices differ in dimensionality, DQCS_FALSE is used.

dqcs_bool_return_t dqcs_mat_approx_unitary(
    dqcs_handle_t matrix,
    double epsilon
)

matrix is a borrowed handle to the matrix to check. epsilon specifies the maximum element-wise root-mean-square error between the product of the matrix and its hermetian compared to the identity matrix.

This function returns DQCS_TRUE if the matrix is approximately unitary, or DQCS_FALSE if not. DQCS_BOOL_ERROR is used when either handle is invalid or not a matrix.

typedef enum { ... } dqcs_predefined_gate_t;

Variants:

dqcs_handle_t dqcs_mat_predef(
    dqcs_predefined_gate_t gate_type,
    dqcs_handle_t param_data
)

gate_type specifies which kind of gate should be constructed.

param_data takes an optional ArbData object used to parameterize the matrix if necessary. If not specified, an empty object is used. The ArbData representation for each gate can be found in the docs for dqcs_predefined_gate_t. If nothing is specified, no ArbData is used.

This function returns the handle to the matrix, or 0 to indicate failure. The parameterization data (if specified) is consumed/deleted by this function if and only if it succeeds.

dqcs_bool_return_t dqcs_mat_is_predef(
    dqcs_handle_t mat,
    dqcs_predefined_gate_t gate_type,
    dqcs_handle_t *param_data,
    double epsilon,
    bool ignore_gphase
)

mat is a borrowed handle to the matrix to check. gate_type specifies which kind of gate should be detected. param_data, if non-null, receives a new ArbData handle with parameterization data, or an empty ArbData if the gate is not parameterized; the caller must delete this object when it is done with it. This function always writes the 0 handle to this return parameter if it fails. The ArbData representation can be found in the documentation for dqcs_predefined_gate_t.

epsilon specifies the maximum element-wise root-mean-square error between the matrices that results in a positive match. ignore_gphase specifies whether the check should ignore global phase.

This function returns DQCS_TRUE if the matrices match according to the aforementioned criteria, or DQCS_FALSE if not. DQCS_BOOL_ERROR is used when either handle is invalid or not a matrix. If the matrices differ in dimensionality, DQCS_FALSE is used.

dqcs_handle_t dqcs_mat_add_controls(
    dqcs_handle_t mat,
    size_t number_of_controls
)

mat specifies the matrix to use as the non-controlled submatrix. This is a borrowed handle. number_of_controls specifies the number of control qubits to add. This function returns a new matrix handle with the constructed matrix, or 0 if it fails.

dqcs_handle_t dqcs_mat_strip_control(
    dqcs_handle_t mat,
    double epsilon,
    bool ignore_global_phase,
    ssize_t **control_indices
)

mat specifies the matrix to modify. This is a borrowed handle. epsilon specifies the maximum magitude of the difference between the column vectors of the input matrix and the identity matrix (after dephasing if ignore_gphase is set) for the column vector to be considered to not affect the respective entry in the quantum state vector. Note that if this is greater than zero, the resulting gate may not be exactly equivalent. If ignore_global_phase is set, any global phase in the matrix is ignored, but note that if control qubits are stripped the "global" phase of the resulting submatrix is always significant. control_indices is a return argument through which DQCsim will pass the indices of the qubits that were removed in the process of constructing the submatrix. This is represented as an array of indices terminated by a -1 entry. The returned matrix must be freed using free() when you are done with it to avoid memory leaks. This function returns a new matrix handle with the submatrix, or 0 if it fails. In this case, control_indices is not mutated.

This function assumes that the incoming matrix is unitary (within epsilon) without verifying that this is the case. The results may thus be invalid if it was not.

typedef enum { ... } dqcs_basis_t;

Variants:

dqcs_handle_t dqcs_mat_basis(dqcs_basis_t basis)

This can be used for constructing measurement or prep gates with the given basis. Returns a new handle to the constructed matrix or returns 0 if an error occurs.

dqcs_bool_return_t dqcs_mat_basis_approx_eq(
    dqcs_handle_t a,
    dqcs_handle_t b,
    double epsilon
)

a and b are borrowed matrix handles. epsilon specifies the maximum element-wise root-mean-square error between the matrices that results in a positive match.

This checks that the following holds for some x and y:

\[ A \cdot \begin{bmatrix} e^{ix} & 0 \\ 0 & e^{iy} \end{bmatrix} \approx B \]

This function returns DQCS_TRUE if the matrices match according to the aforementioned criteria, or DQCS_FALSE if not. DQCS_BOOL_ERROR is used when either handle is invalid or not a matrix. If either matrix is not 2x2, DQCS_FALSE is used.