Add more outlining

Author: sriharikrishna

BLAS/docs/TOLERANCES.md

@@ -0,0 +1,79 @@
+# Differentiation test tolerances
+
+Tolerances and step sizes used for finite-difference checks in BLAS differentiation tests (scalar/vector, forward/reverse). All modes use the same precision-based scheme unless a mixed-precision override applies.
+
+---
+
+## Base tolerances by precision
+
+| Family | Description           | rtol    | atol    |
+|--------|-----------------------|---------|---------|
+| S      | single real (`S*`)    | 2.0e-3  | 2.0e-3  |
+| C      | single complex (`C*`) | 1.0e-3  | 1.0e-3  |
+| D      | double real (`D*`)    | 1.0e-5  | 1.0e-5  |
+| Z      | double complex (`Z*`) | 1.0e-5  | 1.0e-5  |
+
+These values are used in:
+
+- Scalar forward
+- Scalar reverse
+- Vector forward
+- Vector reverse
+
+---
+
+## Step size (h)
+
+For non–mixed-precision functions:
+
+| Precision   | h        |
+|------------|----------|
+| S*, C*     | 1.0e-3   |
+| D*, Z*     | 1.0e-7   |
+
+(≈ 10·√ε for double precision.)
+
+---
+
+## Mixed-precision override
+
+For routines whose **output is double precision** but whose **first differentiable input** is **single precision** (e.g. `DSDOT`), the generator uses single-precision–style settings so the finite-difference check matches the conditioning of the inputs:
+
+- **h** = 1.0e-3  
+- **rtol** = 2.0e-3  
+- **atol** = 2.0e-3  
+
+This override is applied in:
+
+- Scalar reverse
+- Vector forward
+- Vector reverse  
+
+Detection: `precision_type == real(8)` and the first entry in the `inputs` list has `get_param_precision(first_input, func_name, param_types) == "real(4)"`. In the generator, `get_param_precision` returns `real(4)` for **D\*** functions when the parameter is one of **SX**, **SY**, **SB**.
+
+---
+
+## Mixed-precision tests (list)
+
+A test is treated as mixed-precision if it is for a **D\*** (or **Z\***) routine and the **first differentiable input** is single precision. The generator explicitly treats **SX**, **SY**, and **SB** as single precision for **D\*** routines.
+
+**Routines that use the mixed-precision override** (when present in the suite and documented with that input order):
+
+| Routine | First input(s) | Modes using override        |
+|---------|----------------|-----------------------------|
+| **DSDOT** | SX (then SY) | Scalar reverse, vector forward, vector reverse |
+
+**Note:** Any other **D\*** routine whose first `\param[in]` is **SX**, **SY**, or **SB** will also get the override. There is no **Z\*** branch for single-precision inputs in `get_param_precision`, so currently only **D\*** routines can be mixed-precision in this sense. If you add a **D\*** (or in future **Z\***) routine with a single-precision first input, it will automatically receive the same h and tolerances as above.
+
+---
+
+## Summary table (all modes)
+
+| Mode             | S* / C* (h) | D* / Z* (h) | Mixed-precision (h, rtol, atol)      |
+|------------------|-------------|-------------|---------------------------------------|
+| Scalar forward   | 1e-3 / 2e-3 or 1e-3 | 1e-7 / 1e-5 | h = 1e-3 only (rtol/atol stay 1e-5)   |
+| Scalar reverse   | 1e-3 / 2e-3 or 1e-3 | 1e-7 / 1e-5 | 1e-3, 2e-3, 2e-3                      |
+| Vector forward   | 1e-3 / 2e-3 or 1e-3 | 1e-7 / 1e-5 | 1e-3, 2e-3, 2e-3                      |
+| Vector reverse   | 1e-3 / 2e-3 or 1e-3 | 1e-7 / 1e-5 | 1e-3, 2e-3, 2e-3                      |
+
+(Base tolerances for S/C/D/Z are as in the first table; mixed-precision replaces h and rtol/atol only where indicated. In scalar forward, mixed-precision only changes the step size h to 1e-3; rtol/atol remain 1e-5.)

BLAS/run_tests.sh

