Index,Autotest,Coefficient a1,Coefficient a2,Coefficient a3,Real Roots Found,Example Root,Timing (μs/iter),Quibble Notes
1,1,-12.096532,-16.410855,-17.247844,1,13.41562836,13.7104,"Negative discriminant branch; consistent single real root."
2,2,-14.519696,-12.530207,-15.189471,1,15.39754339,14.4632,"Slightly higher time; possibly due to coefficient scaling affecting computations."
3,3,-19.446304,-14.038962,-12.832879,1,20.17373925,13.2621,"Fastest in set; larger magnitude root but efficient path."
4,4,-12.204659,-13.711642,-11.560845,1,13.30088849,13.3265,"Balanced coefficients; stable performance."
5,5,-13.113517,-18.885133,-12.425878,1,14.47727121,16.7593,"Slowest; likely triggered more expensive operations in cube-root path."  

**** figure. RANDOM CUBICS OVERVIEW ****

+----------------------------------------------------------------------------------+
| RANDOM CUBICS - Cardano-Vieta Solver                                             |
|                                                                                  |
|    Solves equations of the form:                                                 |
|         x³ + a1·x² + a2·x + a3 = 0                                               |
|                                                                                  |
|    Generates random coefficients a1, a2, a3                                      |
|    Finds 1, 2, or 3 real roots using Cardano's formula                           |
|                                                                                  |
|    Educational Toy:                                                              |
|      • Demonstrates three distinct algebraic solution branches                   |
|      • Uses NASA/JPL defensive programming (assertions, descriptive names)       |
|      • Measures timing and verifies with relative tolerance                      |
+----------------------------------------------------------------------------------+

**** figure. CARDANO METHOD FLOW ****

+----------------------------------------------------------------------------------+
| CARDANO-VIETA METHOD - Decision Flow                                             |
|                                                                                  |
|    Input: Coefficients a1, a2, a3                                                |
|             │                                                                    |
|             ▼                                                                    |
|    Compute Q = (a1² - 3·a2)/9                                                    |
|    Compute R = (2·a1³ - 9·a1·a2 + 27·a3)/54                                      |
|             │                                                                    |
|             ▼                                                                    |
|    Compute Z = Q³ - R²                                                           |
|             │                                                                    |
|    ┌────────┴────────┐                                                           |
|    │ Z > 0           │ → Three distinct real roots (Vieta trig)                 |
|    │ Z = 0           │ → Double or triple root                                  |
|    │ Z < 0           │ → One real root (cube-root formula)                      |
|    └─────────────────┘                                                           |
|             │                                                                    |
|             ▼                                                                    |
|    Return list of real root(s)                                                   |
+----------------------------------------------------------------------------------+

**** figure. CARDANO SOLUTION BRANCHES ****

+----------------------------------------------------------------------------------+
| THREE SOLUTION BRANCHES IN CARDANO METHOD                                        |
|                                                                                  |
|    Branch 1: Z > 0   (Three Real Roots)                                          |
|      Uses trigonometric identity with acos()                                     |
|      Roots: 2√Q·cos((θ + 2πk)/3) - a1/3    for k=0,1,2                          |
|                                                                                  |
|    Branch 2: Z = 0   (Double or Triple Root)                                     |
|      Simplified square-root formulas                                             |
|                                                                                  |
|    Branch 3: Z < 0   (One Real Root)                                             |
|      Uses cube-root formula with complex intermediates                           |
|      Only one real root (other two are complex)                                  |
|                                                                                  |
|    Educational Value: Clear visual separation of algebraic cases                 |
+----------------------------------------------------------------------------------+

**** figure. DEFENSIVE PROGRAMMING IN RANDOM CUBICS ****

+----------------------------------------------------------------------------------+
| NASA/JPL DEFENSIVE PROGRAMMING FEATURES                                          |
|                                                                                  |
|    • Each proc < 25 lines                                                        |
|    • Minimum 2 assertions per procedure                                          |
|    • Descriptive variable names (cardanoQ, zDiscriminant, etc.)                  |
|    • Input validation before any math                                            |
|    • Defensive clamping on acos() argument to [-1, 1]                            |
|    • Near-zero pivot protection                                                  |
|    • 20% relative tolerance in autotests                                         |
|                                                                                  |
|    Goal: Make code readable, safe, and maintainable by future AI or human        |
+----------------------------------------------------------------------------------+

**** figure. RANDOM CUBIC GENERATION & TIMING ****

