aboutsummaryrefslogtreecommitdiff
path: root/desiredata/extra/pureunity/README
diff options
context:
space:
mode:
Diffstat (limited to 'desiredata/extra/pureunity/README')
-rw-r--r--desiredata/extra/pureunity/README624
1 files changed, 0 insertions, 624 deletions
diff --git a/desiredata/extra/pureunity/README b/desiredata/extra/pureunity/README
deleted file mode 100644
index a3990537..00000000
--- a/desiredata/extra/pureunity/README
+++ /dev/null
@@ -1,624 +0,0 @@
-$Id: README,v 1.1.2.2 2007-06-01 16:31:54 matju Exp $
-
-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,
- etc., in a modularized way, in a DRY/OAOO fashion, thus abstracting out
- common features so that many objects share the same test patch for the
- features that they have in common.
-
-+-+-+--+---+-----+--------+-------------+---------------------+
-REQUIREMENTS
-
- 1. Pd 0.39 (PureMSP or Devel)
-
-+-+-+--+---+-----+--------+-------------+---------------------+
-TEST PROTOCOL
-
- new:
- create common (reusable) fixtures.
-
- inlet 0:
- bang:
- run all available tests in that class. individual tests don't have
- to be available through individual methods but may. If they do, the
- names of the methods must match those given in the test results.
-
- each test should build its own non-reusable fixtures and reinitialize
- common fixtures, not assuming that the previous tests have left the
- common fixtures in a normal state.
-
- outlet 0:
- test results. a sequence of lists like:
- list $passed? $accuracy $elapsed $name1 ...
-
- where:
- $passed? is either 0 for failure or 1 for success
- $accuracy is a float proportional to relative error on math
- (if not applicable, use 0)
- $elapsed is a nonnegative float, the time elapsed in milliseconds
- or it is any negative float meaning the time hasn't been measured.
- $name1 and the rest are symbols and/or floats identifying the test
-
- for example:
- list 1 0 -1 commutative f + *
-
- Which means that the 1st test about commutativity passed ($2=1) because it
- was perfectly accurate ($3==0) and that we didn't measure the time ($4=-).
-
-+-+-+--+---+-----+--------+-------------+---------------------+
-SEVERITIES (in decreasing order)
-
- * crash: Segmentation Fault, Bus Error, Illegal Instruction, Infinite Loop,
- etc. You can't deal with those errors at the level of the tests. Maybe there
- should be a way to tell a test object to skip certain tests, by name, in
- order to be able to perform as many tests as possible while waiting for a
- fix. It could become possible to rescue from some of those crashes if Pd
- supported exceptions (stack-unwinding).
-
- * corruption: this may cause future crashes and failures on innocent
- objects/features. I have no solution for this except to be careful.
-
- * post(),error(),pd_error(): Gets printed in the console. The problem is that
- those can't be handled by the test objects, so someone has to read them and
- interpret them. Also they prevent test objects to ensure that error
- conditions produce error messages. This includes stack overflow.
-
- * pd_error2(): I wish this would exist. It would be sort of like pd_error()
- but it would produce a pd message instead, whose selector would be an
- error code, designed to be both localizable and [route]able. By default, that
- message would be sent to the console, but there would be an internal class
- designed to catch those messages. (If stack-unwinding were possible, it would
- be disabled by default on pd_error2 and could be enabled explicitly
- by-selector).
-
- * failure: a test object reports a problem through outlet 0.
-
- * dropout: a failure in realtimeness... difficult for an object to detect.
-
- * inaccuracy: a test more or less succeeds but the test detected that the
- epsilon sucks.
-
-+-+-+--+---+-----+--------+-------------+---------------------+
-PROTOCOL FOR [error]
-
-new:
- optional argument which would either be a float
- (e.g. the $0 of the enclosing abstraction) or a pointer.
-
-inlet 0:
- set $scapegoat:
- replaces the originator of the message by $scapegoat, which can be a
- float or a pointer
-
- error $1 ...:
- causes its arguments to be concatenated, space-separated (may include
- floats), and then sent through pd_error using the appropriate
- originator (scapegoat).
-
- list $1 ...:
- for future use. would use pd_error2() (see README or previous mail).
- $1 has to be a symbol.
-
-+-+-+--+---+-----+--------+-------------+---------------------+
-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.
-
-+-+-+--+---+-----+--------+-------------+---------------------+
-TYPE PREFIXES
-
-Those have to be prefixes in order to be honored by DOLLSYM:
-[$1norm] should expand to [fnorm], [lfnorm], [#norm], etc.
-
-Those prefixes are necessary in order to achieve polymorphism through
-abstraction arguments.
-
-CURRENT:
- f float
- ~ signal
-
-FUTURE (from PureData):
- s symbol
- p gpointer
- a anything
- l list (of whatever)
- lf list of floats
- ls list of symbols
- lp list of pointers
-
-FUTURE (from DesireData):
- L listpointer (still trying to figure out whether this will really happen)
- v varpointer (instance symbol)
-
-FUTURE (from GridFlow):
- # grid (of whatever)
- #b grid of bytes (uint8)
- #s grid of shorts (int16)
- #i grid of ints (int32)
- #l grid of longs (int64)
- #f grid of floats (float32)
- #d grid of doubles (float64)
- #t grid of Tcl_Object or t_atom or I don't know what.
-
-for a type prefix to be considered implemented, it has to
-have the following class set:
-
- metaabstraction for floats for signals for grids
- [inlet.$1] [inlet] [inlet~] [inlet]
- [outlet.$1] [outlet] [outlet~] [outlet]
- [op2.$1 $2 $3] [$2 $3] [$2~ $3] [# $2 $3]
- [taa.$1] [t a a] noop [t a a]
- [swap.$1] [swap] noop TODO
- [norm.$1] [abs] [env~] [# sq]->[#ravel]->[#fold +]->[#export]->[sqrt]
- [packunpack3.$1] pack,unpack noop TODO
- [rand.$1] ..................................
-
-The first two cannot be implemented as abstractions and instead must be
-defined as aliases in pureunity.c.
-
-extra metaabstractions:
- [$1.rand] [f.rand] [~.rand]TODO [#.rand]TODO
-
-+-+-+--+---+-----+--------+-------------+---------------------+
-OTHER PROTOCOLS
-
-Those four classes are operators that give verify algebraic properties
-of other operators. The more their outputs are close to zero, the more
-those other operators are faithful to an algebraic property.
-
-(here, supported $types are f and ~)
-
-[commutator $type $class] (2 inlets) ab-ba
-[associator $type $class] (2 inlets) (ab)c-a(bc)
-[distributor $type $class1 $class2] (3 inlets) a&(b^c)-(a&b^a&c)
-[invertor $type $class1 $class2] (2 inlets) ab/b-a
-
-+-+-+--+---+-----+--------+-------------+---------------------+
-TESTS AND RULES
-
-For each class, a test file's name is the class name followed by "-test.pd",
-and a rule file's name is the class name followed by "-rule.pd",
-in the same way as it is for help files.
-
-for a class called $foo, the protocol (aka interface aka rule) $foo is the
-set of behaviours expected from the $foo class; the class called $foo-rule
-must repect the $foo protocol as well, plus it should test that the inputs
-are valid, and if they are, it should test for one or several results and
-report any errors.
-
-To report errors and inaccuracies, output them through the properties outlet
-at the right. If there is no properties outlet in $foo (curently almost
-nothing in Pd has one), then $foo-rule must have one more outlet than $foo.
-
-Float messages coming out of the properties outlet of $foo-rule report
-accuracy. Named error messages come out with selector "error" followed by
-an error-symbol and then its arguments.
-
-In the case of true/false logic, a value of 0 means that a test has passed
-and a 1 means that a test has failed. Those values represent failure and not
-success. The reason is so that it matches with accuracy levels, where 0 is
-perfectly accurate, but any inaccuracy shows up as a relative error fraction.
-Any finite nonnegative value is allowed for accuracy, because it is expected
-to be the result of a norm.
-
-In standard math, "Discrete Metric" is when there are only two possible
-distances between objects: together=0 and apart=1
-
-+-+-+--+---+-----+--------+-------------+---------------------+
-RANDOMIZERS (?)
-
-+-+-+--+---+-----+--------+-------------+---------------------+
-ETC
-
-(write me!)
-
-If +-test.pd tests [+], it can test for hotness, coldness, it can test
-that only one result is produced per hot message, that all results are
-float, that a few example additions work, and that with random inputs it
-respects commutativity, associativity, invertibility, within appropriate
-relative-error bounds, etc.
-
-However +-test.pd can't test that errormessages aren't printed during the
-testing. This may be something that we want to check for, and currently
-the best way to handle it is to search the console for error messages, and
-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.
-
-+-+-+--+---+-----+--------+-------------+---------------------+
-
-Date: Fri, 13 Jan 2006 04:07:59 +0900
-From: Mathieu Bouchard <matju@artengine.ca>
-Reply-To: ruby-core@ruby-lang.org
-To: ruby-core@ruby-lang.org
-Subject: Re: Design contracts and refactoring (was Re: mathn: ugly warnings)
-
-On Fri, 13 Jan 2006, mathew wrote:
-
-> *Dean Wampler *<deanwampler gmail.com> writes:
-> > Let me suggest an XP-style alternative; make thorough unit tests
-> > required and make sure they "document" - and test! - the design
-> > "contract".
-> Unit tests are not an alternative. They are an additional requirement.
-
-I find unit-tests to be often decomposable like this. Start with something
-like this:
-
- raise if Blah.new(666) != Blah.new(666)
- raise if Blah.new(747) != Blah.new(747)
- raise if Blah.new(242) != Blah.new(242)
- raise if Blah.new(69) != Blah.new(69)
- raise if Blah.new(37) != Blah.new(37)
-
-then generalize it ("equality is defined based on the arg of .new"):
-
- for x in [666,747,242,69,37] do
- raise if Blah.new(x) != Blah.new(x)
- end
-
-then extract a contract from it:
-
- class CheckedBlah < Blah
- def self.new(x)
- r = super(x)
- raise if r != super(x)
- r
- end
- end
-
-so now all Blah object creation may be checked throughout actual uses of a
-program and not just unit tests. The unit test now reduces to:
-
- for x in [666,747,242,69,37] do Blah.new(x) end
-
-so for many unit tests, all you have to do is just do things and discard
-the results, and the contract will do the job of checking.
-
- _ _ __ ___ _____ ________ _____________ _____________________ ...
-| Mathieu Bouchard - tél:+1.514.383.3801 - http://artengine.ca/matju
-| Freelance Digital Arts Engineer, Montréal QC Canada
-
-+-+-+--+---+-----+--------+-------------+---------------------+
-
-Date: Fri, 13 Jan 2006 05:05:19 +0900
-From: Mathieu Bouchard <matju@artengine.ca>
-Reply-To: ruby-core@ruby-lang.org
-To: ruby-core@ruby-lang.org
-Subject: Re: Design contracts and refactoring (was Re: mathn: ugly warnings)
-
-On Fri, 13 Jan 2006, mathew wrote:
-
-> For example, consider a simple vector addition routine in a 3D library.
-> The unit tests might test its behavior with Float and Integer vectors,
-> since that's why it was written.
-
-Here's another way to factor unit-tests that I haven't mentioned in the
-last mail.
-
-suppose you test for + using:
-
- class IntegerTest
- def test; 2+2==4 or raise; end
- end
- class FloatTest
- def test; 2.0+2.0==4.0 or raise; end
- end
- class RationalTest
- def test; Rational(2,1)+Rational(2,1)==Rational(4,1) or raise; end
- end
-
-you can refactor those tests like this:
-
- class NumericTest
- def initialize nt; @nt; end
- def make x; raise "abstract class" end
- def test; make(2)+make(2)==make(4) or raise; end
- end
- class IntegerTest; def make x; Integer(x) end end
- class FloatTest; def make x; Float(x) end end
- class RationalTest; def make x; Rational(x,1) end end
-
-> However, to do that you need to know whether the feature of supporting
-> (say) Complex vectors or BigDecimal vectors is intended or not. The unit
-> tests won't tell you this.
-
-[...]
-
-> > One limitation of documentation is that it has no enforcement power,
-> > so you have to write tests anyway to test conformance.
-> Unit tests have no enforcement power either, because you can just change the
-> test. Indeed, I've already had to do this once when it turned out that the
-> unit test was wrong. (In net/ftp.)
-
-That was a pretty bad case of strawman argument. Dean was assuming that
-your documentation was not executable when you had quite clearly stated
-that it was the contracts that acted as documentation!
-
-[...]
-
-+-+-+--+---+-----+--------+-------------+---------------------+
-
-Date: Fri, 13 Jan 2006 07:36:36 +0900
-From: Mathieu Bouchard <matju@artengine.ca>
-Reply-To: ruby-core@ruby-lang.org
-To: ruby-core@ruby-lang.org
-Subject: Re: Design contracts and refactoring (was Re: mathn: ugly warnings)
-
-On Fri, 13 Jan 2006, mathew wrote:
-
-> > The XP view is
-> > that you should eliminate the redundancy.
-> Except it's not redundancy.
-> Unit tests define a set of functionality that is required. Documentation tells
-> you the functionality that is supported, which is generally a superset of the
-> functionality required by the unit tests.
-
-Let's follow the argument of both of you to the end.
-
-1. Unit-tests often match inputs with outputs on a case-by-case basis.
-
-2. Redundancy should be eliminated.
-
-(1) suggests that there is a shorter way to express the unit-tests.
-Suppose you are able to find a formula for generating output-validators
-from inputs. Then that formula is a postcondition of a contract, and the
-explicit output-validators of the unit-tests are redundant.
-
-(2) because part of the unit-tests are redundant, part of the unit-tests
-should be eliminated. This causes the postconditions to become an
-essential part of unit-testing.
-
-Unit-tests vs contracts is a false debate.
-
- _ _ __ ___ _____ ________ _____________ _____________________ ...
-| Mathieu Bouchard - tél:+1.514.383.3801 - http://artengine.ca/matju
-| Freelance Digital Arts Engineer, Montréal QC Canada
-
-
-+-+-+--+---+-----+--------+-------------+---------------------+
-Date: Fri, 13 Jan 2006 17:19:41 +0900
-From: Mathieu Bouchard <matju@artengine.ca>
-Reply-To: ruby-core@ruby-lang.org
-To: ruby-core@ruby-lang.org
-Subject: Re: Design contracts and refactoring (was Re: mathn: ugly warnings)
-
-[...]
-
-In order to entrench the tests-as-documentation habit firmly in the Ruby
-community, we need a catchy acronym. Like RTFUT = Read the Fabulous Unit
-Tests!
-
-+-+-+--+---+-----+--------+-------------+---------------------+
-http://lists.puredata.info/pipermail/pd-dev/2006-01/005920.html
-Date: Fri, 20 Jan 2006 23:52:22 -0500 (EST)
-From: Mathieu Bouchard <matju@artengine.ca>
-To: pd-dev <pd-dev@iem.at>
-Subject: macros and such (was: pd-lib, SIMD)
-
-[...]
-
-I think that the Pd source doesn't use nearly enough macros or other
-code-reducing tricks.
-
-The reduction of code isn't so much about making things use less RAM: the
-RAM excuse is quickly evaporating as even the tiniest computers come with
-plenty of RAM and even the faster kinds of RAM come in ever more copious
-amounts (big caches).
-
-The reduction of code is programmer-oriented. I'm not talking about length
-of identifiers here (this is a separate issue). Every line of code should
-do something interesting by itself. Code should read like a good story and
-not like a car. Ever tried to read a car? It's boring. The same damn
-piston copy-pasted 12 times.
-
-The reduction of code is also documentation-oriented. Once the programmer
-has been contaminated with the wisdom required to make small code or
-understand small code, then why wouldn't the programmer explain it to his
-students in higher-level terms instead of chanting 12 times the same
-piston as if it were a marathon of Hail-Marys ?
-
-This is why Pd needs a taxonomy of object classes. If I don't get that
-taxonomy in Pd itself nor in its help files, at least I'll have it in its
-unit tests.
-
-Once and only once.
-Once and only once.
-Once and only once.
-Three strikes and you refactor.
-for x in [1,2,3] say: Once and only once
-
-http://c2.com/cgi/wiki/?ThreeStrikesAndYouRefactor
-
-BTW I'm not talking about only inheritance of implementations. The most
-important thing to me is inheritance of expectations, so that if I name
-100 classes that obey the rule "Operator2", then you have just learned
-something common about 100 classes.
-
-Operator2 means right-inlet is cold, left-inlet is hot, there is a "set"
-method for using left-inlet as cold, there is a "bang" for explicitly
-activating the main computation. The main computation only produces one
-message. That's what "Operator2" means in my taxonomy, and it's that much
-that hasn't to be stated explicitly in each help patch.
-
-Help patches can be abstractions to be used to by other help patches. Just
-put a [operator2-help] object in your help patch to indicate that the
-currently documented class obeys the standard operator2 rules.
-
-Who's against it?
-
-+-+-+--+---+-----+--------+-------------+---------------------+
-http://lists.puredata.info/pipermail/pd-list/2006-02/035169.html
-Date: Sat Feb 4 21:22:29 CET 2006
-From: Mathieu Bouchard <matju@artengine.ca>
-To: pd-list
-
- * Previous message: [PD] dealing with arguments and inlets
- * Next message: [PD] Re: [PD-announce] A new version of FFTease is now available for Pd
- * Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
-
-On Fri, 3 Feb 2006, Hans-Christoph Steiner wrote:
-
-> The way I have been thinking is that the first inlet is the general
-> inlet, and it can accept many types of messages. Then the second inlet
-> lines up with the first argument, the third inlet to the second
-> argument, etc.
-
-I agree. Many objects obey the rule that the k'th inlet matches argument
-$k for several arguments in a row, usually all of them.
-
-> I think this is pretty clean and flexible, and I think
-> it would be nice to have some kind of standard for this.
-
-And the best way to make sure people are following a standard is to make
-it so easy to follow that it's harder to not follow it than to follow it.
-Of course I don't mean adding hurdles to doing it otherwise, but rather
-make a shortcut for those who follow the standard. Short of this, people
-who make abstractions/externals can get a friendly reminder, from someone
-who cares, that it would be better if they followed the standard.
-
-> Obviously, it doesn't work for all objects, but I think it would be good to
-> standardize on objects it does work for.
-
-PureUnity's goal (when I work on it) is to design a taxonomy that
-separates objects that obey certain properties, from those that don't,
-because that's a way to reuse tests, but also because certainly it doesn't
-hurt documentation either, and it's even better if it can influence how
-abstractions are made.
-
- _ _ __ ___ _____ ________ _____________ _____________________ ...
-| Mathieu Bouchard - tél:+1.514.383.3801 - http://artengine.ca/matju
-| Freelance Digital Arts Engineer, Montréal QC Canada
-
-+-+-+--+---+-----+--------+-------------+---------------------+
-From matju@artengine.ca to pd-list on Dec 18, 2006
-
-I thought up some kind of classification of type systems, avoiding to call
-them strong/weak or static/dynamic because those words are confusing.
-
-1. Typed expressions: each piece of code that can give a value, has a
-type that can be figured out at compile-time.
-
-2. Typed variables/parameters: declarations allow runtime checks but not
-compile-time checks.
-
-3. Typed values: variables don't have types, they can contain any value,
-but every value has a type.
-
-4. Typed uses: values don't have types, a type is a way of using a value.
-
-Strictness, in the sense of forbidding things to the user, is not on that
-scale, it's another aspect. A well-balanced strictness allows one to
-bypass the system whenever needed, but without being too error-prone.
-
-However it's difficult to say what it means to "bypass the system" for all
-four typing categories at once, or even within one category.
-
-
-+-+-+--+---+-----+--------+-------------+---------------------+
-From matju@artengine.ca to pd-dev on Jan 2, 2007
-
-PureUnity will now require pd 0.40. This will make things easier, as for
-example the aliases [f.inlet], [~.inlet] can be renamed to [inlet.f] and
-[inlet.~], which makes those class-templates sortable alphabetically, and
-readable as "inlet of float" and "inlet of signal" or maybe "inlet for
-floats" and "inlet for signals"... likewise for all other existing
-templates of PureUnity (do,norm,outlet,packunpack3,rand,swap,taa).
-
-(here, "template" means "parametrized classname" as in C++, and not t_template)
-
-+-+-+--+---+-----+--------+-------------+---------------------+
-Old pre-DesireData ChangeLog for PureUnity:
-
-version 0.0 (2006.01.06):
- * LICENSE is GPL
- * doc is in README
- * new object classes:
- * [commutator], [commutative-test]
- * [associator], [associative-test]
- * [invertor], [invertible-test]
- * [distributor], [distributive-test]
- * [trichotomy-test], ...
- * [twice], [3times], [4times], [^]
- * [tree], [protocols-tree]
- * [rtimer]
- * for $1 in f,~ and some of #:
- [$1.norm], [$1.taa], [$1.do], [$1.packunpack3], [$1.swap]
- [$1.inlet], [$1.outlet]
-
-+-+-+--+---+-----+--------+-------------+---------------------+