updated the description of degree()/ldegree()

[ginac.git] / doc / tutorial / ginac.texi

diff --git a/doc/tutorial/ginac.texi b/doc/tutorial/ginac.texi
index c86114df5b9e07a415190953923634203d6fae81..2af37ad4074211a4f217e9766a3a38b1c3cc1e4b 100644 (file)
--- a/doc/tutorial/ginac.texi
+++ b/doc/tutorial/ginac.texi
@@ -23,7 +23,7 @@
 This is a tutorial that documents GiNaC @value{VERSION}, an open
 framework for symbolic computation within the C++ programming language.
 
-Copyright (C) 1999-2001 Johannes Gutenberg University Mainz, Germany
+Copyright (C) 1999-2002 Johannes Gutenberg University Mainz, Germany
 
 Permission is granted to make and distribute verbatim copies of
 this manual provided the copyright notice and this permission notice
@@ -52,7 +52,7 @@ notice identical to this one.
 
 @page
 @vskip 0pt plus 1filll
-Copyright @copyright{} 1999-2001 Johannes Gutenberg University Mainz, Germany
+Copyright @copyright{} 1999-2002 Johannes Gutenberg University Mainz, Germany
 @sp 2
 Permission is granted to make and distribute verbatim copies of
 this manual provided the copyright notice and this permission notice
@@ -135,7 +135,7 @@ the near future.
 
 @section License
 The GiNaC framework for symbolic computation within the C++ programming
-language is Copyright @copyright{} 1999-2001 Johannes Gutenberg
+language is Copyright @copyright{} 1999-2002 Johannes Gutenberg
 University Mainz, Germany.
 
 This program is free software; you can redistribute it and/or
@@ -984,13 +984,22 @@ The above example prints the following output to screen:
 
 @example
 in 17 digits:
-0.333333333333333333
-3.14159265358979324
+0.33333333333333333334
+3.1415926535897932385
 in 60 digits:
-0.333333333333333333333333333333333333333333333333333333333333333333
-3.14159265358979323846264338327950288419716939937510582097494459231
+0.33333333333333333333333333333333333333333333333333333333333333333334
+3.1415926535897932384626433832795028841971693993751058209749445923078
 @end example
 
+@cindex rounding
+Note that the last number is not necessarily rounded as you would
+naively expect it to be rounded in the decimal system.  But note also,
+that in both cases you got a couple of extra digits.  This is because
+numbers are internally stored by CLN as chunks of binary digits in order
+to match your machine's word size and to not waste precision.  Thus, on
+architectures with differnt word size, the above output might even
+differ with regard to actually computed digits.
+
 It should be clear that objects of class @code{numeric} should be used
 for constructing numbers or for doing arithmetic with them.  The objects
 one deals with most of the time are the polymorphic expressions @code{ex}.
@@ -3182,11 +3191,11 @@ Some examples:
 b^3+a^3+(x+y)^3
 > subs(a^4+b^4+(x+y)^4,$1^2==$1^3);
 b^4+a^4+(x+y)^4
-> subs((a+b+c)^2,a+b=x);
+> subs((a+b+c)^2,a+b==x);
 (a+b+c)^2
 > subs((a+b+c)^2,a+b+$1==x+$1);
 (x+c)^2
-> subs(a+2*b,a+b=x);
+> subs(a+2*b,a+b==x);
 a+2*b
 > subs(4*x^3-2*x^2+5*x-1,x==a);
 -1+5*a-2*a^2+4*a^3
@@ -3434,9 +3443,34 @@ int ex::degree(const ex & s);
 int ex::ldegree(const ex & s);
 @end example
 
-which also work reliably on non-expanded input polynomials (they even work
-on rational functions, returning the asymptotic degree). To extract
-a coefficient with a certain power from an expanded polynomial you use
+These functions only work reliably if the input polynomial is collected in
+terms of the object @samp{s}. Otherwise, they are only guaranteed to return
+the upper/lower bounds of the exponents. If you need accurate results, you
+have to call @code{expand()} and/or @code{collect()} on the input polynomial.
+For example
+
+@example
+> a=(x+1)^2-x^2;
+(1+x)^2-x^2;
+> degree(a,x);
+2
+> degree(expand(a),x);
+1
+@end example
+
+@code{degree()} also works on rational functions, returning the asymptotic
+degree:
+
+@example
+> degree((x+1)/(x^3+1),x);
+-2
+@end example
+
+If the input is not a polynomial or rational function in the variable @samp{s},
+the behavior of @code{degree()} and @code{ldegree()} is undefined.
+
+To extract a coefficient with a certain power from an expanded
+polynomial you use
 
 @example
 ex ex::coeff(const ex & s, int n);
@@ -3617,28 +3651,32 @@ GiNaC still lacks proper factorization support.  Some form of
 factorization is, however, easily implemented by noting that factors
 appearing in a polynomial with power two or more also appear in the
 derivative and hence can easily be found by computing the GCD of the
-original polynomial and its derivatives.  Any system has an interface
-for this so called square-free factorization.  So we provide one, too:
+original polynomial and its derivatives.  Any decent system has an
+interface for this so called square-free factorization.  So we provide
+one, too:
 @example
 ex sqrfree(const ex & a, const lst & l = lst());
 @end example
-Here is an example that by the way illustrates how the result may depend
-on the order of differentiation:
+Here is an example that by the way illustrates how the exact form of the
+result may slightly depend on the order of differentiation, calling for
+some care with subsequent processing of the result:
 @example
     ...
     symbol x("x"), y("y");
-    ex BiVarPol = expand(pow(x-2*y*x,3) * pow(x+y,2) * (x-y));
+    ex BiVarPol = expand(pow(2-2*y,3) * pow(1+x*y,2) * pow(x-2*y,2) * (x+y));
 
     cout << sqrfree(BiVarPol, lst(x,y)) << endl;
-     // -> (y+x)^2*(-1+6*y+8*y^3-12*y^2)*(y-x)*x^3
+     // -> 8*(1-y)^3*(y*x^2-2*y+x*(1-2*y^2))^2*(y+x)
 
     cout << sqrfree(BiVarPol, lst(y,x)) << endl;
-     // -> (1-2*y)^3*(y+x)^2*(-y+x)*x^3
+     // -> 8*(1-y)^3*(-y*x^2+2*y+x*(-1+2*y^2))^2*(y+x)
 
     cout << sqrfree(BiVarPol) << endl;
      // -> depending on luck, any of the above
     ...
 @end example
+Note also, how factors with the same exponents are not fully factorized
+with this method.
 
 
 @node Rational Expressions, Symbolic Differentiation, Polynomial Arithmetic, Methods and Functions