Clean up some of the is_foo_on doctests.

diff --git a/mjo/cone/cone.py b/mjo/cone/cone.py
index 01ef5f9d5cc56b087344237b9b5c915423ac0921..b564661ae7cffcac86c220d88e4f4f07de5fa650 100644 (file)
--- a/mjo/cone/cone.py
+++ b/mjo/cone/cone.py
@@ -17,7 +17,10 @@ def is_positive_on(L,K):
     OUTPUT:
 
     ``True`` if it can be proven that ``L`` is positive on ``K``,
-    and ``False`` otherwise.
+    and ``False`` otherwise. If ``L`` is over an exact ring (the
+    rationals, for example), then you can trust the answer. Only
+    for symbolic ``L`` might there be difficulty in proving
+    positivity.
 
     .. WARNING::
 
@@ -30,8 +33,8 @@ def is_positive_on(L,K):
 
     EXAMPLES:
 
-    Positive operators on the nonnegative orthant are nonnegative
-    matrices::
+    Nonnegative matrices are positive operators on the nonnegative
+    orthant::
 
         sage: K = Cone([(1,0,0),(0,1,0),(0,0,1)])
         sage: L = random_matrix(QQ,3).apply_map(abs)
@@ -40,17 +43,17 @@ def is_positive_on(L,K):
 
     TESTS:
 
-    The identity is always positive in a nontrivial space::
+    The identity operator is always positive::
 
         sage: set_random_seed()
-        sage: K = random_cone(min_ambient_dim=1, max_ambient_dim=8)
+        sage: K = random_cone(max_ambient_dim=8)
         sage: L = identity_matrix(K.lattice_dim())
         sage: is_positive_on(L,K)
         True
 
-    As is the "zero" transformation::
+    The "zero" operator is always positive::
 
-        sage: K = random_cone(min_ambient_dim=1, max_ambient_dim=8)
+        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_positive_on(L,K)
@@ -59,12 +62,12 @@ def is_positive_on(L,K):
     Everything in ``K.positive_operators_gens()`` should be
     positive on ``K``::
 
-        sage: K = random_cone(min_ambient_dim=1, max_ambient_dim=6)
-        sage: all([ is_positive_on(L,K)
-        ....:       for L in K.positive_operators_gens() ])
+        sage: K = random_cone(max_ambient_dim=5)
+        sage: all([ is_positive_on(L,K)                     # long time
+        ....:       for L in K.positive_operators_gens() ]) # long time
         True
-        sage: all([ is_positive_on(L.change_ring(SR),K)
-        ....:       for L in K.positive_operators_gens() ])
+        sage: all([ is_positive_on(L.change_ring(SR),K)     # long time
+        ....:       for L in K.positive_operators_gens() ]) # long time
         True
 
     """
@@ -114,17 +117,17 @@ def is_cross_positive_on(L,K):
 
     EXAMPLES:
 
-    The identity is always cross-positive in a nontrivial space::
+    The identity operator is always cross-positive::
 
         sage: set_random_seed()
-        sage: K = random_cone(min_ambient_dim=1, max_ambient_dim=8)
+        sage: K = random_cone(max_ambient_dim=8)
         sage: L = identity_matrix(K.lattice_dim())
         sage: is_cross_positive_on(L,K)
         True
 
-    As is the "zero" transformation::
+    The "zero" operator is always cross-positive::
 
-        sage: K = random_cone(min_ambient_dim=1, max_ambient_dim=8)
+        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_cross_positive_on(L,K)
@@ -135,12 +138,12 @@ def is_cross_positive_on(L,K):
     Everything in ``K.cross_positive_operators_gens()`` should be
     cross-positive on ``K``::
 
-        sage: K = random_cone(min_ambient_dim=1, max_ambient_dim=6)
-        sage: all([ is_cross_positive_on(L,K)
-        ....:       for L in K.cross_positive_operators_gens() ])
+        sage: K = random_cone(max_ambient_dim=5)
+        sage: all([ is_cross_positive_on(L,K)                     # long time
+        ....:       for L in K.cross_positive_operators_gens() ]) # long time
         True
-        sage: all([ is_cross_positive_on(L.change_ring(SR),K)
-        ....:       for L in K.cross_positive_operators_gens() ])
+        sage: all([ is_cross_positive_on(L.change_ring(SR),K)     # long time
+        ....:       for L in K.cross_positive_operators_gens() ]) # long time
         True
 
     """
