mjo/cone/decomposition.py: rearrangement examples for is_reducible()

diff --git a/mjo/cone/decomposition.py b/mjo/cone/decomposition.py
index ca18b4d89d5bb5bcd4dc230a42b4a18b21fb2487..8520d119c69894d4b646bc2eb19e83b9adff5952 100644 (file)
--- a/mjo/cone/decomposition.py
+++ b/mjo/cone/decomposition.py
@@ -222,6 +222,14 @@ def is_reducible(K):
     A pointed convex cone ``K`` is reducible if some other cone
     appears in its :func:`irreducible_factors`.
 
+   REFERENCES:
+
+    .. [GowdaJeong2018] Juyoung Jeong and M. Seetharama Gowda.
+                  *Permutation invariant proper polyhedral
+                  cones and their Lyapunov rank*.
+                  Journal of Mathematical Analysis and Applications
+                  463(1):377-385, 2018. :doi:`10.1016/j.jmaa.2018.03.024`.
+
     SETUP::
 
         sage: from mjo.cone.decomposition import is_reducible
@@ -238,5 +246,19 @@ def is_reducible(K):
         sage: is_reducible(cones.nonnegative_orthant(3))
         True
 
+    Theorem 4.1 in [GowdaJeong2018]_ says that the Lyapunov rank of a
+    permutation-invariant cone is either ``n`` or ``1``, depending on
+    whether or not it is reducible. Corollary 5.2.4 of [Jeong2017]_
+    then implies that the ``(p,n)`` rearrangement cone is reducible if
+    and only if ``p`` is either ``1`` or ``n-1``. We exclude the
+    possibility of ``p == n`` since that returns a (not pointed)
+    half-space::
+
+        sage: n = ZZ.random_element(10) + 2
+        sage: p = ZZ.random_element(1, n)
+        sage: K = cones.rearrangement(p, n)
+        sage: is_reducible(K) == (p in [1, n-1])
+        True
+
     """
     return len(irreducible_factors(K)) > 1