+----------------------------------------------------------------------------------+
| 1) BROWNIAN MOTION PATH (BuildBrownPath)                                         |
|    Wiener Process W(t) - Discrete approximation                                  |
|                                                                                  |
|    Time 0.0 : Position 0.0                                                       |
|         |                                                                        |
|         v   + dW1 (random)                                                       |
|    Time dt  : Position X1                                                        |
|         |                                                                        |
|         v   + dW2                                                                |
|    Time 2dt : Position X2                                                        |
|         |          ...                                                           |
|         v                                                                        |
|    Time T   : Position XN  (random walk with sqrt(dt) scaling)                   |
|                                                                                  |
|    Each increment:   dW = sqrt(dt) * N(0,1)                                     |
|    Property: E[W(t)] = 0    Var[W(t)] = t                                        |
+----------------------------------------------------------------------------------+

+----------------------------------------------------------------------------------+
| 2) ITO STOCHASTIC INTEGRAL (ItoIntegApprox)                                      |
|    Left-endpoint non-anticipating sum                                            |
|                                                                                  |
|    t=0     t=dt    t=2dt   ...   t=T                                            |
|     |-------|-------|----------|                                                 |
|     v       v       v          v                                                 |
|    f(t0)   f(t1)   f(t2)  ...  f(tN-1)                                          |
|     *dW0   *dW1    *dW2   ...  *dWN                                              |
|                                                                                  |
|    Integral ≈ Σ f(t_i) * ΔW_i     (ΔW_i evaluated AFTER f(t_i))                 |
|                                                                                  |
|    Key: Integrand cannot "see" future Brownian increment                        |
+----------------------------------------------------------------------------------+

+----------------------------------------------------------------------------------+
| 3) TEST INTEGRANDS                                                               |
|                                                                                  |
|    Constant Integrand f(t) = C                                                   |
|    → Expected integral = 0                                                       |
|    → Variance = C² × T                                                           |
|                                                                                  |
|    Exponential Integrand f(t) = exp(0.5 × t)                                    |
|    → Growing function → later steps contribute more variance                     |
|                                                                                  |
|    Both approximated via ItoIntegApprox left Riemann sum                         |
+----------------------------------------------------------------------------------+

+----------------------------------------------------------------------------------+
| 4) STOCHASTIC INVESTMENT STRATEGIES (RunStratSimTest)                           |
|                                                                                  |
|    Wealth(t+1) = Wealth(t) + Stake × ΔW                                         |
|                                                                                  |
|    [Martingale]                                                                  |
|      Stake = 2^(step-1)   (doubles after each round)                             |
|      → High risk of ruin / overflow                                              |
|                                                                                  |
|    [Proportional]                                                                |
|      Stake = 0.2 × |Wealth|   (fractional Kelly-like)                            |
|      → Wealth stays positive longer                                              |
|                                                                                  |
|    [Flatbet]                                                                     |
|      Stake = 1.0 fixed                                                           |
|                                                                                  |
|    ΔW drawn from N(0,1) each step                                                |
+----------------------------------------------------------------------------------+

+----------------------------------------------------------------------------------+
| 5) DRAW NORMAL RANDOM (DrawNormalRand)                                           |
|    Box-Muller Transform                                                          |
|                                                                                  |
|    U1, U2 ~ Uniform(0,1)                                                         |
|         |                                                                        |
|         v                                                                        |
|    Z = sqrt(-2 ln U1) * cos(2π U2)                                               |
|         |                                                                        |
|         v                                                                        |
|    Normal = μ + σ × Z                                                            |
|                                                                                  |
|    Used for every Brownian increment and strategy shock                          |
+----------------------------------------------------------------------------------+

