Trac #19035: Improve assumption documentation and doctest recent impr…

…ovements

With pynac-0.5 this will no longer give wrong results:
{{{
sage: assume(x,'integer')
sage: x.is_integer()
False

sage: assume(x>0)
sage: x.is_positive()
False

sage: f=function('f')(x)
sage: assume(f>0)
sage: f.is_positive()
False
}}}

URL: http://trac.sagemath.org/19035
Reported by: rws
Ticket author(s): Ralf Stephan
Reviewer(s): Vincent Delecroix

src/sage/symbolic/assumptions.py

@@ -1,5 +1,56 @@
 """
 Assumptions
+
+The ``GenericDeclaration`` class provides assumptions about a symbol or
+function in verbal form. Such assumptions can be made using the :func:`assume`
+function in this module, which also can take any relation of symbolic
+expressions as argument. Use :func:`forget` to clear all assumptions.
+Creating a variable with a specific domain is equivalent with making an
+assumption about it.
+
+There is only rudimentary support for consistency and satisfiability checking
+in Sage. Assumptions are used both in Maxima and Pynac to support or refine
+some computations. In the following we show how to make and query assumptions.
+Please see the respective modules for more practical examples.
+
+EXAMPLES:
+
+The default domain of a symbolic variable is the complex plane::
+
+    sage: var('x')
+    x
+    sage: x.is_real()
+    False
+    sage: assume(x,'real')
+    sage: x.is_real()
+    True
+    sage: forget()
+    sage: x.is_real()
+    False
+
+Here is the list of acceptable features::
+
+    sage: maxima('features')
+    [integer,noninteger,even,odd,rational,irrational,real,imaginary,complex,analytic,increasing,decreasing,oddfun,evenfun,posfun,constant,commutative,lassociative,rassociative,symmetric,antisymmetric,integervalued]
+
+Set positive domain using a relation::
+
+    sage: assume(x>0)
+    sage: x.is_positive()
+    True
+    sage: x.is_real()
+    True
+    sage: assumptions()
+    [x > 0]
+
+Assumptions are added and in some cases checked for consistency::
+
+    sage: assume(x>0)
+    sage: assume(x<0)
+    Traceback (most recent call last):
+    ...
+    ValueError: Assumption is inconsistent
+    sage: forget()
 """
 from sage.structure.sage_object import SageObject
 from sage.rings.all import ZZ, QQ, RR, CC
@@ -11,8 +62,8 @@ class GenericDeclaration(SageObject):
     """
     This class represents generic assumptions, such as a variable being
     an integer or a function being increasing. It passes such
-    information to maxima's declare (wrapped in a context so it is able
-    to forget).
+    information to Maxima's declare (wrapped in a context so it is able
+    to forget) and to Pynac.
 
     INPUT:
 

src/sage/symbolic/expression.pyx

@@ -1907,6 +1907,14 @@ cdef class Expression(CommutativeRingElement):
 
             sage: (x*x.conjugate()).is_real()
             False
+
+        Assumption of real has the same effect as setting the domain::
+
+            sage: forget()
+            sage: assume(x, 'real')
+            sage: x.is_real()
+            True
+            sage: forget()
         """
         return self._gobj.info(info_real)
 
@@ -1930,6 +1938,18 @@ cdef class Expression(CommutativeRingElement):
             True
             sage: (t0*x).is_positive()
             False
+
+        ::
+
+            sage: forget()
+            sage: assume(x>0)
+            sage: x.is_positive()
+            True
+            sage: f = function('f')(x)
+            sage: assume(f>0)
+            sage: f.is_positive()
+            True
+            sage: forget()
         """
         return self._gobj.info(info_positive)
 
@@ -1970,6 +1990,14 @@ cdef class Expression(CommutativeRingElement):
             sage: _ = var('n', domain='integer')
             sage: n.is_integer()
             True
+
+        Assumption of integer has the same effect as setting the domain::
+
+            sage: forget()
+            sage: assume(x, 'integer')
+            sage: x.is_integer()
+            True
+            sage: forget()
         """
         return self._gobj.info(info_integer)