add of the function rank_support_of_vector

src/sage/coding/linear_rank_metric.py

@@ -91,6 +91,7 @@
 AUTHORS:
 
 - Marketa Slukova (2019-08-16): initial version
+- Camille Garnier and Rubén Muñoz--Bertrand (2024-02-13): added rank_support_of_vector, and corrected the documentation
 
 TESTS::
 
@@ -146,9 +147,9 @@
       specified, it is the prime subfield `\GF{p}` of `\GF{q^m}`
 
     - ``basis`` -- (default: ``None``) a basis of `\GF{q^m}` as a vector space over
-      ``sub_field``. If not specified, given that `q = p^s`, let
-      `1,\beta,\ldots,\beta^{sm}` be the power basis that SageMath uses to
-      represent `\GF{q^m}`. The default basis is then `1,\beta,\ldots,\beta^{m-1}`.
+      ``sub_field``. If not specified, given that `q = p^s`, let `\beta` be a generator 
+      of the multiplicative group of `\GF{q^m}`.
+     The default basis is then `1,\beta,\ldots,\beta^{m-1}`.
 
     EXAMPLES::
 
@@ -198,9 +199,9 @@
       ``w``.
 
     - ``basis`` -- (default: ``None``) a basis of `\GF{q^m}` as a vector space over
-      `\GF{q}`. If not specified, given that `q = p^s`, let
-      `1,\beta,\ldots,\beta^{sm}` be the power basis that SageMath uses to
-      represent `\GF{q^m}`. The default basis is then `1,\beta,\ldots,\beta^{m-1}`.
+      `\GF{q}`. If not specified, given that `q = p^s`, let `\beta` be a generator 
+    of the multiplicative group of `\GF{q^m}`.
+     The default basis is then `1,\beta,\ldots,\beta^{m-1}`.
 
     EXAMPLES::
 
@@ -230,7 +231,7 @@
     Return the rank of ``c`` as a matrix over ``sub_field``.
 
     If ``c`` is a vector over some field `\GF{q^m}`, the function converts it
