Revert "Remove unused codim() function."

[sage.d.git] / mjo / cone / cone.py

diff --git a/mjo/cone/cone.py b/mjo/cone/cone.py
index b9e930e6819643710b82c06faa0b72b934298d96..ba5f51ea880ccdc2cc3344cb8b91022ff3e5b8cf 100644 (file)
--- a/mjo/cone/cone.py
+++ b/mjo/cone/cone.py
@@ -313,6 +313,100 @@ def lineality(K):
     return K.linear_subspace().dimension()
 
 
+def codim(K):
+    r"""
+    Compute the codimension of this cone.
+
+    The codimension of a cone is the dimension of the space of all
+    elements perpendicular to every element of the cone. In other words,
+    the codimension is the difference between the dimension of the
+    ambient space and the dimension of the cone itself.
+
+    OUTPUT:
+
+    A nonnegative integer representing the dimension of the space of all
+    elements perpendicular to this cone.
+
+    .. seealso::
+
+        :meth:`dim`, :meth:`lattice_dim`
+
+    EXAMPLES:
+
+    The codimension of the nonnegative orthant is zero, since the span of
+    its generators equals the entire ambient space::
+
+        sage: K = Cone([(1,0,0), (0,1,0), (0,0,1)])
+        sage: codim(K)
+        0
+
+    However, if we remove a ray so that the entire cone is contained
+    within the `x-y`-plane, then the resulting cone will have
+    codimension one, because the `z`-axis is perpendicular to every
+    element of the cone::
+
+        sage: K = Cone([(1,0,0), (0,1,0)])
+        sage: codim(K)
+        1
+
+    If our cone is all of `\mathbb{R}^{2}`, then its codimension is zero::
+
+        sage: K = Cone([(1,0), (-1,0), (0,1), (0,-1)])
+        sage: codim(K)
+        0
+
+    And if the cone is trivial in any space, then its codimension is
+    equal to the dimension of the ambient space::
+
+        sage: K = Cone([], lattice=ToricLattice(0))
+        sage: K.lattice_dim()
+        0
+        sage: codim(K)
+        0
+
+        sage: K = Cone([(0,)])
+        sage: K.lattice_dim()
+        1
+        sage: codim(K)
+        1
+
+        sage: K = Cone([(0,0)])
+        sage: K.lattice_dim()
+        2
+        sage: codim(K)
+        2
+
+    TESTS:
+
+    The codimension of a cone should be an integer between zero and
+    the dimension of the ambient space, inclusive::
+
+        sage: set_random_seed()
+        sage: K = random_cone(max_dim = 8)
+        sage: c = codim(K)
+        sage: c in ZZ
+        True
+        sage: (0 <= c) and (c <= K.lattice_dim())
+        True
+
+    A solid cone should have codimension zero::
+
+        sage: set_random_seed()
+        sage: K = random_cone(max_dim = 8, solid = True)
+        sage: codim(K)
+        0
+
+    The codimension of a cone is equal to the lineality of its dual::
+
+        sage: set_random_seed()
+        sage: K = random_cone(max_dim = 8, solid = True)
+        sage: codim(K) == lineality(K.dual())
+        True
+
+    """
+    return (K.lattice_dim() - K.dim())
+
+
 def discrete_complementarity_set(K):
     r"""
     Compute the discrete complementarity set of this cone.