Scalable limit of Laptop Memory, Classical Computer CC

 RAM_bytes = 2^(N + 4), given state_vector of Qubits (N)
 N = log2(RAM_bytes) - 4
 RAM = 1 TB_terabyte = 2^40 bytes
 N = 40 - 4 = 36 qubits, not figuring CC overhead
 Usable Laptop Ram ~ 2.6 GB
 2.6 GB ≈ 2.6 * 2^30 bytes
 2.6 GB ≈ 2^31.3 bytes
 On cheap laptop, 20 Qubits seemed impossible dream
 for both Classical TCL/TK and Classical Python.
 So 20 Qubits picked for scalable limits study.
 N ≈ 20 Qubits, approximate practical
 memory limit of 20 Qubits on laptop. 

Mapping of A Priori Solution, not a math proof

First Test Case (Path 1)
Path 1 uses a designed fraction that forces a near-pi result.
relation PI ≈ 4 * probability, 
So probability ≈ 3.14 / 4 = 0.785. (This is the toy model and A Priori assumption here )

Qubit’s full state is described by 2 complex amplitudes
K = probability = |a|^2        
a = amplitude   = sqrt(K)      
PI/4 = K ~ 0.785 probability (dimensionless)  =>  a = sqrt(K) ~ 0.886 wave amplitude

Number of basis states = 2^N
For N = 2:
    2^2 = 4 basis states
    |00>, |01>, |10>, |11>

In amplitude estimation for QAE: 
    a = amplitude  of the "good" state
    K = probability of measuring the good state
    K = a^2   (strict quantum rule )

   For the 4 Qubit solution.
   4 qubits = 2^N = 2^4 = 16 states total
   each bin is  1/16 = 0.0625 or 6.24 percent
   4-qubit  (16 bins): 
   K=13/16=0.8125, 
   a = sqrt(0.8125) = 0.9014, 
   PI = 4*K ~ 3.25
   Absolute error is 0.1084
   Relative error on 4Q is about 0.0345, or 3.45 percent.

   For a 5 Qubit solution. 
   5 Qubits = 2**5 = 32 states 
   each bin is  1/32 = 0.03125  or 3.125 percent
   5-qubit  (32 bins): 
   K=25/32 = 0.78125, 
   a= sqrt(25/32) = 0.8839, 
   PI= 4 * K = 4 * 0.78125 ~ 3.125
   Absolute error ≈ 0.0166 
   Relative error on 5Q is 0.0053, or 0.53 percent.

   For a 6 Qubit solution. 
   6 Qubits = 2**6 = 64 states 
   each bin is  1/64 = 0.015625  or 1.5625 percent
   6-qubit   (64):
   K=  50/64  =  0.78125 , same as 5 Qubits
   Note, or use K = 51/64 = 0.796875, giving  PI = 3.1875, 
   bins getting small. Model showing diminishing returns.  
   a = sqrt(50/64) ≈ 0.883883  
   PI = 4 * K = 3.125 ????
   The relative error on 6Q is  0.0053, or 0.53 percent.
   Note. Improvement over 5 qubits is modest or zip. 
   Note. Toy Model may be approaching limit of useful 
   returns for computation effort, multiple scalability issues.
   Ideal performance on 10^7 QAE sweeps, order of magnitude estimate
   computation time ~ 40 seconds

   For a 12 Qubit solution, 
   would be painfully slow on laptop.
   12 qubits = 2^12 = 4096 bins
   each bin is  1/4096 =  0.0002441 or 0.02441 percent, rounded
   target p ≈ 0.785
   12-qubit (4096):   
   K = 3214/4096 ≈ 0.785156,   
   a = 0.886, 
   PI = 4*K ~ 3.140625
   Relative error on 12 Qubit case is 0.00031,
   or  0.031 percent. correct checked.  
   Ideal performance on 10^7 QAE sweeps
   time ~ 40 seconds, order of magnitude estimate, Toy Model

   My Classical Laptop equivalent to 20 Qubits
   memory has Scalable limits to QAE
   expr { 2**20} = 1048576
   expr {1./1048576.} = 9.5367E-7, 9.5267E-5 percent
   bins = 2^N = 2^20 ≈ 1048576  bins
   each bin is  1 / 1048576 =   or 9.5267E-5  percent, rounded
   simple ideal logic, overhead & OS would be far more limiting. 
   Low qubits (3–6)   ≈ 3.12–3.15 ,
   3-6 qubits has small number of bins 
   & high granularity, but reasonable C. times
   20-Qubit  (formuala 2^20): 
   K = 823549 / 1048576 = 0.785, rounded.
   expr {  823549 / 1048576.  } = 0.7853975, rnd
   check =  expr {(823549. / 1048576.)**0.5} = 0.886226 rnd
   a = 0.886226 , suspect past or approaching
   wave measurement limits, Checkmate!!! 
   PI = 3.141592,  ideal toy with many assumptions.
   Note: As of 2026, approaching scalability errors,
   readout errors, absolute errors  K
   in the range 0.01 – 0.05  moderate depth.
   Because a = sqrt(K), derived absolute error
   amplitude a is roughly 0.005 – 0.03.
   Final realistic QAE error on pi or e is often 0.02 – 0.15.
   For 20Q toy model, 10^5 to 10^6 sweeps for useful precision.
   For 1E6 sweeps, roughly 2–6 days on 20Q toy model, idealized
   10^9 QAE sweeps ~ time ≈ ~4 years, range 3 to 4 years. 
   but laptop has high overhead
   and beyond 14 qubits near impossible computation times in CC laptop.
   Result on 20 Qubits reflects the design of the toy model rather 
   than a realistic noisy CC  computation.
   Classical overhead, cache behavior, and operating system activity 
   would make laptop runtime even  longer and far more fragile.
   The 20 qubit testcase,  therefore serves best 
   as a conceptual upper bound and a thought experiment on scalability.
  
