**** figure. QUANTUM CIRCUIT VISUALIZATION OVERVIEW ****

+----------------------------------------------------------------------------------+
| QUANTUM CIRCUIT VISUALIZATION - EDUCATIONAL TOY                                  |
|                                                                                  |
|    Features:                                                                     |
|      • Pure ASCII output (strict 7-bit, Playground V9 safe)                      |
|      • Time flows left to right                                                  |
|      • Each horizontal line = one qubit                                          |
|      • Gates shown as [H], [S], [T], [X], M (measurement)                        |
|      • CNOT shown with o (control) ── X (target)                                 |
|      • Double-hatch borders (## ... ##) for clarity                              |
|                                                                                  |
|    Goal: Build intuition for superposition, entanglement,                        |
|          and measurement without heavy simulators                                |
+----------------------------------------------------------------------------------+

**** figure. SINGLE QUBIT SUPERPOSITION (HADAMARD GATE) **** 

+----------------------------------------------------------------------------------+
| 1. SUPERPOSITION EXAMPLE                                                         |
|                                                                                  |
| ## q0: |0> ---[H]--- ##                                                          |
|                                                                                  |
|    Operation: Apply Hadamard gate to qubit 0                                     |
|    Result: Creates equal superposition                                           |
|            |0⟩  →  (|0⟩ + |1⟩)/√2                                                |
|                                                                                  |
|    Classic first step in almost every quantum algorithm                          |
+----------------------------------------------------------------------------------+

**** figure. BELL STATE ENTANGLEMENT (H + CNOT) **** 

+----------------------------------------------------------------------------------+
| 2. BELL STATE (MAXIMALLY ENTANGLED EPR PAIR)                                    |
|                                                                                  |
| ## q0: |0> ---[H]------o----- ##                                                 |
| ## q1: |0> ------------X----- ##                                                 |
|                                                                                  |
|    Steps:                                                                        |
|      1. Hadamard on qubit 0 → superposition                                      |
|      2. CNOT (control 0, target 1) → entanglement                                |
|                                                                                  |
|    Final state: (|00⟩ + |11⟩)/√2   (Bell Φ⁺ state)                              |
|    Classic demonstration of quantum entanglement                                 |
+----------------------------------------------------------------------------------+

**** figure. BELL STATE WITH MEASUREMENT **** 

+----------------------------------------------------------------------------------+
| 3. BELL STATE + MEASUREMENT                                                      |
|                                                                                  |
| ## q0: |0> ---[H]------o-----M--- ##                                             |
| ## q1: |0> ------------X-----M--- ##                                             |
|                                                                                  |
|    Full experiment:                                                              |
|      Create entanglement → measure both qubits                                   |
|                                                                                  |
|    Expected result:                                                              |
|      Always get 00 or 11 together (perfect correlation)                          |
|    Demonstrates collapse and correlation in measurement                          |
+----------------------------------------------------------------------------------+

**** figure. PHASE KICKBACK EXAMPLE **** 

+----------------------------------------------------------------------------------+
| 4. PHASE KICKBACK TOY CIRCUIT                                                    |
|                                                                                  |
| ## q0: |0> ---[H]------[S]------[H]---M--- ##                                    |
|                                                                                  |
|    Sequence: H → S (phase) → H → Measure                                         |
|                                                                                  |
|    Shows how phase on one qubit affects interference                             |
|    Important building block for:                                                 |
|      • Deutsch–Jozsa algorithm                                                   |
|      • Phase estimation                                                          |
|      • Many quantum algorithms                                                   |
+----------------------------------------------------------------------------------+

**** figure. GHZ STATE (THREE-QUBIT ENTANGLEMENT) **** 

+----------------------------------------------------------------------------------+
| 5. GHZ STATE PREPARATION (3 QUBITS)                                             |
|                                                                                  |
| ## q0: |0> ---[H]------o-------------o----- ##                                   |
| ## q1: |0> ------------X-------------|----- ##                                   |
| ## q2: |0> --------------------------X----- ##                                   |
|                                                                                  |
|    Creates GHZ state: (|000⟩ + |111⟩)/√2                                         |
|    True multi-qubit entanglement                                                 |
|    Foundation for quantum error correction and teleportation studies             |
+----------------------------------------------------------------------------------+

**** figure. QUANTUM CIRCUIT SYMBOL LEGEND **** 

+----------------------------------------------------------------------------------+
| QUANTUM CIRCUIT SYMBOL LEGEND                                                    |
|                                                                                  |
|    [H]   → Hadamard gate          (superposition)                                |
|    [S]   → Phase gate (π/2)                                                      |
|    [T]   → T gate (π/4 phase)                                                    |
|    [X]   → Pauli-X (bit flip)                                                    |
|    M     → Measurement (Z basis)                                                 |
|    o-----                                                        |
|         X   → CNOT (controlled-NOT)                                              |
|    ---   → Idle wire / time step                                                 |
|    ##    → Diagram borders (for clarity in wiki/playground)                      |
|                                                                                  |
|    Time flows left → right                                                       |
+----------------------------------------------------------------------------------+

**** figure. QUANTUM CIRCUIT SUMMARY **** 

+----------------------------------------------------------------------------------+
| EDUCATIONAL SUMMARY                                                              |
|                                                                                  |
|    This pure-Tcl ASCII quantum circuit toy lets students:                        |
|      • Visualize superposition and entanglement                                  |
|      • Experiment with gate sequences instantly                                  |
|      • Understand measurement collapse                                           |
|      • Run in Playground V9 without any extra tools                              |
|                                                                                  |
|    Perfect for beginners and collegiate labs                                     |
|    Focuses on intuition rather than heavy simulation                             |
+----------------------------------------------------------------------------------+

# Tcl 
# Educational quantum_circuit_ascii Prototype (strict ASCII only) V5 
# Human Readable Names Employed Edition
# Goal: Make relationships and calculations easier to read and teach
# for Tool Control Language Programs
# Compatible with Tcl/Tk 8.6+
# TCL source code follows
# Written for Windows 11 on ActiveState TCl
# Working on TCL Playground V9, strict ASCII only
# Optimized for collegiate IT lab environments
# Working under TCL version 8.6
# Added Automatic Dump of Examples, Using ActiveState
# Added temp double hatch border.
# Complex math calculations up to 3 units computer time
# Wait for complete calculations before saving files.
# TCL club, 02/3/2026
#
# ----------------------------------------------------------------------------
#  Educational  Prototype (strict ASCII only)
# For Tcl 8.6 or later
# Designed for large font / weak eyes: simple text, clear comments
console show
# print_quantum_circuit --
# Renders ASCII quantum circuit with wide forced dashed line as 
# temp space separator to survive Playground quirks
#
proc print_quantum_circuit {circuit {num_qubits 2}} {
    # Initialize diagram lines for each qubit
    set qubit_diagram_lines {}
    for {set qubit_index 0} {$qubit_index < $num_qubits} {incr qubit_index} {
        lappend qubit_diagram_lines [list "q${qubit_index}: |0>" ""]
    }

    # ─────────────────────────────────────────────────────────────────────────────
    # Process each gate/time-step
    # ─────────────────────────────────────────────────────────────────────────────
    foreach gate_step $circuit {
        set gate_name   [lindex $gate_step 0]
        set gate_args   [lrange $gate_step 1 end]

        # Default wide idle wire
        set column_symbols [lrepeat $num_qubits "----------"]

        if {$gate_name eq "CNOT"} {
            set control_qubit [lindex $gate_args 0]
            set target_qubit  [lindex $gate_args 1]

            lset column_symbols $control_qubit "  o-----  "
            lset column_symbols $target_qubit  "   X      "

            set lower [expr {min($control_qubit, $target_qubit)}]
            set upper [expr {max($control_qubit, $target_qubit)}]
            for {set mid [expr {$lower + 1}]} {$mid < $upper} {incr mid} {
                lset column_symbols $mid "   |      "
            }

        } elseif {$gate_name eq "M"} {
            set measured_qubit [lindex $gate_args 0]
            lset column_symbols $measured_qubit "    M     "

        } else {
            # Single-qubit gate: safe construction to avoid [ ] substitution
            set operated_qubit [lindex $gate_args 0]
            set gate_symbol    [string toupper [string range $gate_name 0 0]]
            # Build string safely: concat pieces
            set gate_block [concat "---" "\[" $gate_symbol "\]" "---"]
            lset column_symbols $operated_qubit $gate_block
        }

        # Append column to each line
        for {set qubit_index 0} {$qubit_index < $num_qubits} {incr qubit_index} {
            set existing_line [lindex $qubit_diagram_lines $qubit_index]
            lset qubit_diagram_lines $qubit_index \
                [concat $existing_line [lindex $column_symbols $qubit_index]]
        }
    }

    # ─────────────────────────────────────────────────────────────────────────────
    # Add left + right double-hatch borders (## ... ##) – pure ASCII
    # ─────────────────────────────────────────────────────────────────────────────
    for {set i 0} {$i < $num_qubits} {incr i} {
        set line [lindex $qubit_diagram_lines $i]
        
        # Join columns first so wires stay connected
        set rendered [join $line ""]
        
        # Add double hatch borders with small spacing
        # set new_rendered " ##${rendered}## "
        # added patch, shows alternate look
        set new_rendered " ## ${rendered} ## "
        # Store as single string per line
        lset qubit_diagram_lines $i [list $new_rendered]
    }

    # Output the diagram
    foreach diagram_line $qubit_diagram_lines {
        puts [lindex $diagram_line 0]
    }
    puts ""   ;# blank separator
}

# ─────────────────────────────────────────────────────────────────────────────
# Automatic examples when file is sourced / run directly
# ─────────────────────────────────────────────────────────────────────────────

if { [info script] eq $::argv0 } {   ;# only run examples if script is main file

    puts "\nEducational quantum circuit examples"
    puts "--------------------------------------------\n"

    puts "1. Superposition:"
    print_quantum_circuit {{H 0}} 1

    puts "2. Bell state (EPR pair):"
    print_quantum_circuit {
        {H 0}
        {CNOT 0 1}
    } 2

    puts "3. Bell state + both measured:"
    print_quantum_circuit {
        {H 0}
        {CNOT 0 1}
        {M 0}
        {M 1}
    } 2

    puts "4. Phase kickback toy example:"
    print_quantum_circuit {
        {H 0}
        {S 0}
        {H 0}
        {M 0}
    } 1

    puts "5. Two-qubit controlled-phase (example):"
    print_quantum_circuit {
        {H 0}
        {H 1}
        {CNOT 0 1}
        {S 1}
        {CNOT 0 1}
    } 2
}

(tcl) 14 % 
(tcl) 14 % # Expected / hoped-for output in Playground:
(tcl) 15 % # q0: |0> ---[H]------[S]------[H]------ M -------

seems to work now. 

There is >>>NO<<< closure bar on the left and right boundary.
May install closure bar  when debugging finished.
% # ─────────────────────────────────────────────────────────────────────────────
(tcl) 6 % # Test:  phase kickback example
(tcl) 7 % # ─────────────────────────────────────────────────────────────────────────────
(tcl) 8 % 
(tcl) 8 % puts "Simple phase kickback toy circuit:"
Simple phase kickback toy circuit:
(tcl) 9 % print_quantum_circuit {>     {H 0}
>     {S 0}
>     {H 0}
>     {M 0}
> } 1
q0: |0>---[H]------[S]------[H]---M

# -----------------------
# Example usages
# -----------------------

puts "1. Superposition:"
print_quantum_circuit {{H 0}} 1
# > q0: |0> ---[H]---

puts "2. Bell state circuit:"
print_quantum_circuit {
    {H 0}
    {CNOT 0 1}
} 2
# > q0: |0> ---[H]---o--
# > q1: |0> -----------X--

puts "3. With measurement:"
print_quantum_circuit {
    {H 0}
    {CNOT 0 1}
    {M 0}
    {M 1}
} 2
# > q0: |0> ---[H]---o-- M 
# > q1: |0> -----------X-- M 

puts "4. Simple phase kickback toy:"
print_quantum_circuit {
    {H 0}
    {S 0}
    {H 0}
    {M 0}
} 1

q0: |0>---[H]------[S]------[H]---M
  

Educational quantum circuit examples
--------------------------------------------

1. Superposition:
 ##q0: |0>---[H]---## 

2. Bell state (EPR pair):
 ##q0: |0>---[H]---o-----## 
 ##q1: |0>----------X## 

3. Bell state + both measured:
 ##q0: |0>---[H]---o-----M----------## 
 ##q1: |0>----------X----------M## 

4. Phase kickback toy example:
 ##q0: |0>---[H]------[S]------[H]---M## 

5. Two-qubit controlled-phase (example):
 ##q0: |0>---[H]-------------o---------------o-----## 
 ##q1: |0>-------------[H]---X---[S]---X## 

        # set new_rendered " ##${rendered}## "
        # added patch, shows alternate look
        set new_rendered " ## ${rendered} ## "