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. +