--- QAE NOTE on Strict Quantum definitions ---
    QAE estimates amplitude `a`.
    Measurement yields prob K = a^2.
    Toy model maps K ,  PI/4 directly; `a` is sqrt(K) only.
    This is where the Quantum algorithm differs from Classical methods,
    Probability is assigned or measured to wave amplitude in QAE.

Mapping of Different QAE Assumptions, not a math proof

Second Test Case (Path 2)

Second path follows the Monte Carlo structure,
meaning the geometric model, 
used in actual QAE-for-pi circuits.
Random points (x, y) are encoded.
A circuit marks states where x^2 + y^2 <= 1.
The good probability is p = pi/4.
QAE estimates p, then multiplies by 4 to recover pi.
Estimates probability points inside the unit circle, 
then scale by 4.
Stays close to the first-path 5-qubit numbers,
so resulting coding formulas almost identical. 
----
The math is kept simple for high-school level mapping.
No heavy arithmetic circuits are simulated.
----
# These are high level  exec or calls in pseudocode
# Caution: Underlying Quantum Interference process is 
# coherent and simultaneous rather than purely sequential.
# This point is where Classical Computers reach limits of 
# Scalability. 
exec { Call state prep for equal superposition over grid points.}
exec { Call coord mapping to encode discrete (x, y) pairs. }
exec { Call marking oracle for x² + y² ≤ 1 states. }
exec { Call controlled amplitude-estimation iterates.}
exec { Call QFT on count register, measure, extract K.}


----

2 qubits = 2**2 = 4 states 
Each bin = 1/4 = 0.25
K = 3/4 = 0.75
a = sqrt(0.75) ≈ 0.8660
PI = 4 * K = 3.00
Absolute error ≈ 0.1416
Relative error ≈ 4.51 percent

4 qubits = 2**4 = 16 states 
Each bin = 1/16 = 0.0625
K = 13/16 = 0.8125
a = sqrt(0.8125) ≈ 0.9014
PI = 4 * K = 3.25
Absolute error ≈ 0.1084
Relative error ≈ 3.45 percent

5 qubits = 2**5 = 32 total states
Target good probability K ≈ 0.785398
Chosen good states (conservative discrete count):
K = 25/32 = 0.78125 
a = sqrt(0.78125) ≈ 0.88388
PI = 4 * K = 3.125
Absolute error ≈ 0.01659
Relative error ≈ 0.53 percent 