+----------------------------------------------------------------------------------+
| RANDOM CUBIC AUTOTESTS                                                           |
|                                                                                  |
|    Each test:                                                                    |
|      1. Generate random coefficients a1,a2,a3 ∈ [-20, -10]                      |
|      2. Solve using Cardano method                                               |
|      3. Measure average time over 1000 iterations                               |
|      4. Verify roots with 20% relative tolerance                                 |
|                                                                                  |
|    Five tests cover:                                                             |
|      • Three-real-roots branch                                                   |
|      • Double-root branch                                                        |
|      • One-real-root branch                                                      |
|      • Two random general cases                                                  |
|                                                                                  |
|    Timing varies with branch taken and coefficient magnitude                     |
+----------------------------------------------------------------------------------+

**** figure. RANDOM CUBICS EDUCATIONAL TOY STRUCTURE ****

+----------------------------------------------------------------------------------+
| RANDOM CUBICS EDUCATIONAL TOY ARCHITECTURE                                       |
|                                                                                  |
|    ┌─────────────────────┐                                                       |
|    │ Random Coefficient   │  → generateRandomCubicCoefficients                   |
|    └──────────┬──────────┘                                                       |
|               ▼                                                                  |
|    ┌─────────────────────┐                                                       |
|    │ Compute Q, R, Z      │  → Cardano intermediates                             |
|    └──────────┬──────────┘                                                       |
|               ▼                                                                  |
|    ┌─────────────────────┐                                                       |
|    │ Branch Dispatcher    │  → Select 1/2/3 real roots path                      |
|    └──────────┬──────────┘                                                       |
|               ▼                                                                  |
|          Solve & Return Roots + Timing + Assertions                              |
|                                                                                  |
|    All operations use strict 7-bit ASCII and defensive checks                    |
+----------------------------------------------------------------------------------+