+----------------------------------------------------------------------------------+
| 6) PROGRAM ORGANIZATION (RunAllItoTests)                                         |
|                                                                                  |
|    SetRandomSeed                                                                 |
|         |                                                                        |
|         v                                                                        |
|    ┌─────────────────────────────────────┐                                       |
|    │ 5 Scenarios (different steps & T)   │                                       |
|    └──────────────────┬──────────────────┘                                       |
|                       |                                                          |
|          ┌────────────┼────────────┐                                             |
|          |            |            |                                             |
|          v            v            v                                             |
|    Brownian     Ito Integrals   Strategy Sims                                    |
|      Path      (Const + Exp)    (Proportional)                                   |
|          |            |            |                                             |
|          └────────────┼────────────┘                                             |
|                       v                                                          |
|                PrintSummStats (Min/Max/Mean)                                     |
|                       |                                                          |
|                       v                                                          |
|                   Edge Case Tests                                                |
|                (T=0, steps=1, steps=1000)                                        |
+----------------------------------------------------------------------------------+

+----------------------------------------------------------------------------------+
| 7) EDGE CASE BATTERY                                                             |
|                                                                                  |
|    Edge A: T = 0.0          → All increments = 0.0 (exact zero integral)         |
|                                                                                  |
|    Edge B: 1000 steps       → Fine grid, mean → 0, variance → theoretical value  |
|                                                                                  |
|    Tests robustness of ItoIntegApprox and random number handling                 |
+----------------------------------------------------------------------------------+

# Stochastic Ito Engine for Brownian Motion  V4
# Tcl 8.6 or greater required
# 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.
# Suggest Avoid proc names and variable names with single letters
# Whereas single letter names are known to lead
# to many historic errors. 
# 
# ----
# 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.
# ----
# 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.
# Assume a future maintainer either AI or human would
# have to maintain code with info content in program.
#
# This is a hacker's patch, not rigorously derived.
# appears correct solutions for autotests.
# TCL Club 5/25/2026 
# =============================================================================
# PURPOSE: Simulate Brownian motion paths, Ito integral approximations,
#          and stochastic investment strategies.
# NAMING CONVENTION: All proc and variable names are 12-15 characters,
#   descriptive, and domain-neutral. Single-letter names are prohibited.
# =============================================================================
console show

# -----------------------------------------------------------------------------
# New: File Logging Setup
# -----------------------------------------------------------------------------
set log_filename "ito_simulation_[clock format [clock seconds] -format %Y%m%d_%H%M%S].log"
set log_file [open $log_filename w]
puts "Console output being logged to: $log_filename"

proc LogToFile {text} {
    global log_file
    puts $log_file $text
    puts $text
}

# -----------------------------------------------------------------------------
# SetRandomSeed
# -----------------------------------------------------------------------------
proc SetRandomSeed {seed_int_val} {
    if {$seed_int_val < 0} {
        expr {srand([clock microseconds])}
        LogToFile "Seed source   : system clock (non-reproducible run)"
    } else {
        expr {srand($seed_int_val)}
        LogToFile "Seed value    : $seed_int_val (fully reproducible run)"
    }
}

# -----------------------------------------------------------------------------
# DrawNormalRand
# -----------------------------------------------------------------------------
proc DrawNormalRand {mean_location spread_factor} {
    set first_uniform  [expr {rand()}]
    set second_uniform [expr {rand()}]

    set epsilon_floor  1.0e-15
    if {$first_uniform < $epsilon_floor} {
        set first_uniform $epsilon_floor
    }

    set math_pi_value  3.14159265358979
    set normal_sample  [expr {
        sqrt(-2.0 * log($first_uniform)) *
        cos(2.0 * $math_pi_value * $second_uniform)
    }]
    return [expr {$mean_location + $spread_factor * $normal_sample}]
}

# -----------------------------------------------------------------------------
# BuildBrownPath
# -----------------------------------------------------------------------------
proc BuildBrownPath {total_step_cnt time_horizon} {
    set step_duration  [expr {double($time_horizon) / $total_step_cnt}]
    set running_postn  0.0
    set path_log_list  {}
    lappend path_log_list "Time 0.0 : Position 0.0"

    for {set step_counter 1} {$step_counter <= $total_step_cnt} {incr step_counter} {
        set path_increment [expr {sqrt($step_duration) * [DrawNormalRand 0.0 1.0]}]
        set running_postn  [expr {$running_postn + $path_increment}]
        set elapsed_time   [expr {$step_counter * $step_duration}]
        lappend path_log_list "Time $elapsed_time : Position $running_postn"
    }
    return $path_log_list
}

# -----------------------------------------------------------------------------
# PrintBrownianWikiTable -  Robust Version
# -----------------------------------------------------------------------------
proc PrintBrownianWikiTable {brownian_path total_step_cnt time_horizon scenario_num} {
    LogToFile "\n%| Index | Time (s)   | Position       | Quibble-Notes          |%"

    set sample_points 11
    set max_idx [expr {[llength $brownian_path] - 1}]
    
    for {set i 0} {$i < $sample_points} {incr i} {
        # Better sampling - works well even with 1 step
        set idx [expr {int($i * $max_idx / double($sample_points - 1))}]
        if {$idx > $max_idx} { set idx $max_idx }
        
        set entry [lindex $brownian_path $idx]
        regexp {Time ([\d\.]+) : Position ([\d\.\-]+)} $entry -> t pos
        
        # Clean formatting
        set time_clean [format "%.4f" $t]
        set pos_clean  [format "%.6f" $pos]
        
        set note [expr {$i == 0 ? "Start" : 
                       ($i == $sample_points-1 ? "End" : "Intermediate")}]
        
        LogToFile "&| $i | $time_clean | $pos_clean | $note |&"
    }
    
    LogToFile "&| AUDIT Window | | | Brownian motion sample - Scenario $scenario_num |&"
    LogToFile ""
}
# -----------------------------------------------------------------------------
# ItoIntegApprox
# -----------------------------------------------------------------------------
proc ItoIntegApprox {total_step_cnt time_horizon integrand_func} {
    set step_duration  [expr {double($time_horizon) / $total_step_cnt}]
    set integral_value 0.0
    set elapsed_time   0.0

    for {set step_counter 1} {$step_counter <= $total_step_cnt} {incr step_counter} {
        set integrand_val  [{*}$integrand_func $elapsed_time]
        set brownian_incr  [expr {sqrt($step_duration) * [DrawNormalRand 0.0 1.0]}]
        set integral_value [expr {$integral_value + $integrand_val * $brownian_incr}]
        set elapsed_time   [expr {$elapsed_time + $step_duration}]
    }
    return $integral_value
}

# -----------------------------------------------------------------------------
# RunConstIntgnd
# -----------------------------------------------------------------------------
proc RunConstIntgnd {const_val_inp total_step_cnt time_horizon} {
    set const_intg_lam [list apply \
        {{const_level_in time_input_val} {expr {$const_level_in}}} \
        $const_val_inp]
    set const_intg_val [ItoIntegApprox $total_step_cnt $time_horizon $const_intg_lam]
    LogToFile "  Const integrand=$const_val_inp  T=$time_horizon  result=$const_intg_val"
    return $const_intg_val
}

# -----------------------------------------------------------------------------
# RunExpIntegral
# -----------------------------------------------------------------------------
proc RunExpIntegral {total_step_cnt time_horizon} {
    set exp_intg_lambda {apply {{time_input_val} {expr {exp(0.5 * $time_input_val)}}}}
    set exp_intg_value  [ItoIntegApprox $total_step_cnt $time_horizon $exp_intg_lambda]
    LogToFile "  Exp  integrand  T=$time_horizon  result=$exp_intg_value"
    return $exp_intg_value
}