6 qubits = 2**6 = 4096 total states
Each bin ≈ 0.0002441
K = 3214/4096 ≈ 0.785156
a ≈ 0.8861
PI = 4 * K ≈ 3.140625
Absolute error ≈ 0.000968
Relative error ≈ 0.031 percent

12 qubits = 2**12 = 4096 states 
Each bin ≈ 0.0002441
K = 3214/4096 ≈ 0.785156
a ≈ 0.8861
PI = 4 * K ≈ 3.140625
Absolute error ≈ 0.000968
Relative error ≈ 0.031 percent

Second path follows the Monte Carlo structure,
meaning the geometric model. 

Mapping of Different QAE Assumptions, not a math proof

Third Test Case (Path 3)
----
Path 3 for e simply reuses the same numerical
framework with a different target constant.
It does not rely on a circle or any geometric area.
It is only an amplitude-estimation style 
mapping chosen for teaching convenience.

----
The math is kept simple and idealized
for high-school level mapping.
No heavy arithmetic circuits are simulated.
----

Target: e ≈ 2.71828
Mapping used: e ≈ 4 * K, 
So target K ≈ 0.67957

2 qubits = 2**2 = 4 states 
K = 3/4 = 0.75
a ≈ 0.8660
e_est = 3.00
Absolute error ≈ 0.2817
Relative error ≈ 10.36 percent

4 qubits = 4^4 = 16 states 
K = 11/16 = 0.6875
a ≈ 0.8292
e_est = 2.75
Absolute error ≈ 0.0317
Relative error ≈ 1.17 percent

5 qubits = 2^5 = 32 states 
K = 22/32 = 0.6875
a ≈ 0.8292
e_est = 2.75
Absolute error ≈ 0.0317
Relative error ≈ 1.17 percent

6 qubits = 2**6 = 64 states 
K = 43/64 = 0.671875
a ≈ 0.8197
e_est = 2.6875
Absolute error ≈ 0.0308
Relative error ≈ 1.13 percent

12 qubits = 4096 states
K = 2784/4096 ≈ 0.679688
a ≈ 0.8244
e_est ≈ 2.71875
Absolute error ≈ 0.00047
Relative error ≈ 0.017 percent

Path 3 keeps the same coding formulas as the earlier lists.
Only the recovered constant changes from pi to e.

Mapping of Different QAE Assumptions, not a math proof

Path 4 with Small Phase Correction (e)

Target: e ≈ 2.71828
Base mapping: e ≈ 4 * K,
so target K ≈ 0.67957  
One extra correction line is added:
e_corrected = 4 * K * (1 + phase_factor)
A small fixed phase_factor of +0.011 is used for illustration.

2 qubits = 2^2 = 4 states 
K = 3/4 = 0.75
e_raw = 3.00
e_corrected = 3.00 * 1.011 ≈ 3.033
Absolute error ≈ 0.315
 
4 qubits = 4^4 = 16 states 
K = 11/16 = 0.6875
e_raw = 2.75
e_corrected = 2.75 * 1.011 ≈ 2.780
Absolute error ≈ 0.062 

5 qubits = 32 states 
K = 22/32 = 0.6875
e_raw = 2.75
e_corrected = 2.75 * 1.011 ≈ 2.780
Absolute error ≈ 0.062 

6 qubits 2^4 = 64 states 
K = 43/64 = 0.671875
e_raw = 2.6875
e_corrected = 2.6875 * 1.011 ≈ 2.717
Absolute error ≈ 0.0013 

12 qubits = 2**12 = 4096 states
K = 2784/4096 ≈ 0.679688
e_raw ≈ 2.71875
e_corrected ≈ 2.71875 * 1.011 ≈ 2.7487
Absolute error ≈ 0.0304 

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

# 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 2002 paper, Quantum Amplitude Estimation (QAE)
# algorithm by Brassard et al., 2002, 
# 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"

