Skip to content

Oracle Construction

ampamp.oracles is the general oracle-construction layer for amplitude-amplification workflows.

It supports four source types:

  • marked basis-state indices
  • marked bitstrings
  • Boolean formula strings
  • user-supplied unitary matrices

Exactly one source is supplied for a single oracle specification.

Boolean Formula To Circuit

Use formula_text when the user gives a Boolean function or expression. The expression is parsed by SymPy and evaluated over variables v0, v1, ..., where v0 denotes the leftmost bit in the bitstring convention.

Supported operator examples include:

  • & for AND
  • | for OR
  • ~ for NOT
  • parentheses for grouping
from ampamp import build_phase_oracle, build_bit_flip_oracle

phase_oracle = build_phase_oracle(
    num_qubits=4,
    formula_text="v0 & (v2 | v3)",
)

bit_flip_oracle = build_bit_flip_oracle(
    num_qubits=4,
    formula_text="v0 & ~v1",
)

For formula sources, synthesis enumerates satisfying assignments. To keep accidental truth-table blowups explicit, formula synthesis defaults to max_formula_qubits=16; raise this value only when that cost is intended.

from ampamp import marked_bitstrings_from_formula

marked = marked_bitstrings_from_formula(
    num_qubits=3,
    formula_text="(v0 & ~v1) | v2",
)

print(marked)

Direct Unitary Matrix Oracle

Use build_unitary_oracle when the oracle is already available as a matrix. The matrix must be:

  • square
  • power-of-two dimensional
  • unitary within the requested tolerance

The number of qubits is inferred from the matrix dimension unless num_qubits is supplied for an extra consistency check.

import numpy as np

from ampamp import build_unitary_oracle

unitary_matrix = np.diag([1, 1, -1, 1])
oracle = build_unitary_oracle(unitary_matrix)

print(oracle.num_qubits)  # 2

For lower-level construction, use OracleBuilder.from_unitary_matrix(...):

import numpy as np

from ampamp import OracleBuilder

oracle = OracleBuilder.from_unitary_matrix(
    np.diag([1, -1]),
).unitary_oracle()

Marked-State Oracles

Marked indices and bitstrings remain the simplest path when the target states are already known.

from ampamp import build_phase_oracle, build_bit_flip_oracle

phase_oracle = build_phase_oracle(
    num_qubits=3,
    marked_indices=[5],
)

bit_flip_oracle = build_bit_flip_oracle(
    num_qubits=3,
    marked_bitstrings=["101"],
)

Builder Pattern

OracleBuilder is useful when the same validated oracle source should expose multiple views:

from ampamp import OracleBuilder

builder = OracleBuilder.from_formula(3, "v0 & ~v1")

print(builder.marked_bitstrings())
print(builder.marked_indices())

phase = builder.phase_oracle()
bit_flip = builder.bit_flip_oracle()

Generated API Reference

ampamp.oracles

OracleBuilder

Build phase and bit-flip oracles from one validated oracle source.

bit_flip_oracle(*, name=None)

Return |x>|y> -> |x>|y xor f(x)> with the output qubit last.

phase_oracle(*, synthesis='auto', name=None)

Return a phase oracle over the input register.

synthesis may be "auto", "mcx", or "diagonal". MCX synthesis is available for the standard sign-flip phase phase = pi. Diagonal synthesis supports arbitrary marked-state phases.

unitary_oracle(*, name=None)

Return a circuit that applies the supplied oracle unitary matrix.

OracleSpec dataclass

Validated oracle source specification.

Exactly one source must be supplied: marked_indices, marked_bitstrings, formula_text, or unitary_matrix. Bitstrings use the usual most-significant-bit-left convention. For formulae, v0 denotes the leftmost bit, v1 the next bit, and so on. Matrix oracles are checked as square power-of-two-dimensional unitary arrays.

build_bit_flip_oracle(num_qubits, *, marked_indices=None, marked_bitstrings=None, formula_text=None, variable_prefix='v', max_formula_qubits=16, name=None)

Convenience wrapper for constructing a bit-flip oracle.

build_phase_oracle(num_qubits, *, marked_indices=None, marked_bitstrings=None, formula_text=None, phase=np.pi, synthesis='auto', variable_prefix='v', max_formula_qubits=16, name=None)

Convenience wrapper for constructing a phase oracle.

build_unitary_oracle(unitary_matrix, *, num_qubits=None, atol=1e-08, name=None)

Convenience wrapper for constructing an oracle from a unitary matrix.

marked_bitstrings_from_formula(num_qubits, formula_text, *, variable_prefix='v', max_formula_qubits=16)

Enumerate satisfying bitstrings for a Boolean formula.

The formula is parsed by SymPy and may use variables such as v0, v1 and standard Boolean operators &, | and ~. The implementation intentionally uses truth-table enumeration so that phase and bit-flip oracle constructors share the same variable-order semantics.