# original by  Rodney Stephenson, reorg here.
# toy on wiki page.tcl V4
# may have to check strict ASCII for Playground V9
# 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, best practises. 
# Working under TCL version 8.6
# Complex math calculations up to 6 units computer time
# Wait for complete calculations before saving files.
#  break Tcl  code into brief modules for best practises. 
# TCL club, 02/18/2026
# =============================================================================
# =============================================================================
# Random Cubic Parameters Reorg V2
# Original math by Rodney Stephenson. Reorganized for TCL Club, 02/18/2026.
# Compatible with Tcl/Tk 8.6+, ActiveState TCL, Windows 11.
# Working on TCL Playground V9, strict 7-bit ASCII only.
# Optimized for collegiate IT lab environments and best practices.
# =============================================================================
#
# TUTORIAL: Random Cubic Parameters Reorg - Program Internals
# Title: Random Cubic Parameters Reorg
# =============================================================================
#
# INTRODUCTION
#
# This program solves cubic (degree-three polynomial) equations of the form
# x^3 + a1*x^2 + a2*x + a3 = 0, where a1, a2, and a3 are real-number
# coefficients. The program applies the classical Cardano-Vieta algebraic
# method to find all real roots of the equation. Five automated tests run
# at program startup to verify correctness and measure execution speed.
#
# WHY CUBIC EQUATIONS MATTER
#
# Cubic equations appear across engineering, physics, and computer graphics.
# A graphics engine computing the intersection of a ray with a curved surface
# may reduce the geometry problem to a cubic equation. A structural engineer
# calculating the natural vibration frequencies of a three-degree-of-freedom
# (DOF) system also solves a cubic. The Cardano method, published by Gerolamo
# Cardano in 1545, gives closed-form (exact algebraic) solutions for all
# real roots without iteration. The closed-form approach is fast and avoids
# the convergence uncertainty of numerical root-finding methods such as
# Newton-Raphson iteration.
#
# THE CARDANO-VIETA ALGORITHM INTERNALS
#
# The algorithm begins by computing two intermediate values called Q and R,
# derived from the three input coefficients. The value Q captures the
# relationship between a1 and a2, while R captures a combination of all
# three coefficients weighted differently. Together, Q and R determine a
# discriminant value called Z, computed as Z = Q^3 - R^2.
#
# The sign of Z selects one of three solution branches. When Z is positive,
# the cubic has three distinct real roots, and the program uses the Vieta
# trigonometric substitution involving the arccosine (acos) function and
# the mathematical constant PI (Pi, approximately 3.14159). When Z equals
# exactly zero, the cubic has a repeated root, meaning at least two roots
# share the same value. If both Q and Z are zero, all three roots collapse
# to a single triple root. When Z is negative, the discriminant indicates
# only one real root exists, and the program uses the classical Cardano
# cube-root formula to extract that single root.
#
# MODULAR DECOMPOSITION FOLLOWING NASA DEFENSIVE RULES
#
# The original monolithic cubic procedure contained approximately forty
# floating-point operations and several conditional branches inside one
# block. A future maintainer reading forty lines of mixed logic must
# simultaneously track the input validation, the Q and R calculations, the
# discriminant branching, and the root extraction formulas. This cognitive
# load makes debugging slow and introduces risk of silent errors.
#
# NASA (National Aeronautics and Space Administration) Rule 1 limits each
# procedure to 25 lines. This program enforces that rule by extracting each
# logical responsibility into its own named procedure. The procedure
# computeCardanoQ handles only the Q calculation and returns immediately.
# The procedure computeCardanoR handles only the R calculation. The procedure
# computeZDiscriminant handles only the discriminant. Three separate
# procedures handle the three solution branches: solveThreeRealRoots,
# solveDoubleRoot, and solveOneRealRoot. The top-level procedure
# solveCubicEquation reads as a clear flowchart: compute Q, compute R,
# compute Z, select a branch, return the result.
#
# ASSERTIONS AS BUILT-IN VERIFICATION
#
# NASA Rule 4 requires a minimum of two assertions per procedure. An
# assertion is a check that a stated condition must be true at that point
# in execution. The helper procedure assertConditionIsTrue accepts a
# boolean result and an error message. If the condition is false, the
# procedure raises a TCL error with the descriptive message. Assertions
# at procedure entry verify that inputs are numeric before any arithmetic
# begins. Assertions at procedure exit verify that the returned list
# contains at least one root. This two-layer checking catches both bad
# inputs from callers and unexpected internal failures.
#
# For example, the procedure solveThreeRealRoots asserts on entry that
# cardanoQ is positive before computing sqrt(cardanoQ), because the square
# root of a negative number would produce a TCL error with a confusing
# message. The assertion converts that silent math failure into a clear
# diagnostic message naming the violated precondition.
#
# DEFENSIVE CLAMPING IN THE TRIGONOMETRIC BRANCH
#
# The Vieta trigonometric branch computes the argument to acos as
# R / sqrt(Q^3). Floating-point rounding can push this ratio slightly
# outside the valid domain of acos, which is the closed interval [-1, 1].
# A value of 1.0000000001 passed to acos returns a domain error in TCL.
# The procedure solveThreeRealRoots defensively clamps the argument to
# exactly [-1, 1] before calling acos. This one-line guard prevents a
# class of silent failures that would only appear with specific unlucky
# coefficient combinations, making the guard hard to discover through
# casual testing.
#
# DESCRIPTIVE VARIABLE NAMING FOR FUTURE MAINTAINERS
#
# NASA Rule 6 requires clear, honest naming. Single-letter variable names
# such as Q, R, and Z appear in mathematics textbooks because the reader
# has the surrounding paragraph for context. In source code, a future
# maintainer reading the variable name z2Value six months after initial
# authorship has no surrounding paragraph. Descriptive names like
# cardanoQ, zDiscriminantNegated, thetaArgument, and coefficientA1 carry
# their meaning inside the name itself. A future AI (Artificial Intelligence)
# model or human maintainer can infer the purpose of zDiscriminantNegated
# without reading the surrounding lines. This self-documenting style is
# especially important in TCL (Tool Control Language), where the dynamic
# type system provides no compile-time type annotations to guide the reader.
#
# TIMING AND AUTOTEST DESIGN
#
# The five autotests each generate a fresh set of random coefficients using
# TCL's built-in rand() function, scaled to the range [-20, -10]. The
# procedure generateRandomCubicCoefficients returns a list of three
# coefficients, and the calling autotest procedure displays all three values
# before solving, so the test is fully reproducible if the user records the
# output. Each autotest then calls TCL's built-in time command with 1000
# iterations to measure the average execution cost in microseconds. Printing
# the coefficients before timing ensures the reader can correlate slow runs
# with coefficient values that trigger the more expensive trigonometric branch.
#
# The timing loop uses 1000 repetitions rather than the original 10000 to
# keep total test runtime under two seconds on typical collegiate lab hardware
# while still averaging out operating system scheduling noise. A reader who
# needs higher statistical confidence can increase the iteration count in
# the runSingleAutotestWithTiming procedure without touching any other code.
#
# CONCLUSION
#
# This reorganization demonstrates that a mathematically complex algorithm
# does not require a complex program structure. Separating the Q calculation,
# the R calculation, the discriminant, and each solution branch into named
# procedures under 25 lines makes each unit individually readable, testable,
# and replaceable. Assertions at procedure boundaries catch bad inputs and
# unexpected outputs without requiring a separate test framework. Descriptive
# variable names make the connection between the mathematical literature and
# the running code visible to any reader, human or AI, encountering the
# program for the first time.
#
# =============================================================================
# END OF TUTORIAL
# =============================================================================

