Skip to content

Custom Oracle

The custom oracle function allows the usage of oracles designed by the user. To define an oracle, one must specify the function by its name (custom_oracle field) and parameters (custom_oracle_params field). Then, it may be used as an oracle for amplitude amplification. The inputs and outputs of the function are identical to those of the inner custom function, which are assumed identical.


  1. There is no validation that the received function is indeed an oracle (i.e., sets phases of \(\pm 1\) for computational states).
  2. The amplitude amplification algorithm requires classical validation of results extracted from Grover operator execution to determine whether to continue executing. We currently do not support custom classical validation, and return True by default.


Function: CustomOracle



In the following example, we define an oracle on 4 qubits (2 2-qubit registers named a and b). The oracle marks states where the state in either a or b is 11, but not both: (a == "11")^(b == "11").

  "function_library": {
    "functions": [
        "name": "my_oracle_function",
        "implementations": [{
          "serialized_circuit": "OPENQASM 2.0;\ninclude \"\";\nqreg q[4];\ncz q[0], q[1];\ncz q[2], q[3];"
        "register_mapping": {
          "input_registers": [
            {"name": "a", "qubits": [0, 1]}, {"name": "b", "qubits": [2, 3]}
          "output_registers": [
            {"name": "a", "qubits": [0, 1]}, {"name": "b", "qubits": [2, 3]}
        "name": "main",
        "logic_flow": [
            "function": "CustomOracle",
            "function_params": {
              "custom_oracle": "my_oracle_function",
              "custom_oracle_params": {
                "input_decls": {"a": {"size": 2}, "b": {"size": 2}},
                "output_decls": {"a": {"size": 2}, "b": {"size": 2}}
from typing import Tuple
from classiq import Model, FunctionLibrary, QASM_INTRO, qfunc, QReg
from classiq.builtin_functions import CustomOracle

def my_oracle_function(a: QReg[2], b: QReg[2]) -> Tuple[QReg[2], QReg[2]]:
    return QASM_INTRO + "qreg q[4];\ncz q[0], q[1];\ncz q[2], q[3];"

library = FunctionLibrary(my_oracle_function)

oracle_params = CustomOracle(

model = Model()

circuit = model.synthesize()