| Test | Qubits | Precision | Marked | Estimated a | Estimated pi | Abs Error |
| 1 | 3 | 1 | 4 | 0.781806 | 3.127226 | 0.014367 |
| 2 | 3 | 2 | 4 | 0.789483 | 3.157931 | 0.016338 |
| 3 | 4 | 1 | 6 | 0.785615 | 3.142459 | 0.000867 |
| 4 | 4 | 2 | 6 | 0.791861 | 3.167444 | 0.025851 |
| 5 | 4 | 3 | 6 | 0.788243 | 3.152971 | 0.011378 |
| 6 | 5 | 2 | 6 | 0.786384 | 3.145535 | 0.003942 |
| 7 | 5 | 3 | 6 | 0.787884 | 3.151537 | 0.009944 |
| 8 | 6 | 2 | 6 | 0.782401 | 3.129604 | 0.011989 |
| 9 | 6 | 3 | 6 | 0.785733 | 3.142931 | 0.001338 |
| 10 | 6 | 4 | 6 | 0.785233 | 3.140932 | 0.000661 |

+-------------------------------------------------------------+
| 2 System Qubits + 2 Ancilla Qubits                         |
|                                                             |
| a0: ─[H]─────────────●───────────────────●───────[QFT†]──M |
|                      │                   │                 |
| a1: ─[H]─────────────┼───────●───────────┼───────[QFT†]──M |
|                      │       │           │                 |
| q0: ─[A]────────[Q¹]─┼───[Q²]───────────┼───────────────── |
|                      │       │           │                 |
| q1: ─[A]────────[Q¹]─┴───[Q²]───────────┴───────────────── |
|                                                             |
| Legend:                                                     |
| [H]    = Hadamard gate                                      |
| [A]    = State Preparation                                  |
| [Q^k]  = Grover operator Q raised to power k (2^k iters)   |
| [QFT†] = Inverse Quantum Fourier Transform                 |
| ●      = Control                                            |
| M      = Measurement                                        |
+-------------------------------------------------------------+

+-------------------------------------------------------------------+
| 3 System Qubits + 3 Ancilla Qubits                               |
|                                                                   |
| a0: ─[H]───────●─────────●─────────●────────────[QFT†]────M     |
|                │         │         │                              |
| a1: ─[H]───────┼────●────┼────●────┼────────────[QFT†]────M     |
|                │    │    │    │    │                              |
| a2: ─[H]───────┼────┼────┼────┼────●────────────[QFT†]────M     |
|                │    │    │    │                                  |
| q0: ─[A]────[Q¹]─┼─[Q²]──┼─[Q⁴]──┼─[Q⁸]─────────────────────── |
|                │    │    │    │                                  |
| q1: ─[A]────[Q¹]─┼─[Q²]──┼─[Q⁴]──┼─[Q⁸]─────────────────────── |
|                │    │    │    │                                  |
| q2: ─[A]────[Q¹]─┴─[Q²]──┴─[Q⁴]──┴─[Q⁸]─────────────────────── |
|                                                                   |
| Legend:                                                           |
| [H]    = Hadamard gate                                            |
| [A]    = State Preparation                                        |
| [Q^k]  = Grover operator Q raised to power k (2^k iterations)    |
| [QFT†] = Inverse Quantum Fourier Transform on ancilla register   |
| ●      = Control                                                  |
| M      = Measurement                                              |
+-------------------------------------------------------------------+

+------------------------------------------------------------+
| STANDARD DIFFUSER BLOCK (same as Grover)                  |
| This block is embedded in every controlled-Q operator     |
|                                                            |
| q0 ─[H]──[X]─────●─────[X]──[H]──                         |
|                  │                                         |
| q1 ─[H]──[X]─────●─────[X]──[H]──                         |
|                  │                                         |
| q2 ─[H]──[X]─────●─────[X]──[H]──                         |
|                                                            |
| Legend:                                                    |
| [H] = Hadamard gate                                        |
| [X] = Pauli-X gate                                         |
| ●   = Multi-controlled Z (CZ for 2 qubits, CCCZ for 3)    |
+------------------------------------------------------------+

