Function dqcsim::bindings::dqcs_gate_new_unitary

#[no_mangle]pub extern "C" fn dqcs_gate_new_unitary(
    targets: dqcs_handle_t, 
    controls: dqcs_handle_t, 
    matrix: dqcs_handle_t
) -> dqcs_handle_t

Constructs a new unitary gate.

targets must be a handle to a non-empty qubit set. The qubits in this set correspond with the supplied unitary matrix.

controls optionally specifies a set of control qubits. You may pass 0 or an empty qubit set if you don't need control qubits.

matrix must be a handle to an appropriately sized matrix.

The supplied matrix is only applied to the target qubits if all the control qubits are or will be determined to be set. For instance, to encode a CCNOT/Toffoli gate, you can specify one target qubits, two control qubits, and [0, 1; 1, 0] (X) for the matrix. This is equivalent to extending the matrix to the full Toffoli matrix and specifying all three qubits in the targets set, or the midway solution using a CNOT matrix, but these solutions may be less efficient depending on whether the simulator can optimize its calculations for controlled gates.

Simulators are not required to apply the (hidden) global phase component of the gate matrix in the same way it is specified; that is, if the simulator can optimize its calculations by altering the global phase it is allowed to.

DQCsim checks whether the matrix is unitary using the equivalent of dqcs_mat_approx_unitary() with an epsilon value of 1e-6.

This function returns the handle to the gate, or 0 to indicate failure. The targets qubit set, (if specified) the controls qubit set, and the matrix are consumed/deleted by this function if and only if it succeeds.