Add free_module method to Rings()

Author: roed314

src/doc/en/thematic_tutorials/coercion_and_categories.rst

@@ -452,7 +452,7 @@ And indeed, ``MS2`` has *more* methods than ``MS1``::
     sage: len([s for s in dir(MS1) if inspect.ismethod(getattr(MS1,s,None))])
     81
     sage: len([s for s in dir(MS2) if inspect.ismethod(getattr(MS2,s,None))])
-    119
+    120
 
 This is because the class of ``MS2`` also inherits from the parent
 class for algebras::

src/sage/categories/rings.py

@@ -1086,6 +1086,73 @@ def normalize_arg(arg):
             from sage.rings.polynomial.polynomial_ring_constructor import PolynomialRing
             return PolynomialRing(self, elts)
 
+        def free_module(self, base=None, basis=None, map=True):
+            """
+            Return a free module `V` over the specified subring together with maps to and from `V`.
+
+            The default implementation only supports the case that the base ring is the ring itself.
+
+            INPUT:
+
+            - ``base`` -- a subring `R` so that this ring is isomorphic
+              to a finite-rank free `R`-module `V`
+
+            - ``basis`` -- (optional) a basis for this ring over the base
+
+            - ``map`` -- boolean (default ``True``), whether to return
+              `R`-linear maps to and from `V`
+
+            OUTPUT:
+
+            - A finite-rank free `R`-module `V`
+
+            - An `R`-module isomorphism from `V` to this ring
+              (only included if ``map`` is ``True``)
+
+            - An `R`-module isomorphism from this ring to `V`
+              (only included if ``map`` is ``True``)
+
+            EXAMPLES::
+
+                sage: R.<x> = QQ[[]]
+                sage: V, from_V, to_V = R.free_module(R)
+                sage: v = to_V(1+x); v
+                (1 + x)
+                sage: from_V(v)
+                1 + x
+                sage: W, from_W, to_W = R.free_module(R, basis=(1-x))
+                sage: W is V
+                True
+                sage: w = to_W(1+x); w
+                (1 - x^2)
+                sage: from_W(w)
+                1 + x + O(x^20)
+            """
+            if base is None:
+                base = self.base_ring()
+            if base is self:
+                V = self**1
+                if not map:
+                    return V
+                if basis is not None:
+                    if isinstance(basis, (list, tuple)):
+                        if len(basis) != 1:
+                            raise ValueError("Basis must have length 1")
+                        basis = basis[0]
+                    basis = self(basis)
+                    if not basis.is_unit():
+                        raise ValueError("Basis element must be a unit")
+                from sage.modules.free_module_morphism import BaseIsomorphism1D_from_FM, BaseIsomorphism1D_to_FM
+                Hfrom = V.Hom(self)
+                Hto = self.Hom(V)
+                from_V = Hfrom.__make_element_class__(BaseIsomorphism1D_from_FM)(Hfrom, basis=basis)
+                to_V = Hto.__make_element_class__(BaseIsomorphism1D_to_FM)(Hto, basis=basis)
+                return V, from_V, to_V
+            else:
+                if not self.has_coerce_map_from(base):
+                    raise ValueError("base must be a subring of this ring")
+                raise NotImplementedError
+
     class ElementMethods:
         def is_unit(self):
             r"""

src/sage/modules/free_module_morphism.py

@@ -43,7 +43,9 @@
 
 import sage.modules.free_module as free_module
 from . import matrix_morphism
+from sage.categories.morphism import Morphism
 from sage.structure.sequence import Sequence
+from sage.structure.richcmp import richcmp, rich_to_bool
 
 from . import free_module_homspace
 
@@ -612,3 +614,178 @@ def minimal_polynomial(self,var='x'):
             raise TypeError("not an endomorphism")
 
     minpoly = minimal_polynomial
+
+class BaseIsomorphism1D(Morphism):
+    """
+    An isomorphism between a ring and a free rank-1 module over the ring.
+
+    EXAMPLES::
+
+        sage: R.<x,y> = QQ[]
+        sage: V, from_V, to_V = R.free_module(R)
+        sage: from_V
+        Isomorphism morphism:
+          From: Ambient free module of rank 1 over the integral domain Multivariate Polynomial Ring in x, y over Rational Field
+          To:   Multivariate Polynomial Ring in x, y over Rational Field
+    """
+    def _repr_type(self):
+        r"""
+        EXAMPLES::
+
+            sage: R.<x,y> = QQ[]
+            sage: V, from_V, to_V = R.free_module(R)
+            sage: from_V._repr_type()
+            'Isomorphism'
+        """
+        return "Isomorphism"
+
+    def is_injective(self):
+        r"""
+        EXAMPLES::
+
+            sage: R.<x,y> = QQ[]
+            sage: V, from_V, to_V = R.free_module(R)
+            sage: from_V.is_injective()
+            True
+        """
+        return True
+
+    def is_surjective(self):
+        r"""
+        EXAMPLES::
+
+            sage: R.<x,y> = QQ[]
+            sage: V, from_V, to_V = R.free_module(R)
+            sage: from_V.is_surjective()
+            True
+        """
+        return True
+
+    def _richcmp_(self, other, op):
+        r"""
+        EXAMPLES::
+
+            sage: R.<x,y> = QQ[]
+            sage: V, fr, to = R.free_module(R)
+            sage: fr == loads(dumps(fr))
+            True
+        """
+        if isinstance(other, BaseIsomorphism1D):
+            return richcmp(self._basis, other._basis, op)
+        else:
+            return rich_to_bool(op, 1)
+
+class BaseIsomorphism1D_to_FM(BaseIsomorphism1D):
+    """
+    An isomorphism from a ring to its 1-dimensional free module
+
+    INPUT:
+
+    - ``parent`` -- the homset
+    - ``basis`` -- (default 1) an invertible element of the ring
+
+    EXAMPLES::
+
+        sage: R = Zmod(8)
+        sage: V, from_V, to_V = R.free_module(R)
+        sage: v = to_V(2); v
+        (2)
+        sage: from_V(v)
+        2
+        sage: W, from_W, to_W = R.free_module(R, basis=3)
+        sage: W is V
+        True
+        sage: w = to_W(2); w
+        (6)
+        sage: from_W(w)
+        2
+
+    The basis vector has to be a unit so that the map is an isomorphism::
+
+        sage: W, from_W, to_W = R.free_module(R, basis=4)
+        Traceback (most recent call last):
+        ...
+        ValueError: Basis element must be a unit
+    """
+    def __init__(self, parent, basis=None):
+        """
+        TESTS::
+
+            sage: R = Zmod(8)
+            sage: W, from_W, to_W = R.free_module(R, basis=3)
+            sage: TestSuite(to_W).run()
+        """
+        Morphism.__init__(self, parent)
+        self._basis = basis
+
+    def _call_(self, x):
+        """
+        TESTS::
+
+            sage: R = Zmod(8)
+            sage: W, from_W, to_W = R.free_module(R, basis=3)
+            sage: to_W(6) # indirect doctest
+            (2)
+        """
+        if self._basis is not None:
+            x *= self._basis
+        return self.codomain()([x])
+
+class BaseIsomorphism1D_from_FM(BaseIsomorphism1D):
+    """
+    An isomorphism to a ring from its 1-dimensional free module
+
+    INPUT:
+
+    - ``parent`` -- the homset
+    - ``basis`` -- (default 1) an invertible element of the ring
+
+    EXAMPLES::
+
+        sage: R.<x> = QQ[[]]
+        sage: V, from_V, to_V = R.free_module(R)
+        sage: v = to_V(1+x); v
+        (1 + x)
+        sage: from_V(v)
+        1 + x
+        sage: W, from_W, to_W = R.free_module(R, basis=(1-x))
+        sage: W is V
+        True
+        sage: w = to_W(1+x); w
+        (1 - x^2)
+        sage: from_W(w)
+        1 + x + O(x^20)
+
+    The basis vector has to be a unit so that the map is an isomorphism::
+
+        sage: W, from_W, to_W = R.free_module(R, basis=x)
+        Traceback (most recent call last):
+        ...
+        ValueError: Basis element must be a unit
+    """
+    def __init__(self, parent, basis=None):
+        """
+        TESTS::
+
+            sage: R.<x> = QQ[[]]
+            sage: W, from_W, to_W = R.free_module(R, basis=(1-x))
+            sage: TestSuite(from_W).run(skip='_test_nonzero_equal')
+        """
+        Morphism.__init__(self, parent)
+        self._basis = basis
+
+    def _call_(self, x):
+        """
+        TESTS::
+
+            sage: R.<x> = QQ[[]]
+            sage: W, from_W, to_W = R.free_module(R, basis=(1-x))
+            sage: w = to_W(1+x); w
+            (1 - x^2)
+            sage: from_W(w)
+            1 + x + O(x^20)
+        """
+        if self._basis is None:
+            return x[0]
+        else:
+            return self.codomain()(x[0] / self._basis)

src/sage/rings/number_field/number_field.py

@@ -8170,7 +8170,11 @@ def free_module(self, base=None, basis=None, map=True):
             sage: to_V(from_V(V([0,-1/7,0])))
             (0, -1/7, 0)
         """