+---------------------------------------------------------------+
| QAE ANCILLA MEASUREMENT BINS (8 bins from 3 ancilla qubits)  |
|                                                               |
| Bin:   0     1     2     3     4     5     6     7          |
| Prob: 0.00  0.00  0.00  0.05  0.90  0.05  0.00  0.00        |
|                                                               |
|        |     |     |     |     |     |     |     |           |
|        |     |     |     |#### |######|#### |     |           |
|        |     |     |     |#### |######|#### |     |           |
|        |     |     |     |#### |######|#### |     |           |
|        +-----+-----+-----+-----+-----+-----+-----+           |
|                                                               |
| Tall central bin  = most likely phase estimate                |
| Side lobes        = quantum interference (Fourier leakage)    |
| More ancilla qubits = narrower bins = sharper estimate        |
+---------------------------------------------------------------+

+----------------------------------------------------------------------------------+
| SCALABLE LIMIT OF LAPTOP MEMORY, CLASSICAL COMPUTER CC                          |
|                                                                                    |
|   Formula: RAM_bytes = 2^(N + 4)   given complex state_vector of N Qubits          |
|   Solve for N: N = log2(RAM_bytes) - 4  , empirical formula for Toy, not derived   |
|                                                                                    |
|   +----------------------+---------------------+------------------------+       |
|   | RAM available        | RAM in bytes         | N (max qubits)         |       |
|   +----------------------+---------------------+------------------------+       |
|   | 1 TB (theoretical)   | 2^40 bytes            | 40 - 4 = 36 qubits     |       |
|   |                      |                       | (not counting overhead)|       |
|   | 2.6 GB (usable)      | approx 2^31.3 bytes   | usable est. = 20 qubits |       |
|   +----------------------+---------------------+------------------------+       |
|                                                                                    |
|   Practical study limit chosen for this toy model: 20 qubits.                   |
|   20 qubits already strains pure Tcl / pure Python on a typical laptop.         |
+----------------------------------------------------------------------------------+

+----------------------------------------------------------------------------------+
| QAE TOY MODEL: OVERALL WORKED-PROBLEM FLOW                                       |
|                                                                                    |
|   +-------------------------+                                                    |
|   | Pick target constant    |  example: PI, or e                                |
|   +------------+------------+                                                    |
|                |                                                                 |
|                v                                                                 |
|   +-------------------------+                                                    |
|   | Choose N qubits          |  sets basis states = 2^N                         |
|   +------------+------------+                                                    |
|                |                                                                 |
|                v                                                                 |
|   +-------------------------+                                                    |
|   | Pick good-state count    |  integer count out of 2^N bins                   |
|   +------------+------------+                                                    |
|                |                                                                 |
|                v                                                                 |
|   +-------------------------+                                                    |
|   | K = good_count / 2^N     |  probability, strict rule K = a^2                |
|   +------------+------------+                                                    |
|                |                                                                 |
|                v                                                                 |
|   +-------------------------+                                                    |
|   | a = sqrt(K)               |  wave amplitude                                 |
|   +------------+------------+                                                    |
|                |                                                                 |
|                v                                                                 |
|   +-------------------------+                                                    |
|   | recovered_const = 4 * K  |  toy mapping, not a formal proof                 |
|   +------------+------------+                                                    |
|                |                                                                 |
|                v                                                                 |
|   +-------------------------+                                                    |
|   | compute absolute error   |                                                    |
|   | compute relative error   |                                                    |
|   +-------------------------+                                                    |
|                                                                                |
|   Practical study limit chosen for this toy model: 20 qubits.                   |
|   20 qubits already strains pure Tcl / pure Python on a modest laptop.         |
|                                                                                |
+----------------------------------------------------------------------------------+

+----------------------------------------------------------------------------------+
| PATH 1: PI ESTIMATE BY QUBIT COUNT  (target K approx 0.785)                     |
|                                                                                    |
| +--------+----------+---------------+----------+-----------+-----------------+ |
| | Qubits | 2^N bins | K (fraction)  | a=sqrt(K)| PI = 4*K  | Relative error  | |
| +--------+----------+---------------+----------+-----------+-----------------+ |
| | 4      | 16       | 13/16=0.8125  | 0.9014   | 3.25      | 3.45 percent    | |
| | 5      | 32       | 25/32=0.78125 | 0.8839   | 3.125     | 0.53 percent    | |
| | 6      | 64       | 50/64=0.78125 | 0.8839   | 3.125     | 0.53 percent    | |
| | 12     | 4096     | 3214/4096     | 0.886    | 3.140625  | 0.031 percent   | |
| | 20     | 1048576  | 823550/       | 0.8862   | -         | at limits on Toy | |
| |        |          |   1048576     |          |           | (Toy, ideal)    | |
| +--------+----------+---------------+----------+-----------+-----------------+ |
|                                                                                    |
|   Note: 6-qubit step shows almost no gain over 5-qubit step, diminishing        |
|   returns already visible in a small toy model. Results and numeric stability   |
|   on 20Q are limited  by assumptions on Idealized Toy Model                    |
|                                                                                |
|   Practical study limit chosen for this toy model: 20 qubits.                   |
|   20 qubits already strains pure Tcl / pure Python on a modest laptop.         |
|                                                                                |
+----------------------------------------------------------------------------------+

