Add polynomial ring examples for is_positive_on.

[sage.d.git] / mjo / cone / cone.py

diff --git a/mjo/cone/cone.py b/mjo/cone/cone.py
index aeec0c90b5f582c8ba858d4b616fff191fb6d529..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::
@@ -422,12 +450,28 @@ def is_lyapunov_like_on(L,K):
         ...
         ValueError: The base ring of L is neither SR nor exact.
 
+    An operator is Lyapunov-like on a cone if and only if both the
+    operator and its negation are cross-positive on the cone::
+
+        sage: K = random_cone(max_ambient_dim=5)
+        sage: R = K.lattice().vector_space().base_ring()
+        sage: L = random_matrix(R, K.lattice_dim())
+        sage: actual = is_lyapunov_like_on(L,K)          # long time
+        sage: expected = (is_cross_positive_on(L,K) and  # long time
+        ....:             is_cross_positive_on(-L,K))    # long time
+        sage: actual == expected                         # long time
+        True
+
     """
     if not is_Cone(K):
         raise TypeError('K must be a Cone.')
     if not L.base_ring().is_exact() and not L.base_ring() is SR:
         raise ValueError('The base ring of L is neither SR nor exact.')
 
+    # Even though ``discrete_complementarity_set`` is a cached method
+    # of cones, this is faster than calling ``is_cross_positive_on``
+    # twice: doing so checks twice as many inequalities as the number
+    # of equalities that we're about to check.
     return all([ s*(L*x) == 0
                  for (x,s) in K.discrete_complementarity_set() ])