Add SEEALSO blocks and inexact ring error tests.

diff --git a/mjo/cone/cone.py b/mjo/cone/cone.py
index 865a0700eac91a6af5550477eed6ebe2500cd304..aeec0c90b5f582c8ba858d4b616fff191fb6d529 100644 (file)
--- a/mjo/cone/cone.py
+++ b/mjo/cone/cone.py
@@ -35,6 +35,12 @@ def is_positive_on(L,K):
     - ``False`` will also be returned if we can't decide; specifically
       if we arrive at a symbolic inequality that cannot be resolved.
 
+    .. SEEALSO::
+
+          :func:`is_cross_positive_on`,
+          :func:`is_Z_operator_on`,
+          :func:`is_lyapunov_like_on`
+
     EXAMPLES:
 
     Nonnegative matrices are positive operators on the nonnegative
@@ -77,14 +83,24 @@ def is_positive_on(L,K):
     Technically we could test this, but for now only closed convex cones
     are supported as our ``K`` argument::
 
-        sage: L = identity_matrix(3)
         sage: K = [ vector([1,2,3]), vector([5,-1,7]) ]
+        sage: L = identity_matrix(3)
         sage: is_positive_on(L,K)
         Traceback (most recent call last):
         ...
         TypeError: K must be a Cone.
 
+    We can't give reliable answers over inexact rings::
+
+        sage: K = Cone([(1,2,3), (4,5,6)])
+        sage: L = identity_matrix(RR,3)
+        sage: is_positive_on(L,K)
+        Traceback (most recent call last):
+        ...
+        ValueError: The base ring of L is neither SR nor exact.
+
     """
+
     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:
@@ -138,6 +154,12 @@ def is_cross_positive_on(L,K):
     - ``False`` will also be returned if we can't decide; specifically
       if we arrive at a symbolic inequality that cannot be resolved.
 
+    .. SEEALSO::
+
+          :func:`is_positive_on`,
+          :func:`is_Z_operator_on`,
+          :func:`is_lyapunov_like_on`
+
     EXAMPLES:
 
     The identity operator is always cross-positive::
@@ -179,6 +201,15 @@ def is_cross_positive_on(L,K):
         ...
         TypeError: K must be a Cone.
 
+    We can't give reliable answers over inexact rings::
+
+        sage: K = Cone([(1,2,3), (4,5,6)])
+        sage: L = identity_matrix(RR,3)
+        sage: is_cross_positive_on(L,K)
+        Traceback (most recent call last):
+        ...
+        ValueError: The base ring of L is neither SR nor exact.
+
     """
     if not is_Cone(K):
         raise TypeError('K must be a Cone.')
@@ -188,7 +219,7 @@ def is_cross_positive_on(L,K):
     return all([ s*(L*x) >= 0
                  for (x,s) in K.discrete_complementarity_set() ])
 
-def is_Z_on(L,K):
+def is_Z_operator_on(L,K):
     r"""
     Determine whether or not ``L`` is a Z-operator on ``K``.
 
@@ -227,6 +258,12 @@ def is_Z_on(L,K):
     - ``False`` will also be returned if we can't decide; specifically
       if we arrive at a symbolic inequality that cannot be resolved.
 
+    .. SEEALSO::
+
+          :func:`is_positive_on`,
+          :func:`is_cross_positive_on`,
+          :func:`is_lyapunov_like_on`
+
     EXAMPLES:
 
     The identity operator is always a Z-operator::
@@ -234,7 +271,7 @@ def is_Z_on(L,K):
         sage: set_random_seed()
         sage: K = random_cone(max_ambient_dim=8)
         sage: L = identity_matrix(K.lattice_dim())
-        sage: is_Z_on(L,K)
+        sage: is_Z_operator_on(L,K)
         True
 
     The "zero" operator is always a Z-operator::
@@ -242,7 +279,7 @@ def is_Z_on(L,K):
         sage: K = random_cone(max_ambient_dim=8)
         sage: R = K.lattice().vector_space().base_ring()
         sage: L = zero_matrix(R, K.lattice_dim())
-        sage: is_Z_on(L,K)
+        sage: is_Z_operator_on(L,K)
         True
 
     TESTS:
@@ -251,11 +288,11 @@ def is_Z_on(L,K):
     on ``K``::
 
         sage: K = random_cone(max_ambient_dim=5)
-        sage: all([ is_Z_on(L,K)                     # long time
+        sage: all([ is_Z_operator_on(L,K)            # long time
         ....:       for L in K.Z_operators_gens() ]) # long time
         True
-        sage: all([ is_Z_on(L.change_ring(SR),K)     # long time
-        ....:       for L in K.Z_operators_gens() ]) # long time
+        sage: all([ is_Z_operator_on(L.change_ring(SR),K) # long time
+        ....:       for L in K.Z_operators_gens() ])      # long time
         True
 
     Technically we could test this, but for now only closed convex cones
@@ -263,11 +300,21 @@ def is_Z_on(L,K):
 
         sage: L = identity_matrix(3)
         sage: K = [ vector([-4,20,3]), vector([1,-5,2]) ]
-        sage: is_Z_on(L,K)
+        sage: is_Z_operator_on(L,K)
         Traceback (most recent call last):
         ...
         TypeError: K must be a Cone.
 
+
+    We can't give reliable answers over inexact rings::
+
+        sage: K = Cone([(1,2,3), (4,5,6)])
+        sage: L = identity_matrix(RR,3)
+        sage: is_Z_operator_on(L,K)
+        Traceback (most recent call last):
+        ...
+        ValueError: The base ring of L is neither SR nor exact.
+
     """
     return is_cross_positive_on(-L,K)
 
@@ -282,6 +329,9 @@ def is_lyapunov_like_on(L,K):
     set of ``K``. This property need only be checked for generators of
     ``K`` and its dual.
 
+    An operator is Lyapunov-like on ``K`` if and only if both the
+    operator itself and its negation are cross-positive on ``K``.
+
     To reliably check whether or not ``L`` is Lyapunov-like, its base
     ring must be either exact (for example, the rationals) or ``SR``. An
     exact ring is more reliable, but in some cases a matrix whose
@@ -308,6 +358,12 @@ def is_lyapunov_like_on(L,K):
     - ``False`` will also be returned if we can't decide; specifically
       if we arrive at a symbolic inequality that cannot be resolved.
 
+    .. SEEALSO::
+
+          :func:`is_positive_on`,
+          :func:`is_cross_positive_on`,
+          :func:`is_Z_operator_on`
+
     EXAMPLES:
 
     Diagonal matrices are Lyapunov-like operators on the nonnegative
@@ -357,6 +413,15 @@ def is_lyapunov_like_on(L,K):
         ...
         TypeError: K must be a Cone.
 
+    We can't give reliable answers over inexact rings::
+
+        sage: K = Cone([(1,2,3), (4,5,6)])
+        sage: L = identity_matrix(RR,3)
+        sage: is_lyapunov_like_on(L,K)
+        Traceback (most recent call last):
+        ...
+        ValueError: The base ring of L is neither SR nor exact.
+
     """
     if not is_Cone(K):
         raise TypeError('K must be a Cone.')