+----------------------------------------------------------------------------------+
| PATH 2: PI VIA MONTE CARLO GEOMETRIC MODEL                                      |
|                                                                                    |
|   Setup: random points (x, y), circuit marks states where x^2 + y^2 <= 1        |
|   Good probability p = PI / 4.  QAE estimates p, then result is scaled by 4.    |
|                                                                                    |
| +--------+----------+---------------+----------+-----------+-----------------+ |
| | Qubits | 2^N bins | K (fraction)  | a=sqrt(K)| PI = 4*K  | Relative error  | |
| +--------+----------+---------------+----------+-----------+-----------------+ |
| | 2      | 4        | 3/4=0.75      | 0.8660   | 3.00      | 4.51 percent    | |
| | 4      | 16       | 13/16=0.8125  | 0.9014   | 3.25      | 3.45 percent    | |
| | 5      | 32       | 25/32=0.78125 | 0.8839   | 3.125     | 0.53 percent    | |
| | 6      | 64       | 50/64=0.78125 | 0.8839   | 3.125     | 0.53 percent    | |
| | 12     | 4096     | 3214/4096     | 0.8861   | 3.140625  | 0.031 percent   | | 
| +--------+----------+---------------+----------+-----------+-----------------+ |
|                                                                                    |
|   Result: Path 2 numbers stay close to Path 1, so both paths share almost      |
|   the same underlying coding formulas on Toy Model.                            |
+----------------------------------------------------------------------------------+

+----------------------------------------------------------------------------------+
| PATH 3: ESTIMATING E, SAME FRAMEWORK, DIFFERENT TARGET CONSTANT                 |
|                                                                                    |
|   Target: e approx 2.71828    Mapping: e approx 4 * K                          |
|   Target K approx 0.67957     No circle or geometric shape used, teaching only |
|                                                                                    |
| +--------+----------+---------------+----------+-----------+-----------------+ |
| | Qubits | 2^N bins | K (fraction)  | a=sqrt(K)| e_est=4*K | Relative error  | |
| +--------+----------+---------------+----------+-----------+-----------------+ |
| | 2      | 4        | 3/4=0.75      | 0.8660   | 3.00      | 10.36 percent   | |
| | 4      | 16       | 11/16=0.6875  | 0.8292   | 2.75      | 1.17 percent    | |
| | 5      | 32       | 22/32=0.6875  | 0.8292   | 2.75      | 1.17 percent    | |
| | 6      | 64       | 43/64=0.671875| 0.8197   | 2.6875    | 1.13 percent    | |
| | 12     | 4096     | 2784/4096     | 0.8244   | 2.71875   | 0.017 percent   | |
| +--------+----------+---------------+----------+-----------+-----------------+ |
|                                                                                    |
|   Note: only the recovered constant changes here, from PI to e. Coding         |
|   formulas stay identical to Path 1 and Path 2.                                 |
+----------------------------------------------------------------------------------+

