From 9dbb5fff24c14d8829f062664369fc9c2f24d036 Mon Sep 17 00:00:00 2001 From: "Thomas M. Hermann" Date: Tue, 19 Jan 2010 14:33:10 -0600 Subject: [PATCH] Updated the documentation for the floating point extensions. --- documentation/lisp-unit.html | 246 ++++++++++++++++--------------------------- 1 file changed, 88 insertions(+), 158 deletions(-) diff --git a/documentation/lisp-unit.html b/documentation/lisp-unit.html index 1b2321b..12a5eb3 100644 --- a/documentation/lisp-unit.html +++ b/documentation/lisp-unit.html @@ -25,11 +25,12 @@ visit www.junit.org.

-

This page has two parts:

+

This page has three parts:

@@ -222,8 +223,8 @@ MY-SQRT: 2 assertions passed, 3 failed.

There are also assertion forms to test what code prints, what errors code returns, or what a macro expands into. A complete list of - assertion forms is in the reference - section. + assertion forms is in the reference and + extensions sections.

@@ -265,7 +266,7 @@ MY-SQRT: 2 assertions passed, 3 failed. 

 (defpackage :date
   (:use :common-lisp)
-  (:export #:date->string #:string->date))
+  (:export :date->string :string->date))
   
 (in-package :date)
 
@@ -306,12 +307,12 @@ MY-SQRT: 2 assertions passed, 3 failed.
 
Reference Section

 
 

-  Here is a list of the functions and macros exported by
-  lisp-unit.
+  The list of the basic functions and macros exported by
+  lisp-unit are presented in this section.
 

 
 
-
Functions for managing tests

+
Functions for managing tests

 
 

   

@@ -328,7 +329,7 @@ MY-SQRT: 2 assertions passed, 3 failed.
   
 
   

-    (get-tests [package)
+    (get-tests [package])
   

   

     This function returns the names of all the tests that have been
@@ -337,7 +338,7 @@ MY-SQRT: 2 assertions passed, 3 failed.
   

 
   

-    (get-test-code name [package)
+    (get-test-code name [package])
   

   

     This function returns the body of the code stored for the test
@@ -397,7 +398,7 @@ MY-SQRT: 2 assertions passed, 3 failed.
 

 
 
-
Forms for assertions

+
Forms for assertions

 
 

   All of the assertion forms are macros.  They tally a failure if the
@@ -479,7 +480,7 @@ MY-SQRT: 2 assertions passed, 3 failed.
     error that is equal to or a subtype of
     condition-type. Use error to refer to any
     kind of error. See condition
+    href="http://www.lispworks.com/documentation/HyperSpec/Body/09_aa.htm">condition
     types in the Common Lisp Hyperspec for other possible
     names. For example,
 
@@ -491,7 +492,7 @@ MY-SQRT: 2 assertions passed, 3 failed.
 
 
 
-
Utility predicates

+
Utility predicates

 
 

   Several predicate functions are exported that are often useful in
@@ -517,27 +518,34 @@ MY-SQRT: 2 assertions passed, 3 failed.
   
 
 
-
Floating point predicates and tests

+
+
Extensions Section

 
 

-  The original list unit has been extended with several floating point
-  predicate functions and tests. The predicates can be used with
-  assert-equality or the corresponding tests can be
-  directly applied. All of the floating point comparisons are
-  considered equal if the relative error between the values is less
-  than some epsilon. The internal default value of
-  epsilon is is twice the appropriate float epsilon
-  (i.e. 2*single-float-epsilon or
-  2*double-float-epsilon). Epsilon can be controlled at a
-  lexical level using the package variable *epsilon*. If
-  *epsilon* is set to nil, the internal
-  epsilon values are used. This is the default value of
-  epsilon.
+  The extensions to lisp-unit are presented in this
+  section. The original lisp-unit has been extended
+  with predicate functions and assertions to support numerical
+  testing. The predicates can be used with
+  assert-equality or with the corresponding
+  assertions. All extensions are implemented using generic functions
+  and consequently can be specialized for user classes.
+

+
+
Floating point predicates and assertions

+
+

+  The internal default value of epsilon is is twice the
+  appropriate float epsilon (i.e. 2*single-float-epsilon
+  or 2*double-float-epsilon). Epsilon can be controlled
+  at a lexical level using the package variable
+  *epsilon*. If *epsilon* is set to
+  nil, the internal epsilon values are used. This is the
+  default value of epsilon.
 

 
 

   

-    (float-equal float1 float2 [epsilon])
+    (float-equal data1 data2 [epsilon])
   

   

     (assert-float-equal value form
@@ -545,49 +553,15 @@ MY-SQRT: 2 assertions passed, 3 failed.
   

   

     Return true if the relative error between
-    float1 and float2
-    is less than epsilon. The test tallies the failure if
-    value is not equal to the result returned from
-    form, using float-equal.
-  

-
-  

-    (complex-equal complex1 complex2 [epsilon])
-  

-  

-    (assert-complex-equal value form
-     [form1 form2 ...])
-  

-  

-    Return true if the relative error between
-    Real(complex1),
-    Real(complex2) and
-    Imaginary(complex1),
-    Imaginary(complex2) are each less than
-    epsilon. The test tallies the failure if
-    value is not equal to the result returned from
-    form, using complex-equal.
-  

-  

-    (number-equal number1 number2 [epsilon])
-  

-  
-  

-    (assert-number-equal value form
-     [form1 form2 ...])
-  

-  

-    Return true if the error between number1
-    and number2 is less than
-    epsilon for floating point numbers. If the numbers
-    are integers, return true if the numbers are equal.  The test
-    tallies the failure if value is not equal to the
-    result returned from form, using
-    number-equal.
+    data1 and data2
+    is less than epsilon. The assertion tallies the
+    failure if value is not equal to the result returned
+    from form, using float-equal.
   

 
   

-    (sigfig-equal float1 float2 [significant-figures])
+    (sigfig-equal float1 float2
+     [significant-figures])
   

   

     (assert-sigfig-equal value form
@@ -604,21 +578,39 @@ MY-SQRT: 2 assertions passed, 3 failed.
   
 
   

-    (array-equal array1 array2 [:test])
+    (norm-equal data1 data2
+     [epsilon] [measure])
   

   

-    (assert-array-equal test value form
-    [form1 form2 ...])
+    (assert-norm-equal value form
+     [form1 form2 ...])
   

   

-    Return true if each element of array1 and
-    array2 is equal according to
-    :test which defaults to number-equal.
-    The test tallies the failure if value is not equal to
-    the result returned from form, using
-    numerical-equal. In general, test must
-    be a function that accepts 2 arguments and returns true
-    or false.
+    Return true if the relative error norm between
+    data1 and data2 is
+    less than epsilon.
+  

+

+
+
GSLL Specific Predicates and Assertions

+

+  

+    (number-equal number1 number2
+     [epsilon] [type-eq-p])
+  

+  

+    (assert-number-equal value form
+     [form1 form2 ...])
+  

+  

+    Return true if the error between number1
+    and number2 is less than
+    epsilon. The numbers must be the same type unless
+    type-eq-p is t. For the comparison, both
+    numbers are coerced to (complex double-float) and
+    passed to float-equal. The test tallies the failure
+    if value is not equal to the result returned from
+    form, using number-equal.
   

 
   

@@ -640,113 +632,51 @@ MY-SQRT: 2 assertions passed, 3 failed.
   
 

 
-
-
Floating point diagnostic functions

-
+
Floating point functions

 

-  Failing a unit test is only half of the problem. The other half is
-  understanding why the test failed and what is required to fix
-  it. The default values of epsilon will only be applicable
-  in a few situations. In many situations, the acceptable value of
-  epsilon is dependent on the routine being examined. When
-  testing large sequences or arrays, it is not enough to know that
-  each element is not equal. It is usually necessary to know which
-  specific elements are not equal. The functions presented in this
-  section facilitate diagnosis test failures for floating point
-  numbers, sequences and arrays. For tests that compare the relative
-  error against epsilon, the value of epsilon can be controlled by
-  setting *epsilon*. Similarly, if
-  sigfig-equal is used as the test, the number of
-  significant figures can be set by setting
-  *significant-figures*.
+  The floating point functions can be specialized for user data types
+  and aid in writing user specific predicates.
 

 
 

   

-    (float-error float1 float2)
+    (default-epsilon value)
   

   

-    Return the relative error between float1
-    and float2.
+    Return the default epsilon for value.
   

-
   

-    (float-error-epsilon float1 float2 [epsilon])
+    (relative-error exact approximate)
   

   

-    Return the error expressed as a multiple of epsilon.
-    (relative error)/epsilon
+    Return the relative error.
   

-
   

-    (complex-epsilon complex1 complex2)
+    (sumsq data)
   

   

-    Return a complex value with each component equal to the relative
-    error between the components of complex1
-    and complex2, respectively.
+    Return the scaling parameter and the sum of the squares of the
+    data.
   

-
-  

-    (complex-error-epsilon complex1 complex2 [epsilon])
-  

-  

-    Return a complex value with each component equal to the the error
-    expressed as a multiple of epsilon.
-    

-      #C((real relative error)/epsilon (imaginary
-      relative error)/epsilon)
-    

-  

-
-  

-    (number-epsilon number1 number2)
-  

-  

-    Return the error between number1 and
-    number2. For float and complex numbers,
-    the result is equivalent to float-equal and
-    complex-equal, respectively. If the numbers are
-    integers, the absolute difference between them is returned.
-  

-
   

-    (number-error-epsilon number1 number2 [epsilon])
+    (sump data p)
   

   

-    Return the error expressed as amultiple of epsilon. For floating
-    point numbers, this is equivalent to
-    float-error-epsilon. Similarly, for complex numbers
-    this is equivalent to complex-error-epsilon. This
-    function is not applicable to integers.
+    Return the scaling parameter and the sum of the powers of p of the
+    data.
   

-
   

-    (sequence-error sequence1 sequence2
-    [:test] [:error-function])
+    (norm data [measure])
   

   

-    Return a nested list of the elements that are not equal according
-    :test with the associated index and error data
-    reported by :error-function.
-    

-      (index number1 number2 (error-function n1 n2))
-    

+    Return the element-wise norm of the data.
   

-
   

-    (array-error array1 array2
-    [:test] [:error-function])
+    (relative-error-norm exact approximate [measure])
   

   

-    Return a nested list of the elements that are not equal according
-    :test with the associated indices and error data
-    reported by :error-function.
-    

-      (indices number1 number2 (error-function n1 n2))
-    

+    Return the relative error norm.
   

-
 

 
 

-- 
2.11.4.GIT