console show
# -----------------------------------------------------------------------------
# assertConditionIsTrue
# Purpose  : Helper assertion used by all procedures (NASA Rule 4).
# Arguments: conditionResult    - boolean integer, 1 = pass, 0 = fail
#            errorMessageText   - descriptive message if assertion fails
# Returns  : nothing on pass; raises error on fail
# Lines    : under 25 (NASA Rule 1)
# -----------------------------------------------------------------------------
proc assertConditionIsTrue {conditionResult errorMessageText} {
    # conditionResult must arrive as an already-evaluated 1 or 0.
    # Callers must use [expr {...}] or [string is ...] at the call site,
    # never bare curly braces, which would pass an unevaluated string.
    if {!$conditionResult} {
        error "ASSERTION FAILED: $errorMessageText"
    }
}


# -----------------------------------------------------------------------------
# computeCardanoQ
# Purpose  : Compute the Cardano intermediate value Q from a1 and a2.
#            Q = (a1^2 - 3*a2) / 9
# Arguments: coefficientA1 - first cubic coefficient
#            coefficientA2 - second cubic coefficient
# Returns  : cardanoQ as a floating-point number
# -----------------------------------------------------------------------------
proc computeCardanoQ {coefficientA1 coefficientA2} {
    assertConditionIsTrue \
        [string is double $coefficientA1] \
        "computeCardanoQ: coefficientA1 must be numeric"
    assertConditionIsTrue \
        [string is double $coefficientA2] \
        "computeCardanoQ: coefficientA2 must be numeric"
    set squaredA1    [expr {$coefficientA1 * $coefficientA1}]
    set cardanoQ     [expr {($squaredA1 - 3.0 * $coefficientA2) / 9.0}]
    assertConditionIsTrue \
        [string is double $cardanoQ] \
        "computeCardanoQ: cardanoQ result must be numeric"
    return $cardanoQ
}


# -----------------------------------------------------------------------------
# computeCardanoR
# Purpose  : Compute the Cardano intermediate value R from a1, a2, a3.
#            R = (2*a1^3 - 9*a1*a2 + 27*a3) / 54
# Arguments: coefficientA1 - first cubic coefficient
#            coefficientA2 - second cubic coefficient
#            coefficientA3 - third cubic coefficient
# Returns  : cardanoR as a floating-point number
# -----------------------------------------------------------------------------
proc computeCardanoR {coefficientA1 coefficientA2 coefficientA3} {
    assertConditionIsTrue \
        [string is double $coefficientA1] \
        "computeCardanoR: coefficientA1 must be numeric"
    assertConditionIsTrue \
        [string is double $coefficientA3] \
        "computeCardanoR: coefficientA3 must be numeric"
    set squaredA1    [expr {$coefficientA1 * $coefficientA1}]
    set cubedA1      [expr {$squaredA1 * $coefficientA1}]
    set cardanoR     [expr {(2.0 * $cubedA1 \
                             - 9.0 * $coefficientA1 * $coefficientA2 \
                             + 27.0 * $coefficientA3) / 54.0}]
    assertConditionIsTrue \
        [string is double $cardanoR] \
        "computeCardanoR: cardanoR result must be numeric"
    return $cardanoR
}


# -----------------------------------------------------------------------------
# computeZDiscriminant
# Purpose  : Compute Z = Q^3 - R^2.
#            Sign of Z selects the solution branch.
# Arguments: cardanoQ - intermediate value Q
#            cardanoR - intermediate value R
# Returns  : zDiscriminant as a floating-point number
# -----------------------------------------------------------------------------
proc computeZDiscriminant {cardanoQ cardanoR} {
    assertConditionIsTrue \
        [string is double $cardanoQ] \
        "computeZDiscriminant: cardanoQ must be numeric"
    assertConditionIsTrue \
        [string is double $cardanoR] \
        "computeZDiscriminant: cardanoR must be numeric"
    set cubedQ          [expr {$cardanoQ * $cardanoQ * $cardanoQ}]
    set squaredR        [expr {$cardanoR * $cardanoR}]
    set zDiscriminant   [expr {$cubedQ - $squaredR}]
    return $zDiscriminant
}


