tadd rangetest and documentation - numtools - perform numerical operations on vectors and matrices in unix pipes
 (HTM) git clone git://src.adamsgaard.dk/numtools
 (DIR) Log
 (DIR) Files
 (DIR) Refs
 (DIR) README
 (DIR) LICENSE
       ---
 (DIR) commit 7e56f55f66ac239bcf2628648c43b3dc450b5b7d
 (DIR) parent 6a1c8bfa5f29e9f9ecf851d00f1a0210dac325bf
 (HTM) Author: Anders Damsgaard <anders@adamsgaard.dk>
       Date:   Wed, 13 Jan 2021 16:04:44 +0100
       
       add rangetest and documentation
       
       Diffstat:
         M Makefile                            |       2 +-
         M rangetest                           |       2 +-
         A rangetest.1                         |      84 +++++++++++++++++++++++++++++++
       
       3 files changed, 86 insertions(+), 2 deletions(-)
       ---
 (DIR) diff --git a/Makefile b/Makefile
       t@@ -8,7 +8,7 @@ PREFIX = /usr/local
        MANPREFIX = ${PREFIX}/man
        DOCPREFIX = ${PREFIX}/share/doc/${NAME}
        
       -SCRIPTS = mean max min sum
       +SCRIPTS = mean max min sum rangetest
        
        MAN1 = ${SCRIPTS:=.1}
        DOC = \
 (DIR) diff --git a/rangetest b/rangetest
       t@@ -71,5 +71,5 @@ BEGIN {
                if (min >= max)
                        die("min_val must be smaller than max_val")
        
       -        binary_search(cmd, min, max, 20)
       +        binary_search(cmd, min, max, 10)
        }
 (DIR) diff --git a/rangetest.1 b/rangetest.1
       t@@ -0,0 +1,84 @@
       +.Dd $Mdocdate$
       +.Dt RANGETEST 1
       +.Os
       +.Sh NAME
       +.Nm rangetest
       +.Nd tests the output status of a child program with a range of input values
       +.Sh SYNOPSIS
       +.Nm
       +.Ar cmd
       +.Ar min_val
       +.Ar max_val
       +.Sh DESCRIPTION
       +.Nm
       +performs a binary search to test exit status from a
       +.Ar cmd ,
       +where the first occurance of a string @VAL@ is substituted for
       +floating-point values in the search range from
       +.Ar min_val
       +to
       +.Ar max_val .
       +The search range is iteratively narrowed down to find a close
       +approximation of the threshold value where the 
       +.Ar cmd 
       +transitions between succes to failure, as judged by its exit status.
       +.Pp
       +The behavior of
       +.Ar cmd
       +should transition once between succes and failure in the range of
       +.Ar min_val
       +and
       +.Ar max_val .
       +If
       +.Ar min_val
       +and
       +.Ar max_val
       +both fail or both succeed,
       +.Nm
       +fails.
       +.Sh OUTPUT
       +The parameter values of successful runs are printed to stdout, while
       +values of failed runs are printed to stderr.
       +The output of
       +.Ar cmd
       +is also shown, unless it is surpressed by redirecting its output
       +with ">/dev/null 2>&1".
       +.Sh EXAMPLES
       +Given an example program "condfail" which always fails when its
       +first argument is less than 1.5, show all parameter values which
       +result in a successful invocation of
       +.Ar cmd :
       +.Pp
       +.Dl $ rangetest './condfail @VAL@' 0.0 10.0 2>/dev/null
       +.Dl 0
       +.Dl 1.25
       +.Dl 1.40625
       +.Dl 1.48438
       +.Dl 1.49414
       +.Pp
       +While the above values all result in a successful invocation of
       +.Ar cmd ,
       +.Nm
       +progressively steps closer to the failure threshold.
       +.Pp
       +Find the minimum acceptable length 
       +.Op Fl L
       +for the program
       +.Xr cngf-pf 1 ,
       +while surpressing its output:
       +.Pp
       +.Dl $ ./rangetest 'cngf-pf -L @VAL@ -d 0.1 >/dev/null 2>&1' -2e-1 2e-1 2>/dev/null
       +.Dl 0.2
       +.Dl 0.15
       +.Dl 0.125
       +.Dl 0.1125
       +.Dl 0.10625
       +.Dl 0.103125
       +.Dl 0.101562
       +.Dl 0.100781
       +.Dl 0.100391
       +.Sh SEE ALSO
       +.Xr awk 1
       +.Xr cngf-pf 1
       +.Sh AUTHORS
       +.An Anders Damsgaard Aq Mt anders@adamsgaard.dk