From cbd0e9a0ed9133de08665a55f146d04cb9536ec6 Mon Sep 17 00:00:00 2001
From: Michael Orlitzky <michael@orlitzky.com>
Date: Mon, 27 Jul 2015 10:36:07 -0400
Subject: [PATCH] Update docs for cone.discrete_complementarity_set().

---
 mjo/cone/cone.py | 40 ++++++++++++++++++++++++++++++++++------
 1 file changed, 34 insertions(+), 6 deletions(-)

diff --git a/mjo/cone/cone.py b/mjo/cone/cone.py
index e2c43d8..baff1a7 100644
--- a/mjo/cone/cone.py
+++ b/mjo/cone/cone.py
@@ -282,19 +282,29 @@ def discrete_complementarity_set(K):
     r"""
     Compute the discrete complementarity set of this cone.
 
-    The complementarity set of this cone is the set of all orthogonal
-    pairs `(x,s)` such that `x` is in this cone, and `s` is in its
-    dual. The discrete complementarity set restricts `x` and `s` to be
-    generators of their respective cones.
+    The complementarity set of a cone is the set of all orthogonal pairs
+    `(x,s)` such that `x` is in the cone, and `s` is in its dual. The
+    discrete complementarity set is a subset of the complementarity set
+    where `x` and `s` are required to be generators of their respective
+    cones.
+
+    For polyhedral cones, the discrete complementarity set is always
+    finite.
 
     OUTPUT:
 
     A list of pairs `(x,s)` such that,
 
+      * Both `x` and `s` are vectors (not rays).
       * `x` is a generator of this cone.
       * `s` is a generator of this cone's dual.
       * `x` and `s` are orthogonal.
 
+    REFERENCES:
+
+    .. [Orlitzky/Gowda] M. Orlitzky and M. S. Gowda. The Lyapunov Rank of an
+       Improper Cone. Work in-progress.
+
     EXAMPLES:
 
     The discrete complementarity set of the nonnegative orthant consists
@@ -325,6 +335,13 @@ def discrete_complementarity_set(K):
         sage: discrete_complementarity_set(K)
         []
 
+    Likewise when this cone is trivial (its dual is the entire space)::
+
+        sage: L = ToricLattice(0)
+        sage: K = Cone([], ToricLattice(0))
+        sage: discrete_complementarity_set(K)
+        []
+
     TESTS:
 
     The complementarity set of the dual can be obtained by switching the
@@ -338,12 +355,23 @@ def discrete_complementarity_set(K):
         sage: sorted(actual) == sorted(expected)
         True
 
+    The pairs in the discrete complementarity set are in fact
+    complementary::
+
+        sage: set_random_seed()
+        sage: K = random_cone(max_dim=6)
+        sage: dcs = discrete_complementarity_set(K)
+        sage: sum([x.inner_product(s).abs() for (x,s) in dcs])
+        0
+
     """
     V = K.lattice().vector_space()
 
-    # Convert the rays to vectors so that we can compute inner
-    # products.
+    # Convert rays to vectors so that we can compute inner products.
     xs = [V(x) for x in K.rays()]
+
+    # We also convert the generators of the dual cone so that we
+    # return pairs of vectors and not (vector, ray) pairs.
     ss = [V(s) for s in K.dual().rays()]
 
     return [(x,s) for x in xs for s in ss if x.inner_product(s) == 0]
-- 
2.44.2