-    into a matrix over `\GF{q}`.
+    into a matrix over ``sub_field```.
 
     INPUT:
 
@@ -241,8 +242,8 @@
 
     - ``basis`` -- (default: ``None``) a basis of `\GF{q^m}` as a vector space over
       ``sub_field``. If not specified, given that `q = p^s`, let
-      `1,\beta,\ldots,\beta^{sm}` be the power basis that SageMath uses to
-      represent `\GF{q^m}`. The default basis is then `1,\beta,\ldots,\beta^{m-1}`.
+      `1,\beta,\ldots,\beta^{sm-1}` be the basis that SageMath uses to
+      represent `\GF{q^m}`. The default basis is then `1,\beta,\ldots,\beta^{m-1}`
 
     EXAMPLES::
 
@@ -278,9 +279,9 @@
       specified, it is the prime subfield `\GF{p}` of `\GF{q^m}`
 
     - ``basis`` -- (default: ``None``) a basis of `\GF{q^m}` as a vector space over
-      ``sub_field``. If not specified, given that `q = p^s`, let
-      `1,\beta,\ldots,\beta^{sm}` be the power basis that SageMath uses to
-      represent `\GF{q^m}`. The default basis is then `1,\beta,\ldots,\beta^{m-1}`.
+      ``sub_field``. If not specified, given that `q = p^s`, let `\beta` be a generator 
+     of the multiplicative group of `\GF{q^m}`.
+     The default basis is then `1,\beta,\ldots,\beta^{m-1}`.
 
     EXAMPLES::
 
@@ -379,9 +380,9 @@
         - ``default_decoder_name`` -- the name of the default decoder of ``self``
 
         - ``basis`` -- (default: ``None``) a basis of `\GF{q^m}` as a vector space over
-          ``sub_field``. If not specified, given that `q = p^s`, let
-          `1,\beta,\ldots,\beta^{sm}` be the power basis that SageMath uses to
-          represent `\GF{q^m}`. The default basis is then `1,\beta,\ldots,\beta^{m-1}`.
+          ``sub_field``. If not specified, given that `q = p^s`, let `\beta` be a generator 
+        of the multiplicative group of `\GF{q^m}`.
+        The default basis is then `1,\beta,\ldots,\beta^{m-1}`.
 
         EXAMPLES:
 
@@ -587,6 +588,73 @@
             2
         """
         return rank_weight(word, self.sub_field())
+
+    def rank_support_of_vector(self, word, sub_field=None, basis=None):
+        r"""
+        Return the rank support of ``word`` over ``sub_field``, i.e. the  vector space over 
+        ``sub_field`` generated by its coefficients. 
+        If ``word`` is a vector over some field `\GF{q^m}`, and ``sub_field`` is a subfield of 
+        `\GF{q^m}`, the function converts it into a matrix over ``sub_field``, with 
+        respect to the basis ``basis``.
+
+
+        INPUT:
+
+         - ``word`` -- a vector over the ``base_field`` of ``self``
+
+         - ``sub_field`` -- (default: ``None``) a sub field of the ``base_field`` of ``self``; if not
+         specified, it is the prime subfield `\GF{p}` of the ``base_field`` of ``self``
+
+         - ``basis`` -- (default: ``None``) a basis of ``base_field`` of ``self`` as a vector space over
+         ``sub_field``. 
+
+         If not specified, given that `q = p^s`, let `\beta` be a generator of the multiplicative group 
+         of `\GF{q^m}`. The default basis is then `1,\beta,\ldots,\beta^{m-1}`.
+
+        EXAMPLES::
+
+            sage: G = Matrix(GF(64), [[1,1,0], [0,0,1]])
+            sage: C = codes.LinearRankMetricCode(G, GF(4))
+            sage: a = GF(64).gen()
+            sage: c = vector([a^4 + a^3 + 1, a^4 + a^3 + 1, a^4 + a^3 + a^2 + 1])
+            sage: c in C
+            True
+            sage: C.rank_support_of_vector(c)
+            Vector space of degree 6 and dimension 2 over Finite Field of size 2
+            Basis matrix:
+            [1 0 0 1 1 0]
+            [0 0 1 0 0 0]
+
+        An example with a non canonical basis::
+
+            sage: K.<a> = GF(2^3)
+            sage: G = Matrix(K, [[1,1,0], [0,0,1]])
+            sage: C = codes.LinearRankMetricCode(G)
+            sage: c = vector([a^2, a^2, 0])
+            sage: basis = [a, a+1, a^2]
+            sage: C.rank_support_of_vector(c, basis=basis)
+            Vector space of degree 3 and dimension 1 over Finite Field of size 2
+            Basis matrix:
+            [0 0 1]
+
+        TESTS::
+
+            sage: C.rank_support_of_vector(a)
+            Traceback (most recent call last):
+            ...
+            TypeError: input must be a vector
+
+            sage: C.rank_support_of_vector(c, GF(2^4))
+            Traceback (most recent call last):
+            ...
+            TypeError: the input subfield Finite Field in z4 of size 2^4 is not a subfield of Finite Field in a of size 2^3
+        """
+        if not isinstance(word, Vector):
+            raise TypeError("input must be a vector")
+        if sub_field != None:
+            if self.base_field().degree() % sub_field.degree() != 0:
+                raise TypeError(f"the input subfield {sub_field} is not a subfield of {self.base_field()}")
+        return to_matrix_representation(word, sub_field, basis).column_module()
 
     def matrix_form_of_vector(self, word):
         r"""
@@ -679,9 +747,9 @@
           specified, it is the prime field of ``base_field``
 
         - ``basis`` -- (default: ``None``) a basis of `\GF{q^m}` as a vector space over
-          ``sub_field``. If not specified, given that `q = p^s`, let
-          `1,\beta,\ldots,\beta^{sm}` be the power basis that SageMath uses to
-          represent `\GF{q^m}`. The default basis is then `1,\beta,\ldots,\beta^{m-1}`.
+          ``sub_field``. If not specified, given that `q = p^s`, let `\beta` be a generator 
+         of the multiplicative group of `\GF{q^m}`.
+         The default basis is then `1,\beta,\ldots,\beta^{m-1}`.
 
         EXAMPLES::