dqcs_handle_t dqcs_gate_new_predef(
    dqcs_predefined_gate_t gate_type,
    dqcs_handle_t qubits,
    dqcs_handle_t param_data
)

gate_type specifies which kind of gate should be constructed.

targets must be a handle to a non-empty qubit set, containing at least as many qubits as needed for the specified gate type. If more qubits are specified, the rightmost qubits become the targets, and the remaining qubits become control qubits to make a controlled gate.

param_data takes an optional ArbData object used to parameterize the gate if necessary. If not specified, an empty object is used. Some of the gate types are parameterized, and use values from this ArbData as defined in the docs for dqcs_predefined_gate_t. Anything remaining in the ArbData afterwards is placed in the gate object.

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

dqcs_handle_t dqcs_gate_new_predef_one(
    dqcs_predefined_gate_t gate_type,
    dqcs_qubit_t qa,
    dqcs_handle_t param_data
)

This function is simply a shorthand for dqcs_gate_new_predef() with one qubit in the qubits set, to make constructing one-qubit gates more ergonomic. Refer to its documentation for more information.

dqcs_handle_t dqcs_gate_new_predef_two(
    dqcs_predefined_gate_t gate_type,
    dqcs_qubit_t qa,
    dqcs_qubit_t qb,
    dqcs_handle_t param_data
)

This function is simply a shorthand for dqcs_gate_new_predef() with two qubit in the qubits set, to make constructing two-qubit gates more ergonomic. Refer to its documentation for more information.

dqcs_handle_t dqcs_gate_new_predef_three(
    dqcs_predefined_gate_t gate_type,
    dqcs_qubit_t qa,
    dqcs_qubit_t qb,
    dqcs_qubit_t qc,
    dqcs_handle_t param_data
)

This function is simply a shorthand for dqcs_gate_new_predef() with three qubit in the qubits set, to make constructing three-qubit gates more ergonomic. Refer to its documentation for more information.

dqcs_handle_t dqcs_gate_new_unitary(
    dqcs_handle_t targets,
    dqcs_handle_t controls,
    dqcs_handle_t matrix
)

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.

dqcs_handle_t dqcs_gate_new_measurement(
    dqcs_handle_t measures,
    dqcs_handle_t matrix
)

measures must be a handle to a qubit set. matrix is an optional matrix handle signifying the measurement basis. If zero, the Z basis is used. Otherwise, it must be a handle to a unitary 2x2 matrix, and the semantics of the measurement are as follows:

• apply the hermetian of the matrix to each qubit
• measure each qubit in the Z basis
• apply the matrix to each qubit

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

dqcs_handle_t dqcs_gate_new_prep(
    dqcs_handle_t targets,
    dqcs_handle_t matrix
)

targets must be a handle to a qubit set. matrix is an optional matrix handle signifying the state that the qubits are initialized to. If zero, the qubits are initialized to |0>. Otherwise, it must be a handle to a unitary 2x2 matrix, and the semantics are as follows:

• initialize each qubit to |0>
• apply the matrix to each qubit

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

dqcs_handle_t dqcs_gate_new_custom(
    const char *name,
    dqcs_handle_t targets,
    dqcs_handle_t controls,
    dqcs_handle_t measures,
    dqcs_handle_t matrix
)

The functionality of custom gates is not specified by DQCsim. Instead, this is left up to the plugins. Of course, for this to work, plugins that are connected to each other must agree on the format used.

name specifies the name of the gate. The name is used to indicate which custom operation is to be applied.

targets optionally specifies the set of target qubits. You may pass 0 or an empty qubit set if you don't need target qubits.

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

measures optionally specifies the set of measured qubits. You may pass 0 or an empty qubit set if no qubits are measured. Note that the upstream plugin expects exactly one measurement result for each qubit specified in this set; anything else results in a warning and the measurement result being set to undefined.

matrix optionally specifies a handle to an appropriately sized matrix for the targets qubit set.

In addition to the above data, gate objects implement the arb interface to allow user-specified classical information to be attached.

This function returns the handle to the gate, or 0 to indicate failure. The specified qubit sets are consumed/deleted by this function if and only if it succeeds.

dqcs_handle_t dqcs_gate_reduce_control(
    dqcs_handle_t gate,
    double epsilon,
    bool ignore_gphase
)

This function borrows a handle to any gate with a matrix, and returns an equivalent copy of said gate with any control qubits in the targets set moved to the controls set. The associated gate matrix is accordingly reduced in size. The control qubits are added at the end of the controls set in the same order they appeared in the targets qubit set.

epsilon specifies the maximum element-wise deviation from the identity matrix for the relevant array elements for a qubit to be considered a control qubit. Note that if this is greater than zero, the resulting gate may not be exactly equivalent. If ignore_gphase is set, any global phase in the matrix is ignored, but the global phase of the non-control submatrix is not changed.

This function returns a new gate handle with the modified gate, or a copy of the input gate if the matrix could not be reduced. If the input gate does not have a matrix (measurement gate, or custom gate without matrix) an error is returned instead.

dqcs_handle_t dqcs_gate_expand_control(dqcs_handle_t gate)

This function borrows a handle to any gate with a matrix, and returns an equivalent copy of said gate with any control qubits in the controls set moved to the targets set. The associated gate matrix is extended accordingly. The control qubits are added at the front of the targets set in the same order they appeared in the controls qubit set.

This function returns a new gate handle with the modified gate, or a copy of the input gate if the matrix could not be reduced. If the input gate does not have a matrix (measurement gate, or custom gate without matrix) an error is returned instead.

dqcs_gate_type_t dqcs_gate_type(dqcs_handle_t gate)

Returns DQCS_GATE_TYPE_INVALID if the gate handle is invalid.

typedef enum { ... } dqcs_gate_type_t;

Variants:

dqcs_bool_return_t dqcs_gate_has_targets(dqcs_handle_t gate)

dqcs_handle_t dqcs_gate_targets(dqcs_handle_t gate)

dqcs_bool_return_t dqcs_gate_has_controls(dqcs_handle_t gate)

dqcs_handle_t dqcs_gate_controls(dqcs_handle_t gate)

dqcs_bool_return_t dqcs_gate_has_measures(dqcs_handle_t gate)

dqcs_handle_t dqcs_gate_measures(dqcs_handle_t gate)

dqcs_bool_return_t dqcs_gate_has_matrix(dqcs_handle_t gate)

dqcs_handle_t dqcs_gate_matrix(dqcs_handle_t gate)

If this function succeeds, a new matrix handle is returned. If it fails, 0 is returned.

dqcs_bool_return_t dqcs_gate_has_name(dqcs_handle_t gate)

char *dqcs_gate_name(dqcs_handle_t gate)

This function fails if the gate is not a custom gate. Query dqcs_gate_has_name() to disambiguate between a non-custom gate and a different error.

On success, this returns a newly allocated string containing the gate name. Free it with free() when you're done with it to avoid memory leaks. On failure, this returns NULL.