Add polynomial ring examples for is_positive_on.

diff --git a/mjo/cone/cone.py b/mjo/cone/cone.py
index 0158757ee3c1865f4d90f265e0a68e67d03557cf..4221566a52c1210fa1045b9df9305f04a45924a6 100644 (file)
--- a/mjo/cone/cone.py
+++ b/mjo/cone/cone.py
@@ -51,6 +51,34 @@ def is_positive_on(L,K):
         sage: is_positive_on(L,K)
         True
 
+    Your matrix can be over any exact ring, but you may get unexpected
+    answers with weirder rings. For example, any rational matrix is
+    positive on the plane, but if your matrix contains polynomial
+    variables, the answer will be negative::
+
+        sage: K = Cone([(1,0),(-1,0),(0,1),(0,-1)])
+        sage: K.is_full_space()
+        True
+        sage: L = matrix(QQ[x], [[x,0],[0,1]])
+        sage: is_positive_on(L,K)
+        False
+
+    The previous example is "unexpected" because it depends on how we
+    check whether or not ``L`` is positive. For exact base rings, we
+    check whether or not ``L*z`` belongs to ``K`` for each ``z in K``.
+    If ``K`` is closed, then an equally-valid test would be to check
+    whether the inner product of ``L*z`` and ``s`` is nonnegative for
+    every ``z`` in ``K`` and ``s`` in ``K.dual()``. In fact, that is
+    what we do over inexact rings. In the previous example, that test
+    would return an affirmative answer::
+
+        sage: K = Cone([(1,0),(-1,0),(0,1),(0,-1)])
+        sage: L = matrix(QQ[x], [[x,0],[0,1]])
+        sage: all([ (L*z).inner_product(s) for z in K for s in K.dual() ])
+        True
+        sage: is_positive_on(L.change_ring(SR), K)
+        True
+
     TESTS:
 
     The identity operator is always positive::