[PD-cvs] abstractions/pureunity README,1.3,1.4

[Mathieu Bouchard]

Update of /cvsroot/pure-data/abstractions/pureunity
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv14873

Modified Files:
	README 
Log Message:
more doc, especially about measuring error


Index: README
===================================================================
RCS file: /cvsroot/pure-data/abstractions/pureunity/README,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** README	29 Dec 2005 23:04:27 -0000	1.3
--- README	31 Dec 2005 02:50:12 -0000	1.4
***************
*** 1,13 ****
  PureUnity
  
  Copyright 2006 by Mathieu Bouchard <matju à artengine point ca>
  
! $Id$
  
  +-+-+--+---+-----+--------+-------------+---------------------+
  GOALS
  
!   1. To provide a unit-test framework, which also provide benchmarking features, 
!      all made in Pd for use in Pd.
  
    2. To provide tests for functionality in internals, externals, abstractions, 
--- 1,29 ----
+ $Id$
+ 
  PureUnity
  
  Copyright 2006 by Mathieu Bouchard <matju à artengine point ca>
  
! This program is free software; you can redistribute it and/or
! modify it under the terms of the GNU General Public License
! as published by the Free Software Foundation; either version 2
! of the License, or (at your option) any later version.
! 
! See file ./COPYING for further informations on licensing terms.
! 
! This program is distributed in the hope that it will be useful,
! but WITHOUT ANY WARRANTY; without even the implied warranty of
! MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
! GNU General Public License for more details.
! 
! You should have received a copy of the GNU General Public License
! along with this program; if not, write to the Free Software
! Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  
  +-+-+--+---+-----+--------+-------------+---------------------+
  GOALS
  
!   1. To provide a unit-test framework, which also provide benchmarking
!      features, all made in Pd for use in Pd.
  
    2. To provide tests for functionality in internals, externals, abstractions, 
***************
*** 101,104 ****
--- 117,163 ----
  
  +-+-+--+---+-----+--------+-------------+---------------------+
+ ACCURACY AND ERROR (in math-related unit tests)
+ 
+ The "absolute error" between a practical result and the expected value
+ is considered to be the distance between the two value. That is the
+ absolute value of the difference.
+ 
+ In the case of positions in 2D, 3D, etc., use the L2-Norm which is
+ a generalized Pythagoras' Theorem: dist^2 = x^2 + y^2 + z^2 + ...
+ A norm is a distance between something and zero.
+ 
+ Sometimes you have several practical results for one expected value
+ and must extract a single absolute error out of that. Then you should pick
+ the largest of the individual absolute errors.
+ 
+ Sometimes you don't have an expected value, you just have several
+ practical results that you expect to be quite the same. In that case,
+ the absolute error is the "diameter" of those results. The meaning
+ of diameter here is: the largest distance between any two results.
+ 
+ If in a single test you must compare 2D errors with 3D errors and 1D
+ errors, etc., you may have to adjust them by dividing the error by
+ the square root of N (N is the number of dimensions). In that case,
+ the resulting value is called a RMS (Root-Mean-Square).
+ 
+ The maximum error introduced by just representing a number as a float
+ (instead of an exact value) is at most proportional to the magnitude
+ of the number (e.g. usually 16 million times smaller: about 6 decimals).
+ Also, often we are only interested in relative error, which is absolute
+ error divided by the norm of the expected result, because small absolute
+ errors don't matter much with large results. This is the reason floats
+ exist in the first place. By default, use relative error as the $accuracy
+ in Pd tests.
+ 
+ If you don't have an expected result, then compute the relative error as
+ being the absolute error divided by the norm of the average of practical
+ results.
+ 
+ In the RMS case of relative error, the norms of expected results should also
+ be adjusted, but both adjustments cancel because they get divided by each
+ other. That means: don't divide by the sqrt(N) at all and you'll get an
+ appropriate result.
+ 
+ +-+-+--+---+-----+--------+-------------+---------------------+
  ETC
  
***************
*** 120,121 ****
--- 179,195 ----
  if there are any, restart the tests in verbose mode and see where the
  error happens exactly.
+ 
+ [...]
+ 
+ Floating-point is the scientific notation for numbers that we all
+ learned on paper in school. Rounding and inaccuracy are two sides
+ of the same coin. They are required when it is stupid to have perfect
+ results, that is, when it would mean too many computations for little
+ gain.
+ 
+ However sometimes we want to make sure that our math is accurate enough.
+ Many algorithms are data-recursive: each computation uses previous
+ results. Many of those algorithms have chaotic and/or unstable
+ behaviours, which means that the inaccuracies may skyrocket instead of
+ fading out.
+