Renamed vector subspace complement to othrogonal_complement and changed the complement function

src/sage/modules/free_module.py

@@ -4966,27 +4966,75 @@
         """
         return self.submodule_with_basis(gens, check=check, already_echelonized=already_echelonized)
 
-    def complement(self):
+    def complement(self, *, orthogonal=None):
         r"""
-        Return the complement of ``self`` in the
+        Returns a complementary subspace of ``self`` in the
+        :meth:`~sage.modules.free_module.FreeModule_ambient_field.ambient_vector_space`.
+
+        EXAMPLES::
+
+            sage: V = RR^3
+            sage: S = V.subspace([[1,0,0], [0,1,0]])
+            sage: C = S.complement(orthogonal=False)
+            sage: C
+            Vector space of degree 3 and dimension 1 over Real Field with 53
+            bits of precision
+            Basis matrix:
+            [0.000000000000000 0.000000000000000  1.00000000000000]
+            sage: C + S == V
+            True
+            sage: V = VectorSpace(GF(2), 3)
+            sage: S = V.subspace([[1,1,1], [0,0,1]])
+            sage: C = S.complement(orthogonal=False)
+            sage: C
+            Vector space of degree 3 and dimension 1 over Finite Field of size 2
+            Basis matrix:
+            [0 1 0]
+            sage: C + S == V
+            True
+            sage: C.complement(orthogonal=False) == S
+            False
+        """
+        if orthogonal is None:
+            from sage.misc.superseded import deprecation
+            deprecation(31487, "The functionality of the complement() function"
+                               + " of a vector space is being updated. The original"
+                               + " functionality is being moved to the"
+                               + " orthogonal_complement() function. This function"
+                               + " will instead return a complementary subspace")
+            return self.orthogonal_complement()
+        if orthogonal is True:
+            return self.orthogonal_complement()
+        if orthogonal is False:
+            pivotTuple = self.basis_matrix().pivots()
+            ambientBasisSize = self.ambient_vector_space().dimension()
+            nonPivotList = [i for i in range(ambientBasisSize) if i not in
+            pivotTuple]
+            complementBasis = [self.ambient_vector_space().basis()[i] for i in
+            nonPivotList]
+            return self.ambient_vector_space().subspace(complementBasis)
+
+    def orthogonal_complement(self):
+        r"""
+        Return the orthogonal complement of ``self`` in the
         :meth:`~sage.modules.free_module.FreeModule_ambient_field.ambient_vector_space`.
 
         EXAMPLES::
 
             sage: V = QQ^3
-            sage: V.complement()
+            sage: V.orthogonal_complement()
             Vector space of degree 3 and dimension 0 over Rational Field
             Basis matrix:
             []
-            sage: V == V.complement().complement()
+            sage: V == V.orthogonal_complement().orthogonal_complement()
             True
             sage: W = V.span([[1, 0, 1]])
-            sage: X = W.complement(); X
+            sage: X = W.orthogonal_complement(); X
             Vector space of degree 3 and dimension 2 over Rational Field
             Basis matrix:
             [ 1  0 -1]
             [ 0  1  0]
-            sage: X.complement() == W
+            sage: X.orthogonal_complement() == W
             True
             sage: X + W == V
             True
@@ -4998,32 +5046,32 @@
             sage: V = QQ^3
             sage: W = V.subspace_with_basis([[1,0,1],[-1,1,0]])
             sage: X = W.subspace_with_basis([[1,0,1]])
-            sage: X.complement()
+            sage: X.orthogonal_complement()
             Vector space of degree 3 and dimension 2 over Rational Field
             Basis matrix:
             [ 1  0 -1]
             [ 0  1  0]
 
-        All these complements are only done with respect to the inner
+        All these orthogonal complements are only done with respect to the inner
         product in the usual basis.  Over finite fields, this means
-        we can get complements which are only isomorphic to a vector
-        space decomposition complement. ::
+        we can get orthogonal complements which are only isomorphic to a vector
+        space decomposition orthogonal complements. ::
 
             sage: F2 = GF(2, 'x')
             sage: V = F2^6
             sage: W = V.span([[1,1,0,0,0,0]]); W
             Vector space of degree 6 and dimension 1 over Finite Field of size 2
             Basis matrix:
             [1 1 0 0 0 0]
-            sage: W.complement()
+            sage: W.orthogonal_complement()
             Vector space of degree 6 and dimension 5 over Finite Field of size 2
             Basis matrix:
             [1 1 0 0 0 0]
             [0 0 1 0 0 0]
             [0 0 0 1 0 0]
             [0 0 0 0 1 0]
             [0 0 0 0 0 1]
-            sage: W.intersection(W.complement())
+            sage: W.intersection(W.orthogonal_complement())
             Vector space of degree 6 and dimension 1 over Finite Field of size 2
             Basis matrix:
             [1 1 0 0 0 0]