Cleanup on _restrict_to_space() tests and documentation.

diff --git a/mjo/cone/cone.py b/mjo/cone/cone.py
index 5f058ca9a8c055f972ffffaa216975517e0dc723..6d7d2d9b4d2b379bc6041fe089e5a6ea38b8e48a 100644 (file)
--- a/mjo/cone/cone.py
+++ b/mjo/cone/cone.py
@@ -10,7 +10,22 @@ from sage.all import *
 
 def _restrict_to_space(K, W):
     r"""
-    Restrict this cone a subspace of its ambient space.
+    Restrict this cone (up to linear isomorphism) to a vector subspace.
+
+    This operation not only restricts the cone to a subspace of its
+    ambient space, but also represents the rays of the cone in a new
+    (smaller) lattice corresponding to the subspace. The resulting cone
+    will be linearly isomorphic **but not equal** to the desired
+    restriction, since it has likely undergone a change of basis.
+
+    To explain the difficulty, consider the cone ``K = Cone([(1,1,1)])``
+    having a single ray. The span of ``K`` is a one-dimensional subspace
+    containing ``K``, yet we have no way to perform operations like
+    :meth:`dual` in the subspace. To represent ``K`` in the space
+    ``K.span()``, we must perform a change of basis and write its sole
+    ray as ``(1,0,0)``. Now the restricted ``Cone([(1,)])`` is linearly
+    isomorphic (but of course not equal) to ``K`` interpreted as living
+    in ``K.span()``.
 
     INPUT:
 
@@ -20,16 +35,26 @@ def _restrict_to_space(K, W):
 
     A new cone in a sublattice corresponding to ``W``.
 
+    REFERENCES:
+
+    M. Orlitzky. The Lyapunov rank of an improper cone.
+    http://www.optimization-online.org/DB_HTML/2015/10/5135.html
+
     EXAMPLES:
 
-    When this cone is solid, restricting it into its own span should do
-    nothing::
+    Restricting a solid cone to its own span returns a cone linearly
+    isomorphic to the original::
 
-        sage: K = Cone([(1,)])
-        sage: _restrict_to_space(K, K.span()) == K
+        sage: K = Cone([(1,2,3),(-1,1,0),(9,0,-2)])
+        sage: K.is_solid()
         True
+        sage: _restrict_to_space(K, K.span()).rays()
+        N(-1,  1,  0),
+        N( 1,  0,  0),
+        N( 9, -6, -1)
+        in 3-d lattice N
 
-    A single ray restricted into its own span gives the same output
+    A single ray restricted to its own span has the same representation
     regardless of the ambient space::
 
         sage: K2 = Cone([(1,0)])
@@ -37,7 +62,7 @@ def _restrict_to_space(K, W):
         sage: K2_S
         N(1)
         in 1-d lattice N
-        sage: K3 = Cone([(1,0,0)])
+        sage: K3 = Cone([(1,1,1)])
         sage: K3_S = _restrict_to_space(K3, K3.span()).rays()
         sage: K3_S
         N(1)
@@ -45,83 +70,116 @@ def _restrict_to_space(K, W):
         sage: K2_S == K3_S
         True
 
+    Restricting to a trivial space gives the trivial cone::
+
+        sage: K = Cone([(8,3,-1,0),(9,2,2,0),(-4,6,7,0)])
+        sage: trivial_space = K.lattice().vector_space().span([])
+        sage: _restrict_to_space(K, trivial_space)
+        0-d cone in 0-d lattice N
+
     TESTS:
 
-    The projected cone should always be solid::
+    Restricting a cone to its own span results in a solid cone::
 
         sage: set_random_seed()
         sage: K = random_cone(max_ambient_dim = 8)
-        sage: _restrict_to_space(K, K.span()).is_solid()
+        sage: K_S = _restrict_to_space(K, K.span())
+        sage: K_S.is_solid()
         True
 
-    And the resulting cone should live in a space having the same
-    dimension as the space we restricted it to::
+    Restricting a cone to its own span should not affect the number of
+    rays in the cone::
 
         sage: set_random_seed()
         sage: K = random_cone(max_ambient_dim = 8)
-        sage: K_P = _restrict_to_space(K, K.dual().span())
-        sage: K_P.lattice_dim() == K.dual().dim()
+        sage: K_S = _restrict_to_space(K, K.span())
+        sage: K.nrays() == K_S.nrays()
         True
 
-    This function should not affect the dimension of a cone::
+    Restricting a cone to its own span should not affect its dimension::
 
         sage: set_random_seed()
         sage: K = random_cone(max_ambient_dim = 8)
-        sage: K.dim() == _restrict_to_space(K,K.span()).dim()
+        sage: K_S = _restrict_to_space(K, K.span())
+        sage: K.dim() == K_S.dim()
         True
 
-    Nor should it affect the lineality of a cone::
+    Restricting a cone to its own span should not affects its lineality::
 
         sage: set_random_seed()
         sage: K = random_cone(max_ambient_dim = 8)
-        sage: K.lineality() == _restrict_to_space(K, K.span()).lineality()
+        sage: K_S = _restrict_to_space(K, K.span())
+        sage: K.lineality() == K_S.lineality()
         True
 
-    No matter which space we restrict to, the lineality should not
-    increase::
+    Restricting a cone to its own span should not affect the number of
+    facets it has::
 
         sage: set_random_seed()
         sage: K = random_cone(max_ambient_dim = 8)
-        sage: S = K.span(); P = K.dual().span()
-        sage: K.lineality() >= _restrict_to_space(K,S).lineality()
+        sage: K_S = _restrict_to_space(K, K.span())
+        sage: len(K.facets()) == len(K_S.facets())
         True
-        sage: K.lineality() >= _restrict_to_space(K,P).lineality()
+
+    Restricting a solid cone to its own span is a linear isomorphism and
+    should not affect the dimension of its ambient space::
+
+        sage: set_random_seed()
+        sage: K = random_cone(max_ambient_dim = 8, solid = True)
+        sage: K_S = _restrict_to_space(K, K.span())
+        sage: K.lattice_dim() == K_S.lattice_dim()
         True
 
-    If we do this according to our paper, then the result is proper::
+    Restricting a solid cone to its own span is a linear isomorphism
+    that establishes a one-to-one correspondence of discrete
+    complementarity sets::
 
         sage: set_random_seed()
-        sage: K = random_cone(max_ambient_dim = 8)
+        sage: K = random_cone(max_ambient_dim = 8, solid = True)
         sage: K_S = _restrict_to_space(K, K.span())
-        sage: K_SP = _restrict_to_space(K_S.dual(), K_S.dual().span()).dual()
-        sage: K_SP.is_proper()
+        sage: dcs_K   = K.discrete_complementarity_set()
+        sage: dcs_K_S = K_S.discrete_complementarity_set()
+        sage: len(dcs_K) == len(dcs_K_S)
         True
-        sage: K_SP = _restrict_to_space(K_S, K_S.dual().span())
-        sage: K_SP.is_proper()
+
+    Restricting a solid cone to its own span is a linear isomorphism
+    under which the Lyapunov rank (the length of a Lyapunov-like basis)
+    is invariant::
+
+        sage: set_random_seed()
+        sage: K = random_cone(max_ambient_dim = 8, solid = True)
+        sage: K_S = _restrict_to_space(K, K.span())
+        sage: len(K.lyapunov_like_basis()) == len(K_S.lyapunov_like_basis())
         True
 
-    Test the proposition in our paper concerning the duals and
-    restrictions. Generate a random cone, then create a subcone of
-    it. The operation of dual-taking should then commute with
-    _restrict_to_space::
+    If we restrict a cone to a subspace of its span, the resulting cone
+    should have the same dimension as the space we restricted it to::
 
         sage: set_random_seed()
-        sage: J = random_cone(max_ambient_dim = 8)
-        sage: K = Cone(random_sublist(J.rays(), 0.5), lattice=J.lattice())
-        sage: K_W_star = _restrict_to_space(K, J.span()).dual()
-        sage: K_star_W = _restrict_to_space(K.dual(), J.span())
-        sage: _basically_the_same(K_W_star, K_star_W)
+        sage: K = random_cone(max_ambient_dim = 8)
+        sage: W_basis = random_sublist(K.rays(), 0.5)
+        sage: W = K.lattice().vector_space().span(W_basis)
+        sage: K_W = _restrict_to_space(K, W)
+        sage: K_W.lattice_dim() == W.dimension()
         True
 
+    Through a series of restrictions, any closed convex cone can be
+    reduced to a cartesian product with a proper factor [Orlitzky]_::
+
+        sage: set_random_seed()
+        sage: K = random_cone(max_ambient_dim = 8)
+        sage: K_S = _restrict_to_space(K, K.span())
+        sage: K_SP = _restrict_to_space(K_S, K_S.dual().span())
+        sage: K_SP.is_proper()
+        True
     """
-    # First we want to intersect ``K`` with ``W``. The easiest way to
-    # do this is via cone intersection, so we turn the subspace ``W``
-    # into a cone.
+    # We want to intersect ``K`` with ``W``. An easy way to do this is
+    # via cone intersection, so we turn the space ``W`` into a cone.
     W_cone = Cone(W.basis() + [-b for b in W.basis()], lattice=K.lattice())
     K = K.intersection(W_cone)
 
-    # We've already intersected K with the span of K2, so every
-    # generator of K should belong to W now.
+    # We've already intersected K with W, so every generator of K
+    # should belong to W now.
     K_W_rays = [ W.coordinate_vector(r) for r in K.rays() ]
 
     L = ToricLattice(W.dimension())