Function dqcsim::bindings::dqcs_gm_add_custom_unitary

#[no_mangle]pub extern "C" fn dqcs_gm_add_custom_unitary(
    gm: dqcs_handle_t, 
    key_free: Option<extern "C" fn(key_data: *mut c_void)>, 
    key_data: *mut c_void, 
    detector: Option<extern "C" fn(user_data: *const c_void, matrix: dqcs_handle_t, num_controls: size_t, param_data: *mut dqcs_handle_t) -> dqcs_bool_return_t>, 
    detector_user_free: Option<extern "C" fn(user_data: *mut c_void)>, 
    detector_user_data: *mut c_void, 
    constructor: Option<extern "C" fn(user_data: *const c_void, param_data: *mut dqcs_handle_t, num_controls: *mut isize) -> dqcs_handle_t>, 
    constructor_user_free: Option<extern "C" fn(user_data: *mut c_void)>, 
    constructor_user_data: *mut c_void
) -> dqcs_return_t

Adds a custom unitary gate mapping to the given gate map. >

gm must be a handle to a gate map object (dqcs_gm_new()). key_free is an optional callback function used to free key_data when the gate map is destroyed, or when this function fails. key_data is the user-specified value used to identify this mapping. detector is the detector function pointer. It is optional; if null, this mapping only supports construction. detector_user_free is an optional callback function used to free detector_user_data when the gate map is destroyed, when this function fails, or when detector was null. detector_user_data is a user-specified value that is passed to the detector callback function. It is not used by DQCsim. constructor is the constructor function pointer. It is optional; if null, this mapping only supports detection. constructor_user_free is an optional callback function used to free constructor_user_data when the gate map is destroyed, when this function fails, or when constructor was null. constructor_user_data is a user-specified value that is passed to the constructor callback function. It is not used by DQCsim.

If both constructor and detector are null for some reason, the function is no-op (besides possibly calling the *_free() callbacks.

The detector callback receives a matrix and control qubit information for the user to match. The matrix is passed through the matrix handle. num_controls is passed the number of explicit control qubits that exist besides the matrix (that is, if nonzero, the matrix is actually only the non-controlled submatrix of the controlled gate). param_data is given an ArbData handle initialized with the ArbData attached to the gate. If the gate matches, the detector function must return DQCS_TRUE. In this case, it can mutate the param_data to add the detected gate parameters. If it doesn't match, it must return DQCS_FALSE. If an error occurs, it must call dqcs_error_set() with the error message and return DQCS_BOOL_FAILURE.

The constructor callback performs the reverse operation. It receives an ArbData handle containing the parameterization data, and must construct the matrix, return the bound on the number of control qubits, and must return the ArbData associated with the gate by mutating the param_data handle. num_controls will point to a variable initialized to -1 representing a constraint on the number of control qubits. This works as follows: if negative, any number of qubits is allowed; if zero or positive, only that number is allowed. If construction succeeds, the constructor function must return a handle to the constructed matrix. If it fails, it must call dqcs_error_set() with an error message and return 0.

It is up to the user how to do the matching and constructing, but the converter functions must always return the same value for the same input. In other words, they must be pure functions. Otherwise, the caching behavior of the GateMap will make the results inconsistent.