# -----------------------------------------------------------------------------
# RunStratSimTest
# -----------------------------------------------------------------------------
proc RunStratSimTest {strategy_type total_step_cnt} {
    set wealth_amount  1.0
    for {set step_idx_num 1} {$step_idx_num <= $total_step_cnt} {incr step_idx_num} {
        set wiener_incrmnt [DrawNormalRand 0.0 1.0]

        if {$strategy_type eq "martingale"} {
            set stake_amount   [expr {pow(2.0, $step_idx_num - 1)}]
            if {$stake_amount > 1.0e12} { set stake_amount 1.0e12 }
        } elseif {$strategy_type eq "proportional"} {
            set stake_amount   [expr {0.2 * abs($wealth_amount)}]
        } else {
            set stake_amount   1.0
        }
        set wealth_amount  [expr {$wealth_amount + $stake_amount * $wiener_incrmnt}]
    }
    LogToFile "  Strategy=$strategy_type  steps=$total_step_cnt  final_wealth=$wealth_amount"
    return $wealth_amount
}

# -----------------------------------------------------------------------------
# PrintSummStats
# -----------------------------------------------------------------------------
proc PrintSummStats {result_num_lst label_text_str} {
    set list_item_cnt  [llength $result_num_lst]
    if {$list_item_cnt == 0} {
        LogToFile "  PrintSummStats: empty list passed for '$label_text_str'"
        return
    }
    set running_total  0.0
    set minimum_value  [lindex $result_num_lst 0]
    set maximum_value  [lindex $result_num_lst 0]
    foreach each_rslt_val $result_num_lst {
        set running_total [expr {$running_total + $each_rslt_val}]
        if {$each_rslt_val < $minimum_value} { set minimum_value $each_rslt_val }
        if {$each_rslt_val > $maximum_value} { set maximum_value $each_rslt_val }
    }
    set mean_average   [expr {$running_total / $list_item_cnt}]
    LogToFile ""
    LogToFile "  --- $label_text_str ---"
    LogToFile "  N=$list_item_cnt  Min=$minimum_value  Max=$maximum_value  Mean=$mean_average"
}

# -----------------------------------------------------------------------------
# RunSingleItoScn
# -----------------------------------------------------------------------------
proc RunSingleItoScn {test_idx_num total_step_cnt time_horizon test_label_str} {
    LogToFile "--------------------------------------------------------------"
    LogToFile "  Scenario $test_idx_num : $test_label_str"
    LogToFile "  Steps = $total_step_cnt    Horizon = $time_horizon"
    LogToFile "--------------------------------------------------------------"

    set start_time_ms  [clock milliseconds]
    set brownian_path  [BuildBrownPath $total_step_cnt $time_horizon]
    # replace line here LogToFile "  Path endpoint  : [lindex $brownian_path end]"
    # Clean endpoint display
    set endpoint [lindex $brownian_path end]
    regexp {Time ([\d\.]+) : Position ([\d\.\-]+)} $endpoint -> et ep
    LogToFile "  Path endpoint  : Time [format %.4f $et] : Position [format %.6f $ep]"
    set const_intg_val [RunConstIntgnd  2.5 $total_step_cnt $time_horizon]
    set exp_intg_value [RunExpIntegral      $total_step_cnt $time_horizon]
    set strat_sim_val  [RunStratSimTest "proportional" $total_step_cnt]

    PrintBrownianWikiTable $brownian_path $total_step_cnt $time_horizon $test_idx_num

    set finish_time_ms [clock milliseconds]
    set elapsed_ms_val [expr {$finish_time_ms - $start_time_ms}]
    LogToFile "  Duration       : ${elapsed_ms_val} ms"
    LogToFile ""
    return [list $const_intg_val $exp_intg_value $strat_sim_val]
}