-        if basis is not None or base is not None:
+        if base is None:
+            base = QQ
+        elif base is self:
+            return super(NumberField_absolute, self).free_module(base=base, basis=basis, map=map)
+        if basis is not None or base is not QQ:
             raise NotImplementedError
         V = QQ**self.degree()
         if not map:

src/sage/rings/padics/padic_extension_generic.py

@@ -566,7 +566,7 @@ def random_element(self):
     @cached_method(key=(lambda self, base, basis, map: (base or self.base_ring(), map)))
     def free_module(self, base=None, basis=None, map=True):
         """
-        Return a free module V over a specified base ring together with maps to and from V.
+        Return a free module `V` over a specified base ring together with maps to and from `V`.
 
         INPUT:
 
@@ -575,18 +575,18 @@ def free_module(self, base=None, basis=None, map=True):
 
         - ``basis`` -- a basis for this ring/field over the base
 
-        - ``maps`` -- boolean (default ``True``), whether to return
+        - ``map`` -- boolean (default ``True``), whether to return
           `R`-linear maps to and from `V`
 
         OUTPUT:
 
         - A finite-rank free `R`-module `V`
 
-        - An `R`-module isomorphism ``from_V`` from `V` to this ring/field
-          (only included if ``maps`` is ``True``)
+        - An `R`-module isomorphism from `V` to this ring/field
+          (only included if ``map`` is ``True``)
 
-        - An `R`-module isomorphism ``to_V`` from this ring/field to `V`
-          (only included if ``maps`` is ``True``)
+        - An `R`-module isomorphism from this ring/field to `V`
+          (only included if ``map`` is ``True``)
 
         EXAMPLES::
 
@@ -606,6 +606,10 @@ def free_module(self, base=None, basis=None, map=True):
             (O(5^21), 1 + O(5^20))
             sage: to_W0(pi + O(pi^11))
             (O(5^6), O(5^6), O(5^6), 1 + O(5^5), O(5^5), O(5^5))
+
+            sage: X, from_X, to_X = K.free_module(K)
+            sage: to_X(a)
+            (a + O(5^20))
         """
         if basis is not None:
             raise NotImplementedError
@@ -624,6 +628,8 @@ def free_module(self, base=None, basis=None, map=True):
             V = A**d
             from_V = MapFreeModuleToTwoStep
             to_V = MapTwoStepToFreeModule
+        elif base is self:
+            return super(pAdicExtensionGeneric, self).free_module(base=base, basis=basis, map=map)
         else:
             raise NotImplementedError
         FromV = Hom(V, self)

src/sage/rings/polynomial/polynomial_element.pyx

@@ -3244,9 +3244,8 @@ cdef class Polynomial(CommutativeAlgebraElement):
             True
         """
         if isinstance(R, Map):
-            # we're given a hom of the base ring extend to a poly hom
-            if R.domain() == self.base_ring():
-                R = self._parent.hom(R, self._parent.change_ring(R.codomain()))
+            # extend to a hom of the base ring of the polynomial
+            R = self._parent.hom(R, self._parent.change_ring(R.codomain()))
             return R(self)
         else:
             return self._parent.change_ring(R)(self.list(copy=False))