From 9e7945f39b71d26df4e8d50332a7d8606447c822 Mon Sep 17 00:00:00 2001 From: Michael Orlitzky Date: Fri, 30 Nov 2018 11:01:29 -0500 Subject: [PATCH] mjo/cone: improve docstrings the the rearrangement and schur cones. --- mjo/cone/rearrangement.py | 42 +++++++++++++++++++++++++++++---------- mjo/cone/schur.py | 3 ++- 2 files changed, 34 insertions(+), 11 deletions(-) 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: -- 2.43.2