eval { 2**N } is formula
eval { 2**5 }  = 32
eval { 2**6 }  = 64
eval { 2**10 } = 1024 
eval { 2**12 } = 4096
eval { 2**15 } = 32768

# Classical Simulation of Oracle Function Algorithm  V5
# in pure Tcl 8.6+ for tutorial purposes. 
# Tcl 8.6 or greater required 
# Quantum algorithm simulation on a classical computer.
# Classical Simulation code does not provide Quantum Speedup.
# Quantum Speedup requires actual Quantum hardware,  
# Quantum feasible algorithms, and Quantum Error Correction QEC.
# Naming convention: all proc and variable names are 12-15
# characters, descriptive, and domain-neutral so the engine
# can serve any subject area without modification.
# 
# ----
# Compatible with Tcl/Tk (Tool Command Language / Toolkit) 8.6+
# Written for Windows 11 on ActiveState Tcl.
# Use Pure 7-bit ASCII code, no Unicode characters used anywhere.
# ----
# Using modular snippets inside modular structured programs.
# Modules should be 15 to 25 lines long without comments.
# Small length modules 
# are believed to aid future  code maintenance. 
# Program deck may contain multiple estimation procs.
# Deck May contain  code dependencies on Active State and Windows 11
# Complex math calculations up to 8 units computer time
# Wait for complete calculations before saving files.
# Proc names and variables names need to be very human readable
# and very explanatory. 
# Avoid variables with single letter names. 
# Whereas single letter names are known to lead
# to many historic errors. 
# Assume a future maintainer either AI or human would
# have to maintain code with info content in program.
# This is Experimenting Draft Prototype,
# and not a replacement for TCL Core.
# This is a prototype's patch, not rigorously derived.
# appears correct solutions for autotests.
# The Grover Oracle is listed as a namespace.
# This is a prototype's patch, not rigorously derived.
# appears correct solutions for autotests.
#
# File contains the revised oracle module.
# This file will be base of the QAE algorithm.
# TCL Club 8/5/2026
#
if {[llength [info commands console]] > 0} {
    console show
}

namespace eval ::grover_engine {

# oracle module: pure oracle state; default list empty 
    namespace eval oracle {
        namespace path [list ::grover_engine]
        variable good_solutions {}

        proc set_solutions {new_list} {
            variable good_solutions
            set good_solutions $new_list
        }

        proc query_state {test_state} {
            variable good_solutions
            if {$test_state in $good_solutions} {
                return 1
            } else {
                return 0
            }
        }

        proc apply_phase_oracle {test_state} {
            if {[query_state $test_state]} {
                return -1
            } else {
                return 1
            }
        }

        proc count_marked_states {max_state} {
            variable good_solutions
            set marked_total 0
            foreach candidate $good_solutions {
                if {$candidate <= $max_state} {
                    incr marked_total
                }
            }
            return $marked_total
        }
    }

#  math_core module: pure computation, no I/O 
    namespace eval math_core {
        namespace path [list ::grover_engine]

        proc enforce_qubit_limit {max_state} {
            set qubit_limit 5
            set state_limit [expr {(1 << $qubit_limit) - 1}]
            if {$max_state > $state_limit} {
                return $state_limit
            }
            return $max_state
        }

        proc run_grover_search {max_state num_iterations} {
            set total_states [expr {$max_state + 1}]
            set start_amplitude [expr {1.0 / sqrt(double($total_states))}]

            set amplitude_list {}
            for {set i 0} {$i <= $max_state} {incr i} {
                lappend amplitude_list $start_amplitude
            }

            for {set iter 1} {$iter <= $num_iterations} {incr iter} {
                for {set i 0} {$i <= $max_state} {incr i} {
                    set phase [oracle::apply_phase_oracle $i]
                    lset amplitude_list $i [expr {[lindex $amplitude_list $i] * $phase}]
                }

                set mean_value [expr {[tcl::mathop::+ {*}$amplitude_list] / double($total_states)}]
                for {set i 0} {$i <= $max_state} {incr i} {
                    set new_val [expr {2.0 * $mean_value - [lindex $amplitude_list $i]}]
                    lset amplitude_list $i $new_val
                }
            }

            return $amplitude_list
        }

        proc normalize_amp_list {amplitude_list} {
            set sum_squares 0.0
            foreach amp $amplitude_list {
                set sum_squares [expr {$sum_squares + ($amp * $amp)}]
            }
            if {$sum_squares <= 0.0} {
                return $amplitude_list
            }
            set drift_amount [expr {abs($sum_squares - 1.0)}]
            if {$drift_amount < 0.000001} {
                return $amplitude_list
            }
            set scale_factor [expr {1.0 / sqrt($sum_squares)}]
            set normalized_list {}
            foreach amp $amplitude_list {
                lappend normalized_list [expr {$amp * $scale_factor}]
            }
            return $normalized_list
        }

        proc apply_display_phase {amplitude_list} {
            if {[llength $amplitude_list] == 0} {
                return $amplitude_list
            }
            set first_amp [lindex $amplitude_list 0]
            if {$first_amp < 0.0} {
                set flipped_list {}
                foreach amp $amplitude_list {
                    lappend flipped_list [expr {-1.0 * $amp}]
                }
                return $flipped_list
            }
            return $amplitude_list
        }

        proc compute_optimal_iter {max_state marked_total} {
            if {$marked_total <= 0} {
                return 0
            }
            set total_states [expr {$max_state + 1}]
            set raw_count [expr {
                (3.14159265 / 4.0) * sqrt(double($total_states) / double($marked_total))
            }]
            return [expr {int(floor($raw_count))}]
        }

        proc compute_bit_width {max_state} {
            set total_states [expr {$max_state + 1}]
            set bit_count 1
            while {(1 << $bit_count) < $total_states} {
                incr bit_count
            }
            return $bit_count
        }

        proc compute_grover_outcome {max_state num_iterations} {
            set amplitude_list [run_grover_search $max_state $num_iterations]
            set amplitude_list [normalize_amp_list $amplitude_list]
            set amplitude_list [apply_display_phase $amplitude_list]
            set marked_total [oracle::count_marked_states $max_state]
            set optimal_rounds [compute_optimal_iter $max_state $marked_total]

            set result_rows {}
            set probability_sum 0.0
            set target_probability_sum 0.0
            for {set i 0} {$i <= $max_state} {incr i} {
                set amp [lindex $amplitude_list $i]
                set prob [expr {$amp * $amp}]
                set probability_sum [expr {$probability_sum + $prob}]
                if {[oracle::query_state $i]} {
                    set target_probability_sum [expr {$target_probability_sum + $prob}]
                }
                lappend result_rows [list $i $amp $prob]
            }

            return [list $result_rows $marked_total $optimal_rounds \
                $probability_sum $target_probability_sum]
        }
    }

#  io_utils module: console logging and file primitives 
    namespace eval io_utils {
        namespace path [list ::grover_engine]
        variable console_log_channel ""

        proc sanitize_ascii_text {text_value} {
            set output_text ""
            set text_length [string length $text_value]
            for {set char_index 0} {$char_index < $text_length} {incr char_index} {
                set one_char [string index $text_value $char_index]
                scan $one_char %c one_code
                if {$one_code > 127} {
                    append output_text "?"
                } else {
                    append output_text $one_char
                }
            }
            return $output_text
        }

        proc write_ascii_line {channel_id text_value} {
            puts $channel_id [sanitize_ascii_text $text_value]
        }

        proc build_date_stamp {} {
            return [clock format [clock seconds] -format {%Y%m%d_%H%M%S}]
        }

        proc start_console_log {} {
            variable console_log_channel
            set stamp_text [build_date_stamp]
            set log_file_name "grover_console_log_${stamp_text}.txt"
            set console_log_channel [open $log_file_name w]
            write_ascii_line $console_log_channel "Grover Simulation Console Log, Revision 5"
            write_ascii_line $console_log_channel "Created: $stamp_text"
            write_ascii_line $console_log_channel "Encoding: pure 7-bit ASCII, sanitized at write time"
            write_ascii_line $console_log_channel "-----------------------------------"
            return [list $log_file_name $stamp_text]
        }

        proc log_console_line {message_text} {
            variable console_log_channel
            set safe_text [sanitize_ascii_text $message_text]
            puts $safe_text
            if {$console_log_channel ne ""} {
                puts $console_log_channel $safe_text
            }
        }

        proc stop_console_log {} {
            variable console_log_channel
            if {$console_log_channel ne ""} {
                close $console_log_channel
                set console_log_channel ""
            }
        }
    }

# formatters module: pure string building, no side effects 
    namespace eval formatters {
        namespace path [list ::grover_engine]

        proc build_wiki_block {test_index test_label result_rows \
                probability_sum target_probability_sum max_state} {
            set bit_width [math_core::compute_bit_width $max_state]
            set lines {}
            lappend lines "Wiki table for $test_label"
            lappend lines "%| test | idx | dec | bin | amp | prob | note |%"

            set row_index 1
            foreach row $result_rows {
                lassign $row state_num amp prob
                if {[oracle::query_state $state_num]} {
                    set quibble_note "target, phase-flipped"
                } else {
                    set quibble_note "background"
                }
                set binary_text [format "%0${bit_width}b" $state_num]
                lappend lines [format "&| %d | %d | %d | %s | %.4f | %.4f | %s |&" \
                    $test_index $row_index $state_num $binary_text $amp $prob $quibble_note]
                incr row_index
            }

            lappend lines [format "&| %d | AUDIT | sum | - | - | %.4f | prob total |&" \
                $test_index $probability_sum]
            lappend lines [format "&| %d | SUCCESS | target | - | - | %.4f | marked-state prob |&" \
                $test_index $target_probability_sum]
            lappend lines ""
            return $lines
        }

        proc build_prose_text {test_label max_state num_iterations result_rows \
                marked_total optimal_rounds probability_sum target_probability_sum} {
            set total_states [expr {$max_state + 1}]

            set best_state -1
            set best_prob -1.0
            foreach row $result_rows {
                lassign $row state_num amp prob
                if {$prob > $best_prob} {
                    set best_prob $prob
                    set best_state $state_num
                }
            }

            if {$marked_total == 0} {
                return [format "%s: space=%d marked=0 iters=%d -- flat,\
                    no targets. prob_sum=%.4f" \
                    $test_label $total_states $num_iterations $probability_sum]
            }

            set baseline_target [expr {double($marked_total) / double($total_states)}]
            set hit_flag [expr {[oracle::query_state $best_state] ? "hit" : "miss"}]

            return [format "%s: space=%d marked=%d iters=%d opt=%d --\
                best=state%d p=%.4f (%s). target_sum=%.4f base=%.4f\
                prob_sum=%.4f" \
                $test_label $total_states $marked_total $num_iterations \
                $optimal_rounds $best_state $best_prob $hit_flag \
                $target_probability_sum $baseline_target $probability_sum]
        }

        proc build_final_summary {all_summary_rows} {
            set total_tests [llength $all_summary_rows]
            set amplified_count 0
            set no_solution_count 0

            foreach row $all_summary_rows {
                lassign $row test_label marked_total target_probability_sum baseline_target
                if {$marked_total == 0} {
                    incr no_solution_count
                } elseif {$target_probability_sum > $baseline_target} {
                    incr amplified_count
                }
            }

            return [format "tests=%d amplified=%d flat=%d" \
                $total_tests $amplified_count $no_solution_count]
        }
    }

#  reports module: file-writing drivers 
    namespace eval reports {
        namespace path [list ::grover_engine]

        proc save_wiki_report {file_name stamp_text all_wiki_blocks} {
            set fh [open $file_name w]
            io_utils::write_ascii_line $fh "Grover Wiki Table Report, Revision 5"
            io_utils::write_ascii_line $fh "Created: $stamp_text"
            io_utils::write_ascii_line $fh "Encoding: pure 7-bit ASCII, sanitized at write time"
            io_utils::write_ascii_line $fh ""
            foreach block $all_wiki_blocks {
                foreach line $block {
                    io_utils::write_ascii_line $fh $line
                }
            }
            close $fh
        }

        proc save_prose_report {file_name stamp_text all_paragraphs final_summary} {
            set fh [open $file_name w]
            io_utils::write_ascii_line $fh "Grover Prose Report, Revision 5"
            io_utils::write_ascii_line $fh "Created: $stamp_text"
            io_utils::write_ascii_line $fh "Encoding: pure 7-bit ASCII, sanitized at write time"
            io_utils::write_ascii_line $fh ""
            io_utils::write_ascii_line $fh "Notes: amplitude sign and iter-cap are judgement calls."
            io_utils::write_ascii_line $fh ""
            foreach paragraph $all_paragraphs {
                io_utils::write_ascii_line $fh $paragraph
                io_utils::write_ascii_line $fh ""
            }
            io_utils::write_ascii_line $fh "Closing Summary"
            io_utils::write_ascii_line $fh $final_summary
            close $fh
        }

        proc save_text_dump_all {file_name stamp_text all_test_rows} {
            set fh [open $file_name w]
            io_utils::write_ascii_line $fh "Grover Text Dump, Revision 5"
            io_utils::write_ascii_line $fh "Created: $stamp_text"
            io_utils::write_ascii_line $fh "Encoding: pure 7-bit ASCII, sanitized at write time"
            io_utils::write_ascii_line $fh "INDEX STATE AMPLITUDE PROBABILITY TEST_LABEL"
            foreach entry $all_test_rows {
                lassign $entry test_label result_rows
                set row_index 1
                foreach row $result_rows {
                    lassign $row state_num amp prob
                    io_utils::write_ascii_line $fh [format "%d %d %.6f %.6f %s" \
                        $row_index $state_num $amp $prob $test_label]
                    incr row_index
                }
            }
            close $fh
        }
    }

#  main controller layer 
    proc print_grover_result {max_state num_iterations test_label} {
        set outcome [math_core::compute_grover_outcome $max_state $num_iterations]
        lassign $outcome result_rows marked_total optimal_rounds \
            probability_sum target_probability_sum

        io_utils::log_console_line ""
        io_utils::log_console_line "-- $test_label --"
        io_utils::log_console_line [format "space=%d marked=%d iters=%d opt=%d" \
            [expr {$max_state + 1}] $marked_total $num_iterations $optimal_rounds]
        io_utils::log_console_line "state | amp | prob"
        io_utils::log_console_line "------|-----|-----"

        foreach row $result_rows {
            lassign $row i amp prob
            io_utils::log_console_line [format "%5d | %9.4f | %9.4f" $i $amp $prob]
        }

        io_utils::log_console_line [format "audit: prob_sum=%.4f target_sum=%.4f" \
            $probability_sum $target_probability_sum]

        return [list $result_rows $marked_total $optimal_rounds \
            $probability_sum $target_probability_sum]
    }

    proc run_grover_auto_tests {} {
        set test_cases {
            {7  2 {}}
            {7  2 {7}}
            {15 2 {10}}
            {15 3 {0}}
            {15 2 {3 5}}
            {15 3 {3 5 11}}
            {7  4 {7}}
            {31 3 {13}}
            {31 4 {7 15 23}}
            {3  1 {1}}
        }

        lassign [io_utils::start_console_log] log_file_name stamp_text
        io_utils::log_console_line "Grover auto test run started."
        io_utils::log_console_line "Console log file: $log_file_name"

        set wiki_file_name "grover_wiki_tables_${stamp_text}.txt"
        set prose_file_name "grover_prose_report_${stamp_text}.txt"
        set dump_file_name "grover_text_dump_${stamp_text}.txt"

        set all_wiki_blocks {}
        set all_paragraphs {}
        set all_test_rows {}
        set all_summary_rows {}
        set test_index 1

        foreach case $test_cases {
            lassign $case max_state num_iter marked_list
            set max_state [math_core::enforce_qubit_limit $max_state]
            oracle::set_solutions $marked_list

            set test_label "Test $test_index (max=$max_state iters=$num_iter)"
            io_utils::log_console_line ""
            io_utils::log_console_line "=== $test_label ==="
            io_utils::log_console_line "marked: $marked_list"

            set outcome [print_grover_result $max_state $num_iter $test_label]
            lassign $outcome result_rows marked_total optimal_rounds \
                probability_sum target_probability_sum

            set total_states [expr {$max_state + 1}]
            set baseline_target 0.0
            if {$marked_total > 0} {
                set baseline_target [expr {double($marked_total) / double($total_states)}]
            }

            lappend all_wiki_blocks [formatters::build_wiki_block $test_index $test_label \
                $result_rows $probability_sum $target_probability_sum $max_state]
            lappend all_paragraphs [formatters::build_prose_text $test_label $max_state $num_iter \
                $result_rows $marked_total $optimal_rounds $probability_sum \
                $target_probability_sum]
            lappend all_test_rows [list $test_label $result_rows]
            lappend all_summary_rows [list $test_label $marked_total \
                $target_probability_sum $baseline_target]

            incr test_index
        }

        set final_summary [formatters::build_final_summary $all_summary_rows]

        reports::save_wiki_report $wiki_file_name $stamp_text $all_wiki_blocks
        reports::save_prose_report $prose_file_name $stamp_text $all_paragraphs $final_summary
        reports::save_text_dump_all $dump_file_name $stamp_text $all_test_rows

        io_utils::log_console_line ""
        io_utils::log_console_line "Done: 10 tests."
        io_utils::log_console_line $final_summary
        io_utils::log_console_line "Files:"
        io_utils::log_console_line "   $log_file_name"
        io_utils::log_console_line "   $wiki_file_name"
        io_utils::log_console_line "   $prose_file_name"
        io_utils::log_console_line "   $dump_file_name"

        io_utils::stop_console_log
    }

    namespace export run_grover_auto_tests
}

::grover_engine::run_grover_auto_tests
 
# End of file

# References.
# 
# Inspired by counterfactual principles discussed in Chiara Marletto's book
# "The Science of Can and Can't: A Physicist's Journey 
# Through the Land of Counterfactuals" (2021).
# The dummy subroutine implements a generic simulation
# for educational purposes only.
#
puts "Credits"
# original 1996 paper — "A Fast Quantum Mechanical Algorithm 
# for Database Search," Lov K. Grover, AT&T Bell Labs,
# presented at STOC '96:
# 1997 follow-up, often cited & more accessible physics-journal:
# "Quantum Mechanics Helps in Searching for a Needle 
# in a Haystack," Lov K. Grover,  Phys. Rev. Lett. 79, 325 (1997).
# The algorithm (Shor’s) is public domain,
# and  mathematical knowledge since 1994.
# Peter Shore, Original 1994 Conference Paper
# Algorithms for Quantum Computation: Discrete Logarithms and Factoring
# Peter Shore, Polynomial-Time Algorithms for Prime Factorization
# and Discrete Logarithms on a Quantum Computer (1995 expanded version)
puts "Reference: Maria Violaris, arXiv:2601.08102v1, January 2026"
puts "Reference: https://wiki.tcl-lang.org/page/Snippets+Quantum+Many+Worlds"
puts "Based on ref. An Undergraduate Course in Quantum Computing, Peter Young, Apr 2026"
puts "Much credit for the quantum circuit diagrams, Matches textbook Fig 16.4 etc"
puts "University of California Santa Cruz, CA, arXiv:2604.10396"

+----------------------------------------------------------------------------------+
| TCL ORACLE MODULE: PROGRAM FLOW                                                  |
|                                                                                    |
|   +-------------------------+                                                    |
|   | Start                   |                                                    |
|   | run_grover_auto_tests   |                                                    |
|   +------------+------------+                                                    |
|                |                                                                 |
|                v                                                                 |
|   +-------------------------+                                                    |
|   | start_console_log       |  open dated log file                              |
|   +------------+------------+                                                    |
|                |                                                                 |
|                v                                                                 |
|   +-------------------------+                                                    |
|   | Loop: 10 test cases     |                                                    |
|   +------------+------------+                                                    |
|                |                                                                 |
|                v                                                                 |
|   +-------------------------+                                                    |
|   | enforce_qubit_limit     |                                                    |
|   | oracle set_solutions    |                                                    |
|   +------------+------------+                                                    |
|                |                                                                 |
|                v                                                                 |
|   +-------------------------+                                                    |
|   | run_grover_search       |  init uniform amplitudes                          |
|   |                         |  loop: oracle, diffusion                          |
|   +------------+------------+                                                    |
|                |                                                                 |
|                v                                                                 |
|   +-------------------------+                                                    |
|   | normalize_amp_list      |                                                    |
|   | apply_display_phase     |                                                    |
|   +------------+------------+                                                    |
|                |                                                                 |
|                v                                                                 |
|   +-------------------------+                                                    |
|   | print_grover_result     |  log console lines                                |
|   |                         |  build result rows                                |
|   +------------+------------+                                                    |
|                |                                                                 |
|                v                                                                 |
|   +-------------------------+                                                    |
|   | build_wiki_block        |                                                    |
|   | build_prose_text        |                                                    |
|   | verify_wiki_match       |                                                    |
|   +------------+------------+                                                    |
|                |                                                                 |
|                +--> (back to loop top, 10 times)                                |
|                |                                                                 |
|                v (loop done)                                                     |
|   +-------------------------+                                                    |
|   | build_final_summary     |                                                    |
|   +------------+------------+                                                    |
|                |                                                                 |
|                v                                                                 |
|   +-------------------------+                                                    |
|   | save_wiki_report        |                                                    |
|   | save_prose_report       |                                                    |
|   | save_text_dump_all      |                                                    |
|   +------------+------------+                                                    |
|                |                                                                 |
|                v                                                                 |
|   +-------------------------+                                                    |
|   | stop_console_log        |                                                    |
|   | End                     |                                                    |
|   +-------------------------+                                                    |
+----------------------------------------------------------------------------------+