+----------------------------------------------------------------------------------+
| PATH 4: E ESTIMATE WITH SMALL PHASE CORRECTION                                  |
|                                                                                    |
|   Base mapping: e approx 4 * K       Target K approx 0.67957                   |
|   Correction:  e_corrected = 4 * K * (1 + phase_factor)                        |
|   phase_factor = +0.011  (fixed, empirical, illustration only)                 |
|                                                                                    |
| +--------+----------+-----------+---------------+---------------------------+  |
| | Qubits | 2^N bins | e_raw=4*K | e_corrected   | Absolute error (corrected)|  |
| +--------+----------+-----------+---------------+---------------------------+  |
| | 2      | 4        | 3.00      | 3.033         | 0.315                     |  |
| | 4      | 16       | 2.75      | 2.780         | 0.062                     |  |
| | 5      | 32       | 2.75      | 2.780         | 0.062                     |  |
| | 6      | 64       | 2.6875    | 2.717         | 0.0013                    |  |
| | 12     | 4096     | 2.71875   | 2.7487        | 0.0304                    |  |
|                                                                             |  |
|   Caution: phase_factor is an empirical adjustment, not derived from Quantum   |
|   Phase Estimation (QPE). Applying it does not make this real QPE.             |
+----------------------------------------------------------------------------------+

+----------------------------------------------------------------------------------+
| FOUR PATHS SIDE BY SIDE COMPARISON  (12-qubit case, common reference point)     |
|                                                                                    |
| +--------+------------------+-----------+---------------+---------------------+ |
| | Path   | Target constant  | K value   | Estimate      | Relative error      | |
| +--------+------------------+-----------+---------------+---------------------+ |
| | 1      | PI               | 0.785156  | 3.140625      | 0.031 percent       | |
| | 2      | PI (Monte Carlo) | 0.785156  | 3.140625      | 0.031 percent       | |
| | 3      | e                | 0.679688  | 2.71875       | 0.017 percent       | |
| | 4      | e (corrected)    | 0.679688  | 2.7487        | phase-factor added  | |
| +--------+------------------+-----------+---------------+---------------------+ |
|                                                                                    |
|   Paths 1 and 2 use the same numeric pattern, since Path 2 only reframes       |
|   Path 1 as a geometric Monte Carlo setup. Path 3 swaps in a new target        |
|   constant. Path 4 adds an ad-hoc correction on top of Path 3.                 |
+----------------------------------------------------------------------------------+

+----------------------------------------------------------------------------------+
| TOY RESOURCE ESTIMATE FOR QAE CIRCUITS (WITH BINS, ROUGH, EDUCATIONAL)          |
|                                                                                    |
|   Assumptions:                                                                    |
|   - Canonical QAE style with m ancilla (evaluation) qubits.                      |
|   - Number of bins M = 2^m.                                                      |
|   - Bin width in probability space approx 1/M.                                   |
|   - Each controlled-Q^k block treated as one "macro-gate" in this toy model.    |
|   - Depth measured in macro-gate steps, not individual physical gates.          |
|                                                                                    |
| +--------+----------+----------+----------+------------+------------------+----+ |
| | Qubits | Ancillas | System   | Bins M   | Bin width  | Approx Gate      |Approx| |
| | total  | (m)      | qubits   | (=2^m)   | (prob)     | Count (macro)    |Cir.  | |
| | N      |          | (n)      |          |            |                  |Depth | |
| |        |          |          |          |            |                  |(mac) | |
| +--------+----------+----------+----------+------------+------------------+------+ |
| | 4      | 2        | 2        | 4        | 0.25       | ~20              | ~10  | |
| | 6      | 3        | 3        | 8        | 0.125      | ~40              | ~20  | |
| | 8      | 4        | 4        | 16       | 0.0625     | ~80              | ~40  | |
| | 12     | 6        | 6        | 64       | 0.0156     | ~200             | ~100 | |
| | 16     | 8        | 8        | 256      | 0.0039     | ~500             | ~250 | |
| | 20     | 10       | 10       | 1024     | 0.00098    | ~1200            | ~600 | |
| +--------+----------+----------+----------+------------+------------------+------+ |
|                                                                                    |
|   Notes:                                                                          |
|   - More ancilla qubits give more bins and smaller bin width.                   |
|   - Smaller bin width means finer resolution for the estimated probability.     |
|   - Gate count and depth grow as more ancilla qubits are added.                 |
|   - These numbers are toy estimates, not detailed resource counts.               |
|   - Real QAE circuits also include state preparation, oracle, and QFT gates.     |
                                                                                  |
|                                                                                    |
+----------------------------------------------------------------------------------+

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