# -----------------------------------------------------------------------------
# solveTripleRoot
# Purpose  : Return the single triple root when Q=0 and Z=0.
#            Formula: x0 = -a1/3
# Arguments: coefficientA1 - first cubic coefficient
# Returns  : list with one root value
# -----------------------------------------------------------------------------
proc solveTripleRoot {coefficientA1} {
    assertConditionIsTrue \
        [string is double $coefficientA1] \
        "solveTripleRoot: coefficientA1 must be numeric"
    set tripleRoot      [expr {-$coefficientA1 / 3.0}]
    assertConditionIsTrue \
        [string is double $tripleRoot] \
        "solveTripleRoot: tripleRoot must be numeric"
    return [list $tripleRoot]
}


# -----------------------------------------------------------------------------
# solveDoubleRoot
# Purpose  : Return two roots when Z=0 and Q != 0 (one root is repeated).
# Arguments: cardanoQ      - intermediate value Q
#            cardanoR      - intermediate value R
#            coefficientA1 - first cubic coefficient
# Returns  : list with two root values
# -----------------------------------------------------------------------------
proc solveDoubleRoot {cardanoQ cardanoR coefficientA1} {
    assertConditionIsTrue \
        [expr {$cardanoQ > 0.0}] \
        "solveDoubleRoot: cardanoQ must be positive for sqrt"
    assertConditionIsTrue \
        [string is double $coefficientA1] \
        "solveDoubleRoot: coefficientA1 must be numeric"
    set sqrtQ           [expr {sqrt($cardanoQ)}]
    set a1Over3         [expr {$coefficientA1 / 3.0}]
    if {$cardanoR < 0} {
        set rootOne     [expr {2.0 * $sqrtQ - $a1Over3}]
        set rootTwo     [expr {-$sqrtQ - $a1Over3}]
    } else {
        set rootOne     [expr {$sqrtQ - $a1Over3}]
        set rootTwo     [expr {-2.0 * $sqrtQ - $a1Over3}]
    }
    assertConditionIsTrue \
        [expr {[llength [list $rootOne $rootTwo]] == 2}] \
        "solveDoubleRoot: must return exactly 2 roots"
    return [list $rootOne $rootTwo]
}


# -----------------------------------------------------------------------------
# solveOneRealRoot
# Purpose  : Return one real root when Z < 0 using the Cardano cube-root
#            formula. The negated discriminant (-Z = R^2 - Q^3) is positive
#            in this branch, making its square root well-defined.
# Arguments: cardanoQ      - intermediate value Q
#            cardanoR      - intermediate value R
#            coefficientA1 - first cubic coefficient
# Returns  : list with one root value
# -----------------------------------------------------------------------------
proc solveOneRealRoot {cardanoQ cardanoR coefficientA1} {
    assertConditionIsTrue \
        [string is double $cardanoR] \
        "solveOneRealRoot: cardanoR must be numeric"
    assertConditionIsTrue \
        [string is double $coefficientA1] \
        "solveOneRealRoot: coefficientA1 must be numeric"
    set zNegated        [expr {$cardanoR * $cardanoR \
                               - $cardanoQ * $cardanoQ * $cardanoQ}]
    set z2Value         [expr {pow(sqrt($zNegated) + abs($cardanoR), \
                                   1.0/3.0)}]
    if {$z2Value == 0.0} {
        set z1Value 0.0
    } else {
        set z1Value     [expr {$z2Value + $cardanoQ / $z2Value}]
    }
    if {$cardanoR > 0} {
        set z1Value     [expr {-$z1Value}]
    }
    set singleRealRoot  [expr {$z1Value - $coefficientA1 / 3.0}]
    assertConditionIsTrue \
        [string is double $singleRealRoot] \
        "solveOneRealRoot: singleRealRoot must be numeric"
    return [list $singleRealRoot]
}