# -----------------------------------------------------------------------------
# RunEdgeCaseSet
# -----------------------------------------------------------------------------
proc RunEdgeCaseSet_tester {} {
    LogToFile "\n=============================="
    LogToFile "  EDGE CASE TESTS"
    LogToFile "=============================="

    RunSingleItoScn "E1"  1   1.0  "Single-step minimum"
    RunSingleItoScn "E2" 10   0.001 "Tiny time horizon"
    RunSingleItoScn "E3" 500  5.0  "Large step count, long horizon"
}
# -----------------------------------------------------------------------------
# RunEdgeCaseSet
# -----------------------------------------------------------------------------
# -----------------------------------------------------------------------------
# RunEdgeCaseSet Notes
# Purpose  : Test program behaviour under extreme conditions to verify
#            numerical stability and correctness of Brownian motion & Ito
#            integral approximations.
#   Edge 1 : Very small time horizon (T=0.001)   → Tests near-zero behaviour
#   Edge 2 : Large number of steps (500 steps, T=5.0) → Tests fine resolution
#            and long-run statistics
#   Edge ? : Single-step minimum case omitted here, but available internal
# -----------------------------------------------------------------------------
proc RunEdgeCaseSet {} {
    LogToFile "\n=============================="
    LogToFile "  EDGE CASE TESTS"
    LogToFile "=============================="

    # Removed E1 (Single-step) - low educational value and ugly table
    RunSingleItoScn "E1" 10    0.001  "Tiny time horizon"
    RunSingleItoScn "E2" 500   5.0    "Large step count, long horizon"
}
# -----------------------------------------------------------------------------
# RunAllItoTests
# -----------------------------------------------------------------------------
proc RunAllItoTests {} {
    LogToFile "============================================================"
    LogToFile "  ITO STOCHASTIC ENGINE - FULL TEST SUITE"
    LogToFile "============================================================"

    SetRandomSeed 42

    set all_const_vals {}
    set all_exp_vals   {}
    set all_strat_vals {}

    set scenarios {
        {1   50  1.0  "Base case, fine steps"}
        {2  100  2.0  "Medium horizon"}
        {3  200  0.5  "High resolution, short time"}
        {4   80  1.5  "Variable deterministic focus"}
        {5  150  1.0  "Strategy comparison focus"}
    }

    foreach scn $scenarios {
        lassign $scn idx steps horizon label
        set results [RunSingleItoScn $idx $steps $horizon $label]
        lappend all_const_vals [lindex $results 0]
        lappend all_exp_vals   [lindex $results 1]
        lappend all_strat_vals [lindex $results 2]
    }

    PrintSummStats $all_const_vals "Constant Integrand Results"
    PrintSummStats $all_exp_vals   "Exponential Integrand Results"
    PrintSummStats $all_strat_vals "Proportional Strategy Results"

    RunEdgeCaseSet

    LogToFile "\n============================================================"
    LogToFile "  ALL TESTS COMPLETE"
    LogToFile "============================================================"
}

# -----------------------------------------------------------------------------
# MAIN ENTRY POINT
# -----------------------------------------------------------------------------
RunAllItoTests

close $log_file
puts "\nSimulation completed. Log saved as: $log_filename"

# =============================================================================
# SUGGESTED 5 AUTOTESTS FOR WIKI / CLASSROOM USE
# =============================================================================
# Test 1  : 50 steps,  T=1.0   → Base case, fine steps
# Test 2  : 100 steps, T=2.0   → Medium horizon
# Test 3  : 200 steps, T=0.5   → High resolution, short time
# Test 4  : 80 steps,  T=1.5   → Variable deterministic focus
# Test 5  : 150 steps, T=1.0   → Strategy comparison focus
#
# These five tests give excellent educational coverage:
# from gentle introduction → stress testing resolution → strategy behavior.
# The wiki tables provide clear visual snapshots of Brownian motion.
# ============================================== 
# End of file

# References.
# based on work from Stephen Hawking and Penrose
# 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).
# No text, quotes, or direct examples from the book are used in this code.
# The dummy subroutine implements a generic axiom for educational purposes only.
puts "=============================================================="
puts "Credits"
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"

  Duration       : 248 ms


============================================================
  ALL TESTS COMPLETE
============================================================