Add citations for Lyapunov rank examples/tests.

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

diff --git a/mjo/cone/cone.py b/mjo/cone/cone.py
index 777d45e1a3e7a72a5ebbb167fd1ef6540c745282..dbe369a8c2feabaee32bade898106641c3a3c3f0 100644 (file)
--- a/mjo/cone/cone.py
+++ b/mjo/cone/cone.py
@@ -80,6 +80,20 @@ def discrete_complementarity_set(K):
     return [(x,s) for x in xs for s in ss if x.inner_product(s) == 0]
 
 
+def LL(K):
+    r"""
+    Compute the space `\mathbf{LL}` of all Lyapunov-like transformations
+    on this cone.
+
+    OUTPUT:
+
+    A ``MatrixSpace`` object `M` such that every matrix `L \in M` is
+    Lyapunov-like on this cone.
+
+    """
+    pass # implement me lol
+
+
 def lyapunov_rank(K):
     r"""
     Compute the Lyapunov (or bilinearity) rank of this cone.
@@ -123,17 +137,18 @@ def lyapunov_rank(K):
 
     REFERENCES:
 
-    1. M.S. Gowda and J. Tao. On the bilinearity rank of a proper cone
-       and Lyapunov-like transformations, Mathematical Programming, 147
+    .. [Gowda/Tao] M.S. Gowda and J. Tao. On the bilinearity rank of a proper
+       cone and Lyapunov-like transformations, Mathematical Programming, 147
        (2014) 155-170.
 
-    2. G. Rudolf, N. Noyan, D. Papp, and F. Alizadeh, Bilinear
+    .. [Rudolf et al.] G. Rudolf, N. Noyan, D. Papp, and F. Alizadeh, Bilinear
        optimality constraints for the cone of positive polynomials,
        Mathematical Programming, Series B, 129 (2011) 5-31.
 
     EXAMPLES:
 
-    The nonnegative orthant in `\mathbb{R}^{n}` always has rank `n`::
+    The nonnegative orthant in `\mathbb{R}^{n}` always has rank `n`
+    [Rudolf et al.]_::
 
         sage: positives = Cone([(1,)])
         sage: lyapunov_rank(positives)
@@ -141,23 +156,25 @@ def lyapunov_rank(K):
         sage: quadrant = Cone([(1,0), (0,1)])
         sage: lyapunov_rank(quadrant)
         2
-        sage: octant = Cone([(1,0,0), (0,1,0), (0,0,1)])
+       sage: octant = Cone([(1,0,0), (0,1,0), (0,0,1)])
         sage: lyapunov_rank(octant)
         3
 
-    The `L^{3}_{1}` cone is known to have a Lyapunov rank of one::
+    The `L^{3}_{1}` cone is known to have a Lyapunov rank of one
+    [Rudolf et al.]_::
 
         sage: L31 = Cone([(1,0,1), (0,-1,1), (-1,0,1), (0,1,1)])
         sage: lyapunov_rank(L31)
         1
 
-    Likewise for the `L^{3}_{\infty}` cone::
+    Likewise for the `L^{3}_{\infty}` cone [Rudolf et al.]_::
 
         sage: L3infty = Cone([(0,1,1), (1,0,1), (0,-1,1), (-1,0,1)])
         sage: lyapunov_rank(L3infty)
         1
 
-    The Lyapunov rank should be additive on a product of cones::
+    The Lyapunov rank should be additive on a product of cones
+    [Rudolf et al.]_::
 
         sage: L31 = Cone([(1,0,1), (0,-1,1), (-1,0,1), (0,1,1)])
         sage: octant = Cone([(1,0,0), (0,1,0), (0,0,1)])
@@ -165,8 +182,8 @@ def lyapunov_rank(K):
         sage: lyapunov_rank(K) == lyapunov_rank(L31) + lyapunov_rank(octant)
         True
 
-    Two isomorphic cones should have the same Lyapunov rank. The cone
-    ``K`` in the following example is isomorphic to the nonnegative
+    Two isomorphic cones should have the same Lyapunov rank [Rudolf et al.]_.
+    The cone ``K`` in the following example is isomorphic to the nonnegative
     octant in `\mathbb{R}^{3}`::
 
         sage: K = Cone([(1,2,3), (-1,1,0), (1,0,6)])
@@ -174,7 +191,7 @@ def lyapunov_rank(K):
         3
 
     The dual cone `K^{*}` of ``K`` should have the same Lyapunov rank as ``K``
-    itself::
+    itself [Rudolf et al.]_::
 
         sage: K = Cone([(2,2,4), (-1,9,0), (2,0,6)])
         sage: lyapunov_rank(K) == lyapunov_rank(K.dual())
@@ -182,7 +199,8 @@ def lyapunov_rank(K):
 
     TESTS:
 
-    The Lyapunov rank should be additive on a product of cones::
+    The Lyapunov rank should be additive on a product of cones
+    [Rudolf et al.]_::
 
         sage: K1 = random_cone(max_dim=10, max_rays=10)
         sage: K2 = random_cone(max_dim=10, max_rays=10)
@@ -191,12 +209,25 @@ def lyapunov_rank(K):
         True
 
     The dual cone `K^{*}` of ``K`` should have the same Lyapunov rank as ``K``
-    itself::
+    itself [Rudolf et al.]_::
 
         sage: K = random_cone(max_dim=10, max_rays=10)
         sage: lyapunov_rank(K) == lyapunov_rank(K.dual())
         True
 
+    The Lyapunov rank of a proper polyhedral cone in `n` dimensions can
+    be any number between `1` and `n` inclusive, excluding `n-1`
+    [Gowda/Tao]_ (by accident, this holds for the trivial cone in a
+    trivial space as well)::
+
+        sage: K = random_cone(max_dim=10, strictly_convex=True, solid=True)
+        sage: b = lyapunov_rank(K)
+        sage: n = K.lattice_dim()
+        sage: 1 <= b and b <= n
+        True
+        sage: b == n-1
+        False
+
     """
     V = K.lattice().vector_space()