# -----------------------------------------------------------------------------
# solveThreeRealRoots
# Purpose  : Return three distinct real roots when Z > 0.
#            Uses the Vieta trigonometric substitution with acos.
#            Defensively clamps the acos argument to [-1, 1] to prevent
#            floating-point domain errors near the branch boundary.
# Arguments: cardanoQ      - intermediate value Q (must be positive)
#            cardanoR      - intermediate value R
#            coefficientA1 - first cubic coefficient
# Returns  : list with three root values
# -----------------------------------------------------------------------------
proc solveThreeRealRoots {cardanoQ cardanoR coefficientA1} {
    assertConditionIsTrue \
        [expr {$cardanoQ > 0.0}] \
        "solveThreeRealRoots: cardanoQ must be positive for sqrt"
    assertConditionIsTrue \
        [string is double $coefficientA1] \
        "solveThreeRealRoots: coefficientA1 must be numeric"
    set piValue             3.14159265358979323846
    set cubedQ              [expr {$cardanoQ * $cardanoQ * $cardanoQ}]
    set thetaArgument       [expr {$cardanoR / sqrt($cubedQ)}]
    if {$thetaArgument >  1.0} {set thetaArgument  1.0}
    if {$thetaArgument < -1.0} {set thetaArgument -1.0}
    set thetaRadians        [expr {acos($thetaArgument)}]
    set q2ScalingFactor     [expr {-2.0 * sqrt($cardanoQ)}]
    set a1Over3             [expr {$coefficientA1 / 3.0}]
    set rootOne   [expr {$q2ScalingFactor * cos($thetaRadians / 3.0) \
                         - $a1Over3}]
    set rootTwo   [expr {$q2ScalingFactor * cos(($thetaRadians \
                         + 2.0 * $piValue) / 3.0) - $a1Over3}]
    set rootThree [expr {$q2ScalingFactor * cos(($thetaRadians \
                         + 4.0 * $piValue) / 3.0) - $a1Over3}]
    assertConditionIsTrue \
        [expr {[llength [list $rootOne $rootTwo $rootThree]] == 3}] \
        "solveThreeRealRoots: must return exactly 3 roots"
    return [list $rootOne $rootTwo $rootThree]
}


# -----------------------------------------------------------------------------
# solveCubicEquation
# Purpose  : Top-level dispatcher. Validates inputs, computes Q, R, and Z,
#            selects the correct solution branch, and returns the root list.
# Arguments: coefficientA1 - coefficient of x^2 term
#            coefficientA2 - coefficient of x term
#            coefficientA3 - constant term
# Returns  : list of 1, 2, or 3 real roots
# -----------------------------------------------------------------------------
proc solveCubicEquation {coefficientA1 coefficientA2 coefficientA3} {
    assertConditionIsTrue \
        [string is double $coefficientA1] \
        "solveCubicEquation: coefficientA1 must be numeric"
    assertConditionIsTrue \
        [string is double $coefficientA2] \
        "solveCubicEquation: coefficientA2 must be numeric"
    assertConditionIsTrue \
        [string is double $coefficientA3] \
        "solveCubicEquation: coefficientA3 must be numeric"
    set cardanoQ        [computeCardanoQ $coefficientA1 $coefficientA2]
    set cardanoR        [computeCardanoR $coefficientA1 $coefficientA2 \
                                         $coefficientA3]
    set zDiscriminant   [computeZDiscriminant $cardanoQ $cardanoR]
    if {$zDiscriminant == 0.0} {
        if {$cardanoQ == 0.0} {
            set rootList [solveTripleRoot $coefficientA1]
        } else {
            set rootList [solveDoubleRoot $cardanoQ $cardanoR $coefficientA1]
        }
    } elseif {$zDiscriminant < 0.0} {
        set rootList [solveOneRealRoot $cardanoQ $cardanoR $coefficientA1]
    } else {
        set rootList [solveThreeRealRoots $cardanoQ $cardanoR $coefficientA1]
    }
    assertConditionIsTrue \
        [expr {[llength $rootList] >= 1}] \
        "solveCubicEquation: rootList must contain at least one root"
    return $rootList
}


# -----------------------------------------------------------------------------
# generateRandomCubicCoefficients
# Purpose  : Generate three random coefficients in the range [-20, -10].
#            Returns a list suitable for passing to solveCubicEquation.
# Arguments: none
# Returns  : list of three floating-point values {a1 a2 a3}
# -----------------------------------------------------------------------------
proc generateRandomCubicCoefficients {} {
    set randomCoefficientA1 [expr {rand() * 10.0 - 20.0}]
    set randomCoefficientA2 [expr {rand() * 10.0 - 20.0}]
    set randomCoefficientA3 [expr {rand() * 10.0 - 20.0}]
    assertConditionIsTrue \
        [expr {[llength [list $randomCoefficientA1 \
                              $randomCoefficientA2 \
                              $randomCoefficientA3]] == 3}] \
        "generateRandomCubicCoefficients: must produce 3 coefficients"
    return [list $randomCoefficientA1 \
                 $randomCoefficientA2 \
                 $randomCoefficientA3]
}


# -----------------------------------------------------------------------------
# formatRootListForDisplay
# Purpose  : Format a root list as a human-readable multi-line string.
# Arguments: rootList - list of one, two, or three root values
# Returns  : formatted string with one root per line
# -----------------------------------------------------------------------------
proc formatRootListForDisplay {rootList} {
    assertConditionIsTrue \
        [expr {[llength $rootList] >= 1}] \
        "formatRootListForDisplay: rootList must not be empty"
    set formattedOutputText ""
    foreach singleRootValue $rootList {
        append formattedOutputText \
            [format "      root = %14.8f\n" $singleRootValue]
    }
    assertConditionIsTrue \
        [expr {[string length $formattedOutputText] > 0}] \
        "formatRootListForDisplay: output must not be empty"
    return $formattedOutputText
}


# -----------------------------------------------------------------------------
# runSingleAutotestWithTiming
# Purpose  : Run one autotest. Accepts explicit coefficients and a branch
#            label so the caller controls which solution branch is exercised.
#            Timing uses 1000 iterations to average scheduling noise.
#            format "%.4f" cleans the floating-point rounding artifact that
#            appears in the raw time result string (e.g. 13.7104000000002).
# Arguments: autotestNumber      - integer label 1 through 5
#            givenA1             - a1 coefficient for this test
#            givenA2             - a2 coefficient for this test
#            givenA3             - a3 coefficient for this test
#            expectedBranchLabel - human-readable name of expected branch
# Returns  : nothing (side effect: prints to stdout)
# NASA Rule 3: fixed loop bound of 1000 in time command
# -----------------------------------------------------------------------------
proc runSingleAutotestWithTiming {autotestNumber givenA1 givenA2 givenA3
                                   expectedBranchLabel} {
    assertConditionIsTrue \
        [expr {$autotestNumber >= 1 && $autotestNumber <= 5}] \
        "runSingleAutotestWithTiming: autotestNumber must be 1 to 5"
    assertConditionIsTrue \
        [string is double $givenA1] \
        "runSingleAutotestWithTiming: givenA1 must be numeric"
    puts "--- Autotest $autotestNumber  (expected branch: $expectedBranchLabel) ---"
    puts [format "  Coefficients:  a1 = %12.6f   a2 = %12.6f   a3 = %12.6f" \
          $givenA1 $givenA2 $givenA3]
    set rootList  [solveCubicEquation $givenA1 $givenA2 $givenA3]
    set rootCount [llength $rootList]
    puts "  Real roots found: $rootCount"
    puts [formatRootListForDisplay $rootList]
    set rawTimingString     [time {solveCubicEquation $givenA1 $givenA2 $givenA3} 1000]
    set microsecondsValue   [lindex $rawTimingString 0]
    puts [format "  Timing per call (1000-iteration average): %.4f microseconds" \
          $microsecondsValue]
    puts ""
}


# -----------------------------------------------------------------------------
# runAllFiveAutotests
# Purpose  : Execute all five autotests in sequence.
#            Tests 1-3 use fixed coefficients chosen to guarantee that each
#            of the three Cardano solution branches is exercised at least once.
#            Tests 4-5 use random coefficients for general coverage.
#
#            Fixed coefficient derivations:
#              Test 1 -- THREE REAL ROOTS (Z > 0)
#                a1=0, a2=-3, a3=0  gives  Q=1, R=0, Z=1 > 0
#                Roots of  x^3 - 3x = 0  are  0, +sqrt(3), -sqrt(3)
#
#              Test 2 -- DOUBLE ROOT (Z = 0, Q != 0)
#                a1=0, a2=-3, a3=2  gives  Q=1, R=1, Z=0
#                Roots of  x^3 - 3x + 2 = 0  are  +1 (double), -2
#
#              Test 3 -- ONE REAL ROOT (Z < 0)
#                a1=0, a2=1, a3=1   gives  Q=-1/3, R=0.5, Z < 0
#                Root of  x^3 + x + 1 = 0  is approximately -0.6824
#
# Arguments: none
# Returns  : nothing (side effect: prints results to stdout)
# NASA Rule 3: outer loop bound fixed at exactly 5 iterations
# -----------------------------------------------------------------------------
proc runAllFiveAutotests {} {
    puts "=============================================================="
    puts " Random Cubic Parameters Reorg V2 - Five Autotests"
    puts " TCL Club 02/18/2026 -- Cardano-Vieta Cubic Solver"
    puts "=============================================================="
    puts ""
    # Tests 1-3: fixed coefficients, one per solution branch
    runSingleAutotestWithTiming 1  0.0  -3.0   0.0  "THREE REAL ROOTS  (Z > 0)"
    runSingleAutotestWithTiming 2  0.0  -3.0   2.0  "DOUBLE ROOT       (Z = 0)"
    runSingleAutotestWithTiming 3  0.0   1.0   1.0  "ONE REAL ROOT     (Z < 0)"
    # Tests 4-5: random coefficients for general stress coverage
    set randomTriple4 [generateRandomCubicCoefficients]
    runSingleAutotestWithTiming 4 \
        [lindex $randomTriple4 0] \
        [lindex $randomTriple4 1] \
        [lindex $randomTriple4 2] \
        "RANDOM coefficients"
    set randomTriple5 [generateRandomCubicCoefficients]
    runSingleAutotestWithTiming 5 \
        [lindex $randomTriple5 0] \
        [lindex $randomTriple5 1] \
        [lindex $randomTriple5 2] \
        "RANDOM coefficients"
    puts "=============================================================="
    puts " All 5 autotests completed successfully."
    puts "=============================================================="
}