+----------------------------------------------------------------------------------+
| 2 QUBIT GROVER CIRCUIT, MARKED STATE 2 (BINARY 10), ONE ITERATION               |
|                                                                                  |
|  q0: -[H]--[X]-------------*--------------------(DIFFUSER)---------------------- |
|  q1: -[H]------------------X--------------------(DIFFUSER)---------------------- |
|                                                                                  |
|  Oracle: control on q0, X-target on q1                                           |
|  Legend: [H] Hadamard   [X] Pauli-X   * control   X target of CX                |
+----------------------------------------------------------------------------------+

+----------------------------------------------------------------------------------+
| 3 QUBIT GROVER CIRCUIT, MARKED STATE 7 (BINARY 111), ONE ITERATION              |
|                                                                                  |
|  q0: -[H]--------------------*--------------------(DIFFUSER)-------------------- |
|  q1: -[H]--------------------*--------------------(DIFFUSER)-------------------- |
|  q2: -[H]--------------------X--------------------(DIFFUSER)-------------------- |
|                                                                                  |
|  Oracle: CCX with q0,q1 controls and q2 as target                                |
|  Legend: [H] Hadamard   [X] Pauli-X   * control   X target of CCX               |
+----------------------------------------------------------------------------------+

+----------------------------------------------------------------------------------+
| 2 QUBIT GROVER CIRCUIT, MARKED STATE 2 (BINARY 10), ONE ITERATION               |
|                                                                                    |
|  q0: -[H]--[X]---*---[X]--[H]--[X]--------*---[X]--[H]------                    |
|  q1: -[H]--[H]---X---[H]--[H]--[X]--[H]---X---[H]--[X]--[H]-                    |
|                                                                                    |
|  Legend: [H] Hadamard   [X] Pauli-X   * control point   X target of CX or CCX   |
+----------------------------------------------------------------------------------+

+----------------------------------------------------------------------------------+
| 3 QUBIT GROVER CIRCUIT, MARKED STATE 4 (BINARY 100), ONE ITERATION              |
|                                                                                  |
|  q0: -[H]--[X]-------------*--------------------(DIFFUSER)---------------------- |
|  q1: -[H]------------------*--------------------(DIFFUSER)---------------------- |
|  q2: -[H]------------------X--------------------(DIFFUSER)---------------------- |
|                                                                                  |
|  Oracle: CCX with q0,q1 controls and q2 target (after X on q0)                  |
|  Legend: [H] Hadamard   [X] Pauli-X   * control   X target of CCX               |
+----------------------------------------------------------------------------------+

+----------------------------------------------------------------------------------+
STANDARD GROVER DIFFUSER (n qubits)

   [H]   [X]      CZ      [X]   [H]
q0 ─┬────┬────────●────────┬────┬──
    │    │        │        │    │
q1 ─┼────┼────────●────────┼────┼──
    │    │        │        │    │
q2 ─┼────┼────────●────────┼────┼──
    │    │        │        │    │
q3 ─┴────┴────────●────────┴────┴──

Legend:
[H] Hadamard
[X] Pauli-X
●   multi-controlled Z (all qubits control the bottom Z)
+----------------------------------------------------------------------------------+

+----------------------------------------------------------------------------------+
| GRAPH 1 – INITIAL UNIFORM DISTRIBUTION (Before Any Oracle)                     |
|                                                                                  |
|   Search Space (N=8):                                                           |
|   State:  0    1    2    3    4    5    6    7                                 |
|   Amp:   0.35 0.35 0.35 0.35 0.35 0.35 0.35 0.35                              |
|                                                                                  |
|   All states have equal amplitude. No information yet.                          |
|   This is the starting point before the first oracle call.                      |
+----------------------------------------------------------------------------------+

+----------------------------------------------------------------------------------+
| GRAPH 2 – AFTER ORACLE (Phase Flip on Winning State=3)                         |
|                                                                                  |
|   State:  0    1    2    3    4    5    6    7                                 |
|   Amp:   0.35 0.35 0.35 -0.35 0.35 0.35 0.35 0.35                             |
|                                                                                  |
|   Oracle marks the winning state with a negative sign (phase flip).             |
|   Diffusion stage will now amplify this marked state.                           |
+----------------------------------------------------------------------------------+

+----------------------------------------------------------------------------------+
| GRAPH 3 – AFTER FIRST DIFFUSION                                                |
|                                                                                  |
|   Mean amplitude ≈ 0.25                                                         |
|   State:   00    01    10    11                                                 |
|   Amp:    0.00   1.00   0.00   0.00                                             |
|                                                                                  |
|   Diffusion reflects all amplitudes about the mean.                             |
|   Winning state (01) is strongly amplified to probability ~ 1.0.                  |
+----------------------------------------------------------------------------------+

+----------------------------------------------------------------------------------+
| GRAPH 4 – 2-QUBIT GROVER CIRCUIT (Marked State 01)                             |
|                                                                                  |
|  q0: ─[H]────────────────────*────────────────────(DIFFUSER)────────────────── |
|  q1: ─[H]──[X]──[H]──────────X────────────────────(DIFFUSER)────────────────── |
|                                                                                  |
|  Oracle: Control on q0, X-target on q1 (marks |01>)                             |
|  Legend: [H] Hadamard   [X] Pauli-X   * control   X target                      |
+----------------------------------------------------------------------------------+

Accuracy: approximate decimal-place precision.
Algorithm: step-by-step procedure for solving a problem.
Algorithm Classical: algorithm for a classical computer.
Algorithm Quantum: algorithm for a quantum computer.
Ancilla Qubits: Spare or extra helper qubits
    that receive Hadamard gates to create superposition under QAE.
Ancilla Register: Extra qubits used for phase estimation.
    The measurement of these qubits gives the estimated amplitude.
Backend-aware: can target simulators or real quantum hardware.
Backend classical: classical execution backend or simulator.
Backend quantum: quantum execution backend or device.
Basis State:  A basis state is a single possible outcome of the qubits.  
    It is written as |00>, |01>, |10>, |11>, etc.  
    For n qubits there are exactly 2^n basis states.  
    These are the standard building blocks of quantum states.
Bit: classical information unit for a classical computer.
BQP: bounded-error quantum polynomial-time.
Call Program: program that calls another program or routine.
Classical complexity: polynomial-time, but expensive for high precision.
Classical Error: usually scales as 1/sqrt(N), while quantum error scales as 1/N in a toy model.
Classical method: classical sampling or Monte Carlo-style estimation.
Circuit-based: programs are built as quantum circuits.
Computer Hardware: real hardware has noise, error correction overhead, 
     and implementation costs; these estimates are idealized 
     for tutorial purposes, not final engineering estimates.
Control Point:  
    The qubit with the black dot controls the gate below.  
    The target gate only activates when this qubit is |1⟩.
Controlled-Controlled-X: or Toffoli Gate, 
         CCX Flips the target qubit (applies X) only when both  
         control qubits are |1⟩.
Controlled-Z Gate: CZ Flips the phase (multiplies by -1) of the target qubit,  
         only when the control qubit is |1⟩.
Corner case: a more extreme edge case involving several boundary conditions at once.
DFT: discrete Fourier transform; FT for a finite list of values.
DFT Inverse: inverse discrete Fourier transform; 
   converts frequency data back to the original list.