@@ -189,17 +192,17 @@ def is_Z_on(L,K):
 
     EXAMPLES:
 
-    The identity is always a Z-operator in a nontrivial space::
+    The identity operator is always a Z-operator::
 
         sage: set_random_seed()
-        sage: K = random_cone(min_ambient_dim=1, max_ambient_dim=8)
+        sage: K = random_cone(max_ambient_dim=8)
         sage: L = identity_matrix(K.lattice_dim())
         sage: is_Z_on(L,K)
         True
 
-    As is the "zero" transformation::
+    The "zero" operator is always a Z-operator::
 
-        sage: K = random_cone(min_ambient_dim=1, max_ambient_dim=8)
+        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)
@@ -210,12 +213,12 @@ def is_Z_on(L,K):
     Everything in ``K.Z_operators_gens()`` should be a Z-operator
     on ``K``::
 
-        sage: K = random_cone(min_ambient_dim=1, max_ambient_dim=6)
-        sage: all([ is_Z_on(L,K)
-        ....:       for L in K.Z_operators_gens() ])
+        sage: K = random_cone(max_ambient_dim=5)
+        sage: all([ is_Z_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)
-        ....:       for L in K.Z_operators_gens() ])
+        sage: all([ is_Z_on(L.change_ring(SR),K)     # long time
+        ....:       for L in K.Z_operators_gens() ]) # long time
         True
 
     """
@@ -254,8 +257,8 @@ def is_lyapunov_like_on(L,K):
 
     EXAMPLES:
 
-    Lyapunov-like operators on the nonnegative orthant are diagonal
-    matrices::
+    Diagonal matrices are Lyapunov-like operators on the nonnegative
+    orthant::
 
         sage: K = Cone([(1,0,0),(0,1,0),(0,0,1)])
         sage: L = diagonal_matrix(random_vector(QQ,3))
@@ -264,17 +267,17 @@ def is_lyapunov_like_on(L,K):
 
     TESTS:
 
-    The identity is always Lyapunov-like in a nontrivial space::
+    The identity operator is always Lyapunov-like::
 
         sage: set_random_seed()
-        sage: K = random_cone(min_ambient_dim=1, max_ambient_dim=8)
+        sage: K = random_cone(max_ambient_dim=8)
         sage: L = identity_matrix(K.lattice_dim())
         sage: is_lyapunov_like_on(L,K)
         True
 
-    As is the "zero" transformation::
+    The "zero" operator is always Lyapunov-like::
 
-        sage: K = random_cone(min_ambient_dim=1, max_ambient_dim=8)
+        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_lyapunov_like_on(L,K)
@@ -283,18 +286,16 @@ def is_lyapunov_like_on(L,K):
     Everything in ``K.lyapunov_like_basis()`` should be Lyapunov-like
     on ``K``::
 
-        sage: K = random_cone(min_ambient_dim=1, max_ambient_dim=6)
-        sage: all([ is_lyapunov_like_on(L,K)
-        ....:       for L in K.lyapunov_like_basis() ])
+        sage: K = random_cone(max_ambient_dim=5)
+        sage: all([ is_lyapunov_like_on(L,K)            # long time
+        ....:       for L in K.lyapunov_like_basis() ]) # long time
         True
-        sage: all([ is_lyapunov_like_on(L.change_ring(SR),K)
-        ....:       for L in K.lyapunov_like_basis() ])
+        sage: all([ is_lyapunov_like_on(L.change_ring(SR),K) # long time
+        ....:       for L in K.lyapunov_like_basis() ])      # long time
         True
 
     """
     if L.base_ring().is_exact() or L.base_ring() is SR:
-        # The "fast method" of creating a vector space based on a
-        # ``lyapunov_like_basis`` is actually slower than this.
         return all([ s*(L*x) == 0
                      for (x,s) in K.discrete_complementarity_set() ])
     else: