From: Michael Orlitzky <michael@orlitzky.com>
Date: Fri, 30 Nov 2018 16:01:29 +0000 (-0500)
Subject: mjo/cone: improve docstrings the the rearrangement and schur cones.
X-Git-Url: https://gitweb.michael.orlitzky.com/?a=commitdiff_plain;h=9e7945f39b71d26df4e8d50332a7d8606447c822;p=sage.d.git

mjo/cone: improve docstrings the the rearrangement and schur cones.
---

diff --git a/mjo/cone/rearrangement.py b/mjo/cone/rearrangement.py
index 3e09c8a..fa232bc 100644
--- a/mjo/cone/rearrangement.py
+++ b/mjo/cone/rearrangement.py
@@ -36,20 +36,26 @@ def rearrangement_cone(p,n,lattice=None):
     that lattice unless its rank is incompatible with the dimension
     ``n`` (in which case a ``ValueError`` is raised).
 
-    REFERENCES:
+    ALGORITHM:
 
-    .. [HenrionSeeger] Rene Henrion and Alberto Seeger.
-       Inradius and Circumradius of Various Convex Cones Arising in
-       Applications. Set-Valued and Variational Analysis, 18(3-4),
-       483-511, 2010. doi:10.1007/s11228-010-0150-z
+    The generators for the rearrangement cone are given by [Jeong]_
+    Theorem 5.2.3.
+
+    REFERENCES:
 
     .. [GowdaJeong] Muddappa Seetharama Gowda and Juyoung Jeong.
        Spectral cones in Euclidean Jordan algebras.
        Linear Algebra and its Applications, 509, 286-305.
        doi:10.1016/j.laa.2016.08.004
 
+    .. [HenrionSeeger] Rene Henrion and Alberto Seeger.
+       Inradius and Circumradius of Various Convex Cones Arising in
+       Applications. Set-Valued and Variational Analysis, 18(3-4),
+       483-511, 2010. doi:10.1007/s11228-010-0150-z
+
     .. [Jeong] Juyoung Jeong.
        Spectral sets and functions on Euclidean Jordan algebras.
+       University of Maryland, Baltimore County, Ph.D. thesis, 2017.
 
     SETUP::
 
@@ -73,7 +79,8 @@ def rearrangement_cone(p,n,lattice=None):
         sage: rearrangement_cone(5,5).lineality()
         4
 
-    All rearrangement cones are proper::
+    All rearrangement cones are proper when ``p`` is less than ``n`` by
+    [Jeong]_ Proposition 5.2.1::
 
         sage: all( rearrangement_cone(p,n).is_proper()
         ....:              for n in xrange(10)
@@ -81,7 +88,8 @@ def rearrangement_cone(p,n,lattice=None):
         True
 
     The Lyapunov rank of the rearrangement cone of order ``p`` in ``n``
-    dimensions is ``n`` for ``p == 1`` or ``p == n`` and one otherwise::
+    dimensions is ``n`` for ``p == 1`` or ``p == n`` and one otherwise,
+    by [Jeong]_ Corollary 5.2.4::
 
         sage: all( rearrangement_cone(p,n).lyapunov_rank() == n
         ....:              for n in xrange(2, 10)
@@ -94,7 +102,8 @@ def rearrangement_cone(p,n,lattice=None):
 
     TESTS:
 
-    The rearrangement cone is permutation-invariant::
+    All rearrangement cones are permutation-invariant by [Jeong]_
+    Proposition 5.2.1::
 
         sage: n = ZZ.random_element(2,10).abs()
         sage: p = ZZ.random_element(1,n)
@@ -119,8 +128,8 @@ def rearrangement_cone(p,n,lattice=None):
         ....: )
         True
 
-    The rearrangenent cone of order ``p`` is contained in the
-    rearrangement cone of order ``p + 1``::
+    The rearrangenent cone of order ``p`` is contained in the rearrangement
+    cone of order ``p + 1`` by [Jeong]_ Proposition 5.2.1::
 
         sage: set_random_seed()
         sage: n = ZZ.random_element(2,10)
@@ -130,6 +139,19 @@ def rearrangement_cone(p,n,lattice=None):
         sage: all( x in K2 for x in K1 )
         True
 
+    The rearrangement cone of order ``p`` is linearly isomorphic to the
+    rearrangement cone of order ``n - p`` when ``p`` is less than ``n``,
+    by [Jeong]_ Proposition 5.2.1::
+
+        sage: set_random_seed()
+        sage: n = ZZ.random_element(2,10)
+        sage: p = ZZ.random_element(1,n)
+        sage: K1 = rearrangement_cone(p,n)
+        sage: K2 = rearrangement_cone(n-p, n)
+        sage: Mp = (1/p)*matrix.ones(QQ,n) - identity_matrix(QQ,n)
+        sage: Cone( (Mp*K2.rays()).columns() ).is_equivalent(K1)
+        True
+
     The order ``p`` should be between ``1`` and ``n``, inclusive::
 
         sage: rearrangement_cone(0,3)
diff --git a/mjo/cone/schur.py b/mjo/cone/schur.py
index 88b7d82..d9371fb 100644
--- a/mjo/cone/schur.py
+++ b/mjo/cone/schur.py
@@ -7,7 +7,8 @@ from sage.all import *
 
 def schur_cone(n, lattice=None):
     r"""
-    Return the Schur cone in ``n`` dimensions.
+    Return the Schur cone in ``n`` dimensions that induces the
+    majorization ordering.
 
     INPUT: