Fix SymmetricPSD documentation and add the column-major vec() function.

[dunshire.git] / src / dunshire / cones.py

diff --git a/src/dunshire/cones.py b/src/dunshire/cones.py
index 4176f573bb68b462c2cff38cf133970e5159a20e..2609b16eea729651c7d005c226d5f47ab4cd616c 100644 (file)
--- a/src/dunshire/cones.py
+++ b/src/dunshire/cones.py
@@ -316,13 +316,24 @@ class IceCream(SymmetricCone):
 
 class SymmetricPSD(SymmetricCone):
     """
-    The nonnegative orthant in ``n`` dimensions.
+    The cone of real symmetric positive-semidefinite matrices.
+
+    This cone has a dimension ``n`` associated with it, but we let ``n``
+    refer to the dimension of the domain of our matrices and not the
+    dimension of the (much larger) space in which the matrices
+    themselves live. In other words, our ``n`` is the ``n`` that appears
+    in the usual notation `S^{n}` for symmetric matrices.
+
+    As a result, the cone ``SymmetricPSD(n)`` lives in a space of dimension
+    ``(n**2 + n)/2)``.
 
     EXAMPLES:
 
         >>> K = SymmetricPSD(3)
         >>> print(K)
         Cone of symmetric positive-semidefinite matrices on the real 3-space
+        >>> K.dimension()
+        3
 
     """
     def __str__(self):
@@ -342,16 +353,37 @@ class SymmetricPSD(SymmetricCone):
 
         An instance of the ``cvxopt.base.matrix`` class having
         dimensions ``(n,n)`` where ``n`` is the dimension of this cone.
-        Its type code must be 'd'.
 
         EXAMPLES:
 
             >>> K = SymmetricPSD(2)
-            >>> matrix([[1,0],[0,1]], tc='d') in K
+            >>> matrix([[1,0],[0,1]]) in K
             True
 
             >>> K = SymmetricPSD(2)
-            >>> matrix([[0,0],[0,0]], tc='d') in K
+            >>> matrix([[0,0],[0,0]]) in K
+            True
+
+            >>> K = SymmetricPSD(3)
+            >>> matrix([[2,-1,0],[-1,2,-1],[0,-1,2]]) in K
+            True
+
+            >>> K = SymmetricPSD(5)
+            >>> A = matrix([[5,4,3,2,1],
+            ...            [4,5,4,3,2],
+            ...            [3,4,5,4,3],
+            ...            [2,3,4,5,4],
+            ...            [1,2,3,4,5]])
+            >>> A in K
+            True
+
+            >>> K = SymmetricPSD(5)
+            >>> A = matrix([[1,0,0,0,0],
+            ...            [0,1,0,0,0],
+            ...            [0,0,0,0,0],
+            ...            [0,0,0,1,0],
+            ...            [0,0,0,0,1]])
+            >>> A in K
             True
 
             >>> K = SymmetricPSD(2)
@@ -361,7 +393,7 @@ class SymmetricPSD(SymmetricCone):
             TypeError: the given point is not a cvxopt.base.matrix
 
             >>> K = SymmetricPSD(3)
-            >>> matrix([[1,2],[3,4]], tc='d') in K
+            >>> matrix([[1,2],[3,4]]) in K
             Traceback (most recent call last):
             ...
             TypeError: the given point has the wrong dimensions
@@ -371,6 +403,8 @@ class SymmetricPSD(SymmetricCone):
             raise TypeError('the given point is not a cvxopt.base.matrix')
         if not point.size == (self.dimension(), self.dimension()):
             raise TypeError('the given point has the wrong dimensions')
+        if not point.typecode == 'd':
+            point = matrix(point, (self.dimension(), self.dimension()), 'd')
         return all([e >= 0 for e in eigenvalues(point)])
 
 
@@ -388,11 +422,33 @@ class SymmetricPSD(SymmetricCone):
         EXAMPLES:
 
             >>> K = SymmetricPSD(2)
-            >>> K.contains_strict(matrix([[1,0],[0,1]], tc='d'))
+            >>> K.contains_strict(matrix([[1,0],[0,1]]))
             True
 
             >>> K = SymmetricPSD(2)
-            >>> K.contains_strict(matrix([[0,0],[0,0]], tc='d'))
+            >>> K.contains_strict(matrix([[0,0],[0,0]]))
+            False
+
+            >>> K = SymmetricPSD(3)
+            >>> matrix([[2,-1,0],[-1,2,-1],[0,-1,2]]) in K
+            True
+
+            >>> K = SymmetricPSD(5)
+            >>> A = matrix([[5,4,3,2,1],
+            ...            [4,5,4,3,2],
+            ...            [3,4,5,4,3],
+            ...            [2,3,4,5,4],
+            ...            [1,2,3,4,5]])
+            >>> A in K
+            True
+
+            >>> K = SymmetricPSD(5)
+            >>> A = matrix([[1,0,0,0,0],
+            ...            [0,1,0,0,0],
+            ...            [0,0,0,0,0],
+            ...            [0,0,0,1,0],
+            ...            [0,0,0,0,1]])
+            >>> K.contains_strict(A)
             False
 
             >>> K = SymmetricPSD(2)
@@ -402,7 +458,7 @@ class SymmetricPSD(SymmetricCone):
             TypeError: the given point is not a cvxopt.base.matrix
 
             >>> K = SymmetricPSD(3)
-            >>> K.contains_strict(matrix([[1,2],[3,4]], tc='d'))
+            >>> K.contains_strict(matrix([[1,2],[3,4]]))
             Traceback (most recent call last):
             ...
             TypeError: the given point has the wrong dimensions
@@ -412,6 +468,8 @@ class SymmetricPSD(SymmetricCone):
             raise TypeError('the given point is not a cvxopt.base.matrix')
         if not point.size == (self.dimension(), self.dimension()):
             raise TypeError('the given point has the wrong dimensions')
+        if not point.typecode == 'd':
+            point = matrix(point, (self.dimension(), self.dimension()), 'd')
         return all([e > 0 for e in eigenvalues(point)])