@@ -309,9 +309,13 @@ run_single_test() {
     local has_acceptable=false
     local has_outside_tolerance=false
 
-    if grep -q "FAIL: Large errors detected" "$output_file" 2>/dev/null; then
+    # Any FAIL: line from the test indicates derivative or test failure -> outside tolerance
+    if grep -q "FAIL:" "$output_file" 2>/dev/null; then
         has_outside_tolerance=true
-    elif grep -q "PASS: Derivatives are accurate to machine precision" "$output_file" 2>/dev/null; then
+    fi
+    # Only check PASS/WARNING if no FAIL was found
+    if [ "$has_outside_tolerance" = false ]; then
+    if grep -q "PASS: Derivatives are accurate to machine precision" "$output_file" 2>/dev/null; then
         has_machine_precision=true
     elif grep -q "PASS: Vector derivatives are accurate to machine precision" "$output_file" 2>/dev/null; then
         has_machine_precision=true
@@ -328,6 +332,7 @@ run_single_test() {
     elif grep -q "WARNING: Vector derivatives may have significant errors" "$output_file" 2>/dev/null; then
         has_outside_tolerance=true
     fi
+    fi
 
     # Determine test result category and update counters
     if [ $exit_code -eq 0 ] && [ "$has_execution_failures" = false ]; then

BLAS/test/test_caxpy.f90

@@ -47,14 +47,14 @@ subroutine run_test_for_size(n, passed)
     integer :: incy
 
     ! Derivative variables
+    complex(4), dimension(n) :: cy_d
     complex(4) :: ca_d
     complex(4), dimension(n) :: cx_d
-    complex(4), dimension(n) :: cy_d
 
     ! Array restoration and derivative storage
+    complex(4), dimension(n) :: cy_orig, cy_d_orig
     complex(4) :: ca_orig, ca_d_orig
     complex(4), dimension(n) :: cx_orig, cx_d_orig
-    complex(4), dimension(n) :: cy_orig, cy_d_orig
     real(4) :: temp_re, temp_im  ! For complex random init
     integer :: i, j
 
@@ -77,27 +77,27 @@ subroutine run_test_for_size(n, passed)
     end do
 
     ! Initialize input derivatives
-    call random_number(temp_re)
-    call random_number(temp_im)
-    ca_d = cmplx(temp_re * 2.0 - 1.0, temp_im * 2.0 - 1.0, kind=4)
     do i = 1, n
       call random_number(temp_re)
       call random_number(temp_im)
-      cx_d(i) = cmplx(temp_re * 2.0 - 1.0, temp_im * 2.0 - 1.0, kind=4)
+      cy_d(i) = cmplx(temp_re * 2.0 - 1.0, temp_im * 2.0 - 1.0, kind=4)
     end do
+    call random_number(temp_re)
+    call random_number(temp_im)
+    ca_d = cmplx(temp_re * 2.0 - 1.0, temp_im * 2.0 - 1.0, kind=4)
     do i = 1, n
       call random_number(temp_re)
       call random_number(temp_im)
-      cy_d(i) = cmplx(temp_re * 2.0 - 1.0, temp_im * 2.0 - 1.0, kind=4)
+      cx_d(i) = cmplx(temp_re * 2.0 - 1.0, temp_im * 2.0 - 1.0, kind=4)
     end do
 
     ! Store _orig and _d_orig
+    cy_d_orig = cy_d
     ca_d_orig = ca_d
     cx_d_orig = cx_d
-    cy_d_orig = cy_d
+    cy_orig = cy
     ca_orig = ca
     cx_orig = cx
-    cy_orig = cy
 
     write(*,*) 'Testing CAXPY (n =', n, ')'
     cy_orig = cy
@@ -108,17 +108,17 @@ subroutine run_test_for_size(n, passed)
     write(*,*) 'Function calls completed successfully'
 
     ! Numerical differentiation check
-    call check_derivatives_numerically(n, nsize, ca_orig, cx_orig, cy_orig, ca_d_orig, cx_d_orig, cy_d_orig, cy_d, passed)
+    call check_derivatives_numerically(n, nsize, cy_orig, ca_orig, cx_orig, cy_d_orig, ca_d_orig, cx_d_orig, cy_d, passed)
 
   end subroutine run_test_for_size
 
-  subroutine check_derivatives_numerically(n, nsize, ca_orig, cx_orig, cy_orig, ca_d_orig, cx_d_orig, cy_d_orig, cy_d, passed)
+  subroutine check_derivatives_numerically(n, nsize, cy_orig, ca_orig, cx_orig, cy_d_orig, ca_d_orig, cx_d_orig, cy_d, passed)
     implicit none
     integer, intent(in) :: n
     integer, intent(in) :: nsize
+    complex(4), intent(in) :: cy_orig(n), cy_d_orig(n)
     complex(4), intent(in) :: ca_orig, ca_d_orig
     complex(4), intent(in) :: cx_orig(n), cx_d_orig(n)
-    complex(4), intent(in) :: cy_orig(n), cy_d_orig(n)
     complex(4), intent(in) :: cy_d(n)
     logical, intent(out) :: passed
 
@@ -129,9 +129,9 @@ subroutine check_derivatives_numerically(n, nsize, ca_orig, cx_orig, cy_orig, ca
     logical :: has_large_errors
     complex(4), dimension(n) :: cy_forward, cy_backward
     integer :: i, j
+    complex(4), dimension(n) :: cy
     complex(4) :: ca
     complex(4), dimension(n) :: cx
-    complex(4), dimension(n) :: cy
 
     max_error = 0.0e0
     has_large_errors = .false.
@@ -140,16 +140,16 @@ subroutine check_derivatives_numerically(n, nsize, ca_orig, cx_orig, cy_orig, ca
     write(*,*) 'Step size h =', h
 
     ! Forward perturbation: f(x + h)
+    cy = cy_orig + h * cy_d_orig
     ca = ca_orig + h * ca_d_orig
     cx = cx_orig + h * cx_d_orig
-    cy = cy_orig + h * cy_d_orig
     call caxpy(nsize, ca, cx, 1, cy, 1)
     cy_forward = cy
 
     ! Backward perturbation: f(x - h)
+    cy = cy_orig - h * cy_d_orig
     ca = ca_orig - h * ca_d_orig
     cx = cx_orig - h * cx_d_orig
-    cy = cy_orig - h * cy_d_orig
     call caxpy(nsize, ca, cx, 1, cy, 1)
     cy_backward = cy