# -----------------------------------------------------------------------------
# MAIN ENTRY POINT
# Run all five autotests when the script is sourced or executed directly.
# -----------------------------------------------------------------------------
runAllFiveAutotests
# end of file

==============================================================
 Random Cubic Parameters Reorg V2 - Five Autotests
 TCL Club 02/18/2026 -- Cardano-Vieta Cubic Solver
==============================================================

--- Autotest 1  (expected branch: THREE REAL ROOTS  (Z > 0)) ---
  Coefficients:  a1 =     0.000000   a2 =    -3.000000   a3 =     0.000000
  Real roots found: 3
      root =    -1.73205081
      root =     1.73205081
      root =     0.00000000

  Timing per call (1000-iteration average): 14.5569 microseconds

--- Autotest 2  (expected branch: DOUBLE ROOT       (Z = 0)) ---
  Coefficients:  a1 =     0.000000   a2 =    -3.000000   a3 =     2.000000
  Real roots found: 2
      root =     1.00000000
      root =    -2.00000000

  Timing per call (1000-iteration average): 16.8754 microseconds

--- Autotest 3  (expected branch: ONE REAL ROOT     (Z < 0)) ---
  Coefficients:  a1 =     0.000000   a2 =     1.000000   a3 =     1.000000
  Real roots found: 1
      root =    -0.68232780

  Timing per call (1000-iteration average): 12.9756 microseconds

--- Autotest 4  (expected branch: RANDOM coefficients) ---
  Coefficients:  a1 =   -18.367673   a2 =   -15.475877   a3 =   -13.071075
  Real roots found: 1
      root =    19.20876542

  Timing per call (1000-iteration average): 13.4169 microseconds

--- Autotest 5  (expected branch: RANDOM coefficients) ---
  Coefficients:  a1 =   -15.550394   a2 =   -15.464058   a3 =   -14.422953
  Real roots found: 1
      root =    16.53817818

  Timing per call (1000-iteration average): 15.8156 microseconds

==============================================================
 All 5 autotests completed successfully.
==============================================================
(Downloads) 1 % 

(tcl) 283 % # MAIN ENTRY POINT
(tcl) 284 % # Run all five autotests when the script is sourced or executed directly.
(tcl) 285 % # -----------------------------------------------------------------------------
(tcl) 286 % runAllFiveAutotests
==============================================================
 Random Cubic Parameters Reorg V2 - Five Autotests
 TCL Club 02/18/2026 -- Cardano-Vieta Cubic Solver
==============================================================

--- Autotest 1 ---
  Coefficients:  a1 =   -11.146664   a2 =   -11.979824   a3 =   -14.903189
  Real roots found: 1
      root =    12.22621154

  Timing per call (1000-iteration average): 70.818 microseconds per iteration

--- Autotest 2 ---
  Coefficients:  a1 =   -17.904209   a2 =   -16.048333   a3 =   -14.333990
  Real roots found: 1
      root =    18.79847565

  Timing per call (1000-iteration average): 8.885 microseconds per iteration

--- Autotest 3 ---
  Coefficients:  a1 =   -11.372972   a2 =   -15.547309   a3 =   -13.614127
  Real roots found: 1
      root =    12.68340090

  Timing per call (1000-iteration average): 8.908 microseconds per iteration

--- Autotest 4 ---
  Coefficients:  a1 =   -12.630371   a2 =   -18.637821   a3 =   -15.853139
  Real roots found: 1
      root =    14.03843927

  Timing per call (1000-iteration average): 8.986 microseconds per iteration

--- Autotest 5 ---
  Coefficients:  a1 =   -13.708612   a2 =   -10.644051   a3 =   -14.571415
  Real roots found: 1
      root =    14.51130972

  Timing per call (1000-iteration average): 71.407 microseconds per iteration

==============================================================
 All 5 autotests completed successfully.
==============================================================
(tcl) 287 % # end of file

two separate bugs fixed on 1-2 iterations, but solution looks rough here:

The oracle is flipping the wrong component.

The diffusion step is mathematically fine, but with the wrong oracle it cancels out and leaves the state uniform.