Digits: number of correct decimal places.
Distribution data: data used to describe how values are spread or sampled.
Edge case: a rare or boundary condition that needs special handling.
Edge on Corner case: a more extreme edge case involving several boundary conditions at once.
Estimation Classical: estimation method for a classical computer.
Estimation Quantum: estimation method for a quantum computer.
Experimental: used for testing new ideas, not yet final or stable.
Exponential Speedup: reducing a needed size or number of trials from N to log(N) in idealized cases.
Gate Logic: gate-level logic representation.
Grover Operator Q: Q = - Diffusion × Oracle
      Q amplifies the amplitude of the marked (good) states.
Hardware integration: connects to IBM quantum devices and other backends.
Hadamard Gate: Creates superposition in a qubit. 
Iteration: repeated application of a procedure or update rule.
Logarithmic Speedup: reduction in cost proportional to log(N).
Measurement: Measures the qubit and collapses qubit into a classical 0 or 1.
Monte Carlo: classical random-sampling algorithm.
Monte Carlo PI: classical Monte Carlo estimation of pi.
Monte Carlo PI Weighted: weighted classical Monte Carlo estimation of pi.
Modular design: supports extensions, addons, and custom workflows.
Mockup: early draft version used for testing ideas.
Number of trials: N.
Oracle: black-box subcircuit used by a quantum algorithm, such as in Qiskit.
Open source SDK: free SDK for building and testing quantum programs.
Open source software: software whose source code is publicly 
   available to use, study, modify, and share.
Pauli-X: single-qubit bit-flip gate; quantum NOT.
Phase Estimation Bins: The possible measurement outcomes from the ancilla qubits.
   More ancilla qubits = more bins = higher precision.
Primitives: higher-level interfaces for running quantum workloads.
Production software: software intended for real use and release.
Prototype: early working version used for experimentation.
Python: high-level programming language.
Python-first: designed to feel natural for Python users, rule of Qiskit library
Python-Qiskit: Python environment with Qiskit library, for Python users.
Python-Qiskit-SDKs: Python environment with Qiskit library, on personal Workspace
Q Operator:  Operator represents the Grover iterate in Quantum Amplitude Estimation QAE.
Quantum Fourier Transform: Quantum version of the DFT 
   applied to qubit amplitudes.
Quantum Fourier Transform, Inverse: reverse QFT; 
   converts the QFT state back to the original state.
Qiskit: open-source quantum SDK for building, optimizing, and running quantum programs.
Quadratic speedup: reducing a needed size or number of trials 
   from N to sqrt(N), or from 1/sqrt(N) to 1/N 
   depending on the setup; faster, but not magical.
Quantum AI: AI methods using quantum computing or quantum-inspired workflows.
Quantum Amplitude Estimation: quantum method for estimating amplitudes or probabilities.
Quantum complexity: quadratic improvement in ideal cases for estimation tasks.
Quantum Error Correction: methods that protect quantum information from errors in a quantum computer.
Quantum Fourier Transform: 
Quantum Fourier Transform, Inverse: 
Quantum method: amplitude estimation, or a related quantum mean-estimation method.
Quantum Trials: research ~= (number of digits)^2.
Qubit: quantum information unit for a quantum computer.
Research friendly: good for experimentation, benchmarking, and algorithm development.
Sandbox: isolated test environment for trying ideas safely.
State Preparation Operator A: Initializes the system qubits into
  a superposition encoding the search or estimation problem. 
Scaling in code: metrics as program keeps working as the input size,
 number of users, or amount of data grows.
SDKs: software development kits.
Stub Program: placeholder program used during development.
Tcl/Tk: scripting language and GUI toolkit.
Toy model: simplified estimate for tutorial purposes.
Transpilation: rewrites circuits to fit a target device efficiently.
Visualization: includes tools for drawing and inspecting circuits.
Vaporware: announced software that is not yet real or deliverable.
Workspace Station: working machine or personal environment used for development.
X (target of CCX):  
         The target qubit that gets flipped in a CCX/Toffoli gate.  
         It changes |0⟩ to |1⟩ or |1⟩ to |0⟩ when both controls are active.
# End of File

evidence_tokens → score each conclusion → normalize → top-N conclusions