Free modules - Modules

Skip to content
Back to top
View this page
Edit this page

# Free modules

Sage supports computation with free modules over an arbitrary commutative ring. Nontrivial functionality is available over \(\ZZ\), fields, and some principal ideal domains (e.g. \(\QQ[x]\) and rings of integers of number fields). All free modules over an integral domain are equipped with an embedding in an ambient vector space and an inner product, which you can specify and change.

Create the free module of rank \(n\) over an arbitrary commutative ring \(R\) using the command `FreeModule(R,n)`. Equivalently, `R^n` also creates that free module.

The following example illustrates the creation of both a vector space and a free module over the integers and a submodule of it. Use the functions `FreeModule`, `span` and member functions of free modules to create free modules. Do not use the FreeModule_xxx constructors directly.

EXAMPLES:

Sage

    sage: V = VectorSpace(QQ, 3)
    sage: W = V.subspace([[1,2,7], [1,1,0]])
    sage: W
    Vector space of degree 3 and dimension 2 over Rational Field
    Basis matrix:
    [ 1  0 -7]
    [ 0  1  7]
    sage: C = VectorSpaces(FiniteField(7))
    sage: C
    Category of vector spaces over Finite Field of size 7
    sage: C(W)
    Vector space of degree 3 and dimension 2 over Finite Field of size 7
    Basis matrix:
    [1 0 0]
    [0 1 0]

Python

    >>> from sage.all import *
    >>> V = VectorSpace(QQ, Integer(3))
    >>> W = V.subspace([[Integer(1),Integer(2),Integer(7)], [Integer(1),Integer(1),Integer(0)]])
    >>> W
    Vector space of degree 3 and dimension 2 over Rational Field
    Basis matrix:
    [ 1  0 -7]
    [ 0  1  7]
    >>> C = VectorSpaces(FiniteField(Integer(7)))
    >>> C
    Category of vector spaces over Finite Field of size 7
    >>> C(W)
    Vector space of degree 3 and dimension 2 over Finite Field of size 7
    Basis matrix:
    [1 0 0]
    [0 1 0]

Sage

    sage: M = ZZ^3
    sage: C = VectorSpaces(FiniteField(7))
    sage: C(M)
    Vector space of dimension 3 over Finite Field of size 7
    sage: W = M.submodule([[1,2,7], [8,8,0]])
    sage: C(W)
    Vector space of degree 3 and dimension 2 over Finite Field of size 7
    Basis matrix:
    [1 0 0]
    [0 1 0]

[Python]

    >>> from sage.all import *
    >>> M = ZZ**Integer(3)
    >>> C = VectorSpaces(FiniteField(Integer(7)))
    >>> C(M)
    Vector space of dimension 3 over Finite Field of size 7
    >>> W = M.submodule([[Integer(1),Integer(2),Integer(7)], [Integer(8),Integer(8),Integer(0)]])
    >>> C(W)
    Vector space of degree 3 and dimension 2 over Finite Field of size 7
    Basis matrix:
    [1 0 0]
    [0 1 0]

We illustrate the exponent notation for creation of free modules.

Sage

    sage: ZZ^4
    Ambient free module of rank 4 over the principal ideal domain Integer Ring
    sage: QQ^2
    Vector space of dimension 2 over Rational Field
    sage: RR^3
    Vector space of dimension 3 over Real Field with 53 bits of precision

Python

    >>> from sage.all import *
    >>> ZZ**Integer(4)
    Ambient free module of rank 4 over the principal ideal domain Integer Ring
    >>> QQ**Integer(2)
    Vector space of dimension 2 over Rational Field
    >>> RR**Integer(3)
    Vector space of dimension 3 over Real Field with 53 bits of precision

Base ring:

Sage

    sage: R.<x,y> = QQ[]
    sage: M = FreeModule(R,2)
    sage: M.base_ring()
    Multivariate Polynomial Ring in x, y over Rational Field

[Python]

    >>> from sage.all import *
    >>> R = QQ['x, y']; (x, y,) = R._first_ngens(2)
    >>> M = FreeModule(R,Integer(2))
    >>> M.base_ring()
    Multivariate Polynomial Ring in x, y over Rational Field

Sage

    sage: VectorSpace(QQ, 10).base_ring()
    Rational Field

Python

    >>> from sage.all import *
    >>> VectorSpace(QQ, Integer(10)).base_ring()
    Rational Field

Enumeration of \(\ZZ^n\) happens in order of increasing \(1\)-norm primarily and increasing \(\infty\)-norm secondarily:

Sage

    sage: print([v for _,v in zip(range(31), ZZ^3)])
    [(0, 0, 0),
     (1, 0, 0), (-1, 0, 0), (0, 1, 0), (0, -1, 0), (0, 0, 1), (0, 0, -1),
     (1, 1, 0), (-1, 1, 0), (1, -1, 0), (-1, -1, 0), (1, 0, 1), (-1, 0, 1), (1, 0, -1), (-1, 0, -1), (0, 1, 1), (0, -1, 1), (0, 1, -1), (0, -1, -1),
     (2, 0, 0), (-2, 0, 0), (0, 2, 0), (0, -2, 0), (0, 0, 2), (0, 0, -2),
     (1, 1, 1), (-1, 1, 1), (1, -1, 1), (-1, -1, 1), (1, 1, -1), ...]

[Python]

    >>> from sage.all import *
    >>> print([v for _,v in zip(range(Integer(31)), ZZ**Integer(3))])
    [(0, 0, 0),
     (1, 0, 0), (-1, 0, 0), (0, 1, 0), (0, -1, 0), (0, 0, 1), (0, 0, -1),
     (1, 1, 0), (-1, 1, 0), (1, -1, 0), (-1, -1, 0), (1, 0, 1), (-1, 0, 1), (1, 0, -1), (-1, 0, -1), (0, 1, 1), (0, -1, 1), (0, 1, -1), (0, -1, -1),
     (2, 0, 0), (-2, 0, 0), (0, 2, 0), (0, -2, 0), (0, 0, 2), (0, 0, -2),
     (1, 1, 1), (-1, 1, 1), (1, -1, 1), (-1, -1, 1), (1, 1, -1), ...]

For other infinite enumerated base rings (i.e., rings which are objects of the category `InfiniteEnumeratedSets`), a free module of rank \(r\) is enumerated by applying `FreeModule_ambient.linear_combination_of_basis()` to all vectors in \(\ZZ^r\), enumerated in the way shown above.

AUTHORS:

- William Stein (2005, 2007)

- David Kohel (2007, 2008)

- Niles Johnson (2010-08): (Issue #3893) `random_element()` should pass on `*args` and `**kwds`.

- Simon King (2010-12): (Issue #8800) fixed a bug in `denominator()`.

- Simon King (2010-12), Peter Bruin (June 2014): (Issue #10513) new coercion model and category framework.

class sage.modules.free_module.ComplexDoubleVectorSpace_class(n)

  Bases: `FreeModule_ambient_field`

  coordinates(v)

class sage.modules.free_module.EchelonMatrixKey(obj)

  Bases: `object`

  A total ordering on free modules for sorting.

  This class orders modules by their ambient spaces, then by dimension, then in order by their echelon matrices. If a function returns a list of free modules, this can be used to sort the output and thus render it deterministic.

  INPUT:

  - `obj` – a free module

  EXAMPLES:

  Sage

      sage: V = span([[1,2,3], [5,6,7], [8,9,10]], QQ)
      sage: W = span([[5,6,7], [8,9,10]], QQ)
      sage: X = span([[5,6,7]], ZZ).scale(1/11)
      sage: Y = CC^3
      sage: Z = ZZ^2
      sage: modules = [V,W,X,Y,Z]
      sage: modules_sorted = [Z,X,V,W,Y]
      sage: from sage.modules.free_module import EchelonMatrixKey
      sage: modules.sort(key=EchelonMatrixKey)
      sage: modules == modules_sorted
      True

  Python

      >>> from sage.all import *
      >>> V = span([[Integer(1),Integer(2),Integer(3)], [Integer(5),Integer(6),Integer(7)], [Integer(8),Integer(9),Integer(10)]], QQ)
      >>> W = span([[Integer(5),Integer(6),Integer(7)], [Integer(8),Integer(9),Integer(10)]], QQ)
      >>> X = span([[Integer(5),Integer(6),Integer(7)]], ZZ).scale(Integer(1)/Integer(11))
      >>> Y = CC**Integer(3)
      >>> Z = ZZ**Integer(2)
      >>> modules = [V,W,X,Y,Z]
      >>> modules_sorted = [Z,X,V,W,Y]
      >>> from sage.modules.free_module import EchelonMatrixKey
      >>> modules.sort(key=EchelonMatrixKey)
      >>> modules == modules_sorted
      True

sage.modules.free_module.FreeModule(base_ring, rank_or_basis_keys, sparse, inner_product_matrix, with_basis=None, rank=False, basis_keys=None, **args)

  Create a free module over the given commutative `base_ring`.

  `FreeModule` can be called with the following positional arguments:

  - `FreeModule(base_ring, rank, ...)`

  - `FreeModule(base_ring, basis_keys, ...)`

  INPUT:

  - `base_ring` – a commutative ring

  - `rank` – nonnegative integer

  - `basis_keys` – a finite or enumerated family of arbitrary objects

  - `sparse` – boolean (default: `False`)

  - `inner_product_matrix` – the inner product matrix (default: `None`)

  - `with_basis` – either `'standard'` (the default), in which case a free module with the standard basis as the distinguished basis is created; or `None`, in which case a free module without distinguished basis is created.

  - further options may be accepted by various implementation classes

  OUTPUT: a free module

  This factory function creates instances of various specialized classes depending on the input. Not all combinations of options are implemented.

  - If the parameter `basis_keys` is provided, it must be a finite or enumerated family of objects, and an instance of `CombinatorialFreeModule` is created.

    > EXAMPLES:

    > Sage

    >     sage: CombinatorialFreeModule(QQ, ['a','b','c'])
    >     Free module generated by {'a', 'b', 'c'} over Rational Field

    > Python

    >     >>> from sage.all import *
    >     >>> CombinatorialFreeModule(QQ, ['a','b','c'])
    >     Free module generated by {'a', 'b', 'c'} over Rational Field

    > It has a distinguished standard basis that is indexed by the provided `basis_keys`. See the documentation of `CombinatorialFreeModule` for more examples and details, including its `UniqueRepresentation` semantics.

  - If the parameter `with_basis` is set to `None`, then a free module of the given `rank` without distinguished basis is created. It is represented by an instance of `FiniteRankFreeModule`.

    > EXAMPLES:

    > Sage

    >     sage: FiniteRankFreeModule(ZZ, 3, name='M')
    >     Rank-3 free module M over the Integer Ring

    > Python

    >     >>> from sage.all import *
    >     >>> FiniteRankFreeModule(ZZ, Integer(3), name='M')
    >     Rank-3 free module M over the Integer Ring

    > See the documentation of `FiniteRankFreeModule` for more options, examples, and details.

  - If `rank` is provided and the option `with_basis` is left at its default value, `'standard'`, then a free ambient module with distinguished standard basis indexed by `range(rank)` is created. There is only one dense and one sparse free ambient module of given `rank` over `base_ring`.

    EXAMPLES:

    Sage

        sage: FreeModule(Integers(8), 10)
        Ambient free module of rank 10 over Ring of integers modulo 8

    Python

        >>> from sage.all import *
        >>> FreeModule(Integers(Integer(8)), Integer(10))
        Ambient free module of rank 10 over Ring of integers modulo 8

    The remainder of this documentation discusses this case of free ambient modules.

  EXAMPLES:

  First we illustrate creating free modules over various base fields. The base field affects the free module that is created. For example, free modules over a field are vector spaces, and free modules over a principal ideal domain are special in that more functionality is available for them than for completely general free modules.

  Sage

      sage: FreeModule(QQ,10)
      Vector space of dimension 10 over Rational Field
      sage: FreeModule(ZZ,10)
      Ambient free module of rank 10 over the principal ideal domain Integer Ring
      sage: FreeModule(FiniteField(5), 10)
      Vector space of dimension 10 over Finite Field of size 5
      sage: FreeModule(Integers(7), 10)
      Vector space of dimension 10 over Ring of integers modulo 7
      sage: FreeModule(PolynomialRing(QQ,'x'), 5)
      Ambient free module of rank 5 over the principal ideal domain
       Univariate Polynomial Ring in x over Rational Field
      sage: FreeModule(PolynomialRing(ZZ,'x'), 5)
      Ambient free module of rank 5 over the integral domain
       Univariate Polynomial Ring in x over Integer Ring

  Python

      >>> from sage.all import *
      >>> FreeModule(QQ,Integer(10))
      Vector space of dimension 10 over Rational Field
      >>> FreeModule(ZZ,Integer(10))
      Ambient free module of rank 10 over the principal ideal domain Integer Ring
      >>> FreeModule(FiniteField(Integer(5)), Integer(10))
      Vector space of dimension 10 over Finite Field of size 5
      >>> FreeModule(Integers(Integer(7)), Integer(10))
      Vector space of dimension 10 over Ring of integers modulo 7
      >>> FreeModule(PolynomialRing(QQ,'x'), Integer(5))
      Ambient free module of rank 5 over the principal ideal domain
       Univariate Polynomial Ring in x over Rational Field
      >>> FreeModule(PolynomialRing(ZZ,'x'), Integer(5))
      Ambient free module of rank 5 over the integral domain
       Univariate Polynomial Ring in x over Integer Ring

  Of course we can make rank 0 free modules:

  Sage

      sage: FreeModule(RealField(100),0)
      Vector space of dimension 0 over Real Field with 100 bits of precision

  [Python]

      >>> from sage.all import *
      >>> FreeModule(RealField(Integer(100)),Integer(0))
      Vector space of dimension 0 over Real Field with 100 bits of precision

  Next we create a free module with sparse representation of elements. Functionality with sparse modules is identical to dense modules, but they may use less memory and arithmetic may be faster (or slower!).

  Sage

      sage: M = FreeModule(ZZ,200,sparse=True)
      sage: M.is_sparse()
      True
      sage: type(M.0)
      <class 'sage.modules.free_module_element.FreeModuleElement_generic_sparse'>

  Python

      >>> from sage.all import *
      >>> M = FreeModule(ZZ,Integer(200),sparse=True)
      >>> M.is_sparse()
      True
      >>> type(M.gen(0))
      <class 'sage.modules.free_module_element.FreeModuleElement_generic_sparse'>

  The default is dense.

  Sage

      sage: M = ZZ^200
      sage: type(M.0)
      <class 'sage.modules.vector_integer_dense.Vector_integer_dense'>

  [Python]

      >>> from sage.all import *
      >>> M = ZZ**Integer(200)
      >>> type(M.gen(0))
      <class 'sage.modules.vector_integer_dense.Vector_integer_dense'>

  Note that matrices associated in some way to sparse free modules are sparse by default:

  Sage

      sage: M = FreeModule(Integers(8), 2)
      sage: A = M.basis_matrix()
      sage: A.is_sparse()
      False
      sage: Ms = FreeModule(Integers(8), 2, sparse=True)
      sage: M == Ms  # as mathematical objects they are equal
      True
      sage: Ms.basis_matrix().is_sparse()
      True

  Python

      >>> from sage.all import *
      >>> M = FreeModule(Integers(Integer(8)), Integer(2))
      >>> A = M.basis_matrix()
      >>> A.is_sparse()
      False
      >>> Ms = FreeModule(Integers(Integer(8)), Integer(2), sparse=True)
      >>> M == Ms  # as mathematical objects they are equal
      True
      >>> Ms.basis_matrix().is_sparse()
      True

  We can also specify an inner product matrix, which is used when computing inner products of elements.

  Sage

      sage: A = MatrixSpace(ZZ, 2)([[1,0], [0,-1]])
      sage: M = FreeModule(ZZ, 2, inner_product_matrix=A)
      sage: v, w = M.gens()
      sage: v.inner_product(w)
      0
      sage: v.inner_product(v)
      1
      sage: w.inner_product(w)
      -1
      sage: (v+2*w).inner_product(w)
      -2

  [Python]

      >>> from sage.all import *
      >>> A = MatrixSpace(ZZ, Integer(2))([[Integer(1),Integer(0)], [Integer(0),-Integer(1)]])
      >>> M = FreeModule(ZZ, Integer(2), inner_product_matrix=A)
      >>> v, w = M.gens()
      >>> v.inner_product(w)
      0
      >>> v.inner_product(v)
      1
      >>> w.inner_product(w)
      -1
      >>> (v+Integer(2)*w).inner_product(w)
      -2

  You can also specify the inner product matrix by giving anything that coerces to an appropriate matrix. This is only useful if the inner product matrix takes values in the base ring.

  Sage

      sage: FreeModule(ZZ, 2, inner_product_matrix=1).inner_product_matrix()
      [1 0]
      [0 1]
      sage: FreeModule(ZZ, 2, inner_product_matrix=[1,2,3,4]).inner_product_matrix()
      [1 2]
      [3 4]
      sage: FreeModule(ZZ, 2, inner_product_matrix=[[1,2], [3,4]]).inner_product_matrix()
      [1 2]
      [3 4]

  Python

      >>> from sage.all import *
      >>> FreeModule(ZZ, Integer(2), inner_product_matrix=Integer(1)).inner_product_matrix()
      [1 0]
      [0 1]
      >>> FreeModule(ZZ, Integer(2), inner_product_matrix=[Integer(1),Integer(2),Integer(3),Integer(4)]).inner_product_matrix()
      [1 2]
      [3 4]
      >>> FreeModule(ZZ, Integer(2), inner_product_matrix=[[Integer(1),Integer(2)], [Integer(3),Integer(4)]]).inner_product_matrix()
      [1 2]
      [3 4]

  Todo

  Refactor modules such that it only counts what category the base ring belongs to, but not what is its Python class.

  EXAMPLES:

  Sage

      sage: FreeModule(QQ, ['a', 'b', 'c'])
      Free module generated by {'a', 'b', 'c'} over Rational Field
      sage: _.category()
      Category of finite dimensional vector spaces with basis over Rational Field

      sage: FreeModule(QQ, 3, with_basis=None)
      3-dimensional vector space over the Rational Field
      sage: _.category()
      Category of finite dimensional vector spaces over Rational Field

      sage: FreeModule(QQ, [1, 2, 3, 4], with_basis=None)
      4-dimensional vector space over the Rational Field
      sage: _.category()
      Category of finite dimensional vector spaces over Rational Field

  [Python]

      >>> from sage.all import *
      >>> FreeModule(QQ, ['a', 'b', 'c'])
      Free module generated by {'a', 'b', 'c'} over Rational Field
      >>> _.category()
      Category of finite dimensional vector spaces with basis over Rational Field

      >>> FreeModule(QQ, Integer(3), with_basis=None)
      3-dimensional vector space over the Rational Field
      >>> _.category()
      Category of finite dimensional vector spaces over Rational Field

      >>> FreeModule(QQ, [Integer(1), Integer(2), Integer(3), Integer(4)], with_basis=None)
      4-dimensional vector space over the Rational Field
      >>> _.category()
      Category of finite dimensional vector spaces over Rational Field

class sage.modules.free_module.FreeModuleFactory

  Bases: `UniqueFactory`

  Factory class for the finite-dimensional free modules with standard basis

  create_key(base_ring, rank, sparse=False, inner_product_matrix=None)
  create_object(version, key)

class sage.modules.free_module.FreeModule_ambient(base_ring, rank, sparse=False, coordinate_ring=None, category=None)

  Bases: `FreeModule_generic`

  Ambient free module over a commutative ring.

  ambient_module()

    Return `self`, since `self` is ambient.

    EXAMPLES:

    Sage

        sage: A = QQ^5; A.ambient_module()
        Vector space of dimension 5 over Rational Field
        sage: A = ZZ^5; A.ambient_module()
        Ambient free module of rank 5 over the principal ideal domain Integer Ring

    Python

        >>> from sage.all import *
        >>> A = QQ**Integer(5); A.ambient_module()
        Vector space of dimension 5 over Rational Field
        >>> A = ZZ**Integer(5); A.ambient_module()
        Ambient free module of rank 5 over the principal ideal domain Integer Ring

  basis()

    Return a basis for this ambient free module.

    OUTPUT:

    - `Sequence` – an immutable sequence with universe this ambient free module

    EXAMPLES:

    Sage

        sage: A = ZZ^3; B = A.basis(); B
        [(1, 0, 0), (0, 1, 0), (0, 0, 1)]
        sage: B.universe()
        Ambient free module of rank 3 over the principal ideal domain Integer Ring

    Python

        >>> from sage.all import *
        >>> A = ZZ**Integer(3); B = A.basis(); B
        [(1, 0, 0), (0, 1, 0), (0, 0, 1)]
        >>> B.universe()
        Ambient free module of rank 3 over the principal ideal domain Integer Ring

  change_ring(R)

    Return the ambient free module over `R` of the same rank as `self`.

    This also preserves the sparsity.

    EXAMPLES:

    Sage

        sage: A = ZZ^3; A.change_ring(QQ)
        Vector space of dimension 3 over Rational Field
        sage: A = ZZ^3; A.change_ring(GF(5))
        Vector space of dimension 3 over Finite Field of size 5

    Python

        >>> from sage.all import *
        >>> A = ZZ**Integer(3); A.change_ring(QQ)
        Vector space of dimension 3 over Rational Field
        >>> A = ZZ**Integer(3); A.change_ring(GF(Integer(5)))
        Vector space of dimension 3 over Finite Field of size 5

    For ambient modules any change of rings is defined:

    Sage

        sage: A = GF(5)**3; A.change_ring(QQ)
        Vector space of dimension 3 over Rational Field

    [Python]

        >>> from sage.all import *
        >>> A = GF(Integer(5))**Integer(3); A.change_ring(QQ)
        Vector space of dimension 3 over Rational Field

  coordinate_vector(v, check=True)

    Write \(v\) in terms of the standard basis for `self` and return the resulting coefficients in a vector over the fraction field of the base ring.

    Returns a vector \(c\) such that if \(B\) is the basis for self, then

    \[\sum c_i B_i = v.\]

    If \(v\) is not in self, raise an `ArithmeticError` exception.

    EXAMPLES:

    Sage

        sage: V = Integers(16)^3
        sage: v = V.coordinate_vector([1,5,9]); v
        (1, 5, 9)
        sage: v.parent()
        Ambient free module of rank 3 over Ring of integers modulo 16

    Python

        >>> from sage.all import *
        >>> V = Integers(Integer(16))**Integer(3)
        >>> v = V.coordinate_vector([Integer(1),Integer(5),Integer(9)]); v
        (1, 5, 9)
        >>> v.parent()
        Ambient free module of rank 3 over Ring of integers modulo 16

  echelon_coordinate_vector(v, check=True)

    Same as `self.coordinate_vector(v)`, since `self` is an ambient free module.

    INPUT:

    - `v` – vector

    - `check` – boolean (default: `True`); if `True`, also verify that \(v\) is really in `self`

    OUTPUT: list

    EXAMPLES:

    Sage

        sage: V = QQ^4
        sage: v = V([-1/2,1/2,-1/2,1/2])
        sage: v
        (-1/2, 1/2, -1/2, 1/2)
        sage: V.coordinate_vector(v)
        (-1/2, 1/2, -1/2, 1/2)
        sage: V.echelon_coordinate_vector(v)
        (-1/2, 1/2, -1/2, 1/2)
        sage: W = V.submodule_with_basis([[1/2,1/2,1/2,1/2],[1,0,1,0]])
        sage: W.coordinate_vector(v)
        (1, -1)
        sage: W.echelon_coordinate_vector(v)
        (-1/2, 1/2)

    Python

        >>> from sage.all import *
        >>> V = QQ**Integer(4)
        >>> v = V([-Integer(1)/Integer(2),Integer(1)/Integer(2),-Integer(1)/Integer(2),Integer(1)/Integer(2)])
        >>> v
        (-1/2, 1/2, -1/2, 1/2)
        >>> V.coordinate_vector(v)
        (-1/2, 1/2, -1/2, 1/2)
        >>> V.echelon_coordinate_vector(v)
        (-1/2, 1/2, -1/2, 1/2)
        >>> W = V.submodule_with_basis([[Integer(1)/Integer(2),Integer(1)/Integer(2),Integer(1)/Integer(2),Integer(1)/Integer(2)],[Integer(1),Integer(0),Integer(1),Integer(0)]])
        >>> W.coordinate_vector(v)
        (1, -1)
        >>> W.echelon_coordinate_vector(v)
        (-1/2, 1/2)

  echelon_coordinates(v, check=True)

    Return the coordinate vector of v in terms of the echelon basis for `self`.

    EXAMPLES:

    Sage

        sage: U = VectorSpace(QQ,3)
        sage: [ U.coordinates(v) for v in U.basis() ]
        [[1, 0, 0], [0, 1, 0], [0, 0, 1]]
        sage: [ U.echelon_coordinates(v) for v in U.basis() ]
        [[1, 0, 0], [0, 1, 0], [0, 0, 1]]
        sage: V = U.submodule([[1,1,0],[0,1,1]])
        sage: V
        Vector space of degree 3 and dimension 2 over Rational Field
        Basis matrix:
        [ 1  0 -1]
        [ 0  1  1]
        sage: [ V.coordinates(v) for v in V.basis() ]
        [[1, 0], [0, 1]]
        sage: [ V.echelon_coordinates(v) for v in V.basis() ]
        [[1, 0], [0, 1]]
        sage: W = U.submodule_with_basis([[1,1,0],[0,1,1]])
        sage: W
        Vector space of degree 3 and dimension 2 over Rational Field
        User basis matrix:
        [1 1 0]
        [0 1 1]
        sage: [ W.coordinates(v) for v in W.basis() ]
        [[1, 0], [0, 1]]
        sage: [ W.echelon_coordinates(v) for v in W.basis() ]
        [[1, 1], [0, 1]]

    Python

        >>> from sage.all import *
        >>> U = VectorSpace(QQ,Integer(3))
        >>> [ U.coordinates(v) for v in U.basis() ]
        [[1, 0, 0], [0, 1, 0], [0, 0, 1]]
        >>> [ U.echelon_coordinates(v) for v in U.basis() ]
        [[1, 0, 0], [0, 1, 0], [0, 0, 1]]
        >>> V = U.submodule([[Integer(1),Integer(1),Integer(0)],[Integer(0),Integer(1),Integer(1)]])
        >>> V
        Vector space of degree 3 and dimension 2 over Rational Field
        Basis matrix:
        [ 1  0 -1]
        [ 0  1  1]
        >>> [ V.coordinates(v) for v in V.basis() ]
        [[1, 0], [0, 1]]
        >>> [ V.echelon_coordinates(v) for v in V.basis() ]
        [[1, 0], [0, 1]]
        >>> W = U.submodule_with_basis([[Integer(1),Integer(1),Integer(0)],[Integer(0),Integer(1),Integer(1)]])
        >>> W
        Vector space of degree 3 and dimension 2 over Rational Field
        User basis matrix:
        [1 1 0]
        [0 1 1]
        >>> [ W.coordinates(v) for v in W.basis() ]
        [[1, 0], [0, 1]]
        >>> [ W.echelon_coordinates(v) for v in W.basis() ]
        [[1, 1], [0, 1]]

  echelonized_basis()

    Return a basis for this ambient free module in echelon form.

    EXAMPLES:

    Sage

        sage: A = ZZ^3; A.echelonized_basis()
        [(1, 0, 0), (0, 1, 0), (0, 0, 1)]

    Python

        >>> from sage.all import *
        >>> A = ZZ**Integer(3); A.echelonized_basis()
        [(1, 0, 0), (0, 1, 0), (0, 0, 1)]

  echelonized_basis_matrix()

    The echelonized basis matrix of `self`.

    EXAMPLES:

    Sage

        sage: V = ZZ^4
        sage: W = V.submodule([ V.gen(i)-V.gen(0) for i in range(1,4) ])
        sage: W.basis_matrix()
        [ 1  0  0 -1]
        [ 0  1  0 -1]
        [ 0  0  1 -1]
        sage: W.echelonized_basis_matrix()
        [ 1  0  0 -1]
        [ 0  1  0 -1]
        [ 0  0  1 -1]
        sage: U = V.submodule_with_basis([ V.gen(i)-V.gen(0) for i in range(1,4) ])
        sage: U.basis_matrix()
        [-1  1  0  0]
        [-1  0  1  0]
        [-1  0  0  1]
        sage: U.echelonized_basis_matrix()
        [ 1  0  0 -1]
        [ 0  1  0 -1]
        [ 0  0  1 -1]

    Python

        >>> from sage.all import *
        >>> V = ZZ**Integer(4)
        >>> W = V.submodule([ V.gen(i)-V.gen(Integer(0)) for i in range(Integer(1),Integer(4)) ])
        >>> W.basis_matrix()
        [ 1  0  0 -1]
        [ 0  1  0 -1]
        [ 0  0  1 -1]
        >>> W.echelonized_basis_matrix()
        [ 1  0  0 -1]
        [ 0  1  0 -1]
        [ 0  0  1 -1]
        >>> U = V.submodule_with_basis([ V.gen(i)-V.gen(Integer(0)) for i in range(Integer(1),Integer(4)) ])
        >>> U.basis_matrix()
        [-1  1  0  0]
        [-1  0  1  0]
        [-1  0  0  1]
        >>> U.echelonized_basis_matrix()
        [ 1  0  0 -1]
        [ 0  1  0 -1]
        [ 0  0  1 -1]

  gen(i=0)

    Return the \(i\)-th generator for `self`.

    Here \(i\) is between 0 and rank - 1, inclusive.

    INPUT:

    - `i` – integer (default: 0)

    OUTPUT: \(i\)-th basis vector for `self`

    EXAMPLES:

    Sage

        sage: n = 5
        sage: V = QQ^n
        sage: B = [V.gen(i) for i in range(n)]
        sage: B
        [(1, 0, 0, 0, 0),
        (0, 1, 0, 0, 0),
        (0, 0, 1, 0, 0),
        (0, 0, 0, 1, 0),
        (0, 0, 0, 0, 1)]
        sage: V.gens() == tuple(B)
        True

    Python

        >>> from sage.all import *
        >>> n = Integer(5)
        >>> V = QQ**n
        >>> B = [V.gen(i) for i in range(n)]
        >>> B
        [(1, 0, 0, 0, 0),
        (0, 1, 0, 0, 0),
        (0, 0, 1, 0, 0),
        (0, 0, 0, 1, 0),
        (0, 0, 0, 0, 1)]
        >>> V.gens() == tuple(B)
        True

  is_ambient()

    Return `True` since this module is an ambient module.

    EXAMPLES:

    Sage

        sage: A = QQ^5; A.is_ambient()
        True
        sage: A = (QQ^5).span([[1,2,3,4,5]]); A.is_ambient()
        False

    Python

        >>> from sage.all import *
        >>> A = QQ**Integer(5); A.is_ambient()
        True
        >>> A = (QQ**Integer(5)).span([[Integer(1),Integer(2),Integer(3),Integer(4),Integer(5)]]); A.is_ambient()
        False

  linear_combination_of_basis(v)

    Return the linear combination of the basis for `self` obtained from the elements of the list v.

    INPUT:

    - `v` – list

    EXAMPLES:

    Sage

        sage: V = span([[1,2,3], [4,5,6]], ZZ)
        sage: V
        Free module of degree 3 and rank 2 over Integer Ring
        Echelon basis matrix:
        [1 2 3]
        [0 3 6]
        sage: V.linear_combination_of_basis([1,1])
        (1, 5, 9)

    Python

        >>> from sage.all import *
        >>> V = span([[Integer(1),Integer(2),Integer(3)], [Integer(4),Integer(5),Integer(6)]], ZZ)
        >>> V
        Free module of degree 3 and rank 2 over Integer Ring
        Echelon basis matrix:
        [1 2 3]
        [0 3 6]
        >>> V.linear_combination_of_basis([Integer(1),Integer(1)])
        (1, 5, 9)

    This should raise an error if the resulting element is not in self:

    Sage

        sage: W = span([[2,4]], ZZ)
        sage: W.linear_combination_of_basis([1/2])
        Traceback (most recent call last):
        ...
        TypeError: element [1, 2] is not in free module

    [Python]

        >>> from sage.all import *
        >>> W = span([[Integer(2),Integer(4)]], ZZ)
        >>> W.linear_combination_of_basis([Integer(1)/Integer(2)])
        Traceback (most recent call last):
        ...
        TypeError: element [1, 2] is not in free module

  random_element(prob=1.0, *args, **kwds)

    Return a random element of `self`.

    INPUT:

    - `prob` – float. Each coefficient will be set to zero with probability \(1-prob\). Otherwise coefficients will be chosen randomly from base ring (and may be zero).

    - `*args`, `**kwds` – passed on to random_element function of base ring

    EXAMPLES:

    Sage

        sage: M = FreeModule(ZZ, 3)
        sage: M.random_element().parent() is M
        True

    Python

        >>> from sage.all import *
        >>> M = FreeModule(ZZ, Integer(3))
        >>> M.random_element().parent() is M
        True

    Passes extra positional or keyword arguments through:

    Sage

        sage: all(i in range(5, 10) for i in M.random_element(1.0, 5, 10))
        True

    [Python]

        >>> from sage.all import *
        >>> all(i in range(Integer(5), Integer(10)) for i in M.random_element(RealNumber('1.0'), Integer(5), Integer(10)))
        True

    Sage

        sage: M = FreeModule(ZZ, 16)
        sage: M.random_element().parent() is M
        True

        sage: def add_sample(**kwds):
        ....:     global total, zeros
        ....:     v = M.random_element(**kwds)
        ....:     total += M.rank()
        ....:     zeros += sum(i == 0 for i in v)

        sage: total = 0
        sage: zeros = 0
        sage: add_sample()
        sage: expected = 1/5
        sage: while abs(zeros/total - expected) > 0.01:
        ....:     add_sample()

        sage: total = 0
        sage: zeros = 0
        sage: add_sample(prob=0.3)
        sage: expected = 1/5 * 3/10 + 7/10
        sage: while abs(zeros/total - expected) > 0.01:
        ....:     add_sample(prob=0.3)

        sage: total = 0
        sage: zeros = 0
        sage: add_sample(prob=0.7)
        sage: expected = 1/5 * 7/10 + 3/10
        sage: while abs(zeros/total - expected) > 0.01:
        ....:     add_sample(prob=0.7)

    Python

        >>> from sage.all import *
        >>> M = FreeModule(ZZ, Integer(16))
        >>> M.random_element().parent() is M
        True

        >>> def add_sample(**kwds):
        ...     global total, zeros
        ...     v = M.random_element(**kwds)
        ...     total += M.rank()
        ...     zeros += sum(i == Integer(0) for i in v)

        >>> total = Integer(0)
        >>> zeros = Integer(0)
        >>> add_sample()
        >>> expected = Integer(1)/Integer(5)
        >>> while abs(zeros/total - expected) > RealNumber('0.01'):
        ...     add_sample()

        >>> total = Integer(0)
        >>> zeros = Integer(0)
        >>> add_sample(prob=RealNumber('0.3'))
        >>> expected = Integer(1)/Integer(5) * Integer(3)/Integer(10) + Integer(7)/Integer(10)
        >>> while abs(zeros/total - expected) > RealNumber('0.01'):
        ...     add_sample(prob=RealNumber('0.3'))

        >>> total = Integer(0)
        >>> zeros = Integer(0)
        >>> add_sample(prob=RealNumber('0.7'))
        >>> expected = Integer(1)/Integer(5) * Integer(7)/Integer(10) + Integer(3)/Integer(10)
        >>> while abs(zeros/total - expected) > RealNumber('0.01'):
        ...     add_sample(prob=RealNumber('0.7'))

class sage.modules.free_module.FreeModule_ambient_domain(base_ring, rank, sparse=False, coordinate_ring=None, category=None)

  Bases: `FreeModule_generic_domain`, `FreeModule_ambient`

  Ambient free module over an integral domain.

  EXAMPLES:

  Sage

      sage: FreeModule(PolynomialRing(GF(5), 'x'), 3)
      Ambient free module of rank 3 over the principal ideal domain
       Univariate Polynomial Ring in x over Finite Field of size 5

  Python

      >>> from sage.all import *
      >>> FreeModule(PolynomialRing(GF(Integer(5)), 'x'), Integer(3))
      Ambient free module of rank 3 over the principal ideal domain
       Univariate Polynomial Ring in x over Finite Field of size 5

  ambient_vector_space()

    Return the ambient vector space, which is this free module tensored with its fraction field.

    EXAMPLES:

    Sage

        sage: M = ZZ^3
        sage: V = M.ambient_vector_space(); V
        Vector space of dimension 3 over Rational Field

    Python

        >>> from sage.all import *
        >>> M = ZZ**Integer(3)
        >>> V = M.ambient_vector_space(); V
        Vector space of dimension 3 over Rational Field

    If an inner product on the module is specified, then this is preserved on the ambient vector space.

    Sage

        sage: N = FreeModule(ZZ,4,inner_product_matrix=1)
        sage: U = N.ambient_vector_space()
        sage: U
        Ambient quadratic space of dimension 4 over Rational Field
        Inner product matrix:
        [1 0 0 0]
        [0 1 0 0]
        [0 0 1 0]
        [0 0 0 1]
        sage: P = N.submodule_with_basis([[1,-1,0,0],[0,1,-1,0],[0,0,1,-1]])
        sage: P.gram_matrix()
        [ 2 -1  0]
        [-1  2 -1]
        [ 0 -1  2]
        sage: U == N.ambient_vector_space()
        True
        sage: U == V
        False

    [Python]

        >>> from sage.all import *
        >>> N = FreeModule(ZZ,Integer(4),inner_product_matrix=Integer(1))
        >>> U = N.ambient_vector_space()
        >>> U
        Ambient quadratic space of dimension 4 over Rational Field
        Inner product matrix:
        [1 0 0 0]
        [0 1 0 0]
        [0 0 1 0]
        [0 0 0 1]
        >>> P = N.submodule_with_basis([[Integer(1),-Integer(1),Integer(0),Integer(0)],[Integer(0),Integer(1),-Integer(1),Integer(0)],[Integer(0),Integer(0),Integer(1),-Integer(1)]])
        >>> P.gram_matrix()
        [ 2 -1  0]
        [-1  2 -1]
        [ 0 -1  2]
        >>> U == N.ambient_vector_space()
        True
        >>> U == V
        False

  coordinate_vector(v, check=True)

    Write \(v\) in terms of the standard basis for `self` and return the resulting coefficients in a vector over the fraction field of the base ring.

    INPUT:

    - `v` – vector

    - `check` – boolean (default: `True`); if `True`, also verify that \(v\) is really in `self`

    OUTPUT: list

    The output is a vector \(c\) such that if \(B\) is the basis for `self`, then

    \[\sum c_i B_i = v.\]

    If \(v\) is not in self, raise an `ArithmeticError` exception.

    EXAMPLES:

    Sage

        sage: V = ZZ^3
        sage: v = V.coordinate_vector([1,5,9]); v
        (1, 5, 9)
        sage: v.parent()
        Vector space of dimension 3 over Rational Field

    Python

        >>> from sage.all import *
        >>> V = ZZ**Integer(3)
        >>> v = V.coordinate_vector([Integer(1),Integer(5),Integer(9)]); v
        (1, 5, 9)
        >>> v.parent()
        Vector space of dimension 3 over Rational Field

  vector_space(base_field=None)

    Return the vector space obtained from `self` by tensoring with the fraction field of the base ring and extending to the field.

    EXAMPLES:

    Sage

        sage: M = ZZ^3;  M.vector_space()
        Vector space of dimension 3 over Rational Field

    Python

        >>> from sage.all import *
        >>> M = ZZ**Integer(3);  M.vector_space()
        Vector space of dimension 3 over Rational Field

class sage.modules.free_module.FreeModule_ambient_field(base_field, dimension, sparse=False, category=None)

  Bases: `FreeModule_generic_field`, `FreeModule_ambient_pid`

  Create the ambient vector space of given dimension over the given field.

  INPUT:

  - `base_field` – a field

  - `dimension` – nonnegative integer

  - `sparse` – boolean (default: `False`)

  EXAMPLES:

  Sage

      sage: QQ^3
      Vector space of dimension 3 over Rational Field

  Python

      >>> from sage.all import *
      >>> QQ**Integer(3)
      Vector space of dimension 3 over Rational Field

  ambient_vector_space()

    Return `self` as the ambient vector space.

    EXAMPLES:

    Sage

        sage: M = QQ^3
        sage: M.ambient_vector_space()
        Vector space of dimension 3 over Rational Field

    Python

        >>> from sage.all import *
        >>> M = QQ**Integer(3)
        >>> M.ambient_vector_space()
        Vector space of dimension 3 over Rational Field

  base_field()

    Return the base field of this vector space.

    EXAMPLES:

    Sage

        sage: M = QQ^3
        sage: M.base_field()
        Rational Field

    Python

        >>> from sage.all import *
        >>> M = QQ**Integer(3)
        >>> M.base_field()
        Rational Field

class sage.modules.free_module.FreeModule_ambient_pid(base_ring, rank, sparse=False, coordinate_ring=None, category=None)

  Bases: `FreeModule_generic_pid`, `FreeModule_ambient_domain`

  Ambient free module over a principal ideal domain.

class sage.modules.free_module.FreeModule_generic(base_ring, rank, degree, sparse=False, coordinate_ring=None, category=None)

  Bases: `Module_free_ambient`

  Base class for all free modules.

  INPUT:

  - `base_ring` – a commutative ring

  - `rank` – nonnegative integer

  - `degree` – nonnegative integer

  - `sparse` – boolean (default: `False`)

  - `coordinate_ring` – a ring containing `base_ring` (default: equal to `base_ring`)

  - `category` – category (default: `None`)

  If `base_ring` is a field, then the default category is the category of finite-dimensional vector spaces over that field; otherwise it is the category of finite-dimensional free modules over that ring. In addition, the category is intersected with the category of finite enumerated sets if the ring is finite or the rank is 0.

  EXAMPLES:

  Sage

      sage: PolynomialRing(QQ,3,'x')^3
      Ambient free module of rank 3 over the integral domain
       Multivariate Polynomial Ring in x0, x1, x2 over Rational Field

      sage: FreeModule(GF(7), 3).category()
      Category of enumerated finite dimensional vector spaces with basis over
       (finite enumerated fields and subquotients of monoids and quotients of semigroups)
      sage: V = QQ^4; V.category()
      Category of finite dimensional vector spaces with basis over
       (number fields and quotient fields and metric spaces)
      sage: V = GF(5)**20; V.category()
      Category of enumerated finite dimensional vector spaces with basis over
       (finite enumerated fields and subquotients of monoids and quotients of semigroups)
      sage: FreeModule(ZZ,3).category()
      Category of finite dimensional modules with basis over
       (Dedekind domains and euclidean domains
        and noetherian rings and infinite enumerated sets
        and metric spaces)
      sage: (QQ^0).category()
      Category of finite enumerated finite dimensional vector spaces with basis
       over (number fields and quotient fields and metric spaces)

  Python

      >>> from sage.all import *
      >>> PolynomialRing(QQ,Integer(3),'x')**Integer(3)
      Ambient free module of rank 3 over the integral domain
       Multivariate Polynomial Ring in x0, x1, x2 over Rational Field

      >>> FreeModule(GF(Integer(7)), Integer(3)).category()
      Category of enumerated finite dimensional vector spaces with basis over
       (finite enumerated fields and subquotients of monoids and quotients of semigroups)
      >>> V = QQ**Integer(4); V.category()
      Category of finite dimensional vector spaces with basis over
       (number fields and quotient fields and metric spaces)
      >>> V = GF(Integer(5))**Integer(20); V.category()
      Category of enumerated finite dimensional vector spaces with basis over
       (finite enumerated fields and subquotients of monoids and quotients of semigroups)
      >>> FreeModule(ZZ,Integer(3)).category()
      Category of finite dimensional modules with basis over
       (Dedekind domains and euclidean domains
        and noetherian rings and infinite enumerated sets
        and metric spaces)
      >>> (QQ**Integer(0)).category()
      Category of finite enumerated finite dimensional vector spaces with basis
       over (number fields and quotient fields and metric spaces)

  are_linearly_dependent(vecs)

    Return `True` if the vectors `vecs` are linearly dependent and `False` otherwise.

    EXAMPLES:

    Sage

        sage: M = QQ^3
        sage: vecs = [M([1,2,3]), M([4,5,6])]
        sage: M.are_linearly_dependent(vecs)
        False
        sage: vecs.append(M([3,3,3]))
        sage: M.are_linearly_dependent(vecs)
        True

        sage: R.<x> = QQ[]
        sage: M = FreeModule(R, 2)
        sage: vecs = [M([x^2+1, x+1]), M([x+2, 2*x+1])]
        sage: M.are_linearly_dependent(vecs)
        False
        sage: vecs.append(M([-2*x+1, -2*x^2+1]))
        sage: M.are_linearly_dependent(vecs)
        True

    Python

        >>> from sage.all import *
        >>> M = QQ**Integer(3)
        >>> vecs = [M([Integer(1),Integer(2),Integer(3)]), M([Integer(4),Integer(5),Integer(6)])]
        >>> M.are_linearly_dependent(vecs)
        False
        >>> vecs.append(M([Integer(3),Integer(3),Integer(3)]))
        >>> M.are_linearly_dependent(vecs)
        True

        >>> R = QQ['x']; (x,) = R._first_ngens(1)
        >>> M = FreeModule(R, Integer(2))
        >>> vecs = [M([x**Integer(2)+Integer(1), x+Integer(1)]), M([x+Integer(2), Integer(2)*x+Integer(1)])]
        >>> M.are_linearly_dependent(vecs)
        False
        >>> vecs.append(M([-Integer(2)*x+Integer(1), -Integer(2)*x**Integer(2)+Integer(1)]))
        >>> M.are_linearly_dependent(vecs)
        True

  base_field()

    Return the base field, which is the fraction field of the base ring of this module.

    EXAMPLES:

    Sage

        sage: FreeModule(GF(3), 2).base_field()
        Finite Field of size 3
        sage: FreeModule(ZZ, 2).base_field()
        Rational Field
        sage: FreeModule(PolynomialRing(GF(7), 'x'), 2).base_field()
        Fraction Field of Univariate Polynomial Ring in x
         over Finite Field of size 7

    Python

        >>> from sage.all import *
        >>> FreeModule(GF(Integer(3)), Integer(2)).base_field()
        Finite Field of size 3
        >>> FreeModule(ZZ, Integer(2)).base_field()
        Rational Field
        >>> FreeModule(PolynomialRing(GF(Integer(7)), 'x'), Integer(2)).base_field()
        Fraction Field of Univariate Polynomial Ring in x
         over Finite Field of size 7

  basis()

    Return the basis of this module.

    EXAMPLES:

    Sage

        sage: FreeModule(Integers(12),3).basis()
        [(1, 0, 0), (0, 1, 0), (0, 0, 1)]

    Python

        >>> from sage.all import *
        >>> FreeModule(Integers(Integer(12)),Integer(3)).basis()
        [(1, 0, 0), (0, 1, 0), (0, 0, 1)]

  basis_matrix(ring=None)

    Return the matrix whose rows are the basis for this free module.

    INPUT:

    - `ring` – (default: `self.coordinate_ring()`) a ring over which the matrix is defined

    EXAMPLES:

    Sage

        sage: FreeModule(Integers(12), 3).basis_matrix()
        [1 0 0]
        [0 1 0]
        [0 0 1]

    Python

        >>> from sage.all import *
        >>> FreeModule(Integers(Integer(12)), Integer(3)).basis_matrix()
        [1 0 0]
        [0 1 0]
        [0 0 1]

    Sage

        sage: M = FreeModule(GF(7), 3).span([[2,3,4], [1,1,1]]); M
        Vector space of degree 3 and dimension 2 over Finite Field of size 7
        Basis matrix:
        [1 0 6]
        [0 1 2]
        sage: M.basis_matrix()
        [1 0 6]
        [0 1 2]

    [Python]

        >>> from sage.all import *
        >>> M = FreeModule(GF(Integer(7)), Integer(3)).span([[Integer(2),Integer(3),Integer(4)], [Integer(1),Integer(1),Integer(1)]]); M
        Vector space of degree 3 and dimension 2 over Finite Field of size 7
        Basis matrix:
        [1 0 6]
        [0 1 2]
        >>> M.basis_matrix()
        [1 0 6]
        [0 1 2]

    Sage

        sage: M = FreeModule(GF(7), 3).span_of_basis([[2,3,4], [1,1,1]])
        sage: M.basis_matrix()
        [2 3 4]
        [1 1 1]

    Python

        >>> from sage.all import *
        >>> M = FreeModule(GF(Integer(7)), Integer(3)).span_of_basis([[Integer(2),Integer(3),Integer(4)], [Integer(1),Integer(1),Integer(1)]])
        >>> M.basis_matrix()
        [2 3 4]
        [1 1 1]

    Sage

        sage: M = FreeModule(QQ, 2).span_of_basis([[1,-1], [1,0]]); M
        Vector space of degree 2 and dimension 2 over Rational Field
        User basis matrix:
        [ 1 -1]
        [ 1  0]
        sage: M.basis_matrix()
        [ 1 -1]
        [ 1  0]

    [Python]

        >>> from sage.all import *
        >>> M = FreeModule(QQ, Integer(2)).span_of_basis([[Integer(1),-Integer(1)], [Integer(1),Integer(0)]]); M
        Vector space of degree 2 and dimension 2 over Rational Field
        User basis matrix:
        [ 1 -1]
        [ 1  0]
        >>> M.basis_matrix()
        [ 1 -1]
        [ 1  0]

  cardinality()

    Return the cardinality of the free module.

    OUTPUT: either an integer or `+Infinity`

    EXAMPLES:

    Sage

        sage: # needs sage.rings.finite_rings
        sage: k.<a> = FiniteField(9)
        sage: V = VectorSpace(k, 3)
        sage: V.cardinality()
        729
        sage: W = V.span([[1,2,1], [0,1,1]])
        sage: W.cardinality()
        81

        sage: R = IntegerModRing(12)
        sage: M = FreeModule(R, 2)
        sage: M.cardinality()
        144

        sage: (QQ^3).cardinality()
        +Infinity

    Python

        >>> from sage.all import *
        >>> # needs sage.rings.finite_rings
        >>> k = FiniteField(Integer(9), names=('a',)); (a,) = k._first_ngens(1)
        >>> V = VectorSpace(k, Integer(3))
        >>> V.cardinality()
        729
        >>> W = V.span([[Integer(1),Integer(2),Integer(1)], [Integer(0),Integer(1),Integer(1)]])
        >>> W.cardinality()
        81

        >>> R = IntegerModRing(Integer(12))
        >>> M = FreeModule(R, Integer(2))
        >>> M.cardinality()
        144

        >>> (QQ**Integer(3)).cardinality()
        +Infinity

  codimension()

    Return the codimension of this free module, which is the dimension of the ambient space minus the dimension of this free module.

    EXAMPLES:

    Sage

        sage: M = Matrix(3, 4, range(12))
        sage: V = M.left_kernel(); V
        Free module of degree 3 and rank 1 over Integer Ring
        Echelon basis matrix:
        [ 1 -2  1]
        sage: V.dimension()
        1
        sage: V.codimension()
        2

    Python

        >>> from sage.all import *
        >>> M = Matrix(Integer(3), Integer(4), range(Integer(12)))
        >>> V = M.left_kernel(); V
        Free module of degree 3 and rank 1 over Integer Ring
        Echelon basis matrix:
        [ 1 -2  1]
        >>> V.dimension()
        1
        >>> V.codimension()
        2

    The codimension of an ambient space is always zero:

    Sage

        sage: (QQ^10).codimension()
        0

    [Python]

        >>> from sage.all import *
        >>> (QQ**Integer(10)).codimension()
        0

  construction()

    The construction functor and base ring for `self`.

    EXAMPLES:

    Sage

        sage: R = PolynomialRing(QQ, 3, 'x')
        sage: V = R^5
        sage: V.construction()
        (VectorFunctor, Multivariate Polynomial Ring in x0, x1, x2 over Rational Field)

    Python

        >>> from sage.all import *
        >>> R = PolynomialRing(QQ, Integer(3), 'x')
        >>> V = R**Integer(5)
        >>> V.construction()
        (VectorFunctor, Multivariate Polynomial Ring in x0, x1, x2 over Rational Field)

  coordinate_module(V)

    Suppose `V` is a submodule of `self` (or a module commensurable with `self`), and that `self` is a free module over \(R\) of rank \(n\). Let \(\phi\) be the map from `self` to \(R^n\) that sends the basis vectors of `self` in order to the standard basis of \(R^n\). This function returns the image \(\phi(V)\).

    Warning

    If there is no integer \(d\) such that \(dV\) is a submodule of `self`, then this function will give total nonsense.

    EXAMPLES:

    We illustrate this function with some \(\ZZ\)-submodules of \(\QQ^3\):

    Sage

        sage: V = (ZZ^3).span([[1/2,3,5], [0,1,-3]])
        sage: W = (ZZ^3).span([[1/2,4,2]])
        sage: V.coordinate_module(W)
        Free module of degree 2 and rank 1 over Integer Ring
        User basis matrix:
        [1 4]
        sage: V.0 + 4*V.1
        (1/2, 4, 2)

    Python

        >>> from sage.all import *
        >>> V = (ZZ**Integer(3)).span([[Integer(1)/Integer(2),Integer(3),Integer(5)], [Integer(0),Integer(1),-Integer(3)]])
        >>> W = (ZZ**Integer(3)).span([[Integer(1)/Integer(2),Integer(4),Integer(2)]])
        >>> V.coordinate_module(W)
        Free module of degree 2 and rank 1 over Integer Ring
        User basis matrix:
        [1 4]
        >>> V.gen(0) + Integer(4)*V.gen(1)
        (1/2, 4, 2)

    In this example, the coordinate module isn’t even in \(\ZZ^3\):

    Sage

        sage: W = (ZZ^3).span([[1/4,2,1]])
        sage: V.coordinate_module(W)
        Free module of degree 2 and rank 1 over Integer Ring
        User basis matrix:
        [1/2   2]

    [Python]

        >>> from sage.all import *
        >>> W = (ZZ**Integer(3)).span([[Integer(1)/Integer(4),Integer(2),Integer(1)]])
        >>> V.coordinate_module(W)
        Free module of degree 2 and rank 1 over Integer Ring
        User basis matrix:
        [1/2   2]

    The following more elaborate example illustrates using this function to write a submodule in terms of integral cuspidal modular symbols:

    Sage

        sage: # needs sage.modular
        sage: M = ModularSymbols(54)
        sage: S = M.cuspidal_subspace()
        sage: K = S.integral_structure(); K
        Free module of degree 19 and rank 8 over Integer Ring
        Echelon basis matrix:
        [ 0  1  0  0 -1  0  0  0  0  0  0  0  0  0  0  0  0  0  0]
        ...
        sage: L = M[0].integral_structure(); L
        Free module of degree 19 and rank 2 over Integer Ring
        Echelon basis matrix:
        [ 0  1  1  0 -2  1 -1  1 -1 -2  2  0  0  0  0  0  0  0  0]
        [ 0  0  3  0 -3  2 -1  2 -1 -4  2 -1 -2  1  2  0  0 -1  1]
        sage: K.coordinate_module(L)
        Free module of degree 8 and rank 2 over Integer Ring
        User basis matrix:
        [ 1  1  1 -1  1 -1  0  0]
        [ 0  3  2 -1  2 -1 -1 -2]
        sage: K.coordinate_module(L).basis_matrix() * K.basis_matrix()
        [ 0  1  1  0 -2  1 -1  1 -1 -2  2  0  0  0  0  0  0  0  0]
        [ 0  0  3  0 -3  2 -1  2 -1 -4  2 -1 -2  1  2  0  0 -1  1]

    Python

        >>> from sage.all import *
        >>> # needs sage.modular
        >>> M = ModularSymbols(Integer(54))
        >>> S = M.cuspidal_subspace()
        >>> K = S.integral_structure(); K
        Free module of degree 19 and rank 8 over Integer Ring
        Echelon basis matrix:
        [ 0  1  0  0 -1  0  0  0  0  0  0  0  0  0  0  0  0  0  0]
        ...
        >>> L = M[Integer(0)].integral_structure(); L
        Free module of degree 19 and rank 2 over Integer Ring
        Echelon basis matrix:
        [ 0  1  1  0 -2  1 -1  1 -1 -2  2  0  0  0  0  0  0  0  0]
        [ 0  0  3  0 -3  2 -1  2 -1 -4  2 -1 -2  1  2  0  0 -1  1]
        >>> K.coordinate_module(L)
        Free module of degree 8 and rank 2 over Integer Ring
        User basis matrix:
        [ 1  1  1 -1  1 -1  0  0]
        [ 0  3  2 -1  2 -1 -1 -2]
        >>> K.coordinate_module(L).basis_matrix() * K.basis_matrix()
        [ 0  1  1  0 -2  1 -1  1 -1 -2  2  0  0  0  0  0  0  0  0]
        [ 0  0  3  0 -3  2 -1  2 -1 -4  2 -1 -2  1  2  0  0 -1  1]

  coordinate_ring()

    Return the ring over which the entries of the vectors are defined.

    This is the same as `base_ring()` unless an explicit basis was given over the fraction field.

    EXAMPLES:

    Sage

        sage: M = ZZ^2
        sage: M.coordinate_ring()
        Integer Ring

    Python

        >>> from sage.all import *
        >>> M = ZZ**Integer(2)
        >>> M.coordinate_ring()
        Integer Ring

    Sage

        sage: M = (ZZ^2) * (1/2)
        sage: M.base_ring()
        Integer Ring
        sage: M.coordinate_ring()
        Rational Field

    [Python]

        >>> from sage.all import *
        >>> M = (ZZ**Integer(2)) * (Integer(1)/Integer(2))
        >>> M.base_ring()
        Integer Ring
        >>> M.coordinate_ring()
        Rational Field

    Sage

        sage: R.<x> = QQ[]
        sage: L = R^2
        sage: L.coordinate_ring()
        Univariate Polynomial Ring in x over Rational Field
        sage: L.span([(x,0), (1,x)]).coordinate_ring()
        Univariate Polynomial Ring in x over Rational Field
        sage: L.span([(x,0), (1,1/x)]).coordinate_ring()
        Fraction Field of Univariate Polynomial Ring in x over Rational Field
        sage: L.span([]).coordinate_ring()
        Univariate Polynomial Ring in x over Rational Field

    Python

        >>> from sage.all import *
        >>> R = QQ['x']; (x,) = R._first_ngens(1)
        >>> L = R**Integer(2)
        >>> L.coordinate_ring()
        Univariate Polynomial Ring in x over Rational Field
        >>> L.span([(x,Integer(0)), (Integer(1),x)]).coordinate_ring()
        Univariate Polynomial Ring in x over Rational Field
        >>> L.span([(x,Integer(0)), (Integer(1),Integer(1)/x)]).coordinate_ring()
        Fraction Field of Univariate Polynomial Ring in x over Rational Field
        >>> L.span([]).coordinate_ring()
        Univariate Polynomial Ring in x over Rational Field

  coordinate_vector(v, check=True)

    Return the vector whose coefficients give \(v\) as a linear combination of the basis for `self`.

    INPUT:

    - `v` – vector

    - `check` – boolean (default: `True`); if `True`, also verify that \(v\) is really in `self`

    OUTPUT: list

    EXAMPLES:

    Sage

        sage: M = FreeModule(ZZ, 2); M0, M1 = M.gens()
        sage: W = M.submodule([M0 + M1, M0 - 2*M1])
        sage: W.coordinate_vector(2*M0 - M1)
        (2, -1)

    Python

        >>> from sage.all import *
        >>> M = FreeModule(ZZ, Integer(2)); M0, M1 = M.gens()
        >>> W = M.submodule([M0 + M1, M0 - Integer(2)*M1])
        >>> W.coordinate_vector(Integer(2)*M0 - M1)
        (2, -1)

  coordinates(v, check=True)

    Write \(v\) in terms of the basis for `self`.

    INPUT:

    - `v` – vector

    - `check` – boolean (default: `True`); if `True`, also verify that \(v\) is really in `self`

    OUTPUT: list

    Returns a list \(c\) such that if \(B\) is the basis for `self`, then

    \[\sum c_i B_i = v.\]

    If \(v\) is not in self, raise an `ArithmeticError` exception.

    EXAMPLES:

    Sage

        sage: M = FreeModule(ZZ, 2); M0, M1 = M.gens()
        sage: W = M.submodule([M0 + M1, M0 - 2*M1])
        sage: W.coordinates(2*M0 - M1)
        [2, -1]

    Python

        >>> from sage.all import *
        >>> M = FreeModule(ZZ, Integer(2)); M0, M1 = M.gens()
        >>> W = M.submodule([M0 + M1, M0 - Integer(2)*M1])
        >>> W.coordinates(Integer(2)*M0 - M1)
        [2, -1]

  dense_module()

    Return corresponding dense module.

    EXAMPLES:

    We first illustrate conversion with ambient spaces:

    Sage

        sage: M = FreeModule(QQ, 3)
        sage: S = FreeModule(QQ, 3, sparse=True)
        sage: M.sparse_module()
        Sparse vector space of dimension 3 over Rational Field
        sage: S.dense_module()
        Vector space of dimension 3 over Rational Field
        sage: M.sparse_module() == S
        True
        sage: S.dense_module() == M
        True
        sage: M.dense_module() == M
        True
        sage: S.sparse_module() == S
        True

    Python

        >>> from sage.all import *
        >>> M = FreeModule(QQ, Integer(3))
        >>> S = FreeModule(QQ, Integer(3), sparse=True)
        >>> M.sparse_module()
        Sparse vector space of dimension 3 over Rational Field
        >>> S.dense_module()
        Vector space of dimension 3 over Rational Field
        >>> M.sparse_module() == S
        True
        >>> S.dense_module() == M
        True
        >>> M.dense_module() == M
        True
        >>> S.sparse_module() == S
        True

    Next we create a subspace:

    Sage

        sage: M = FreeModule(QQ, 3, sparse=True)
        sage: V = M.span([ [1,2,3] ] ); V
        Sparse vector space of degree 3 and dimension 1 over Rational Field
        Basis matrix:
        [1 2 3]
        sage: V.sparse_module()
        Sparse vector space of degree 3 and dimension 1 over Rational Field
        Basis matrix:
        [1 2 3]

    [Python]

        >>> from sage.all import *
        >>> M = FreeModule(QQ, Integer(3), sparse=True)
        >>> V = M.span([ [Integer(1),Integer(2),Integer(3)] ] ); V
        Sparse vector space of degree 3 and dimension 1 over Rational Field
        Basis matrix:
        [1 2 3]
        >>> V.sparse_module()
        Sparse vector space of degree 3 and dimension 1 over Rational Field
        Basis matrix:
        [1 2 3]

  dimension()

    Return the dimension of this free module.

    EXAMPLES:

    Sage

        sage: M = FreeModule(FiniteField(19), 100)
        sage: W = M.submodule([M.gen(50)])
        sage: W.dimension()
        1

    Python

        >>> from sage.all import *
        >>> M = FreeModule(FiniteField(Integer(19)), Integer(100))
        >>> W = M.submodule([M.gen(Integer(50))])
        >>> W.dimension()
        1

  direct_sum(other)

    Return the direct sum of `self` and `other` as a free module.

    EXAMPLES:

    Sage

        sage: V = (ZZ^3).span([[1/2,3,5], [0,1,-3]]); V
        Free module of degree 3 and rank 2 over Integer Ring
        Echelon basis matrix:
        [1/2   0  14]
        [  0   1  -3]
        sage: W = (ZZ^3).span([[1/2,4,2]]); W
        Free module of degree 3 and rank 1 over Integer Ring
        Echelon basis matrix:
        [1/2   4   2]
        sage: V.direct_sum(W)
        Free module of degree 6 and rank 3 over Integer Ring
        Echelon basis matrix:
        [1/2   0  14   0   0   0]
        [  0   1  -3   0   0   0]
        [  0   0   0 1/2   4   2]

    Python

        >>> from sage.all import *
        >>> V = (ZZ**Integer(3)).span([[Integer(1)/Integer(2),Integer(3),Integer(5)], [Integer(0),Integer(1),-Integer(3)]]); V
        Free module of degree 3 and rank 2 over Integer Ring
        Echelon basis matrix:
        [1/2   0  14]
        [  0   1  -3]
        >>> W = (ZZ**Integer(3)).span([[Integer(1)/Integer(2),Integer(4),Integer(2)]]); W
        Free module of degree 3 and rank 1 over Integer Ring
        Echelon basis matrix:
        [1/2   4   2]
        >>> V.direct_sum(W)
        Free module of degree 6 and rank 3 over Integer Ring
        Echelon basis matrix:
        [1/2   0  14   0   0   0]
        [  0   1  -3   0   0   0]
        [  0   0   0 1/2   4   2]

  discriminant()

    Return the discriminant of this free module.

    EXAMPLES:

    Sage

        sage: M = FreeModule(ZZ, 3)
        sage: M.discriminant()
        1
        sage: W = M.span([[1,2,3]])
        sage: W.discriminant()
        14
        sage: W2 = M.span([[1,2,3], [1,1,1]])
        sage: W2.discriminant()
        6

    Python

        >>> from sage.all import *
        >>> M = FreeModule(ZZ, Integer(3))
        >>> M.discriminant()
        1
        >>> W = M.span([[Integer(1),Integer(2),Integer(3)]])
        >>> W.discriminant()
        14
        >>> W2 = M.span([[Integer(1),Integer(2),Integer(3)], [Integer(1),Integer(1),Integer(1)]])
        >>> W2.discriminant()
        6

  echelonized_basis_matrix()

    The echelonized basis matrix (not implemented for this module).

    This example works because M is an ambient module. Submodule creation should exist for generic modules.

    EXAMPLES:

    Sage

        sage: R = IntegerModRing(12)
        sage: S.<x,y> = R[]
        sage: M = FreeModule(S, 3)
        sage: M.echelonized_basis_matrix()
        [1 0 0]
        [0 1 0]
        [0 0 1]

    Python

        >>> from sage.all import *
        >>> R = IntegerModRing(Integer(12))
        >>> S = R['x, y']; (x, y,) = S._first_ngens(2)
        >>> M = FreeModule(S, Integer(3))
        >>> M.echelonized_basis_matrix()
        [1 0 0]
        [0 1 0]
        [0 0 1]

  free_module()

    Return this free module. (This is used by the `FreeModule` functor, and simply returns self.)

    EXAMPLES:

    Sage

        sage: M = FreeModule(ZZ, 3)
        sage: M.free_module()
        Ambient free module of rank 3 over the principal ideal domain Integer Ring

    Python

        >>> from sage.all import *
        >>> M = FreeModule(ZZ, Integer(3))
        >>> M.free_module()
        Ambient free module of rank 3 over the principal ideal domain Integer Ring

  gen(i=0)

    Return the \(i\)-th generator for `self`.

    Here \(i\) is between 0 and rank - 1, inclusive.

    INPUT:

    - `i` – integer (default: 0)

    OUTPUT: \(i\)-th basis vector for `self`

    EXAMPLES:

    Sage

        sage: n = 5
        sage: V = QQ^n
        sage: B = [V.gen(i) for i in range(n)]
        sage: B
        [(1, 0, 0, 0, 0),
        (0, 1, 0, 0, 0),
        (0, 0, 1, 0, 0),
        (0, 0, 0, 1, 0),
        (0, 0, 0, 0, 1)]
        sage: V.gens() == tuple(B)
        True

    Python

        >>> from sage.all import *
        >>> n = Integer(5)
        >>> V = QQ**n
        >>> B = [V.gen(i) for i in range(n)]
        >>> B
        [(1, 0, 0, 0, 0),
        (0, 1, 0, 0, 0),
        (0, 0, 1, 0, 0),
        (0, 0, 0, 1, 0),
        (0, 0, 0, 0, 1)]
        >>> V.gens() == tuple(B)
        True

  gens()

    Return a tuple of basis elements of `self`.

    EXAMPLES:

    Sage

        sage: FreeModule(Integers(12),3).gens()
        ((1, 0, 0), (0, 1, 0), (0, 0, 1))

    Python

        >>> from sage.all import *
        >>> FreeModule(Integers(Integer(12)),Integer(3)).gens()
        ((1, 0, 0), (0, 1, 0), (0, 0, 1))

  gram_matrix()

    Return the gram matrix associated to this free module, defined to be \(G = B*A*B.transpose()\), where A is the inner product matrix (induced from the ambient space), and B the basis matrix.

    EXAMPLES:

    Sage

        sage: V = VectorSpace(QQ,4)
        sage: u = V([1/2,1/2,1/2,1/2])
        sage: v = V([0,1,1,0])
        sage: w = V([0,0,1,1])
        sage: M = span([u,v,w], ZZ)
        sage: M.inner_product_matrix() == V.inner_product_matrix()
        True
        sage: L = M.submodule_with_basis([u,v,w])
        sage: L.inner_product_matrix() == M.inner_product_matrix()
        True
        sage: L.gram_matrix()
        [1 1 1]
        [1 2 1]
        [1 1 2]

    Python

        >>> from sage.all import *
        >>> V = VectorSpace(QQ,Integer(4))
        >>> u = V([Integer(1)/Integer(2),Integer(1)/Integer(2),Integer(1)/Integer(2),Integer(1)/Integer(2)])
        >>> v = V([Integer(0),Integer(1),Integer(1),Integer(0)])
        >>> w = V([Integer(0),Integer(0),Integer(1),Integer(1)])
        >>> M = span([u,v,w], ZZ)
        >>> M.inner_product_matrix() == V.inner_product_matrix()
        True
        >>> L = M.submodule_with_basis([u,v,w])
        >>> L.inner_product_matrix() == M.inner_product_matrix()
        True
        >>> L.gram_matrix()
        [1 1 1]
        [1 2 1]
        [1 1 2]

  has_user_basis()

    Return `True` if the basis of this free module is specified by the user, as opposed to being the default echelon form.

    EXAMPLES:

    Sage

        sage: V = QQ^3
        sage: W = V.subspace([[2,'1/2', 1]])
        sage: W.has_user_basis()
        False
        sage: W = V.subspace_with_basis([[2,'1/2',1]])
        sage: W.has_user_basis()
        True

    Python

        >>> from sage.all import *
        >>> V = QQ**Integer(3)
        >>> W = V.subspace([[Integer(2),'1/2', Integer(1)]])
        >>> W.has_user_basis()
        False
        >>> W = V.subspace_with_basis([[Integer(2),'1/2',Integer(1)]])
        >>> W.has_user_basis()
        True

  hom(im_gens, codomain=None, **kwds)

    Override the hom method to handle the case of morphisms given by left-multiplication of a matrix and the codomain is not given.

    EXAMPLES:

    Sage

        sage: W = ZZ^2; W.hom(matrix(1, [1, 2]), side='right')
        Free module morphism defined as left-multiplication by the matrix
        [1 2]
        Domain: Ambient free module of rank 2 over the principal ideal domain Integer Ring
        Codomain: Ambient free module of rank 1 over the principal ideal domain Integer Ring
        sage: V = QQ^2; V.hom(identity_matrix(2), side='right')
        Vector space morphism represented as left-multiplication by the matrix:
        [1 0]
        [0 1]
        Domain: Vector space of dimension 2 over Rational Field
        Codomain: Vector space of dimension 2 over Rational Field

    Python

        >>> from sage.all import *
        >>> W = ZZ**Integer(2); W.hom(matrix(Integer(1), [Integer(1), Integer(2)]), side='right')
        Free module morphism defined as left-multiplication by the matrix
        [1 2]
        Domain: Ambient free module of rank 2 over the principal ideal domain Integer Ring
        Codomain: Ambient free module of rank 1 over the principal ideal domain Integer Ring
        >>> V = QQ**Integer(2); V.hom(identity_matrix(Integer(2)), side='right')
        Vector space morphism represented as left-multiplication by the matrix:
        [1 0]
        [0 1]
        Domain: Vector space of dimension 2 over Rational Field
        Codomain: Vector space of dimension 2 over Rational Field

  inner_product_matrix()

    Return the default identity inner product matrix associated to this module.

    By definition this is the inner product matrix of the ambient space, hence may be of degree greater than the rank of the module.

    TODO: Differentiate the image ring of the inner product from the base ring of the module and/or ambient space. E.g. On an integral module over ZZ the inner product pairing could naturally take values in ZZ, QQ, RR, or CC.

    EXAMPLES:

    Sage

        sage: M = FreeModule(ZZ, 3)
        sage: M.inner_product_matrix()
        [1 0 0]
        [0 1 0]
        [0 0 1]

    Python

        >>> from sage.all import *
        >>> M = FreeModule(ZZ, Integer(3))
        >>> M.inner_product_matrix()
        [1 0 0]
        [0 1 0]
        [0 0 1]

  is_ambient()

    Return `False` since this is not an ambient free module.

    EXAMPLES:

    Sage

        sage: M = FreeModule(ZZ, 3).span([[1,2,3]]); M
        Free module of degree 3 and rank 1 over Integer Ring
        Echelon basis matrix:
        [1 2 3]
        sage: M.is_ambient()
        False
        sage: M = (ZZ^2).span([[1,0], [0,1]])
        sage: M
        Free module of degree 2 and rank 2 over Integer Ring
        Echelon basis matrix:
        [1 0]
        [0 1]
        sage: M.is_ambient()
        False
        sage: M == M.ambient_module()
        True

    Python

        >>> from sage.all import *
        >>> M = FreeModule(ZZ, Integer(3)).span([[Integer(1),Integer(2),Integer(3)]]); M
        Free module of degree 3 and rank 1 over Integer Ring
        Echelon basis matrix:
        [1 2 3]
        >>> M.is_ambient()
        False
        >>> M = (ZZ**Integer(2)).span([[Integer(1),Integer(0)], [Integer(0),Integer(1)]])
        >>> M
        Free module of degree 2 and rank 2 over Integer Ring
        Echelon basis matrix:
        [1 0]
        [0 1]
        >>> M.is_ambient()
        False
        >>> M == M.ambient_module()
        True

  is_dense()

    Return `True` if the underlying representation of this module uses dense vectors, and `False` otherwise.

    EXAMPLES:

    Sage

        sage: FreeModule(ZZ, 2).is_dense()
        True
        sage: FreeModule(ZZ, 2, sparse=True).is_dense()
        False

    Python

        >>> from sage.all import *
        >>> FreeModule(ZZ, Integer(2)).is_dense()
        True
        >>> FreeModule(ZZ, Integer(2), sparse=True).is_dense()
        False

  is_finite()

    Return `True` if the underlying set of this free module is finite.

    EXAMPLES:

    Sage

        sage: FreeModule(ZZ, 2).is_finite()
        False
        sage: FreeModule(Integers(8), 2).is_finite()
        True
        sage: FreeModule(ZZ, 0).is_finite()
        True

    Python

        >>> from sage.all import *
        >>> FreeModule(ZZ, Integer(2)).is_finite()
        False
        >>> FreeModule(Integers(Integer(8)), Integer(2)).is_finite()
        True
        >>> FreeModule(ZZ, Integer(0)).is_finite()
        True

  is_full()

    Return `True` if the rank of this module equals its degree.

    EXAMPLES:

    Sage

        sage: FreeModule(ZZ, 2).is_full()
        True
        sage: M = FreeModule(ZZ, 2).span([[1,2]])
        sage: M.is_full()
        False

    Python

        >>> from sage.all import *
        >>> FreeModule(ZZ, Integer(2)).is_full()
        True
        >>> M = FreeModule(ZZ, Integer(2)).span([[Integer(1),Integer(2)]])
        >>> M.is_full()
        False

  is_submodule(other)

    Return `True` if `self` is a submodule of `other`.

    EXAMPLES:

    Sage

        sage: M = FreeModule(ZZ, 3)
        sage: V = M.ambient_vector_space()
        sage: X = V.span([[1/2,1/2,0], [1/2,0,1/2]], ZZ)
        sage: Y = V.span([[1,1,1]], ZZ)
        sage: N = X + Y
        sage: M.is_submodule(X)
        False
        sage: M.is_submodule(Y)
        False
        sage: Y.is_submodule(M)
        True
        sage: N.is_submodule(M)
        False
        sage: M.is_submodule(N)
        True

        sage: M = FreeModule(ZZ, 2)
        sage: M.is_submodule(M)
        True
        sage: N = M.scale(2)
        sage: N.is_submodule(M)
        True
        sage: M.is_submodule(N)
        False
        sage: N = M.scale(1/2)
        sage: N.is_submodule(M)
        False
        sage: M.is_submodule(N)
        True

    Python

        >>> from sage.all import *
        >>> M = FreeModule(ZZ, Integer(3))
        >>> V = M.ambient_vector_space()
        >>> X = V.span([[Integer(1)/Integer(2),Integer(1)/Integer(2),Integer(0)], [Integer(1)/Integer(2),Integer(0),Integer(1)/Integer(2)]], ZZ)
        >>> Y = V.span([[Integer(1),Integer(1),Integer(1)]], ZZ)
        >>> N = X + Y
        >>> M.is_submodule(X)
        False
        >>> M.is_submodule(Y)
        False
        >>> Y.is_submodule(M)
        True
        >>> N.is_submodule(M)
        False
        >>> M.is_submodule(N)
        True

        >>> M = FreeModule(ZZ, Integer(2))
        >>> M.is_submodule(M)
        True
        >>> N = M.scale(Integer(2))
        >>> N.is_submodule(M)
        True
        >>> M.is_submodule(N)
        False
        >>> N = M.scale(Integer(1)/Integer(2))
        >>> N.is_submodule(M)
        False
        >>> M.is_submodule(N)
        True

    Since `basis()` is not implemented in general, submodule testing does not work for all PID’s. However, trivial cases are already used (and useful) for coercion, e.g.:

    Sage

        sage: QQ(1/2) * vector(ZZ['x']['y'], [1,2,3,4])
        (1/2, 1, 3/2, 2)
        sage: vector(ZZ['x']['y'], [1,2,3,4]) * QQ(1/2)
        (1/2, 1, 3/2, 2)

    [Python]

        >>> from sage.all import *
        >>> QQ(Integer(1)/Integer(2)) * vector(ZZ['x']['y'], [Integer(1),Integer(2),Integer(3),Integer(4)])
        (1/2, 1, 3/2, 2)
        >>> vector(ZZ['x']['y'], [Integer(1),Integer(2),Integer(3),Integer(4)]) * QQ(Integer(1)/Integer(2))
        (1/2, 1, 3/2, 2)

  matrix()

    Return the basis matrix of this module, which is the matrix whose rows are a basis for this module.

    EXAMPLES:

    Sage

        sage: M = FreeModule(ZZ, 2)
        sage: M.matrix()
        [1 0]
        [0 1]
        sage: M.submodule([M.gen(0) + M.gen(1), M.gen(0) - 2*M.gen(1)]).matrix()
        [1 1]
        [0 3]

    Python

        >>> from sage.all import *
        >>> M = FreeModule(ZZ, Integer(2))
        >>> M.matrix()
        [1 0]
        [0 1]
        >>> M.submodule([M.gen(Integer(0)) + M.gen(Integer(1)), M.gen(Integer(0)) - Integer(2)*M.gen(Integer(1))]).matrix()
        [1 1]
        [0 3]

  ngens()

    Return the number of basis elements of this free module.

    EXAMPLES:

    Sage

        sage: FreeModule(ZZ, 2).ngens()
        2
        sage: FreeModule(ZZ, 0).ngens()
        0
        sage: FreeModule(ZZ, 2).span([[1,1]]).ngens()
        1

    Python

        >>> from sage.all import *
        >>> FreeModule(ZZ, Integer(2)).ngens()
        2
        >>> FreeModule(ZZ, Integer(0)).ngens()
        0
        >>> FreeModule(ZZ, Integer(2)).span([[Integer(1),Integer(1)]]).ngens()
        1

  nonembedded_free_module()

    Return an ambient free module that is isomorphic to this free module.

    Thus if this free module is of rank \(n\) over a ring \(R\), then this function returns \(R^n\), as an ambient free module.

    EXAMPLES:

    Sage

        sage: FreeModule(ZZ, 2).span([[1,1]]).nonembedded_free_module()
        Ambient free module of rank 1 over the principal ideal domain Integer Ring

    Python

        >>> from sage.all import *
        >>> FreeModule(ZZ, Integer(2)).span([[Integer(1),Integer(1)]]).nonembedded_free_module()
        Ambient free module of rank 1 over the principal ideal domain Integer Ring

  pseudoHom(twist, codomain=None)

    Return the pseudo-Hom space corresponding to given data.

    INPUT:

    - `twist` – the twisting morphism or the twisting derivation

    - `codomain` – (default: `None`) the codomain of the pseudo morphisms; if `None`, the codomain is the same as the domain

    EXAMPLES:

    Sage

        sage: F = GF(25)
        sage: Frob = F.frobenius_endomorphism()
        sage: M = F^2
        sage: M.pseudoHom(Frob)
        Set of Pseudoendomorphisms (twisted by z2 |--> z2^5) of Vector space of dimension 2 over Finite Field in z2 of size 5^2

    Python

        >>> from sage.all import *
        >>> F = GF(Integer(25))
        >>> Frob = F.frobenius_endomorphism()
        >>> M = F**Integer(2)
        >>> M.pseudoHom(Frob)
        Set of Pseudoendomorphisms (twisted by z2 |--> z2^5) of Vector space of dimension 2 over Finite Field in z2 of size 5^2

    See also

    `pseudohom()`

  pseudohom(f, twist, codomain=None, side='left')

    Return the pseudohomomorphism corresponding to the given data.

    We recall that, given two \(R\)-modules \(M\) and \(M'\) together with a ring homomorphism \(\theta: R \to R\) and a \(\theta\)-derivation, \(\delta: R \to R\) (that is, a map such that \(\delta(xy) = \theta(x)\delta(y) + \delta(x)y\)), a pseudomorphism \(f : M \to M'\) is an additive map such that

    \[f(\lambda x) = \theta(\lambda) f(x) + \delta(\lambda) x\]

    When \(\delta\) is nonzero, this requires that \(M\) coerces into \(M'\).

    Note

    Internally, pseudomorphisms are represented by matrices with coefficient in the base ring \(R\). See class `sage.modules.free_module_pseudomorphism.FreeModulePseudoMorphism` for details.

    INPUT:

    - `f` – a matrix (or any other data) defining the pseudomorphism

    - `twist` – the twisting morphism or the twisting derivation (if a derivation is given, the corresponding morphism \(\theta\) is automatically inferred; see also `sage.rings.polynomial.ore_polynomial_ring.OrePolynomialRing`)

    - `codomain` – (default: `None`) the codomain of the pseudo morphisms; if `None`, the codomain is the same than the domain

    - `side` – (default: `left`) side of the vectors acted on by the matrix

    EXAMPLES:

    Sage

        sage: K.<z> = GF(5^5)
        sage: Frob = K.frobenius_endomorphism()
        sage: V = K^2; W = K^3
        sage: f = V.pseudohom([[1, z, z^2], [1, z^2, z^4]], Frob, codomain=W)
        sage: f
        Free module pseudomorphism (twisted by z |--> z^5) defined by the matrix
        [  1   z z^2]
        [  1 z^2 z^4]
        Domain: Vector space of dimension 2 over Finite Field in z of size 5^5
        Codomain: Vector space of dimension 3 over Finite Field in z of size 5^5

    Python

        >>> from sage.all import *
        >>> K = GF(Integer(5)**Integer(5), names=('z',)); (z,) = K._first_ngens(1)
        >>> Frob = K.frobenius_endomorphism()
        >>> V = K**Integer(2); W = K**Integer(3)
        >>> f = V.pseudohom([[Integer(1), z, z**Integer(2)], [Integer(1), z**Integer(2), z**Integer(4)]], Frob, codomain=W)
        >>> f
        Free module pseudomorphism (twisted by z |--> z^5) defined by the matrix
        [  1   z z^2]
        [  1 z^2 z^4]
        Domain: Vector space of dimension 2 over Finite Field in z of size 5^5
        Codomain: Vector space of dimension 3 over Finite Field in z of size 5^5

    We check that \(f\) is indeed semi-linear:

    Sage

        sage: v = V([z+1, z+2])
        sage: f(z*v)
        (2*z^2 + z + 4, z^4 + 2*z^3 + 3*z^2 + z, 4*z^4 + 2*z^2 + 3*z + 2)
        sage: z^5 * f(v)
        (2*z^2 + z + 4, z^4 + 2*z^3 + 3*z^2 + z, 4*z^4 + 2*z^2 + 3*z + 2)

    [Python]

        >>> from sage.all import *
        >>> v = V([z+Integer(1), z+Integer(2)])
        >>> f(z*v)
        (2*z^2 + z + 4, z^4 + 2*z^3 + 3*z^2 + z, 4*z^4 + 2*z^2 + 3*z + 2)
        >>> z**Integer(5) * f(v)
        (2*z^2 + z + 4, z^4 + 2*z^3 + 3*z^2 + z, 4*z^4 + 2*z^2 + 3*z + 2)

    An example with a derivation:

    Sage

        sage: R.<t> = ZZ[]
        sage: d = R.derivation()
        sage: M = R^2
        sage: Nabla = M.pseudohom([[1, t], [t^2, t^3]], d, side='right')
        sage: Nabla
        Free module pseudomorphism (twisted by d/dt) defined as left-multiplication by the matrix
        [  1   t]
        [t^2 t^3]
        Domain: Ambient free module of rank 2 over the integral domain Univariate Polynomial Ring in t over Integer Ring
        Codomain: Ambient free module of rank 2 over the integral domain Univariate Polynomial Ring in t over Integer Ring

        sage: v = M([1,1])
        sage: Nabla(v)
        (t + 1, t^3 + t^2)
        sage: Nabla(t*v)
        (t^2 + t + 1, t^4 + t^3 + 1)
        sage: Nabla(t*v) == t * Nabla(v) + v
        True

    Python

        >>> from sage.all import *
        >>> R = ZZ['t']; (t,) = R._first_ngens(1)
        >>> d = R.derivation()
        >>> M = R**Integer(2)
        >>> Nabla = M.pseudohom([[Integer(1), t], [t**Integer(2), t**Integer(3)]], d, side='right')
        >>> Nabla
        Free module pseudomorphism (twisted by d/dt) defined as left-multiplication by the matrix
        [  1   t]
        [t^2 t^3]
        Domain: Ambient free module of rank 2 over the integral domain Univariate Polynomial Ring in t over Integer Ring
        Codomain: Ambient free module of rank 2 over the integral domain Univariate Polynomial Ring in t over Integer Ring

        >>> v = M([Integer(1),Integer(1)])
        >>> Nabla(v)
        (t + 1, t^3 + t^2)
        >>> Nabla(t*v)
        (t^2 + t + 1, t^4 + t^3 + 1)
        >>> Nabla(t*v) == t * Nabla(v) + v
        True

    If the twisting derivation is not zero, the domain must coerce into the codomain:

    Sage

        sage: N = R^3
        sage: M.pseudohom([[1, t, t^2], [1, t^2, t^4]], d, codomain=N)
        Traceback (most recent call last):
        ...
        ValueError: the domain does not coerce into the codomain

    [Python]

        >>> from sage.all import *
        >>> N = R**Integer(3)
        >>> M.pseudohom([[Integer(1), t, t**Integer(2)], [Integer(1), t**Integer(2), t**Integer(4)]], d, codomain=N)
        Traceback (most recent call last):
        ...
        ValueError: the domain does not coerce into the codomain

    See also

    `pseudoHom()`

  random_element(prob=1.0, *args, **kwds)

    Return a random element of `self`.

    INPUT:

    - `prob` – float. Each coefficient will be set to zero with probability \(1-prob\). Otherwise coefficients will be chosen randomly from base ring (and may be zero).

    - `*args`, `**kwds` – passed on to the `random_element()` function of the base ring

    EXAMPLES:

    Sage

        sage: M = FreeModule(ZZ, 2).span([[1, 1]])
        sage: v = M.random_element()
        sage: v.parent() is M
        True
        sage: v in M
        True

    Python

        >>> from sage.all import *
        >>> M = FreeModule(ZZ, Integer(2)).span([[Integer(1), Integer(1)]])
        >>> v = M.random_element()
        >>> v.parent() is M
        True
        >>> v in M
        True

    Small entries are likely:

    Sage

        sage: for i in [-2, -1, 0, 1, 2]:
        ....:     while vector([i, i]) != M.random_element():
        ....:         pass

    [Python]

        >>> from sage.all import *
        >>> for i in [-Integer(2), -Integer(1), Integer(0), Integer(1), Integer(2)]:
        ...     while vector([i, i]) != M.random_element():
        ...         pass

    Large entries appear as well:

    Sage

        sage: while abs(M.random_element()[0]) < 100:
        ....:     pass

    Python

        >>> from sage.all import *
        >>> while abs(M.random_element()[Integer(0)]) < Integer(100):
        ...     pass

    Passes extra positional or keyword arguments through:

    Sage

        sage: all(i in range(5, 10) for i in M.random_element(1.0, 5, 10))
        True

    [Python]

        >>> from sage.all import *
        >>> all(i in range(Integer(5), Integer(10)) for i in M.random_element(RealNumber('1.0'), Integer(5), Integer(10)))
        True

  rank()

    Return the rank of this free module.

    EXAMPLES:

    Sage

        sage: FreeModule(Integers(6), 10000000).rank()
        10000000
        sage: FreeModule(ZZ, 2).span([[1,1], [2,2], [3,4]]).rank()
        2

    Python

        >>> from sage.all import *
        >>> FreeModule(Integers(Integer(6)), Integer(10000000)).rank()
        10000000
        >>> FreeModule(ZZ, Integer(2)).span([[Integer(1),Integer(1)], [Integer(2),Integer(2)], [Integer(3),Integer(4)]]).rank()
        2

  relations()

    Return the module of relations of `self`.

    EXAMPLES:

    Sage

        sage: V = GF(2)^2
        sage: V.relations() == V.zero_submodule()
        True
        sage: W = V.subspace([[1, 0]])
        sage: W.relations() == V.zero_submodule()
        True

        sage: Q = V / W
        sage: Q.relations() == W
        True

    Python

        >>> from sage.all import *
        >>> V = GF(Integer(2))**Integer(2)
        >>> V.relations() == V.zero_submodule()
        True
        >>> W = V.subspace([[Integer(1), Integer(0)]])
        >>> W.relations() == V.zero_submodule()
        True

        >>> Q = V / W
        >>> Q.relations() == W
        True

  scale(other)

    Return the product of this module by the number other, which is the module spanned by other times each basis vector.

    EXAMPLES:

    Sage

        sage: M = FreeModule(ZZ, 3)
        sage: M.scale(2)
        Free module of degree 3 and rank 3 over Integer Ring
        Echelon basis matrix:
        [2 0 0]
        [0 2 0]
        [0 0 2]

    Python

        >>> from sage.all import *
        >>> M = FreeModule(ZZ, Integer(3))
        >>> M.scale(Integer(2))
        Free module of degree 3 and rank 3 over Integer Ring
        Echelon basis matrix:
        [2 0 0]
        [0 2 0]
        [0 0 2]

    Sage

        sage: a = QQ('1/3')
        sage: M.scale(a)
        Free module of degree 3 and rank 3 over Integer Ring
        Echelon basis matrix:
        [1/3   0   0]
        [  0 1/3   0]
        [  0   0 1/3]

    [Python]

        >>> from sage.all import *
        >>> a = QQ('1/3')
        >>> M.scale(a)
        Free module of degree 3 and rank 3 over Integer Ring
        Echelon basis matrix:
        [1/3   0   0]
        [  0 1/3   0]
        [  0   0 1/3]

  sparse_module()

    Return the corresponding sparse module with the same defining data.

    EXAMPLES:

    We first illustrate conversion with ambient spaces:

    Sage

        sage: M = FreeModule(Integers(8), 3)
        sage: S = FreeModule(Integers(8), 3, sparse=True)
        sage: M.sparse_module()
        Ambient sparse free module of rank 3 over Ring of integers modulo 8
        sage: S.dense_module()
        Ambient free module of rank 3 over Ring of integers modulo 8
        sage: M.sparse_module() is S
        True
        sage: S.dense_module() is M
        True
        sage: M.dense_module() is M
        True
        sage: S.sparse_module() is S
        True

    Python

        >>> from sage.all import *
        >>> M = FreeModule(Integers(Integer(8)), Integer(3))
        >>> S = FreeModule(Integers(Integer(8)), Integer(3), sparse=True)
        >>> M.sparse_module()
        Ambient sparse free module of rank 3 over Ring of integers modulo 8
        >>> S.dense_module()
        Ambient free module of rank 3 over Ring of integers modulo 8
        >>> M.sparse_module() is S
        True
        >>> S.dense_module() is M
        True
        >>> M.dense_module() is M
        True
        >>> S.sparse_module() is S
        True

    Next we convert a subspace:

    Sage

        sage: M = FreeModule(QQ,3)
        sage: V = M.span([ [1,2,3] ] ); V
        Vector space of degree 3 and dimension 1 over Rational Field
        Basis matrix:
        [1 2 3]
        sage: V.sparse_module()
        Sparse vector space of degree 3 and dimension 1 over Rational Field
        Basis matrix:
        [1 2 3]

    [Python]

        >>> from sage.all import *
        >>> M = FreeModule(QQ,Integer(3))
        >>> V = M.span([ [Integer(1),Integer(2),Integer(3)] ] ); V
        Vector space of degree 3 and dimension 1 over Rational Field
        Basis matrix:
        [1 2 3]
        >>> V.sparse_module()
        Sparse vector space of degree 3 and dimension 1 over Rational Field
        Basis matrix:
        [1 2 3]

  uses_ambient_inner_product()

    Return `True` if the inner product on this module is the one induced by the ambient inner product.

    EXAMPLES:

    Sage

        sage: M = FreeModule(ZZ, 2)
        sage: W = M.submodule([[1,2]])
        sage: W.uses_ambient_inner_product()
        True
        sage: W.inner_product_matrix()
        [1 0]
        [0 1]

    Python

        >>> from sage.all import *
        >>> M = FreeModule(ZZ, Integer(2))
        >>> W = M.submodule([[Integer(1),Integer(2)]])
        >>> W.uses_ambient_inner_product()
        True
        >>> W.inner_product_matrix()
        [1 0]
        [0 1]

    Sage

        sage: W.gram_matrix()
        [5]

    [Python]

        >>> from sage.all import *
        >>> W.gram_matrix()
        [5]

class sage.modules.free_module.FreeModule_generic_domain(base_ring, rank, degree, sparse=False, coordinate_ring=None, category=None)

  Bases: `FreeModule_generic`

  Base class for free modules over an integral domain.

class sage.modules.free_module.FreeModule_generic_field(base_field, dimension, degree, sparse=False, category=None)

  Bases: `FreeModule_generic_pid`

  Base class for all free modules over fields.

  complement()

    Return the complement of `self` in the `ambient_vector_space()`.

    EXAMPLES:

    Sage

        sage: V = QQ^3
        sage: V.complement()
        Vector space of degree 3 and dimension 0 over Rational Field
        Basis matrix:
        []
        sage: V == V.complement().complement()
        True
        sage: W = V.span([[1, 0, 1]])
        sage: X = W.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
        True
        sage: X + W == V
        True

    Python

        >>> from sage.all import *
        >>> V = QQ**Integer(3)
        >>> V.complement()
        Vector space of degree 3 and dimension 0 over Rational Field
        Basis matrix:
        []
        >>> V == V.complement().complement()
        True
        >>> W = V.span([[Integer(1), Integer(0), Integer(1)]])
        >>> X = W.complement(); X
        Vector space of degree 3 and dimension 2 over Rational Field
        Basis matrix:
        [ 1  0 -1]
        [ 0  1  0]
        >>> X.complement() == W
        True
        >>> X + W == V
        True

    Even though we construct a subspace of a subspace, the orthogonal complement is still done in the ambient vector space \(\QQ^3\):

    Sage

        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()
        Vector space of degree 3 and dimension 2 over Rational Field
        Basis matrix:
        [ 1  0 -1]
        [ 0  1  0]

    [Python]

        >>> from sage.all import *
        >>> V = QQ**Integer(3)
        >>> W = V.subspace_with_basis([[Integer(1),Integer(0),Integer(1)],[-Integer(1),Integer(1),Integer(0)]])
        >>> X = W.subspace_with_basis([[Integer(1),Integer(0),Integer(1)]])
        >>> X.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 product in the usual basis. Over finite fields, this means we can get complements which are only isomorphic to a vector space decomposition complement.

    Sage

        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()
        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())
        Vector space of degree 6 and dimension 1 over Finite Field of size 2
        Basis matrix:
        [1 1 0 0 0 0]

    Python

        >>> from sage.all import *
        >>> F2 = GF(Integer(2), 'x')
        >>> V = F2**Integer(6)
        >>> W = V.span([[Integer(1),Integer(1),Integer(0),Integer(0),Integer(0),Integer(0)]]); W
        Vector space of degree 6 and dimension 1 over Finite Field of size 2
        Basis matrix:
        [1 1 0 0 0 0]
        >>> W.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]
        >>> W.intersection(W.complement())
        Vector space of degree 6 and dimension 1 over Finite Field of size 2
        Basis matrix:
        [1 1 0 0 0 0]

  echelonized_basis_matrix()

    Return basis matrix for `self` in row echelon form.

    EXAMPLES:

    Sage

        sage: V = FreeModule(QQ, 3).span_of_basis([[1,2,3],[4,5,6]])
        sage: V.basis_matrix()
        [1 2 3]
        [4 5 6]
        sage: V.echelonized_basis_matrix()
        [ 1  0 -1]
        [ 0  1  2]

    Python

        >>> from sage.all import *
        >>> V = FreeModule(QQ, Integer(3)).span_of_basis([[Integer(1),Integer(2),Integer(3)],[Integer(4),Integer(5),Integer(6)]])
        >>> V.basis_matrix()
        [1 2 3]
        [4 5 6]
        >>> V.echelonized_basis_matrix()
        [ 1  0 -1]
        [ 0  1  2]

  intersection(other)

    Return the intersection of `self` and `other`, which must be \(R\)-submodules of a common ambient vector space.

    EXAMPLES:

    Sage

        sage: V  = VectorSpace(QQ,3)
        sage: W1 = V.submodule([V.gen(0), V.gen(0) + V.gen(1)])
        sage: W2 = V.submodule([V.gen(1), V.gen(2)])
        sage: W1.intersection(W2)
        Vector space of degree 3 and dimension 1 over Rational Field
        Basis matrix:
        [0 1 0]
        sage: W2.intersection(W1)
        Vector space of degree 3 and dimension 1 over Rational Field
        Basis matrix:
        [0 1 0]
        sage: V.intersection(W1)
        Vector space of degree 3 and dimension 2 over Rational Field
        Basis matrix:
        [1 0 0]
        [0 1 0]
        sage: W1.intersection(V)
        Vector space of degree 3 and dimension 2 over Rational Field
        Basis matrix:
        [1 0 0]
        [0 1 0]
        sage: Z = V.submodule([])
        sage: W1.intersection(Z)
        Vector space of degree 3 and dimension 0 over Rational Field
        Basis matrix:
        []

    Python

        >>> from sage.all import *
        >>> V  = VectorSpace(QQ,Integer(3))
        >>> W1 = V.submodule([V.gen(Integer(0)), V.gen(Integer(0)) + V.gen(Integer(1))])
        >>> W2 = V.submodule([V.gen(Integer(1)), V.gen(Integer(2))])
        >>> W1.intersection(W2)
        Vector space of degree 3 and dimension 1 over Rational Field
        Basis matrix:
        [0 1 0]
        >>> W2.intersection(W1)
        Vector space of degree 3 and dimension 1 over Rational Field
        Basis matrix:
        [0 1 0]
        >>> V.intersection(W1)
        Vector space of degree 3 and dimension 2 over Rational Field
        Basis matrix:
        [1 0 0]
        [0 1 0]
        >>> W1.intersection(V)
        Vector space of degree 3 and dimension 2 over Rational Field
        Basis matrix:
        [1 0 0]
        [0 1 0]
        >>> Z = V.submodule([])
        >>> W1.intersection(Z)
        Vector space of degree 3 and dimension 0 over Rational Field
        Basis matrix:
        []

  is_subspace(other)

    `True` if this vector space is a subspace of `other`.

    EXAMPLES:

    Sage

        sage: V = VectorSpace(QQ,3)
        sage: W = V.subspace([V.gen(0), V.gen(0) + V.gen(1)])
        sage: W2 = V.subspace([V.gen(1)])
        sage: W.is_subspace(V)
        True
        sage: W2.is_subspace(V)
        True
        sage: W.is_subspace(W2)
        False
        sage: W2.is_subspace(W)
        True

    Python

        >>> from sage.all import *
        >>> V = VectorSpace(QQ,Integer(3))
        >>> W = V.subspace([V.gen(Integer(0)), V.gen(Integer(0)) + V.gen(Integer(1))])
        >>> W2 = V.subspace([V.gen(Integer(1))])
        >>> W.is_subspace(V)
        True
        >>> W2.is_subspace(V)
        True
        >>> W.is_subspace(W2)
        False
        >>> W2.is_subspace(W)
        True

  linear_dependence(vectors, zeros='left', check=True)

    Return a list of vectors giving relations of linear dependence for the input list of vectors.

    Can be used to check linear independence of a set of vectors.

    INPUT:

    - `vectors` – list of vectors; all from the same vector space

    - `zeros` – (default: `'left'`) `'left'` or `'right'` as a general preference for where zeros are located in the returned coefficients

    - `check` – (default: `True`) if `True` each item in the list `vectors` is checked for membership in `self`. Set to `False` if you can be certain the vectors come from the vector space.

    OUTPUT:

    Returns a list of vectors. The scalar entries of each vector provide the coefficients for a linear combination of the input vectors that will equal the zero vector in `self`. Furthermore, the returned list is linearly independent in the vector space over the same base field with degree equal to the length of the list `vectors`.

    The linear independence of `vectors` is equivalent to the returned list being empty, so this provides a test - see the examples below.

    The returned vectors are always independent, and with `zeros` set to `'left'` they have 1s in their first nonzero entries and a qualitative disposition to having zeros in the low-index entries. With `zeros` set to `'right'` the situation is reversed with a qualitative disposition for zeros in the high-index entries.

    If the vectors in `vectors` are made the rows of a matrix \(V\) and the returned vectors are made the rows of a matrix \(R\), then the matrix product \(RV\) is a zero matrix of the proper size. And \(R\) is a matrix of full rank. This routine uses kernels of matrices to compute these relations of linear dependence, but handles all the conversions between sets of vectors and matrices. If speed is important, consider working with the appropriate matrices and kernels instead.

    EXAMPLES:

    We begin with two linearly independent vectors, and add three non-trivial linear combinations to the set. We illustrate both types of output and check a selected relation of linear dependence.

    Sage

        sage: v1 = vector(QQ, [2, 1, -4, 3])
        sage: v2 = vector(QQ, [1, 5, 2, -2])
        sage: V = QQ^4
        sage: V.linear_dependence([v1,v2])
        []

        sage: v3 = v1 + v2
        sage: v4 = 3*v1 - 4*v2
        sage: v5 = -v1 + 2*v2
        sage: L = [v1, v2, v3, v4, v5]

        sage: relations = V.linear_dependence(L, zeros='left')
        sage: relations
        [(1, 0, 0, -1, -2), (0, 1, 0, -1/2, -3/2), (0, 0, 1, -3/2, -7/2)]
        sage: v2 + (-1/2)*v4 + (-3/2)*v5
        (0, 0, 0, 0)

        sage: relations = V.linear_dependence(L, zeros='right')
        sage: relations
        [(-1, -1, 1, 0, 0), (-3, 4, 0, 1, 0), (1, -2, 0, 0, 1)]
        sage: z = sum([relations[2][i]*L[i] for i in range(len(L))])
        sage: z == zero_vector(QQ, 4)
        True

    Python

        >>> from sage.all import *
        >>> v1 = vector(QQ, [Integer(2), Integer(1), -Integer(4), Integer(3)])
        >>> v2 = vector(QQ, [Integer(1), Integer(5), Integer(2), -Integer(2)])
        >>> V = QQ**Integer(4)
        >>> V.linear_dependence([v1,v2])
        []

        >>> v3 = v1 + v2
        >>> v4 = Integer(3)*v1 - Integer(4)*v2
        >>> v5 = -v1 + Integer(2)*v2
        >>> L = [v1, v2, v3, v4, v5]

        >>> relations = V.linear_dependence(L, zeros='left')
        >>> relations
        [(1, 0, 0, -1, -2), (0, 1, 0, -1/2, -3/2), (0, 0, 1, -3/2, -7/2)]
        >>> v2 + (-Integer(1)/Integer(2))*v4 + (-Integer(3)/Integer(2))*v5
        (0, 0, 0, 0)

        >>> relations = V.linear_dependence(L, zeros='right')
        >>> relations
        [(-1, -1, 1, 0, 0), (-3, 4, 0, 1, 0), (1, -2, 0, 0, 1)]
        >>> z = sum([relations[Integer(2)][i]*L[i] for i in range(len(L))])
        >>> z == zero_vector(QQ, Integer(4))
        True

    A linearly independent set returns an empty list, a result that can be tested.

    Sage

        sage: v1 = vector(QQ, [0,1,-3])
        sage: v2 = vector(QQ, [4,1,0])
        sage: V = QQ^3
        sage: relations = V.linear_dependence([v1, v2]); relations
        []
        sage: relations == []
        True

    [Python]

        >>> from sage.all import *
        >>> v1 = vector(QQ, [Integer(0),Integer(1),-Integer(3)])
        >>> v2 = vector(QQ, [Integer(4),Integer(1),Integer(0)])
        >>> V = QQ**Integer(3)
        >>> relations = V.linear_dependence([v1, v2]); relations
        []
        >>> relations == []
        True

    Exact results result from exact fields. We start with three linearly independent vectors and add in two linear combinations to make a linearly dependent set of five vectors.

    Sage

        sage: F = FiniteField(17)
        sage: v1 = vector(F, [1, 2, 3, 4, 5])
        sage: v2 = vector(F, [2, 4, 8, 16, 15])
        sage: v3 = vector(F, [1, 0, 0, 0, 1])
        sage: (F^5).linear_dependence([v1, v2, v3]) == []
        True
        sage: L = [v1, v2, v3, 2*v1+v2, 3*v2+6*v3]
        sage: (F^5).linear_dependence(L)
        [(1, 0, 16, 8, 3), (0, 1, 2, 0, 11)]
        sage: v1 + 16*v3 + 8*(2*v1+v2) + 3*(3*v2+6*v3)
        (0, 0, 0, 0, 0)
        sage: v2 + 2*v3 + 11*(3*v2+6*v3)
        (0, 0, 0, 0, 0)
        sage: (F^5).linear_dependence(L, zeros='right')
        [(15, 16, 0, 1, 0), (0, 14, 11, 0, 1)]

    Python

        >>> from sage.all import *
        >>> F = FiniteField(Integer(17))
        >>> v1 = vector(F, [Integer(1), Integer(2), Integer(3), Integer(4), Integer(5)])
        >>> v2 = vector(F, [Integer(2), Integer(4), Integer(8), Integer(16), Integer(15)])
        >>> v3 = vector(F, [Integer(1), Integer(0), Integer(0), Integer(0), Integer(1)])
        >>> (F**Integer(5)).linear_dependence([v1, v2, v3]) == []
        True
        >>> L = [v1, v2, v3, Integer(2)*v1+v2, Integer(3)*v2+Integer(6)*v3]
        >>> (F**Integer(5)).linear_dependence(L)
        [(1, 0, 16, 8, 3), (0, 1, 2, 0, 11)]
        >>> v1 + Integer(16)*v3 + Integer(8)*(Integer(2)*v1+v2) + Integer(3)*(Integer(3)*v2+Integer(6)*v3)
        (0, 0, 0, 0, 0)
        >>> v2 + Integer(2)*v3 + Integer(11)*(Integer(3)*v2+Integer(6)*v3)
        (0, 0, 0, 0, 0)
        >>> (F**Integer(5)).linear_dependence(L, zeros='right')
        [(15, 16, 0, 1, 0), (0, 14, 11, 0, 1)]

  quotient_abstract(sub, check=True, **kwds)

    Return an ambient free module isomorphic to the quotient space of `self` modulo `sub`, together with maps from `self` to the quotient, and a lifting map in the other direction.

    Use `self.quotient(sub)` to obtain the quotient module as an object equipped with natural maps in both directions, and a canonical coercion.

    INPUT:

    - `sub` – a submodule of `self` or something that can be turned into one via `self.submodule(sub)`

    - `check` – boolean (default: `True`); whether or not to check that sub is a submodule

    - further named arguments, that are currently ignored.

    OUTPUT:

    - `U`; the quotient as an abstract ambient free module

    - `pi`; projection map to the quotient

    - `lift`; lifting map back from quotient

    EXAMPLES:

    Sage

        sage: V = GF(19)^3
        sage: W = V.span_of_basis([[1,2,3], [1,0,1]])
        sage: U, pi, lift = V.quotient_abstract(W)
        sage: pi(V.2)
        (18)
        sage: pi(V.0)
        (1)
        sage: pi(V.0 + V.2)
        (0)

    Python

        >>> from sage.all import *
        >>> V = GF(Integer(19))**Integer(3)
        >>> W = V.span_of_basis([[Integer(1),Integer(2),Integer(3)], [Integer(1),Integer(0),Integer(1)]])
        >>> U, pi, lift = V.quotient_abstract(W)
        >>> pi(V.gen(2))
        (18)
        >>> pi(V.gen(0))
        (1)
        >>> pi(V.gen(0) + V.gen(2))
        (0)

    Another example involving a quotient of one subspace by another:

    Sage

        sage: A = matrix(QQ, 4,4, [0,1,0,0, 0,0,1,0, 0,0,0,1, 0,0,0,0])
        sage: V = (A^3).kernel()
        sage: W = A.kernel()
        sage: U, pi, lift = V.quotient_abstract(W)
        sage: [pi(v) == 0 for v in W.gens()]
        [True]
        sage: [pi(lift(b)) == b for b in U.basis()]
        [True, True]

    [Python]

        >>> from sage.all import *
        >>> A = matrix(QQ, Integer(4),Integer(4), [Integer(0),Integer(1),Integer(0),Integer(0), Integer(0),Integer(0),Integer(1),Integer(0), Integer(0),Integer(0),Integer(0),Integer(1), Integer(0),Integer(0),Integer(0),Integer(0)])
        >>> V = (A**Integer(3)).kernel()
        >>> W = A.kernel()
        >>> U, pi, lift = V.quotient_abstract(W)
        >>> [pi(v) == Integer(0) for v in W.gens()]
        [True]
        >>> [pi(lift(b)) == b for b in U.basis()]
        [True, True]

  quotient_module(sub, check=True)

    Return the quotient of `self` by the given subspace sub.

    INPUT:

    - `sub` – a submodule of `self`, or something that can be turned into one via `self.submodule(sub)`

    - `check` – boolean (default: `True`); whether or not to check that `sub` is a submodule

    EXAMPLES:

    Sage

        sage: A = QQ^3; V = A.span([[1,2,3], [4,5,6]])
        sage: Q = V.quotient( [V.0 + V.1] ); Q
        Vector space quotient V/W of dimension 1 over Rational Field where
        V: Vector space of degree 3 and dimension 2 over Rational Field
        Basis matrix:
        [ 1  0 -1]
        [ 0  1  2]
        W: Vector space of degree 3 and dimension 1 over Rational Field
        Basis matrix:
        [1 1 1]
        sage: Q(V.0 + V.1)
        (0)

    Python

        >>> from sage.all import *
        >>> A = QQ**Integer(3); V = A.span([[Integer(1),Integer(2),Integer(3)], [Integer(4),Integer(5),Integer(6)]])
        >>> Q = V.quotient( [V.gen(0) + V.gen(1)] ); Q
        Vector space quotient V/W of dimension 1 over Rational Field where
        V: Vector space of degree 3 and dimension 2 over Rational Field
        Basis matrix:
        [ 1  0 -1]
        [ 0  1  2]
        W: Vector space of degree 3 and dimension 1 over Rational Field
        Basis matrix:
        [1 1 1]
        >>> Q(V.gen(0) + V.gen(1))
        (0)

    We illustrate that the base rings must be the same:

    Sage

        sage: (QQ^2)/(ZZ^2)
        Traceback (most recent call last):
        ...
        ValueError: base rings must be the same

    [Python]

        >>> from sage.all import *
        >>> (QQ**Integer(2))/(ZZ**Integer(2))
        Traceback (most recent call last):
        ...
        ValueError: base rings must be the same

  scale(other)

    Return the product of `self` by the number other, which is the module spanned by `other` times each basis vector. Since `self` is a vector space this product equals `self` if `other` is nonzero, and is the zero vector space if `other` is 0.

    EXAMPLES:

    Sage

        sage: V = QQ^4
        sage: V.scale(5)
        Vector space of dimension 4 over Rational Field
        sage: V.scale(0)
        Vector space of degree 4 and dimension 0 over Rational Field
        Basis matrix:
        []

    Python

        >>> from sage.all import *
        >>> V = QQ**Integer(4)
        >>> V.scale(Integer(5))
        Vector space of dimension 4 over Rational Field
        >>> V.scale(Integer(0))
        Vector space of degree 4 and dimension 0 over Rational Field
        Basis matrix:
        []

    Sage

        sage: W = V.span([[1,1,1,1]])
        sage: W.scale(2)
        Vector space of degree 4 and dimension 1 over Rational Field
        Basis matrix:
        [1 1 1 1]
        sage: W.scale(0)
        Vector space of degree 4 and dimension 0 over Rational Field
        Basis matrix:
        []

    [Python]

        >>> from sage.all import *
        >>> W = V.span([[Integer(1),Integer(1),Integer(1),Integer(1)]])
        >>> W.scale(Integer(2))
        Vector space of degree 4 and dimension 1 over Rational Field
        Basis matrix:
        [1 1 1 1]
        >>> W.scale(Integer(0))
        Vector space of degree 4 and dimension 0 over Rational Field
        Basis matrix:
        []

    Sage

        sage: V = QQ^4; V
        Vector space of dimension 4 over Rational Field
        sage: V.scale(3)
        Vector space of dimension 4 over Rational Field
        sage: V.scale(0)
        Vector space of degree 4 and dimension 0 over Rational Field
        Basis matrix:
        []

    Python

        >>> from sage.all import *
        >>> V = QQ**Integer(4); V
        Vector space of dimension 4 over Rational Field
        >>> V.scale(Integer(3))
        Vector space of dimension 4 over Rational Field
        >>> V.scale(Integer(0))
        Vector space of degree 4 and dimension 0 over Rational Field
        Basis matrix:
        []

  span_of_basis(basis, base_ring=None, check=True, already_echelonized=False)

    Return the free K-module with the given basis, where K is the base field of `self` or user specified base_ring.

    Note that this span is a subspace of the ambient vector space, but need not be a subspace of `self`.

    INPUT:

    - `basis` – list of vectors

    - `check` – boolean (default: `True`); whether or not to coerce entries of gens into base field

    - `already_echelonized` – boolean (default: `False`); set this if you know the gens are already in echelon form

    EXAMPLES:

    Sage

        sage: V = VectorSpace(GF(7), 3)
        sage: W = V.subspace([[2,3,4]]); W
        Vector space of degree 3 and dimension 1 over Finite Field of size 7
        Basis matrix:
        [1 5 2]
        sage: W.span_of_basis([[2,2,2], [3,3,0]])
        Vector space of degree 3 and dimension 2 over Finite Field of size 7
        User basis matrix:
        [2 2 2]
        [3 3 0]

    Python

        >>> from sage.all import *
        >>> V = VectorSpace(GF(Integer(7)), Integer(3))
        >>> W = V.subspace([[Integer(2),Integer(3),Integer(4)]]); W
        Vector space of degree 3 and dimension 1 over Finite Field of size 7
        Basis matrix:
        [1 5 2]
        >>> W.span_of_basis([[Integer(2),Integer(2),Integer(2)], [Integer(3),Integer(3),Integer(0)]])
        Vector space of degree 3 and dimension 2 over Finite Field of size 7
        User basis matrix:
        [2 2 2]
        [3 3 0]

    The basis vectors must be linearly independent or a `ValueError` exception is raised:

    Sage

        sage: W.span_of_basis([[2,2,2], [3,3,3]])
        Traceback (most recent call last):
        ...
        ValueError: the given basis vectors must be linearly independent

    [Python]

        >>> from sage.all import *
        >>> W.span_of_basis([[Integer(2),Integer(2),Integer(2)], [Integer(3),Integer(3),Integer(3)]])
        Traceback (most recent call last):
        ...
        ValueError: the given basis vectors must be linearly independent

  subspace(gens, check=True, already_echelonized=False)

    Return the subspace of `self` spanned by the elements of gens.

    INPUT:

    - `gens` – list of vectors

    - `check` – boolean (default: `True`); verify that gens are all in `self`

    - `already_echelonized` – boolean (default: `False`); set to `True` if you know the gens are in Echelon form

    EXAMPLES:

    First we create a 1-dimensional vector subspace of an ambient \(3\)-dimensional space over the finite field of order \(7\):

    Sage

        sage: V = VectorSpace(GF(7), 3)
        sage: W = V.subspace([[2,3,4]]); W
        Vector space of degree 3 and dimension 1 over Finite Field of size 7
        Basis matrix:
        [1 5 2]

    Python

        >>> from sage.all import *
        >>> V = VectorSpace(GF(Integer(7)), Integer(3))
        >>> W = V.subspace([[Integer(2),Integer(3),Integer(4)]]); W
        Vector space of degree 3 and dimension 1 over Finite Field of size 7
        Basis matrix:
        [1 5 2]

    Next we create an invalid subspace, but it’s allowed since `check=False`. This is just equivalent to computing the span of the element:

    Sage

        sage: W.subspace([[1,1,0]], check=False)
        Vector space of degree 3 and dimension 1 over Finite Field of size 7
        Basis matrix:
        [1 1 0]

    [Python]

        >>> from sage.all import *
        >>> W.subspace([[Integer(1),Integer(1),Integer(0)]], check=False)
        Vector space of degree 3 and dimension 1 over Finite Field of size 7
        Basis matrix:
        [1 1 0]

    With `check=True` (the default) the mistake is correctly detected and reported with an `ArithmeticError` exception:

    Sage

        sage: W.subspace([[1,1,0]], check=True)
        Traceback (most recent call last):
        ...
        ArithmeticError: argument gens (= [[1, 1, 0]]) does not generate a submodule of self

    Python

        >>> from sage.all import *
        >>> W.subspace([[Integer(1),Integer(1),Integer(0)]], check=True)
        Traceback (most recent call last):
        ...
        ArithmeticError: argument gens (= [[1, 1, 0]]) does not generate a submodule of self

  subspace_with_basis(gens, check=True, already_echelonized=False)

    Same as `self.submodule_with_basis(...)`.

    EXAMPLES:

    We create a subspace with a user-defined basis.

    Sage

        sage: V = VectorSpace(GF(7), 3)
        sage: W = V.subspace_with_basis([[2,2,2], [1,2,3]]); W
        Vector space of degree 3 and dimension 2 over Finite Field of size 7
        User basis matrix:
        [2 2 2]
        [1 2 3]

    Python

        >>> from sage.all import *
        >>> V = VectorSpace(GF(Integer(7)), Integer(3))
        >>> W = V.subspace_with_basis([[Integer(2),Integer(2),Integer(2)], [Integer(1),Integer(2),Integer(3)]]); W
        Vector space of degree 3 and dimension 2 over Finite Field of size 7
        User basis matrix:
        [2 2 2]
        [1 2 3]

    We then create a subspace of the subspace with user-defined basis.

    Sage

        sage: W1 = W.subspace_with_basis([[3,4,5]]); W1
        Vector space of degree 3 and dimension 1 over Finite Field of size 7
        User basis matrix:
        [3 4 5]

    [Python]

        >>> from sage.all import *
        >>> W1 = W.subspace_with_basis([[Integer(3),Integer(4),Integer(5)]]); W1
        Vector space of degree 3 and dimension 1 over Finite Field of size 7
        User basis matrix:
        [3 4 5]

    Notice how the basis for the same subspace is different if we merely use the `subspace` command.

    Sage

        sage: W2 = W.subspace([[3,4,5]]); W2
        Vector space of degree 3 and dimension 1 over Finite Field of size 7
        Basis matrix:
        [1 6 4]

    Python

        >>> from sage.all import *
        >>> W2 = W.subspace([[Integer(3),Integer(4),Integer(5)]]); W2
        Vector space of degree 3 and dimension 1 over Finite Field of size 7
        Basis matrix:
        [1 6 4]

    Nonetheless the two subspaces are equal (as mathematical objects):

    Sage

        sage: W1 == W2
        True

    [Python]

        >>> from sage.all import *
        >>> W1 == W2
        True

  subspaces(dim)

    Iterate over all subspaces of dimension dim.

    INPUT:

    - `dim` – integer; dimension of subspaces to be generated

    EXAMPLES:

    Sage

        sage: V = VectorSpace(GF(3), 5)
        sage: len(list(V.subspaces(0)))
        1
        sage: len(list(V.subspaces(1)))
        121
        sage: len(list(V.subspaces(2)))
        1210
        sage: len(list(V.subspaces(3)))
        1210
        sage: len(list(V.subspaces(4)))
        121
        sage: len(list(V.subspaces(5)))
        1

    Python

        >>> from sage.all import *
        >>> V = VectorSpace(GF(Integer(3)), Integer(5))
        >>> len(list(V.subspaces(Integer(0))))
        1
        >>> len(list(V.subspaces(Integer(1))))
        121
        >>> len(list(V.subspaces(Integer(2))))
        1210
        >>> len(list(V.subspaces(Integer(3))))
        1210
        >>> len(list(V.subspaces(Integer(4))))
        121
        >>> len(list(V.subspaces(Integer(5))))
        1

    Sage

        sage: V = VectorSpace(GF(3), 5)
        sage: V = V.subspace([V([1,1,0,0,0]), V([0,0,1,1,0])])
        sage: list(V.subspaces(1))
        [Vector space of degree 5 and dimension 1 over Finite Field of size 3
        Basis matrix:
        [1 1 0 0 0],
         Vector space of degree 5 and dimension 1 over Finite Field of size 3
        Basis matrix:
        [1 1 1 1 0],
         Vector space of degree 5 and dimension 1 over Finite Field of size 3
        Basis matrix:
        [1 1 2 2 0],
         Vector space of degree 5 and dimension 1 over Finite Field of size 3
        Basis matrix:
        [0 0 1 1 0]]

    [Python]

        >>> from sage.all import *
        >>> V = VectorSpace(GF(Integer(3)), Integer(5))
        >>> V = V.subspace([V([Integer(1),Integer(1),Integer(0),Integer(0),Integer(0)]), V([Integer(0),Integer(0),Integer(1),Integer(1),Integer(0)])])
        >>> list(V.subspaces(Integer(1)))
        [Vector space of degree 5 and dimension 1 over Finite Field of size 3
        Basis matrix:
        [1 1 0 0 0],
         Vector space of degree 5 and dimension 1 over Finite Field of size 3
        Basis matrix:
        [1 1 1 1 0],
         Vector space of degree 5 and dimension 1 over Finite Field of size 3
        Basis matrix:
        [1 1 2 2 0],
         Vector space of degree 5 and dimension 1 over Finite Field of size 3
        Basis matrix:
        [0 0 1 1 0]]

  vector_space(base_field=None)

    Return the vector space associated to `self`. Since `self` is a vector space this function simply returns `self`, unless the base field is different.

    EXAMPLES:

    Sage

        sage: V = span([[1,2,3]],QQ); V
        Vector space of degree 3 and dimension 1 over Rational Field
        Basis matrix:
        [1 2 3]
        sage: V.vector_space()
        Vector space of degree 3 and dimension 1 over Rational Field
        Basis matrix:
        [1 2 3]

    Python

        >>> from sage.all import *
        >>> V = span([[Integer(1),Integer(2),Integer(3)]],QQ); V
        Vector space of degree 3 and dimension 1 over Rational Field
        Basis matrix:
        [1 2 3]
        >>> V.vector_space()
        Vector space of degree 3 and dimension 1 over Rational Field
        Basis matrix:
        [1 2 3]

  zero_submodule()

    Return the zero submodule of `self`.

    EXAMPLES:

    Sage

        sage: (QQ^4).zero_submodule()
        Vector space of degree 4 and dimension 0 over Rational Field
        Basis matrix:
        []

    Python

        >>> from sage.all import *
        >>> (QQ**Integer(4)).zero_submodule()
        Vector space of degree 4 and dimension 0 over Rational Field
        Basis matrix:
        []

  zero_subspace()

    Return the zero subspace of `self`.

    EXAMPLES:

    Sage

        sage: (QQ^4).zero_subspace()
        Vector space of degree 4 and dimension 0 over Rational Field
        Basis matrix:
        []

    Python

        >>> from sage.all import *
        >>> (QQ**Integer(4)).zero_subspace()
        Vector space of degree 4 and dimension 0 over Rational Field
        Basis matrix:
        []

class sage.modules.free_module.FreeModule_generic_pid(base_ring, rank, degree, sparse=False, coordinate_ring=None, category=None)

  Bases: `FreeModule_generic_domain`

  Base class for all free modules over a PID.

  denominator()

    The denominator of the basis matrix of `self` (i.e. the LCM of the coordinate entries with respect to the basis of the ambient space).

    EXAMPLES:

    Sage

        sage: V = QQ^3
        sage: L = V.span([[1,1/2,1/3], [-1/5,2/3,3]],ZZ)
        sage: L
        Free module of degree 3 and rank 2 over Integer Ring
        Echelon basis matrix:
        [ 1/5 19/6 37/3]
        [   0 23/6 46/3]
        sage: L.denominator()
        30

    Python

        >>> from sage.all import *
        >>> V = QQ**Integer(3)
        >>> L = V.span([[Integer(1),Integer(1)/Integer(2),Integer(1)/Integer(3)], [-Integer(1)/Integer(5),Integer(2)/Integer(3),Integer(3)]],ZZ)
        >>> L
        Free module of degree 3 and rank 2 over Integer Ring
        Echelon basis matrix:
        [ 1/5 19/6 37/3]
        [   0 23/6 46/3]
        >>> L.denominator()
        30

  index_in(other)

    Return the lattice index [other:self] of `self` in other, as an element of the base field. When `self` is contained in other, the lattice index is the usual index. If the index is infinite, then this function returns infinity.

    EXAMPLES:

    Sage

        sage: L1 = span([[1,2]], ZZ)
        sage: L2 = span([[3,6]], ZZ)
        sage: L2.index_in(L1)
        3

    Python

        >>> from sage.all import *
        >>> L1 = span([[Integer(1),Integer(2)]], ZZ)
        >>> L2 = span([[Integer(3),Integer(6)]], ZZ)
        >>> L2.index_in(L1)
        3

    Note that the free modules being compared need not be integral.

    Sage

        sage: L1 = span([['1/2','1/3'], [4,5]], ZZ)
        sage: L2 = span([[1,2], [3,4]], ZZ)
        sage: L2.index_in(L1)
        12/7
        sage: L1.index_in(L2)
        7/12
        sage: L1.discriminant() / L2.discriminant()
        49/144

    [Python]

        >>> from sage.all import *
        >>> L1 = span([['1/2','1/3'], [Integer(4),Integer(5)]], ZZ)
        >>> L2 = span([[Integer(1),Integer(2)], [Integer(3),Integer(4)]], ZZ)
        >>> L2.index_in(L1)
        12/7
        >>> L1.index_in(L2)
        7/12
        >>> L1.discriminant() / L2.discriminant()
        49/144

    The index of a lattice of infinite index is infinite.

    Sage

        sage: L1 = FreeModule(ZZ, 2)
        sage: L2 = span([[1,2]], ZZ)
        sage: L2.index_in(L1)
        +Infinity

    Python

        >>> from sage.all import *
        >>> L1 = FreeModule(ZZ, Integer(2))
        >>> L2 = span([[Integer(1),Integer(2)]], ZZ)
        >>> L2.index_in(L1)
        +Infinity

  index_in_saturation()

    Return the index of this module in its saturation, i.e., its intersection with \(R^n\).

    EXAMPLES:

    Sage

        sage: W = span([[2,4,6]], ZZ)
        sage: W.index_in_saturation()
        2
        sage: W = span([[1/2,1/3]], ZZ)
        sage: W.index_in_saturation()
        1/6

    Python

        >>> from sage.all import *
        >>> W = span([[Integer(2),Integer(4),Integer(6)]], ZZ)
        >>> W.index_in_saturation()
        2
        >>> W = span([[Integer(1)/Integer(2),Integer(1)/Integer(3)]], ZZ)
        >>> W.index_in_saturation()
        1/6

  intersection(other)

    Return the intersection of `self` and `other`.

    EXAMPLES:

    We intersect two submodules one of which is clearly contained in the other:

    Sage

        sage: A = ZZ^2
        sage: M1 = A.span([[1,1]])
        sage: M2 = A.span([[3,3]])
        sage: M1.intersection(M2)
        Free module of degree 2 and rank 1 over Integer Ring
        Echelon basis matrix:
        [3 3]
        sage: M1.intersection(M2) is M2
        True

    Python

        >>> from sage.all import *
        >>> A = ZZ**Integer(2)
        >>> M1 = A.span([[Integer(1),Integer(1)]])
        >>> M2 = A.span([[Integer(3),Integer(3)]])
        >>> M1.intersection(M2)
        Free module of degree 2 and rank 1 over Integer Ring
        Echelon basis matrix:
        [3 3]
        >>> M1.intersection(M2) is M2
        True

    We intersection two submodules of \(\ZZ^3\) of rank \(2\), whose intersection has rank \(1\):

    Sage

        sage: A = ZZ^3
        sage: M1 = A.span([[1,1,1], [1,2,3]])
        sage: M2 = A.span([[2,2,2], [1,0,0]])
        sage: M1.intersection(M2)
        Free module of degree 3 and rank 1 over Integer Ring
        Echelon basis matrix:
        [2 2 2]

    [Python]

        >>> from sage.all import *
        >>> A = ZZ**Integer(3)
        >>> M1 = A.span([[Integer(1),Integer(1),Integer(1)], [Integer(1),Integer(2),Integer(3)]])
        >>> M2 = A.span([[Integer(2),Integer(2),Integer(2)], [Integer(1),Integer(0),Integer(0)]])
        >>> M1.intersection(M2)
        Free module of degree 3 and rank 1 over Integer Ring
        Echelon basis matrix:
        [2 2 2]

    We compute an intersection of two \(\ZZ\)-modules that are not submodules of \(\ZZ^2\):

    Sage

        sage: A = ZZ^2
        sage: M1 = A.span([[1,2]]).scale(1/6)
        sage: M2 = A.span([[1,2]]).scale(1/15)
        sage: M1.intersection(M2)
        Free module of degree 2 and rank 1 over Integer Ring
        Echelon basis matrix:
        [1/3 2/3]

    Python

        >>> from sage.all import *
        >>> A = ZZ**Integer(2)
        >>> M1 = A.span([[Integer(1),Integer(2)]]).scale(Integer(1)/Integer(6))
        >>> M2 = A.span([[Integer(1),Integer(2)]]).scale(Integer(1)/Integer(15))
        >>> M1.intersection(M2)
        Free module of degree 2 and rank 1 over Integer Ring
        Echelon basis matrix:
        [1/3 2/3]

    We intersect a \(\ZZ\)-module with a \(\QQ\)-vector space:

    Sage

        sage: A = ZZ^3
        sage: L = ZZ^3
        sage: V = QQ^3
        sage: W = L.span([[1/2,0,1/2]])
        sage: K = V.span([[1,0,1], [0,0,1]])
        sage: W.intersection(K)
        Free module of degree 3 and rank 1 over Integer Ring
        Echelon basis matrix:
        [1/2   0 1/2]
        sage: K.intersection(W)
        Free module of degree 3 and rank 1 over Integer Ring
        Echelon basis matrix:
        [1/2   0 1/2]

    [Python]

        >>> from sage.all import *
        >>> A = ZZ**Integer(3)
        >>> L = ZZ**Integer(3)
        >>> V = QQ**Integer(3)
        >>> W = L.span([[Integer(1)/Integer(2),Integer(0),Integer(1)/Integer(2)]])
        >>> K = V.span([[Integer(1),Integer(0),Integer(1)], [Integer(0),Integer(0),Integer(1)]])
        >>> W.intersection(K)
        Free module of degree 3 and rank 1 over Integer Ring
        Echelon basis matrix:
        [1/2   0 1/2]
        >>> K.intersection(W)
        Free module of degree 3 and rank 1 over Integer Ring
        Echelon basis matrix:
        [1/2   0 1/2]

    We intersect two modules over the ring of integers of a number field:

    Sage

        sage: # needs sage.rings.number_field
        sage: x = polygen(ZZ, 'x')
        sage: L.<w> = NumberField(x^2 - x + 2)
        sage: OL = L.ring_of_integers()
        sage: V = L**3
        sage: W1 = V.span([[0,w/5,0], [1,0,-1/17]], OL)
        sage: W2 = V.span([[0,(1-w)/5,0]], OL)
        sage: W1.intersection(W2)
        Free module of degree 3 and rank 1 over Maximal Order generated by w
         in Number Field in w with defining polynomial x^2 - x + 2
        Echelon basis matrix:
        [  0 2/5   0]

    Python

        >>> from sage.all import *
        >>> # needs sage.rings.number_field
        >>> x = polygen(ZZ, 'x')
        >>> L = NumberField(x**Integer(2) - x + Integer(2), names=('w',)); (w,) = L._first_ngens(1)
        >>> OL = L.ring_of_integers()
        >>> V = L**Integer(3)
        >>> W1 = V.span([[Integer(0),w/Integer(5),Integer(0)], [Integer(1),Integer(0),-Integer(1)/Integer(17)]], OL)
        >>> W2 = V.span([[Integer(0),(Integer(1)-w)/Integer(5),Integer(0)]], OL)
        >>> W1.intersection(W2)
        Free module of degree 3 and rank 1 over Maximal Order generated by w
         in Number Field in w with defining polynomial x^2 - x + 2
        Echelon basis matrix:
        [  0 2/5   0]

  quotient_module(sub, check=True, **kwds)

    Return the quotient of `self` by the given submodule sub.

    INPUT:

    - `sub` – a submodule of `self`, or something that can be turned into one via `self.submodule(sub)`

    - `check` – boolean (default: `True`); whether or not to check that `sub` is a submodule

    - further named arguments, that are passed to the constructor of the quotient space

    EXAMPLES:

    Sage

        sage: A = ZZ^3; V = A.span([[1,2,3], [4,5,6]])
        sage: Q = V.quotient( [V.0 + V.1] ); Q
        Finitely generated module V/W over Integer Ring with invariants (0)

    Python

        >>> from sage.all import *
        >>> A = ZZ**Integer(3); V = A.span([[Integer(1),Integer(2),Integer(3)], [Integer(4),Integer(5),Integer(6)]])
        >>> Q = V.quotient( [V.gen(0) + V.gen(1)] ); Q
        Finitely generated module V/W over Integer Ring with invariants (0)

  saturation()

    Return the saturated submodule of \(R^n\) that spans the same vector space as `self`.

    EXAMPLES:

    We create a 1-dimensional lattice that is obviously not saturated and saturate it.

    Sage

        sage: L = span([[9,9,6]], ZZ); L
        Free module of degree 3 and rank 1 over Integer Ring
        Echelon basis matrix:
        [9 9 6]
        sage: L.saturation()
        Free module of degree 3 and rank 1 over Integer Ring
        Echelon basis matrix:
        [3 3 2]

    Python

        >>> from sage.all import *
        >>> L = span([[Integer(9),Integer(9),Integer(6)]], ZZ); L
        Free module of degree 3 and rank 1 over Integer Ring
        Echelon basis matrix:
        [9 9 6]
        >>> L.saturation()
        Free module of degree 3 and rank 1 over Integer Ring
        Echelon basis matrix:
        [3 3 2]

    We create a lattice spanned by two vectors, and saturate. Computation of discriminants shows that the index of lattice in its saturation is \(3\), which is a prime of congruence between the two generating vectors.

    Sage

        sage: L = span([[1,2,3], [4,5,6]], ZZ)
        sage: L.saturation()
        Free module of degree 3 and rank 2 over Integer Ring
        Echelon basis matrix:
        [ 1  0 -1]
        [ 0  1  2]
        sage: L.discriminant()
        54
        sage: L.saturation().discriminant()
        6

    [Python]

        >>> from sage.all import *
        >>> L = span([[Integer(1),Integer(2),Integer(3)], [Integer(4),Integer(5),Integer(6)]], ZZ)
        >>> L.saturation()
        Free module of degree 3 and rank 2 over Integer Ring
        Echelon basis matrix:
        [ 1  0 -1]
        [ 0  1  2]
        >>> L.discriminant()
        54
        >>> L.saturation().discriminant()
        6

    Notice that the saturation of a non-integral lattice \(L\) is defined, but the result is integral hence does not contain \(L\):

    Sage

        sage: L = span([['1/2',1,3]], ZZ)
        sage: L.saturation()
        Free module of degree 3 and rank 1 over Integer Ring
        Echelon basis matrix:
        [1 2 6]

    Python

        >>> from sage.all import *
        >>> L = span([['1/2',Integer(1),Integer(3)]], ZZ)
        >>> L.saturation()
        Free module of degree 3 and rank 1 over Integer Ring
        Echelon basis matrix:
        [1 2 6]

  span_of_basis(basis, base_ring=None, check=True, already_echelonized=False)

    Return the free R-module with the given basis, where R is the base ring of `self` or user specified base_ring.

    Note that this R-module need not be a submodule of self, nor even of the ambient space. It must, however, be contained in the ambient vector space, i.e., the ambient space tensored with the fraction field of R.

    EXAMPLES:

    Sage

        sage: M = FreeModule(ZZ,3)
        sage: W = M.span_of_basis([M([1,2,3])])

    Python

        >>> from sage.all import *
        >>> M = FreeModule(ZZ,Integer(3))
        >>> W = M.span_of_basis([M([Integer(1),Integer(2),Integer(3)])])

    Next we create two free \(\ZZ\)-modules, neither of which is a submodule of \(W\).

    Sage

        sage: W.span_of_basis([M([2,4,0])])
        Free module of degree 3 and rank 1 over Integer Ring
        User basis matrix:
        [2 4 0]

    [Python]

        >>> from sage.all import *
        >>> W.span_of_basis([M([Integer(2),Integer(4),Integer(0)])])
        Free module of degree 3 and rank 1 over Integer Ring
        User basis matrix:
        [2 4 0]

    The following module isn’t in the ambient module \(\ZZ^3\) but is contained in the ambient vector space \(\QQ^3\):

    Sage

        sage: V = M.ambient_vector_space()
        sage: W.span_of_basis([ V([1/5,2/5,0]), V([1/7,1/7,0]) ])
        Free module of degree 3 and rank 2 over Integer Ring
        User basis matrix:
        [1/5 2/5   0]
        [1/7 1/7   0]

    Python

        >>> from sage.all import *
        >>> V = M.ambient_vector_space()
        >>> W.span_of_basis([ V([Integer(1)/Integer(5),Integer(2)/Integer(5),Integer(0)]), V([Integer(1)/Integer(7),Integer(1)/Integer(7),Integer(0)]) ])
        Free module of degree 3 and rank 2 over Integer Ring
        User basis matrix:
        [1/5 2/5   0]
        [1/7 1/7   0]

    Of course the input basis vectors must be linearly independent:

    Sage

        sage: W.span_of_basis([ [1,2,0], [2,4,0] ])
        Traceback (most recent call last):
        ...
        ValueError: the given basis vectors must be linearly independent

    [Python]

        >>> from sage.all import *
        >>> W.span_of_basis([ [Integer(1),Integer(2),Integer(0)], [Integer(2),Integer(4),Integer(0)] ])
        Traceback (most recent call last):
        ...
        ValueError: the given basis vectors must be linearly independent

  submodule_with_basis(basis, check=True, already_echelonized=False)

    Create the \(R\)-submodule of the ambient vector space with given basis, where \(R\) is the base ring of `self`.

    INPUT:

    - `basis` – list of linearly independent vectors

    - `check` – whether or not to verify that each gen is in the ambient vector space

    OUTPUT: `FreeModule`; the \(R\)-submodule with given basis

    EXAMPLES:

    First we create a submodule of \(\\ZZ^3\):

    Sage

        sage: M = FreeModule(ZZ, 3)
        sage: B = M.basis()
        sage: N = M.submodule_with_basis([B[0]+B[1], 2*B[1]-B[2]])
        sage: N
        Free module of degree 3 and rank 2 over Integer Ring
        User basis matrix:
        [ 1  1  0]
        [ 0  2 -1]

    Python

        >>> from sage.all import *
        >>> M = FreeModule(ZZ, Integer(3))
        >>> B = M.basis()
        >>> N = M.submodule_with_basis([B[Integer(0)]+B[Integer(1)], Integer(2)*B[Integer(1)]-B[Integer(2)]])
        >>> N
        Free module of degree 3 and rank 2 over Integer Ring
        User basis matrix:
        [ 1  1  0]
        [ 0  2 -1]

    A list of vectors in the ambient vector space may fail to generate a submodule.

    Sage

        sage: V = M.ambient_vector_space()
        sage: X = M.submodule_with_basis([ V(B[0]+B[1])/2, V(B[1]-B[2])/2])
        Traceback (most recent call last):
        ...
        ArithmeticError: The given basis does not generate a submodule of self.

    [Python]

        >>> from sage.all import *
        >>> V = M.ambient_vector_space()
        >>> X = M.submodule_with_basis([ V(B[Integer(0)]+B[Integer(1)])/Integer(2), V(B[Integer(1)]-B[Integer(2)])/Integer(2)])
        Traceback (most recent call last):
        ...
        ArithmeticError: The given basis does not generate a submodule of self.

    However, we can still determine the R-span of vectors in the ambient space, or over-ride the submodule check by setting check to False.

    Sage

        sage: X = V.span([ V(B[0]+B[1])/2, V(B[1]-B[2])/2 ], ZZ)
        sage: X
        Free module of degree 3 and rank 2 over Integer Ring
        Echelon basis matrix:
        [ 1/2    0   1/2]
        [   0  1/2  -1/2]
        sage: Y = M.submodule([ V(B[0]+B[1])/2, V(B[1]-B[2])/2 ], check=False)
        sage: X == Y
        True

    Python

        >>> from sage.all import *
        >>> X = V.span([ V(B[Integer(0)]+B[Integer(1)])/Integer(2), V(B[Integer(1)]-B[Integer(2)])/Integer(2) ], ZZ)
        >>> X
        Free module of degree 3 and rank 2 over Integer Ring
        Echelon basis matrix:
        [ 1/2    0   1/2]
        [   0  1/2  -1/2]
        >>> Y = M.submodule([ V(B[Integer(0)]+B[Integer(1)])/Integer(2), V(B[Integer(1)]-B[Integer(2)])/Integer(2) ], check=False)
        >>> X == Y
        True

    Next we try to create a submodule of a free module over the principal ideal domain \(\QQ[x]\), using our general Hermite normal form implementation:

    Sage

        sage: R = PolynomialRing(QQ, 'x'); x = R.gen()
        sage: M = FreeModule(R, 3)
        sage: B = M.basis()
        sage: W = M.submodule_with_basis([x*B[0], 2*B[0]- x*B[2]]); W
        Free module of degree 3 and rank 2 over Univariate Polynomial Ring in x over Rational Field
        User basis matrix:
        [ x  0  0]
        [ 2  0 -x]

    [Python]

        >>> from sage.all import *
        >>> R = PolynomialRing(QQ, 'x'); x = R.gen()
        >>> M = FreeModule(R, Integer(3))
        >>> B = M.basis()
        >>> W = M.submodule_with_basis([x*B[Integer(0)], Integer(2)*B[Integer(0)]- x*B[Integer(2)]]); W
        Free module of degree 3 and rank 2 over Univariate Polynomial Ring in x over Rational Field
        User basis matrix:
        [ x  0  0]
        [ 2  0 -x]

  vector_space_span(gens, check=True)

    Create the vector subspace of the ambient vector space with given generators.

    INPUT:

    - `gens` – list of vector in `self`

    - `check` – whether or not to verify that each gen is in the ambient vector space

    OUTPUT: a vector subspace

    EXAMPLES:

    We create a \(2\)-dimensional subspace of \(\QQ^3\).

    Sage

        sage: V = VectorSpace(QQ, 3)
        sage: B = V.basis()
        sage: W = V.vector_space_span([B[0]+B[1], 2*B[1]-B[2]])
        sage: W
        Vector space of degree 3 and dimension 2 over Rational Field
        Basis matrix:
        [   1    0  1/2]
        [   0    1 -1/2]

    Python

        >>> from sage.all import *
        >>> V = VectorSpace(QQ, Integer(3))
        >>> B = V.basis()
        >>> W = V.vector_space_span([B[Integer(0)]+B[Integer(1)], Integer(2)*B[Integer(1)]-B[Integer(2)]])
        >>> W
        Vector space of degree 3 and dimension 2 over Rational Field
        Basis matrix:
        [   1    0  1/2]
        [   0    1 -1/2]

    We create a subspace of a vector space over \(\QQ(i)\).

    Sage

        sage: R.<x> = QQ[]
        sage: K = NumberField(x^2 + 1, 'a'); a = K.gen()                            # needs sage.rings.number_field
        sage: V = VectorSpace(K, 3)                                                 # needs sage.rings.number_field
        sage: V.vector_space_span([2*V.gen(0) + 3*V.gen(2)])                        # needs sage.rings.number_field
        Vector space of degree 3 and dimension 1
         over Number Field in a with defining polynomial x^2 + 1
        Basis matrix:
        [  1   0 3/2]

    [Python]

        >>> from sage.all import *
        >>> R = QQ['x']; (x,) = R._first_ngens(1)
        >>> K = NumberField(x**Integer(2) + Integer(1), 'a'); a = K.gen()                            # needs sage.rings.number_field
        >>> V = VectorSpace(K, Integer(3))                                                 # needs sage.rings.number_field
        >>> V.vector_space_span([Integer(2)*V.gen(Integer(0)) + Integer(3)*V.gen(Integer(2))])                        # needs sage.rings.number_field
        Vector space of degree 3 and dimension 1
         over Number Field in a with defining polynomial x^2 + 1
        Basis matrix:
        [  1   0 3/2]

    We use the `vector_space_span` command to create a vector subspace of the ambient vector space of a submodule of \(\ZZ^3\).

    Sage

        sage: M = FreeModule(ZZ, 3)
        sage: W = M.submodule([M([1,2,3])])
        sage: W.vector_space_span([M([2,3,4])])
        Vector space of degree 3 and dimension 1 over Rational Field
        Basis matrix:
        [  1 3/2   2]

    Python

        >>> from sage.all import *
        >>> M = FreeModule(ZZ, Integer(3))
        >>> W = M.submodule([M([Integer(1),Integer(2),Integer(3)])])
        >>> W.vector_space_span([M([Integer(2),Integer(3),Integer(4)])])
        Vector space of degree 3 and dimension 1 over Rational Field
        Basis matrix:
        [  1 3/2   2]

  vector_space_span_of_basis(basis, check=True)

    Create the vector subspace of the ambient vector space with given basis.

    INPUT:

    - `basis` – list of linearly independent vectors

    - `check` – whether or not to verify that each gen is in the ambient vector space

    OUTPUT: a vector subspace with user-specified basis

    EXAMPLES:

    Sage

        sage: V = VectorSpace(QQ, 3)
        sage: B = V.basis()
        sage: W = V.vector_space_span_of_basis([B[0] + B[1], 2*B[1] - B[2]])
        sage: W
        Vector space of degree 3 and dimension 2 over Rational Field
        User basis matrix:
        [ 1  1  0]
        [ 0  2 -1]

    Python

        >>> from sage.all import *
        >>> V = VectorSpace(QQ, Integer(3))
        >>> B = V.basis()
        >>> W = V.vector_space_span_of_basis([B[Integer(0)] + B[Integer(1)], Integer(2)*B[Integer(1)] - B[Integer(2)]])
        >>> W
        Vector space of degree 3 and dimension 2 over Rational Field
        User basis matrix:
        [ 1  1  0]
        [ 0  2 -1]

  zero_submodule()

    Return the zero submodule of this module.

    EXAMPLES:

    Sage

        sage: V = FreeModule(ZZ,2)
        sage: V.zero_submodule()
        Free module of degree 2 and rank 0 over Integer Ring
        Echelon basis matrix:
        []

    Python

        >>> from sage.all import *
        >>> V = FreeModule(ZZ,Integer(2))
        >>> V.zero_submodule()
        Free module of degree 2 and rank 0 over Integer Ring
        Echelon basis matrix:
        []

class sage.modules.free_module.FreeModule_submodule_field(ambient, gens, check=True, already_echelonized=False, category=None)

  Bases: `FreeModule_submodule_with_basis_field`

  An embedded vector subspace with echelonized basis.

  EXAMPLES:

  Since this is an embedded vector subspace with echelonized basis, the echelon_coordinates() and user coordinates() agree:

  Sage

      sage: V = QQ^3
      sage: W = V.span([[1,2,3],[4,5,6]])
      sage: W
      Vector space of degree 3 and dimension 2 over Rational Field
      Basis matrix:
      [ 1  0 -1]
      [ 0  1  2]

  Python

      >>> from sage.all import *
      >>> V = QQ**Integer(3)
      >>> W = V.span([[Integer(1),Integer(2),Integer(3)],[Integer(4),Integer(5),Integer(6)]])
      >>> W
      Vector space of degree 3 and dimension 2 over Rational Field
      Basis matrix:
      [ 1  0 -1]
      [ 0  1  2]

  Sage

      sage: v = V([1,5,9])
      sage: W.echelon_coordinates(v)
      [1, 5]
      sage: vector(QQ, W.echelon_coordinates(v)) * W.basis_matrix()
      (1, 5, 9)
      sage: v = V([1,5,9])
      sage: W.coordinates(v)
      [1, 5]
      sage: vector(QQ, W.coordinates(v)) * W.basis_matrix()
      (1, 5, 9)

  [Python]

      >>> from sage.all import *
      >>> v = V([Integer(1),Integer(5),Integer(9)])
      >>> W.echelon_coordinates(v)
      [1, 5]
      >>> vector(QQ, W.echelon_coordinates(v)) * W.basis_matrix()
      (1, 5, 9)
      >>> v = V([Integer(1),Integer(5),Integer(9)])
      >>> W.coordinates(v)
      [1, 5]
      >>> vector(QQ, W.coordinates(v)) * W.basis_matrix()
      (1, 5, 9)

  coordinate_vector(v, check=True)

    Write \(v\) in terms of the user basis for `self`.

    INPUT:

    - `v` – vector

    - `check` – boolean (default: `True`); if `True`, also verify that

        \(v\) is really in `self`

    OUTPUT: list

    The output is a list \(c\) such that if \(B\) is the basis for `self`, then

    \[\sum c_i B_i = v.\]

    If \(v\) is not in `self`, raise an `ArithmeticError` exception.

    EXAMPLES:

    Sage

        sage: V = QQ^3
        sage: W = V.span([[1,2,3],[4,5,6]]); W
        Vector space of degree 3 and dimension 2 over Rational Field
        Basis matrix:
        [ 1  0 -1]
        [ 0  1  2]
        sage: v = V([1,5,9])
        sage: W.coordinate_vector(v)
        (1, 5)
        sage: W.coordinates(v)
        [1, 5]
        sage: vector(QQ, W.coordinates(v)) * W.basis_matrix()
        (1, 5, 9)

    Python

        >>> from sage.all import *
        >>> V = QQ**Integer(3)
        >>> W = V.span([[Integer(1),Integer(2),Integer(3)],[Integer(4),Integer(5),Integer(6)]]); W
        Vector space of degree 3 and dimension 2 over Rational Field
        Basis matrix:
        [ 1  0 -1]
        [ 0  1  2]
        >>> v = V([Integer(1),Integer(5),Integer(9)])
        >>> W.coordinate_vector(v)
        (1, 5)
        >>> W.coordinates(v)
        [1, 5]
        >>> vector(QQ, W.coordinates(v)) * W.basis_matrix()
        (1, 5, 9)

    Sage

        sage: V = VectorSpace(QQ,5, sparse=True)
        sage: W = V.subspace([[0,1,2,0,0], [0,-1,0,0,-1/2]])
        sage: W.coordinate_vector([0,0,2,0,-1/2])
        (0, 2)

    [Python]

        >>> from sage.all import *
        >>> V = VectorSpace(QQ,Integer(5), sparse=True)
        >>> W = V.subspace([[Integer(0),Integer(1),Integer(2),Integer(0),Integer(0)], [Integer(0),-Integer(1),Integer(0),Integer(0),-Integer(1)/Integer(2)]])
        >>> W.coordinate_vector([Integer(0),Integer(0),Integer(2),Integer(0),-Integer(1)/Integer(2)])
        (0, 2)

  echelon_coordinates(v, check=True)

    Write \(v\) in terms of the echelonized basis of `self`.

    INPUT:

    - `v` – vector

    - `check` – boolean (default: `True`); if `True`, also verify that \(v\) is really in `self`

    OUTPUT: list

    The output is a list \(c\) such that if \(B\) is the basis for `self`, then

    \[\sum c_i B_i = v.\]

    If \(v\) is not in `self`, raise an `ArithmeticError` exception.

    EXAMPLES:

    Sage

        sage: V = QQ^3
        sage: W = V.span([[1,2,3],[4,5,6]])
        sage: W
        Vector space of degree 3 and dimension 2 over Rational Field
        Basis matrix:
        [ 1  0 -1]
        [ 0  1  2]

    Python

        >>> from sage.all import *
        >>> V = QQ**Integer(3)
        >>> W = V.span([[Integer(1),Integer(2),Integer(3)],[Integer(4),Integer(5),Integer(6)]])
        >>> W
        Vector space of degree 3 and dimension 2 over Rational Field
        Basis matrix:
        [ 1  0 -1]
        [ 0  1  2]

    Sage

        sage: v = V([1,5,9])
        sage: W.echelon_coordinates(v)
        [1, 5]
        sage: vector(QQ, W.echelon_coordinates(v)) * W.basis_matrix()
        (1, 5, 9)

    [Python]

        >>> from sage.all import *
        >>> v = V([Integer(1),Integer(5),Integer(9)])
        >>> W.echelon_coordinates(v)
        [1, 5]
        >>> vector(QQ, W.echelon_coordinates(v)) * W.basis_matrix()
        (1, 5, 9)

  has_user_basis()

    Return `True` if the basis of this free module is specified by the user, as opposed to being the default echelon form.

    EXAMPLES:

    Sage

        sage: V = QQ^3
        sage: W = V.subspace([[2,'1/2', 1]])
        sage: W.has_user_basis()
        False
        sage: W = V.subspace_with_basis([[2,'1/2',1]])
        sage: W.has_user_basis()
        True

    Python

        >>> from sage.all import *
        >>> V = QQ**Integer(3)
        >>> W = V.subspace([[Integer(2),'1/2', Integer(1)]])
        >>> W.has_user_basis()
        False
        >>> W = V.subspace_with_basis([[Integer(2),'1/2',Integer(1)]])
        >>> W.has_user_basis()
        True

class sage.modules.free_module.FreeModule_submodule_pid(ambient, gens, check=True, already_echelonized=False, category=None)

  Bases: `FreeModule_submodule_with_basis_pid`

  An \(R\)-submodule of \(K^n\) where \(K\) is the fraction field of a principal ideal domain \(R\).

  EXAMPLES:

  Sage

      sage: M = ZZ^3
      sage: W = M.span_of_basis([[1,2,3],[4,5,19]]); W
      Free module of degree 3 and rank 2 over Integer Ring
      User basis matrix:
      [ 1  2  3]
      [ 4  5 19]

  Python

      >>> from sage.all import *
      >>> M = ZZ**Integer(3)
      >>> W = M.span_of_basis([[Integer(1),Integer(2),Integer(3)],[Integer(4),Integer(5),Integer(19)]]); W
      Free module of degree 3 and rank 2 over Integer Ring
      User basis matrix:
      [ 1  2  3]
      [ 4  5 19]

  Generic tests, including saving and loading submodules and elements:

  Sage

      sage: TestSuite(W).run()
      sage: v = W.0 + W.1
      sage: TestSuite(v).run()

  [Python]

      >>> from sage.all import *
      >>> TestSuite(W).run()
      >>> v = W.gen(0) + W.gen(1)
      >>> TestSuite(v).run()

  coordinate_vector(v, check=True)

    Write \(v\) in terms of the user basis for `self`.

    INPUT:

    - `v` – vector

    - `check` – boolean (default: `True`); if `True`, also verify that

        \(v\) is really in `self`

    OUTPUT: list

    The output is a list \(c\) such that if \(B\) is the basis for `self`, then

    \[\sum c_i B_i = v.\]

    If \(v\) is not in self, raise an `ArithmeticError` exception.

    EXAMPLES:

    Sage

        sage: V = ZZ^3
        sage: W = V.span_of_basis([[1,2,3],[4,5,6]])
        sage: W.coordinate_vector([1,5,9])
        (5, -1)

    Python

        >>> from sage.all import *
        >>> V = ZZ**Integer(3)
        >>> W = V.span_of_basis([[Integer(1),Integer(2),Integer(3)],[Integer(4),Integer(5),Integer(6)]])
        >>> W.coordinate_vector([Integer(1),Integer(5),Integer(9)])
        (5, -1)

  has_user_basis()

    Return `True` if the basis of this free module is specified by the user, as opposed to being the default echelon form.

    EXAMPLES:

    Sage

        sage: A = ZZ^3; A
        Ambient free module of rank 3 over the principal ideal domain Integer Ring
        sage: A.has_user_basis()
        False
        sage: W = A.span_of_basis([[2,'1/2',1]])
        sage: W.has_user_basis()
        True
        sage: W = A.span([[2,'1/2',1]])
        sage: W.has_user_basis()
        False

    Python

        >>> from sage.all import *
        >>> A = ZZ**Integer(3); A
        Ambient free module of rank 3 over the principal ideal domain Integer Ring
        >>> A.has_user_basis()
        False
        >>> W = A.span_of_basis([[Integer(2),'1/2',Integer(1)]])
        >>> W.has_user_basis()
        True
        >>> W = A.span([[Integer(2),'1/2',Integer(1)]])
        >>> W.has_user_basis()
        False

class sage.modules.free_module.FreeModule_submodule_with_basis_field(ambient, basis, check=True, echelonize=False, echelonized_basis=None, already_echelonized=False, category=None)

  Bases: `FreeModule_generic_field`, `FreeModule_submodule_with_basis_pid`

  An embedded vector subspace with a distinguished user basis.

  EXAMPLES:

  Sage

      sage: M = QQ^3; W = M.submodule_with_basis([[1,2,3], [4,5,19]]); W
      Vector space of degree 3 and dimension 2 over Rational Field
      User basis matrix:
      [ 1  2  3]
      [ 4  5 19]

  Python

      >>> from sage.all import *
      >>> M = QQ**Integer(3); W = M.submodule_with_basis([[Integer(1),Integer(2),Integer(3)], [Integer(4),Integer(5),Integer(19)]]); W
      Vector space of degree 3 and dimension 2 over Rational Field
      User basis matrix:
      [ 1  2  3]
      [ 4  5 19]

  Since this is an embedded vector subspace with a distinguished user basis possibly different than the echelonized basis, the echelon_coordinates() and user coordinates() do not agree:

  Sage

      sage: V = QQ^3

  [Python]

      >>> from sage.all import *
      >>> V = QQ**Integer(3)

  Sage

      sage: W = V.submodule_with_basis([[1,2,3], [4,5,6]])
      sage: W
      Vector space of degree 3 and dimension 2 over Rational Field
      User basis matrix:
      [1 2 3]
      [4 5 6]

  Python

      >>> from sage.all import *
      >>> W = V.submodule_with_basis([[Integer(1),Integer(2),Integer(3)], [Integer(4),Integer(5),Integer(6)]])
      >>> W
      Vector space of degree 3 and dimension 2 over Rational Field
      User basis matrix:
      [1 2 3]
      [4 5 6]

  Sage

      sage: v = V([1,5,9])
      sage: W.echelon_coordinates(v)
      [1, 5]
      sage: vector(QQ, W.echelon_coordinates(v)) * W.echelonized_basis_matrix()
      (1, 5, 9)

  [Python]

      >>> from sage.all import *
      >>> v = V([Integer(1),Integer(5),Integer(9)])
      >>> W.echelon_coordinates(v)
      [1, 5]
      >>> vector(QQ, W.echelon_coordinates(v)) * W.echelonized_basis_matrix()
      (1, 5, 9)

  Sage

      sage: v = V([1,5,9])
      sage: W.coordinates(v)
      [5, -1]
      sage: vector(QQ, W.coordinates(v)) * W.basis_matrix()
      (1, 5, 9)

  Python

      >>> from sage.all import *
      >>> v = V([Integer(1),Integer(5),Integer(9)])
      >>> W.coordinates(v)
      [5, -1]
      >>> vector(QQ, W.coordinates(v)) * W.basis_matrix()
      (1, 5, 9)

  Generic tests, including saving and loading submodules and elements:

  Sage

      sage: TestSuite(W).run()

      sage: K.<x> = FractionField(PolynomialRing(QQ,'x'))
      sage: M = K^3; W = M.span_of_basis([[1,1,x]])
      sage: TestSuite(W).run()

  [Python]

      >>> from sage.all import *
      >>> TestSuite(W).run()

      >>> K = FractionField(PolynomialRing(QQ,'x'), names=('x',)); (x,) = K._first_ngens(1)
      >>> M = K**Integer(3); W = M.span_of_basis([[Integer(1),Integer(1),x]])
      >>> TestSuite(W).run()

  is_ambient()

    Return `False` since this is not an ambient module.

    EXAMPLES:

    Sage

        sage: V = QQ^3
        sage: V.is_ambient()
        True
        sage: W = V.span_of_basis([[1,2,3],[4,5,6]])
        sage: W.is_ambient()
        False

    Python

        >>> from sage.all import *
        >>> V = QQ**Integer(3)
        >>> V.is_ambient()
        True
        >>> W = V.span_of_basis([[Integer(1),Integer(2),Integer(3)],[Integer(4),Integer(5),Integer(6)]])
        >>> W.is_ambient()
        False

class sage.modules.free_module.FreeModule_submodule_with_basis_pid(ambient, basis, check=True, echelonize=False, echelonized_basis=None, already_echelonized=False, category=None)

  Bases: `FreeModule_generic_pid`

  Construct a submodule of a free module over PID with a distinguished basis.

  INPUT:

  - `ambient` – ambient free module over a principal ideal domain \(R\), i.e. \(R^n\)

  - `basis` – list of elements of \(K^n\), where \(K\) is the fraction field of \(R\); these elements must be linearly independent and will be used as the default basis of the constructed submodule

  - `check` – boolean (default: `True`); if `False`, correctness of the input will not be checked and type conversion may be omitted, use with care

  - `echelonize` – (default: `False`) if `True`, `basis` will be echelonized and the result will be used as the default basis of the constructed submodule

  - `echelonized_basis` – (default: `None`) if not `None`, must be the echelonized basis spanning the same submodule as `basis`

  - `already_echelonized` – boolean (default: `False`); if `True`, `basis` must be already given in the echelonized form

  OUTPUT: \(R\)-submodule of \(K^n\) with the user-specified `basis`

  EXAMPLES:

  Sage

      sage: M = ZZ^3
      sage: W = M.span_of_basis([[1,2,3], [4,5,6]]); W
      Free module of degree 3 and rank 2 over Integer Ring
      User basis matrix:
      [1 2 3]
      [4 5 6]

  Python

      >>> from sage.all import *
      >>> M = ZZ**Integer(3)
      >>> W = M.span_of_basis([[Integer(1),Integer(2),Integer(3)], [Integer(4),Integer(5),Integer(6)]]); W
      Free module of degree 3 and rank 2 over Integer Ring
      User basis matrix:
      [1 2 3]
      [4 5 6]

  Now we create a submodule of the ambient vector space, rather than `M` itself:

  Sage

      sage: W = M.span_of_basis([[1,2,3/2], [4,5,6]]); W
      Free module of degree 3 and rank 2 over Integer Ring
      User basis matrix:
      [  1   2 3/2]
      [  4   5   6]

  [Python]

      >>> from sage.all import *
      >>> W = M.span_of_basis([[Integer(1),Integer(2),Integer(3)/Integer(2)], [Integer(4),Integer(5),Integer(6)]]); W
      Free module of degree 3 and rank 2 over Integer Ring
      User basis matrix:
      [  1   2 3/2]
      [  4   5   6]

  ambient()

    Return the ambient module or space for `self`.

    EXAMPLES:

    Sage

        sage: M = ZZ^3
        sage: W = M.span_of_basis([[1,2,3],[4,5,6]]); W
        Free module of degree 3 and rank 2 over Integer Ring
        User basis matrix:
        [1 2 3]
        [4 5 6]
        sage: W.ambient()
        Ambient free module of rank 3 over the principal ideal domain Integer Ring

    Python

        >>> from sage.all import *
        >>> M = ZZ**Integer(3)
        >>> W = M.span_of_basis([[Integer(1),Integer(2),Integer(3)],[Integer(4),Integer(5),Integer(6)]]); W
        Free module of degree 3 and rank 2 over Integer Ring
        User basis matrix:
        [1 2 3]
        [4 5 6]
        >>> W.ambient()
        Ambient free module of rank 3 over the principal ideal domain Integer Ring

    Now we create a submodule of the ambient vector space, rather than `M` itself:

    Sage

        sage: W = M.span_of_basis([[1,2,3/2],[4,5,6]]); W
        Free module of degree 3 and rank 2 over Integer Ring
        User basis matrix:
        [  1   2 3/2]
        [  4   5   6]
        sage: W.ambient()
        Vector space of dimension 3 over Rational Field

    [Python]

        >>> from sage.all import *
        >>> W = M.span_of_basis([[Integer(1),Integer(2),Integer(3)/Integer(2)],[Integer(4),Integer(5),Integer(6)]]); W
        Free module of degree 3 and rank 2 over Integer Ring
        User basis matrix:
        [  1   2 3/2]
        [  4   5   6]
        >>> W.ambient()
        Vector space of dimension 3 over Rational Field

    A submodule of a submodule:

    Sage

        sage: M = ZZ^3
        sage: W = M.span_of_basis([[1,2,3],[4,5,6]]); W
        Free module of degree 3 and rank 2 over Integer Ring
        User basis matrix:
        [1 2 3]
        [4 5 6]
        sage: U = W.span_of_basis([[5,7,9]]); U
        Free module of degree 3 and rank 1 over Integer Ring
        User basis matrix:
        [5 7 9]
        sage: U.ambient()
        Ambient free module of rank 3 over the principal ideal domain Integer Ring

    Python

        >>> from sage.all import *
        >>> M = ZZ**Integer(3)
        >>> W = M.span_of_basis([[Integer(1),Integer(2),Integer(3)],[Integer(4),Integer(5),Integer(6)]]); W
        Free module of degree 3 and rank 2 over Integer Ring
        User basis matrix:
        [1 2 3]
        [4 5 6]
        >>> U = W.span_of_basis([[Integer(5),Integer(7),Integer(9)]]); U
        Free module of degree 3 and rank 1 over Integer Ring
        User basis matrix:
        [5 7 9]
        >>> U.ambient()
        Ambient free module of rank 3 over the principal ideal domain Integer Ring

  ambient_module()

    Return the ambient module related to the \(R\)-module self, which was used when creating this module, and is of the form \(R^n\). Note that `self` need not be contained in the ambient module, though `self` will be contained in the ambient vector space.

    EXAMPLES:

    Sage

        sage: A = ZZ^3
        sage: M = A.span_of_basis([[1,2,'3/7'],[4,5,6]])
        sage: M
        Free module of degree 3 and rank 2 over Integer Ring
        User basis matrix:
        [  1   2 3/7]
        [  4   5   6]
        sage: M.ambient_module()
        Ambient free module of rank 3 over the principal ideal domain Integer Ring
        sage: M.is_submodule(M.ambient_module())
        False

    Python

        >>> from sage.all import *
        >>> A = ZZ**Integer(3)
        >>> M = A.span_of_basis([[Integer(1),Integer(2),'3/7'],[Integer(4),Integer(5),Integer(6)]])
        >>> M
        Free module of degree 3 and rank 2 over Integer Ring
        User basis matrix:
        [  1   2 3/7]
        [  4   5   6]
        >>> M.ambient_module()
        Ambient free module of rank 3 over the principal ideal domain Integer Ring
        >>> M.is_submodule(M.ambient_module())
        False

  ambient_vector_space()

    Return the ambient vector space in which this free module is embedded.

    EXAMPLES:

    Sage

        sage: M = ZZ^3;  M.ambient_vector_space()
        Vector space of dimension 3 over Rational Field

    Python

        >>> from sage.all import *
        >>> M = ZZ**Integer(3);  M.ambient_vector_space()
        Vector space of dimension 3 over Rational Field

    Sage

        sage: N = M.span_of_basis([[1,2,'1/5']])
        sage: N
        Free module of degree 3 and rank 1 over Integer Ring
        User basis matrix:
        [  1   2 1/5]
        sage: M.ambient_vector_space()
        Vector space of dimension 3 over Rational Field
        sage: M.ambient_vector_space() is N.ambient_vector_space()
        True

    [Python]

        >>> from sage.all import *
        >>> N = M.span_of_basis([[Integer(1),Integer(2),'1/5']])
        >>> N
        Free module of degree 3 and rank 1 over Integer Ring
        User basis matrix:
        [  1   2 1/5]
        >>> M.ambient_vector_space()
        Vector space of dimension 3 over Rational Field
        >>> M.ambient_vector_space() is N.ambient_vector_space()
        True

    If an inner product on the module is specified, then this is preserved on the ambient vector space.

    Sage

        sage: M = FreeModule(ZZ,4,inner_product_matrix=1)
        sage: V = M.ambient_vector_space()
        sage: V
        Ambient quadratic space of dimension 4 over Rational Field
        Inner product matrix:
        [1 0 0 0]
        [0 1 0 0]
        [0 0 1 0]
        [0 0 0 1]
        sage: N = M.submodule([[1,-1,0,0],[0,1,-1,0],[0,0,1,-1]])
        sage: N.gram_matrix()
        [2 1 1]
        [1 2 1]
        [1 1 2]
        sage: V == N.ambient_vector_space()
        True

    Python

        >>> from sage.all import *
        >>> M = FreeModule(ZZ,Integer(4),inner_product_matrix=Integer(1))
        >>> V = M.ambient_vector_space()
        >>> V
        Ambient quadratic space of dimension 4 over Rational Field
        Inner product matrix:
        [1 0 0 0]
        [0 1 0 0]
        [0 0 1 0]
        [0 0 0 1]
        >>> N = M.submodule([[Integer(1),-Integer(1),Integer(0),Integer(0)],[Integer(0),Integer(1),-Integer(1),Integer(0)],[Integer(0),Integer(0),Integer(1),-Integer(1)]])
        >>> N.gram_matrix()
        [2 1 1]
        [1 2 1]
        [1 1 2]
        >>> V == N.ambient_vector_space()
        True

  basis()

    Return the user basis for this free module.

    EXAMPLES:

    Sage

        sage: V = ZZ^3
        sage: V.basis()
        [(1, 0, 0), (0, 1, 0), (0, 0, 1)]
        sage: M = V.span_of_basis([['1/8',2,1]])
        sage: M.basis()
        [(1/8, 2, 1)]

    Python

        >>> from sage.all import *
        >>> V = ZZ**Integer(3)
        >>> V.basis()
        [(1, 0, 0), (0, 1, 0), (0, 0, 1)]
        >>> M = V.span_of_basis([['1/8',Integer(2),Integer(1)]])
        >>> M.basis()
        [(1/8, 2, 1)]

  change_ring(R)

    Return the free module over \(R\) obtained by coercing each element of the basis of `self` into a vector over the fraction field of \(R\), then taking the resulting \(R\)-module.

    INPUT:

    - `R` – a principal ideal domain

    EXAMPLES:

    Sage

        sage: V = QQ^3
        sage: W = V.subspace([[2, 1/2, 1]])
        sage: W.change_ring(GF(7))
        Vector space of degree 3 and dimension 1 over Finite Field of size 7
        Basis matrix:
        [1 2 4]

    Python

        >>> from sage.all import *
        >>> V = QQ**Integer(3)
        >>> W = V.subspace([[Integer(2), Integer(1)/Integer(2), Integer(1)]])
        >>> W.change_ring(GF(Integer(7)))
        Vector space of degree 3 and dimension 1 over Finite Field of size 7
        Basis matrix:
        [1 2 4]

    Sage

        sage: M = (ZZ^2) * (1/2)
        sage: N = M.change_ring(QQ)
        sage: N
        Vector space of degree 2 and dimension 2 over Rational Field
        Basis matrix:
        [1 0]
        [0 1]
        sage: N = M.change_ring(QQ['x'])
        sage: N
        Free module of degree 2 and rank 2
         over Univariate Polynomial Ring in x over Rational Field
        Echelon basis matrix:
        [1/2   0]
        [  0 1/2]
        sage: N.coordinate_ring()
        Univariate Polynomial Ring in x over Rational Field

    [Python]

        >>> from sage.all import *
        >>> M = (ZZ**Integer(2)) * (Integer(1)/Integer(2))
        >>> N = M.change_ring(QQ)
        >>> N
        Vector space of degree 2 and dimension 2 over Rational Field
        Basis matrix:
        [1 0]
        [0 1]
        >>> N = M.change_ring(QQ['x'])
        >>> N
        Free module of degree 2 and rank 2
         over Univariate Polynomial Ring in x over Rational Field
        Echelon basis matrix:
        [1/2   0]
        [  0 1/2]
        >>> N.coordinate_ring()
        Univariate Polynomial Ring in x over Rational Field

    The ring must be a principal ideal domain:

    Sage

        sage: M.change_ring(ZZ['x'])
        Traceback (most recent call last):
        ...
        TypeError: the new ring Univariate Polynomial Ring in x over Integer Ring
        should be a principal ideal domain

    Python

        >>> from sage.all import *
        >>> M.change_ring(ZZ['x'])
        Traceback (most recent call last):
        ...
        TypeError: the new ring Univariate Polynomial Ring in x over Integer Ring
        should be a principal ideal domain

  construction()

    Return the functorial construction of `self`, namely, the subspace of the ambient module spanned by the given basis.

    EXAMPLES:

    Sage

        sage: M = ZZ^3
        sage: W = M.span_of_basis([[1,2,3],[4,5,6]]); W
        Free module of degree 3 and rank 2 over Integer Ring
        User basis matrix:
        [1 2 3]
        [4 5 6]
        sage: c, V = W.construction()
        sage: c(V) == W
        True

    Python

        >>> from sage.all import *
        >>> M = ZZ**Integer(3)
        >>> W = M.span_of_basis([[Integer(1),Integer(2),Integer(3)],[Integer(4),Integer(5),Integer(6)]]); W
        Free module of degree 3 and rank 2 over Integer Ring
        User basis matrix:
        [1 2 3]
        [4 5 6]
        >>> c, V = W.construction()
        >>> c(V) == W
        True

  coordinate_vector(v, check=True)

    Write \(v\) in terms of the user basis for `self`.

    INPUT:

    - `v` – vector

    - `check` – boolean (default: `True`); if `True`, also verify that \(v\) is really in `self`

    OUTPUT: list

    The output is a vector \(c\) such that if \(B\) is the basis for `self`, then

    \[\sum c_i B_i = v.\]

    If \(v\) is not in self, raise an `ArithmeticError` exception.

    EXAMPLES:

    Sage

        sage: V = ZZ^3
        sage: M = V.span_of_basis([['1/8',2,1]])
        sage: M.coordinate_vector([1,16,8])
        (8)

    Python

        >>> from sage.all import *
        >>> V = ZZ**Integer(3)
        >>> M = V.span_of_basis([['1/8',Integer(2),Integer(1)]])
        >>> M.coordinate_vector([Integer(1),Integer(16),Integer(8)])
        (8)

  echelon_coordinate_vector(v, check=True)

    Write \(v\) in terms of the echelonized basis for `self`.

    INPUT:

    - `v` – vector

    - `check` – boolean (default: `True`); if `True`, also verify that \(v\) is really in `self`

    Returns a list \(c\) such that if \(B\) is the echelonized basis for `self`, then

    \[\sum c_i B_i = v.\]

    If \(v\) is not in self, raise an `ArithmeticError` exception.

    EXAMPLES:

    Sage

        sage: V = ZZ^3
        sage: M = V.span_of_basis([['1/2',3,1], [0,'1/6',0]])
        sage: B = M.echelonized_basis(); B
        [(1/2, 0, 1), (0, 1/6, 0)]
        sage: M.echelon_coordinate_vector(['1/2', 3, 1])
        (1, 18)

    Python

        >>> from sage.all import *
        >>> V = ZZ**Integer(3)
        >>> M = V.span_of_basis([['1/2',Integer(3),Integer(1)], [Integer(0),'1/6',Integer(0)]])
        >>> B = M.echelonized_basis(); B
        [(1/2, 0, 1), (0, 1/6, 0)]
        >>> M.echelon_coordinate_vector(['1/2', Integer(3), Integer(1)])
        (1, 18)

  echelon_coordinates(v, check=True)

    Write \(v\) in terms of the echelonized basis for `self`.

    INPUT:

    - `v` – vector

    - `check` – boolean (default: `True`); if `True`, also verify that \(v\) is really in `self`

    OUTPUT: list

    Returns a list \(c\) such that if \(B\) is the basis for self, then

    \[\sum c_i B_i = v.\]

    If \(v\) is not in self, raise an `ArithmeticError` exception.

    EXAMPLES:

    Sage

        sage: A = ZZ^3
        sage: M = A.span_of_basis([[1,2,'3/7'],[4,5,6]])
        sage: M.coordinates([8,10,12])
        [0, 2]
        sage: M.echelon_coordinates([8,10,12])
        [8, -2]
        sage: B = M.echelonized_basis(); B
        [(1, 2, 3/7), (0, 3, -30/7)]
        sage: 8*B[0] - 2*B[1]
        (8, 10, 12)

    Python

        >>> from sage.all import *
        >>> A = ZZ**Integer(3)
        >>> M = A.span_of_basis([[Integer(1),Integer(2),'3/7'],[Integer(4),Integer(5),Integer(6)]])
        >>> M.coordinates([Integer(8),Integer(10),Integer(12)])
        [0, 2]
        >>> M.echelon_coordinates([Integer(8),Integer(10),Integer(12)])
        [8, -2]
        >>> B = M.echelonized_basis(); B
        [(1, 2, 3/7), (0, 3, -30/7)]
        >>> Integer(8)*B[Integer(0)] - Integer(2)*B[Integer(1)]
        (8, 10, 12)

    We do an example with a sparse vector space:

    Sage

        sage: V = VectorSpace(QQ,5, sparse=True)
        sage: W = V.subspace_with_basis([[0,1,2,0,0], [0,-1,0,0,-1/2]])
        sage: W.echelonized_basis()
        [(0, 1, 0, 0, 1/2), (0, 0, 1, 0, -1/4)]
        sage: W.echelon_coordinates([0,0,2,0,-1/2])
        [0, 2]

    [Python]

        >>> from sage.all import *
        >>> V = VectorSpace(QQ,Integer(5), sparse=True)
        >>> W = V.subspace_with_basis([[Integer(0),Integer(1),Integer(2),Integer(0),Integer(0)], [Integer(0),-Integer(1),Integer(0),Integer(0),-Integer(1)/Integer(2)]])
        >>> W.echelonized_basis()
        [(0, 1, 0, 0, 1/2), (0, 0, 1, 0, -1/4)]
        >>> W.echelon_coordinates([Integer(0),Integer(0),Integer(2),Integer(0),-Integer(1)/Integer(2)])
        [0, 2]

  echelon_to_user_matrix()

    Return matrix that transforms the echelon basis to the user basis of `self`. This is a matrix \(A\) such that if \(v\) is a vector written with respect to the echelon basis for `self` then \(vA\) is that vector written with respect to the user basis of `self`.

    EXAMPLES:

    Sage

        sage: V = QQ^3
        sage: W = V.span_of_basis([[1,2,3],[4,5,6]])
        sage: W.echelonized_basis()
        [(1, 0, -1), (0, 1, 2)]
        sage: A = W.echelon_to_user_matrix(); A
        [-5/3  2/3]
        [ 4/3 -1/3]

    Python

        >>> from sage.all import *
        >>> V = QQ**Integer(3)
        >>> W = V.span_of_basis([[Integer(1),Integer(2),Integer(3)],[Integer(4),Integer(5),Integer(6)]])
        >>> W.echelonized_basis()
        [(1, 0, -1), (0, 1, 2)]
        >>> A = W.echelon_to_user_matrix(); A
        [-5/3  2/3]
        [ 4/3 -1/3]

    The vector \((1,1,1)\) has coordinates \(v=(1,1)\) with respect to the echelonized basis for `self`. Multiplying \(vA\) we find the coordinates of this vector with respect to the user basis.

    Sage

        sage: v = vector(QQ, [1,1]); v
        (1, 1)
        sage: v * A
        (-1/3, 1/3)
        sage: u0, u1 = W.basis()
        sage: (-u0 + u1)/3
        (1, 1, 1)

    [Python]

        >>> from sage.all import *
        >>> v = vector(QQ, [Integer(1),Integer(1)]); v
        (1, 1)
        >>> v * A
        (-1/3, 1/3)
        >>> u0, u1 = W.basis()
        >>> (-u0 + u1)/Integer(3)
        (1, 1, 1)

  echelonized_basis()

    Return the basis for `self` in echelon form.

    EXAMPLES:

    Sage

        sage: V = ZZ^3
        sage: M = V.span_of_basis([['1/2',3,1], [0,'1/6',0]])
        sage: M.basis()
        [(1/2, 3, 1), (0, 1/6, 0)]
        sage: B = M.echelonized_basis(); B
        [(1/2, 0, 1), (0, 1/6, 0)]
        sage: V.span(B) == M
        True

    Python

        >>> from sage.all import *
        >>> V = ZZ**Integer(3)
        >>> M = V.span_of_basis([['1/2',Integer(3),Integer(1)], [Integer(0),'1/6',Integer(0)]])
        >>> M.basis()
        [(1/2, 3, 1), (0, 1/6, 0)]
        >>> B = M.echelonized_basis(); B
        [(1/2, 0, 1), (0, 1/6, 0)]
        >>> V.span(B) == M
        True

  echelonized_basis_matrix()

    Return basis matrix for `self` in row echelon form.

    EXAMPLES:

    Sage

        sage: V = FreeModule(ZZ, 3).span_of_basis([[1,2,3],[4,5,6]])
        sage: V.basis_matrix()
        [1 2 3]
        [4 5 6]
        sage: V.echelonized_basis_matrix()
        [1 2 3]
        [0 3 6]

        sage: from sage.modules.free_module import FreeModule_ambient_pid, FreeModule_submodule_with_basis_pid
        sage: V = FreeModule_ambient_pid(ZZ, 3)
        sage: W = FreeModule_submodule_with_basis_pid(V, [[1,2,3], [1,1,1]])
        sage: W.basis_matrix()
        [1 2 3]
        [1 1 1]
        sage: W._FreeModule_submodule_with_basis_pid__echelonized_basis_matrix is not None
        False
        sage: W.echelonized_basis_matrix()
        [ 1  0 -1]
        [ 0  1  2]

    Python

        >>> from sage.all import *
        >>> V = FreeModule(ZZ, Integer(3)).span_of_basis([[Integer(1),Integer(2),Integer(3)],[Integer(4),Integer(5),Integer(6)]])
        >>> V.basis_matrix()
        [1 2 3]
        [4 5 6]
        >>> V.echelonized_basis_matrix()
        [1 2 3]
        [0 3 6]

        >>> from sage.modules.free_module import FreeModule_ambient_pid, FreeModule_submodule_with_basis_pid
        >>> V = FreeModule_ambient_pid(ZZ, Integer(3))
        >>> W = FreeModule_submodule_with_basis_pid(V, [[Integer(1),Integer(2),Integer(3)], [Integer(1),Integer(1),Integer(1)]])
        >>> W.basis_matrix()
        [1 2 3]
        [1 1 1]
        >>> W._FreeModule_submodule_with_basis_pid__echelonized_basis_matrix is not None
        False
        >>> W.echelonized_basis_matrix()
        [ 1  0 -1]
        [ 0  1  2]

  has_user_basis()

    Return `True` if the basis of this free module is specified by the user, as opposed to being the default echelon form.

    EXAMPLES:

    Sage

        sage: V = ZZ^3; V.has_user_basis()
        False
        sage: M = V.span_of_basis([[1,3,1]]); M.has_user_basis()
        True
        sage: M = V.span([[1,3,1]]); M.has_user_basis()
        False

    Python

        >>> from sage.all import *
        >>> V = ZZ**Integer(3); V.has_user_basis()
        False
        >>> M = V.span_of_basis([[Integer(1),Integer(3),Integer(1)]]); M.has_user_basis()
        True
        >>> M = V.span([[Integer(1),Integer(3),Integer(1)]]); M.has_user_basis()
        False

  lift()

    The lift (embedding) map from `self` to the ambient module or space.

    EXAMPLES:

    Sage

        sage: M = ZZ^3
        sage: W = M.span_of_basis([[1,2,3],[4,5,6]]); W
        Free module of degree 3 and rank 2 over Integer Ring
        User basis matrix:
        [1 2 3]
        [4 5 6]
        sage: W.lift
        Generic morphism:
        From: Free module of degree 3 and rank 2 over Integer Ring
        User basis matrix:
        [1 2 3]
        [4 5 6]
        To:   Ambient free module of rank 3 over the principal ideal domain Integer Ring
        sage: w = W([5,7,9])
        sage: m = W.lift(w); m
        (5, 7, 9)
        sage: m.parent()
        Ambient free module of rank 3 over the principal ideal domain Integer Ring

    Python

        >>> from sage.all import *
        >>> M = ZZ**Integer(3)
        >>> W = M.span_of_basis([[Integer(1),Integer(2),Integer(3)],[Integer(4),Integer(5),Integer(6)]]); W
        Free module of degree 3 and rank 2 over Integer Ring
        User basis matrix:
        [1 2 3]
        [4 5 6]
        >>> W.lift
        Generic morphism:
        From: Free module of degree 3 and rank 2 over Integer Ring
        User basis matrix:
        [1 2 3]
        [4 5 6]
        To:   Ambient free module of rank 3 over the principal ideal domain Integer Ring
        >>> w = W([Integer(5),Integer(7),Integer(9)])
        >>> m = W.lift(w); m
        (5, 7, 9)
        >>> m.parent()
        Ambient free module of rank 3 over the principal ideal domain Integer Ring

  linear_combination_of_basis(v)

    Return the linear combination of the basis for `self` obtained from the coordinates of v.

    INPUT:

    - `v` – list

    EXAMPLES:

    Sage

        sage: V = span([[1,2,3], [4,5,6]], ZZ); V
        Free module of degree 3 and rank 2 over Integer Ring
        Echelon basis matrix:
        [1 2 3]
        [0 3 6]
        sage: V.linear_combination_of_basis([1,1])
        (1, 5, 9)

    Python

        >>> from sage.all import *
        >>> V = span([[Integer(1),Integer(2),Integer(3)], [Integer(4),Integer(5),Integer(6)]], ZZ); V
        Free module of degree 3 and rank 2 over Integer Ring
        Echelon basis matrix:
        [1 2 3]
        [0 3 6]
        >>> V.linear_combination_of_basis([Integer(1),Integer(1)])
        (1, 5, 9)

    This should raise an error if the resulting element is not in self:

    Sage

        sage: W = (QQ**2).span([[2, 0], [0, 8]], ZZ)
        sage: W.linear_combination_of_basis([1, -1/2])
        Traceback (most recent call last):
        ...
        TypeError: element [2, -4] is not in free module

    [Python]

        >>> from sage.all import *
        >>> W = (QQ**Integer(2)).span([[Integer(2), Integer(0)], [Integer(0), Integer(8)]], ZZ)
        >>> W.linear_combination_of_basis([Integer(1), -Integer(1)/Integer(2)])
        Traceback (most recent call last):
        ...
        TypeError: element [2, -4] is not in free module

  relations()

    Return the submodule defining the relations of `self` as a subquotient (considering the ambient module as a quotient module).

    EXAMPLES:

    Sage

        sage: V = GF(2)^2
        sage: W = V.subspace([[1, 0]])
        sage: W.relations() == V.zero_submodule()
        True

        sage: Q = V / W
        sage: Q.relations() == W
        True
        sage: Q.zero_submodule().relations() == W
        True

    Python

        >>> from sage.all import *
        >>> V = GF(Integer(2))**Integer(2)
        >>> W = V.subspace([[Integer(1), Integer(0)]])
        >>> W.relations() == V.zero_submodule()
        True

        >>> Q = V / W
        >>> Q.relations() == W
        True
        >>> Q.zero_submodule().relations() == W
        True

  retract()

    The retract map from the ambient space.

    This is a partial map, which gives an error for elements not in the subspace.

    Calling this map on elements of the ambient space is the same as calling the element constructor of `self`.

    EXAMPLES:

    Sage

        sage: M = ZZ^3
        sage: W = M.span_of_basis([[1,2,3],[4,5,6]]); W
        Free module of degree 3 and rank 2 over Integer Ring
        User basis matrix:
        [1 2 3]
        [4 5 6]
        sage: W.retract
        Generic morphism:
        From: Ambient free module of rank 3 over the principal ideal domain Integer Ring
        To:   Free module of degree 3 and rank 2 over Integer Ring
        User basis matrix:
        [1 2 3]
        [4 5 6]
        sage: m = M([5, 7, 9])
        sage: w = W.retract(m); w
        (5, 7, 9)
        sage: w.parent()
        Free module of degree 3 and rank 2 over Integer Ring
        User basis matrix:
        [1 2 3]
        [4 5 6]

    Python

        >>> from sage.all import *
        >>> M = ZZ**Integer(3)
        >>> W = M.span_of_basis([[Integer(1),Integer(2),Integer(3)],[Integer(4),Integer(5),Integer(6)]]); W
        Free module of degree 3 and rank 2 over Integer Ring
        User basis matrix:
        [1 2 3]
        [4 5 6]
        >>> W.retract
        Generic morphism:
        From: Ambient free module of rank 3 over the principal ideal domain Integer Ring
        To:   Free module of degree 3 and rank 2 over Integer Ring
        User basis matrix:
        [1 2 3]
        [4 5 6]
        >>> m = M([Integer(5), Integer(7), Integer(9)])
        >>> w = W.retract(m); w
        (5, 7, 9)
        >>> w.parent()
        Free module of degree 3 and rank 2 over Integer Ring
        User basis matrix:
        [1 2 3]
        [4 5 6]

  user_to_echelon_matrix()

    Return matrix that transforms a vector written with respect to the user basis of `self` to one written with respect to the echelon basis. The matrix acts from the right, as is usual in Sage.

    EXAMPLES:

    Sage

        sage: A = ZZ^3
        sage: M = A.span_of_basis([[1,2,3],[4,5,6]])
        sage: M.echelonized_basis()
        [(1, 2, 3), (0, 3, 6)]
        sage: M.user_to_echelon_matrix()
        [ 1  0]
        [ 4 -1]

    Python

        >>> from sage.all import *
        >>> A = ZZ**Integer(3)
        >>> M = A.span_of_basis([[Integer(1),Integer(2),Integer(3)],[Integer(4),Integer(5),Integer(6)]])
        >>> M.echelonized_basis()
        [(1, 2, 3), (0, 3, 6)]
        >>> M.user_to_echelon_matrix()
        [ 1  0]
        [ 4 -1]

    The vector \(v=(5,7,9)\) in \(M\) is \((1,1)\) with respect to the user basis. Multiplying the above matrix on the right by this vector yields \((5,-1)\), which has components the coordinates of \(v\) with respect to the echelon basis.

    Sage

        sage: v0,v1 = M.basis(); v = v0+v1
        sage: e0,e1 = M.echelonized_basis()
        sage: v
        (5, 7, 9)
        sage: 5*e0 + (-1)*e1
        (5, 7, 9)

    [Python]

        >>> from sage.all import *
        >>> v0,v1 = M.basis(); v = v0+v1
        >>> e0,e1 = M.echelonized_basis()
        >>> v
        (5, 7, 9)
        >>> Integer(5)*e0 + (-Integer(1))*e1
        (5, 7, 9)

  vector_space(base_field=None)

    Return the vector space associated to this free module via tensor product with the fraction field of the base ring.

    EXAMPLES:

    Sage

        sage: A = ZZ^3; A
        Ambient free module of rank 3 over the principal ideal domain Integer Ring
        sage: A.vector_space()
        Vector space of dimension 3 over Rational Field
        sage: M = A.span_of_basis([['1/3',2,'3/7'],[4,5,6]]); M
        Free module of degree 3 and rank 2 over Integer Ring
        User basis matrix:
        [1/3   2 3/7]
        [  4   5   6]
        sage: M.vector_space()
        Vector space of degree 3 and dimension 2 over Rational Field
        User basis matrix:
        [1/3   2 3/7]
        [  4   5   6]

    Python

        >>> from sage.all import *
        >>> A = ZZ**Integer(3); A
        Ambient free module of rank 3 over the principal ideal domain Integer Ring
        >>> A.vector_space()
        Vector space of dimension 3 over Rational Field
        >>> M = A.span_of_basis([['1/3',Integer(2),'3/7'],[Integer(4),Integer(5),Integer(6)]]); M
        Free module of degree 3 and rank 2 over Integer Ring
        User basis matrix:
        [1/3   2 3/7]
        [  4   5   6]
        >>> M.vector_space()
        Vector space of degree 3 and dimension 2 over Rational Field
        User basis matrix:
        [1/3   2 3/7]
        [  4   5   6]

class sage.modules.free_module.Module_free_ambient(base_ring, degree, sparse=False, category=None)

  Bases: `Module`

  Base class for modules with elements represented by elements of a free module.

  Modules whose elements are represented by elements of a free module (such as submodules, quotients, and subquotients of a free module) should be either a subclass of this class or `FreeModule_generic`, which itself is a subclass of this class. If the modules have bases and ranks, then use `FreeModule_generic`. Otherwise, use this class.

  INPUT:

  - `base_ring` – a commutative ring

  - `degree` – nonnegative integer; degree of the ambient free module

  - `sparse` – boolean (default: `False`)

  - `category` – category (default: `None`)

  If `base_ring` is a field, then the default category is the category of finite-dimensional vector spaces over that field; otherwise it is the category of finite-dimensional free modules over that ring. In addition, the category is intersected with the category of finite enumerated sets if the ring is finite or the rank is 0.

  EXAMPLES:

  Sage

      sage: S.<x,y,z> = PolynomialRing(QQ)
      sage: M = S**2
      sage: N = M.submodule([vector([x - y, z]), vector([y * z, x * z])])
      sage: N.gens()
      [(x - y, z), (y*z, x*z)]
      sage: N.degree()
      2

  Python

      >>> from sage.all import *
      >>> S = PolynomialRing(QQ, names=('x', 'y', 'z',)); (x, y, z,) = S._first_ngens(3)
      >>> M = S**Integer(2)
      >>> N = M.submodule([vector([x - y, z]), vector([y * z, x * z])])
      >>> N.gens()
      [(x - y, z), (y*z, x*z)]
      >>> N.degree()
      2

  coordinate_ring()

    Return the ring over which the entries of the vectors are defined.

    EXAMPLES:

    Sage

        sage: S.<x,y,z> = PolynomialRing(QQ)
        sage: M = S**2
        sage: N = M.submodule([vector([x - y, z]), vector([y * z, x * z])])
        sage: N.coordinate_ring()
        Multivariate Polynomial Ring in x, y, z over Rational Field

    Python

        >>> from sage.all import *
        >>> S = PolynomialRing(QQ, names=('x', 'y', 'z',)); (x, y, z,) = S._first_ngens(3)
        >>> M = S**Integer(2)
        >>> N = M.submodule([vector([x - y, z]), vector([y * z, x * z])])
        >>> N.coordinate_ring()
        Multivariate Polynomial Ring in x, y, z over Rational Field

  degree()

    Return the degree of this free module. This is the dimension of the ambient vector space in which it is embedded.

    EXAMPLES:

    Sage

        sage: M = FreeModule(ZZ, 10)
        sage: W = M.submodule([M.gen(0), 2*M.gen(3) - M.gen(0), M.gen(0) + M.gen(3)])
        sage: W.degree()
        10
        sage: W.rank()
        2

    Python

        >>> from sage.all import *
        >>> M = FreeModule(ZZ, Integer(10))
        >>> W = M.submodule([M.gen(Integer(0)), Integer(2)*M.gen(Integer(3)) - M.gen(Integer(0)), M.gen(Integer(0)) + M.gen(Integer(3))])
        >>> W.degree()
        10
        >>> W.rank()
        2

  free_resolution(*args, **kwds)

    Return a free resolution of `self`.

    For input options, see `FreeResolution`.

    EXAMPLES:

    Sage

        sage: S.<x,y,z> = PolynomialRing(QQ)
        sage: M = S**2
        sage: N = M.submodule([vector([x - y, z]), vector([y * z, x * z])])
        sage: res = N.free_resolution(); res                                        # needs sage.libs.singular
        S^2 <-- S^2 <-- 0
        sage: ascii_art(res.chain_complex())                                        # needs sage.libs.singular
                    [x - y   y*z]
                    [    z   x*z]
         0 <-- C_0 <-------------- C_1 <-- 0

    Python

        >>> from sage.all import *
        >>> S = PolynomialRing(QQ, names=('x', 'y', 'z',)); (x, y, z,) = S._first_ngens(3)
        >>> M = S**Integer(2)
        >>> N = M.submodule([vector([x - y, z]), vector([y * z, x * z])])
        >>> res = N.free_resolution(); res                                        # needs sage.libs.singular
        S^2 <-- S^2 <-- 0
        >>> ascii_art(res.chain_complex())                                        # needs sage.libs.singular
                    [x - y   y*z]
                    [    z   x*z]
         0 <-- C_0 <-------------- C_1 <-- 0

  graded_free_resolution(*args, **kwds)

    Return a graded free resolution of `self`.

    For input options, see `GradedFiniteFreeResolution`.

    EXAMPLES:

    Sage

        sage: S.<x,y,z> = PolynomialRing(QQ)
        sage: M = S**2
        sage: N = M.submodule([vector([x - y, z]), vector([y * z, x * z])])
        sage: N.graded_free_resolution(shifts=[1, -1])                              # needs sage.libs.singular
        S(-1)⊕S(1) <-- S(-2)⊕S(-3) <-- 0
        sage: N.graded_free_resolution(shifts=[2, 3])                               # needs sage.libs.singular
        S(-2)⊕S(-3) <-- S(-3)⊕S(-4) <-- 0

        sage: N = M.submodule([vector([x^3 - y^6, z^2]), vector([y * z, x])])
        sage: N.graded_free_resolution(degrees=[2, 1, 3], shifts=[2, 3])            # needs sage.libs.singular
        S(-2)⊕S(-3) <-- S(-6)⊕S(-8) <-- 0

    Python

        >>> from sage.all import *
        >>> S = PolynomialRing(QQ, names=('x', 'y', 'z',)); (x, y, z,) = S._first_ngens(3)
        >>> M = S**Integer(2)
        >>> N = M.submodule([vector([x - y, z]), vector([y * z, x * z])])
        >>> N.graded_free_resolution(shifts=[Integer(1), -Integer(1)])                              # needs sage.libs.singular
        S(-1)⊕S(1) <-- S(-2)⊕S(-3) <-- 0
        >>> N.graded_free_resolution(shifts=[Integer(2), Integer(3)])                               # needs sage.libs.singular
        S(-2)⊕S(-3) <-- S(-3)⊕S(-4) <-- 0

        >>> N = M.submodule([vector([x**Integer(3) - y**Integer(6), z**Integer(2)]), vector([y * z, x])])
        >>> N.graded_free_resolution(degrees=[Integer(2), Integer(1), Integer(3)], shifts=[Integer(2), Integer(3)])            # needs sage.libs.singular
        S(-2)⊕S(-3) <-- S(-6)⊕S(-8) <-- 0

  is_exact()

    Test whether elements of this module are represented exactly.

    OUTPUT:

    Return `True` if elements of this module are represented exactly, i.e., there is no precision loss when doing arithmetic.

    EXAMPLES:

    Sage

        sage: (ZZ^2).is_exact()
        True
        sage: (RR^2).is_exact()
        False

    Python

        >>> from sage.all import *
        >>> (ZZ**Integer(2)).is_exact()
        True
        >>> (RR**Integer(2)).is_exact()
        False

  is_sparse()

    Return `True` if the underlying representation of this module uses sparse vectors, and `False` otherwise.

    EXAMPLES:

    Sage

        sage: FreeModule(ZZ, 2).is_sparse()
        False
        sage: FreeModule(ZZ, 2, sparse=True).is_sparse()
        True

    Python

        >>> from sage.all import *
        >>> FreeModule(ZZ, Integer(2)).is_sparse()
        False
        >>> FreeModule(ZZ, Integer(2), sparse=True).is_sparse()
        True

  is_submodule(other)

    Return `True` if `self` is a submodule of `other`.

    EXAMPLES:

    Submodule testing over general rings is not guaranteed to work in all cases. However, it will raise an error when it is unable to determine containment.

    The zero module can always be tested:

    Sage

        sage: S.<x,y,z> = PolynomialRing(QQ)
        sage: M = S**2
        sage: N = M.submodule([vector([x - y, z]), vector([y*z, x*z])])
        sage: N.zero_submodule().is_submodule(M)
        True
        sage: N.zero_submodule().is_submodule(N)
        True
        sage: M.zero_submodule().is_submodule(N)
        True

    Python

        >>> from sage.all import *
        >>> S = PolynomialRing(QQ, names=('x', 'y', 'z',)); (x, y, z,) = S._first_ngens(3)
        >>> M = S**Integer(2)
        >>> N = M.submodule([vector([x - y, z]), vector([y*z, x*z])])
        >>> N.zero_submodule().is_submodule(M)
        True
        >>> N.zero_submodule().is_submodule(N)
        True
        >>> M.zero_submodule().is_submodule(N)
        True

    It also respects which module it is constructed from:

    Sage

        sage: Q = M.quotient_module(N)
        sage: Q.zero_submodule().is_submodule(M)
        False
        sage: Q.zero_submodule().is_submodule(N)
        False
        sage: M.zero_submodule().is_submodule(Q)
        False
        sage: N.zero_submodule().is_submodule(Q)
        False

    [Python]

        >>> from sage.all import *
        >>> Q = M.quotient_module(N)
        >>> Q.zero_submodule().is_submodule(M)
        False
        >>> Q.zero_submodule().is_submodule(N)
        False
        >>> M.zero_submodule().is_submodule(Q)
        False
        >>> N.zero_submodule().is_submodule(Q)
        False

  quotient_module(sub, check=True)

    Return the quotient of `self` by the given subspace `sub`.

    INPUT:

    - `sub` – a submodule of `self` or something that can be turned into one via `self.submodule(sub)`

    - `check` – boolean (default: `True`); whether or not to check that `sub` is a submodule

    EXAMPLES:

    Sage

        sage: S.<x,y,z> = PolynomialRing(QQ)
        sage: M = S**2
        sage: N = M.submodule([vector([x - y, z]), vector([y * z, x * z])])
        sage: M.quotient(N)
        Quotient module by Submodule of Ambient free module of rank 2 over
         the integral domain Multivariate Polynomial Ring in x, y, z over Rational Field
        Generated by the rows of the matrix:
        [x - y     z]
        [  y*z   x*z]

    Python

        >>> from sage.all import *
        >>> S = PolynomialRing(QQ, names=('x', 'y', 'z',)); (x, y, z,) = S._first_ngens(3)
        >>> M = S**Integer(2)
        >>> N = M.submodule([vector([x - y, z]), vector([y * z, x * z])])
        >>> M.quotient(N)
        Quotient module by Submodule of Ambient free module of rank 2 over
         the integral domain Multivariate Polynomial Ring in x, y, z over Rational Field
        Generated by the rows of the matrix:
        [x - y     z]
        [  y*z   x*z]

  relations_matrix()

    Return the matrix of relations of `self`.

    EXAMPLES:

    Sage

        sage: V = GF(2)^2
        sage: V.relations_matrix()
        []
        sage: W = V.subspace([[1, 0]])
        sage: W.relations_matrix()
        []

        sage: Q = V / W
        sage: Q.relations_matrix()
        [1 0]

        sage: S.<x,y,z> = PolynomialRing(QQ)
        sage: M = S**2
        sage: M.relations_matrix()
        []

        sage: N = M.submodule([vector([x - y, z]), vector([y*z, x*z])])
        sage: Q = M.quotient_module(N)
        sage: Q.relations_matrix()
        [x - y     z]
        [  y*z   x*z]

    Python

        >>> from sage.all import *
        >>> V = GF(Integer(2))**Integer(2)
        >>> V.relations_matrix()
        []
        >>> W = V.subspace([[Integer(1), Integer(0)]])
        >>> W.relations_matrix()
        []

        >>> Q = V / W
        >>> Q.relations_matrix()
        [1 0]

        >>> S = PolynomialRing(QQ, names=('x', 'y', 'z',)); (x, y, z,) = S._first_ngens(3)
        >>> M = S**Integer(2)
        >>> M.relations_matrix()
        []

        >>> N = M.submodule([vector([x - y, z]), vector([y*z, x*z])])
        >>> Q = M.quotient_module(N)
        >>> Q.relations_matrix()
        [x - y     z]
        [  y*z   x*z]

  some_elements()

    Return some elements of this free module.

    See `TestSuite` for a typical use case.

    OUTPUT: an iterator

    EXAMPLES:

    Sage

        sage: F = FreeModule(ZZ, 2)
        sage: tuple(F.some_elements())
        ((1, 0),
         (1, 1),
         (0, 1),
         (-1, 2),
         (-2, 3),
         ...
         (-49, 50))

        sage: F = FreeModule(QQ, 3)
        sage: tuple(F.some_elements())
        ((1, 0, 0),
         (1/2, 1/2, 1/2),
         (1/2, -1/2, 2),
         (-2, 0, 1),
         (-1, 42, 2/3),
         (-2/3, 3/2, -3/2),
         (4/5, -4/5, 5/4),
         ...
         (46/103823, -46/103823, 103823/46))

        sage: F = FreeModule(SR, 2)                                                 # needs sage.symbolic
        sage: tuple(F.some_elements())                                              # needs sage.symbolic
        ((1, 0), (some_variable, some_variable))

    Python

        >>> from sage.all import *
        >>> F = FreeModule(ZZ, Integer(2))
        >>> tuple(F.some_elements())
        ((1, 0),
         (1, 1),
         (0, 1),
         (-1, 2),
         (-2, 3),
         ...
         (-49, 50))

        >>> F = FreeModule(QQ, Integer(3))
        >>> tuple(F.some_elements())
        ((1, 0, 0),
         (1/2, 1/2, 1/2),
         (1/2, -1/2, 2),
         (-2, 0, 1),
         (-1, 42, 2/3),
         (-2/3, 3/2, -3/2),
         (4/5, -4/5, 5/4),
         ...
         (46/103823, -46/103823, 103823/46))

        >>> F = FreeModule(SR, Integer(2))                                                 # needs sage.symbolic
        >>> tuple(F.some_elements())                                              # needs sage.symbolic
        ((1, 0), (some_variable, some_variable))

  span(gens, base_ring=None, check=True, already_echelonized=False)

    Return the \(R\)-span of `gens`, where \(R\) is the `base_ring`.

    The default \(R\) is the base ring of `self`. Note that this span need not be a submodule of `self`, nor even of the ambient space. It must, however, be contained in the ambient vector space, i.e., the ambient space tensored with the fraction field of \(R\).

    INPUT:

    - `gens` – list of vectors

    - `base_ring` – (optional) a ring

    - `check` – boolean (default: `True`); whether or not to coerce entries of gens into base field

    - `already_echelonized` – boolean (default: `False`); set this if you know the gens are already in echelon form

    EXAMPLES:

    Sage

        sage: V = VectorSpace(GF(7), 3)
        sage: W = V.subspace([[2, 3, 4]]); W
        Vector space of degree 3 and dimension 1 over Finite Field of size 7
        Basis matrix:
        [1 5 2]
        sage: W.span([[1, 1, 1]])
        Vector space of degree 3 and dimension 1 over Finite Field of size 7
        Basis matrix:
        [1 1 1]

    Python

        >>> from sage.all import *
        >>> V = VectorSpace(GF(Integer(7)), Integer(3))
        >>> W = V.subspace([[Integer(2), Integer(3), Integer(4)]]); W
        Vector space of degree 3 and dimension 1 over Finite Field of size 7
        Basis matrix:
        [1 5 2]
        >>> W.span([[Integer(1), Integer(1), Integer(1)]])
        Vector space of degree 3 and dimension 1 over Finite Field of size 7
        Basis matrix:
        [1 1 1]

    Over a general ring:

    Sage

        sage: S.<x,y,z> = PolynomialRing(QQ)
        sage: M = S**2
        sage: M.span([vector([x - y, z]), vector([y*z, x*z])])
        Submodule of Ambient free module of rank 2 over the integral domain
         Multivariate Polynomial Ring in x, y, z over Rational Field
        Generated by the rows of the matrix:
        [x - y     z]
        [  y*z   x*z]

    [Python]

        >>> from sage.all import *
        >>> S = PolynomialRing(QQ, names=('x', 'y', 'z',)); (x, y, z,) = S._first_ngens(3)
        >>> M = S**Integer(2)
        >>> M.span([vector([x - y, z]), vector([y*z, x*z])])
        Submodule of Ambient free module of rank 2 over the integral domain
         Multivariate Polynomial Ring in x, y, z over Rational Field
        Generated by the rows of the matrix:
        [x - y     z]
        [  y*z   x*z]

    Over a PID:

    Sage

        sage: V = FreeModule(ZZ, 3)
        sage: W = V.submodule([V.gen(0)])
        sage: W.span([V.gen(1)])
        Free module of degree 3 and rank 1 over Integer Ring
        Echelon basis matrix:
        [0 1 0]
        sage: W.submodule([V.gen(1)])
        Traceback (most recent call last):
        ...
        ArithmeticError: argument gens (= [(0, 1, 0)]) does not generate a submodule of self
        sage: V.span([[1,0,0], [1/5,4,0], [6,3/4,0]])
        Free module of degree 3 and rank 2 over Integer Ring
        Echelon basis matrix:
        [1/5   0   0]
        [  0 1/4   0]

    Python

        >>> from sage.all import *
        >>> V = FreeModule(ZZ, Integer(3))
        >>> W = V.submodule([V.gen(Integer(0))])
        >>> W.span([V.gen(Integer(1))])
        Free module of degree 3 and rank 1 over Integer Ring
        Echelon basis matrix:
        [0 1 0]
        >>> W.submodule([V.gen(Integer(1))])
        Traceback (most recent call last):
        ...
        ArithmeticError: argument gens (= [(0, 1, 0)]) does not generate a submodule of self
        >>> V.span([[Integer(1),Integer(0),Integer(0)], [Integer(1)/Integer(5),Integer(4),Integer(0)], [Integer(6),Integer(3)/Integer(4),Integer(0)]])
        Free module of degree 3 and rank 2 over Integer Ring
        Echelon basis matrix:
        [1/5   0   0]
        [  0 1/4   0]

    It also works with other things than integers:

    Sage

        sage: R.<x> = QQ[]
        sage: L = R^1
        sage: a = L.span([(1/x,)])
        sage: a
        Free module of degree 1 and rank 1
         over Univariate Polynomial Ring in x over Rational Field
        Echelon basis matrix:
        [1/x]
        sage: b=L.span([(1/x,)])
        sage: a(b.gens()[0])
        (1/x)
        sage: L2 = R^2
        sage: L2.span([[(x^2+x)/(x^2-3*x+2), 1/5], [(x^2+2*x)/(x^2-4*x+3), x]])
        Free module of degree 2 and rank 2
         over Univariate Polynomial Ring in x over Rational Field
        Echelon basis matrix:
        [x/(x^3 - 6*x^2 + 11*x - 6)  2/15*x^2 - 17/75*x - 1/75]
        [                         0 x^3 - 11/5*x^2 - 3*x + 4/5]

    [Python]

        >>> from sage.all import *
        >>> R = QQ['x']; (x,) = R._first_ngens(1)
        >>> L = R**Integer(1)
        >>> a = L.span([(Integer(1)/x,)])
        >>> a
        Free module of degree 1 and rank 1
         over Univariate Polynomial Ring in x over Rational Field
        Echelon basis matrix:
        [1/x]
        >>> b=L.span([(Integer(1)/x,)])
        >>> a(b.gens()[Integer(0)])
        (1/x)
        >>> L2 = R**Integer(2)
        >>> L2.span([[(x**Integer(2)+x)/(x**Integer(2)-Integer(3)*x+Integer(2)), Integer(1)/Integer(5)], [(x**Integer(2)+Integer(2)*x)/(x**Integer(2)-Integer(4)*x+Integer(3)), x]])
        Free module of degree 2 and rank 2
         over Univariate Polynomial Ring in x over Rational Field
        Echelon basis matrix:
        [x/(x^3 - 6*x^2 + 11*x - 6)  2/15*x^2 - 17/75*x - 1/75]
        [                         0 x^3 - 11/5*x^2 - 3*x + 4/5]

    Note that the `base_ring` can make a huge difference. We repeat the previous example over the fraction field of R and get a simpler vector space.

    Sage

        sage: L2.span([[(x^2+x)/(x^2-3*x+2), 1/5], [(x^2+2*x)/(x^2-4*x+3), x]],
        ....:         base_ring=R.fraction_field())
        Vector space of degree 2 and dimension 2 over
         Fraction Field of Univariate Polynomial Ring in x over Rational Field
        Basis matrix:
        [1 0]
        [0 1]

    Python

        >>> from sage.all import *
        >>> L2.span([[(x**Integer(2)+x)/(x**Integer(2)-Integer(3)*x+Integer(2)), Integer(1)/Integer(5)], [(x**Integer(2)+Integer(2)*x)/(x**Integer(2)-Integer(4)*x+Integer(3)), x]],
        ...         base_ring=R.fraction_field())
        Vector space of degree 2 and dimension 2 over
         Fraction Field of Univariate Polynomial Ring in x over Rational Field
        Basis matrix:
        [1 0]
        [0 1]

  submodule(gens, check=True, already_echelonized=False)

    Create the \(R\)-submodule of the ambient module with given generators, where \(R\) is the base ring of `self`.

    INPUT:

    - `gens` – list of free module elements or a free module

    - `check` – boolean (default: `True`); whether or not to verify that the gens are in `self`

    OUTPUT:

    The submodule spanned by the vectors in the list `gens`. The basis for the subspace is always put in reduced row echelon form (if possible).

    EXAMPLES:

    We create a submodule of \(\ZZ^3\):

    Sage

        sage: M = FreeModule(ZZ, 3)
        sage: B = M.basis()
        sage: W = M.submodule([B[0] + B[1], 2*B[1] - B[2]])
        sage: W
        Free module of degree 3 and rank 2 over Integer Ring
        Echelon basis matrix:
        [ 1  1  0]
        [ 0  2 -1]

    Python

        >>> from sage.all import *
        >>> M = FreeModule(ZZ, Integer(3))
        >>> B = M.basis()
        >>> W = M.submodule([B[Integer(0)] + B[Integer(1)], Integer(2)*B[Integer(1)] - B[Integer(2)]])
        >>> W
        Free module of degree 3 and rank 2 over Integer Ring
        Echelon basis matrix:
        [ 1  1  0]
        [ 0  2 -1]

    We create a submodule of a submodule:

    Sage

        sage: W.submodule([3*B[0] + 3*B[1]])
        Free module of degree 3 and rank 1 over Integer Ring
        Echelon basis matrix:
        [3 3 0]

    [Python]

        >>> from sage.all import *
        >>> W.submodule([Integer(3)*B[Integer(0)] + Integer(3)*B[Integer(1)]])
        Free module of degree 3 and rank 1 over Integer Ring
        Echelon basis matrix:
        [3 3 0]

    We try to create a submodule that is not really a submodule, which results in an `ArithmeticError` exception:

    Sage

        sage: W.submodule([B[0] - B[1]])
        Traceback (most recent call last):
        ...
        ArithmeticError: argument gens (= [(1, -1, 0)]) does not generate a submodule of self

    Python

        >>> from sage.all import *
        >>> W.submodule([B[Integer(0)] - B[Integer(1)]])
        Traceback (most recent call last):
        ...
        ArithmeticError: argument gens (= [(1, -1, 0)]) does not generate a submodule of self

    Next we create a submodule of a free module over the principal ideal domain \(\QQ[x]\), which uses the general Hermite normal form functionality:

    Sage

        sage: R = PolynomialRing(QQ, 'x'); x = R.gen()
        sage: M = FreeModule(R, 3)
        sage: B = M.basis()
        sage: W = M.submodule([x*B[0], 2*B[1] - x*B[2]]); W
        Free module of degree 3 and rank 2
         over Univariate Polynomial Ring in x over Rational Field
        Echelon basis matrix:
        [ x  0  0]
        [ 0  2 -x]
        sage: W.ambient_module()
        Ambient free module of rank 3 over the principal ideal domain
         Univariate Polynomial Ring in x over Rational Field

    [Python]

        >>> from sage.all import *
        >>> R = PolynomialRing(QQ, 'x'); x = R.gen()
        >>> M = FreeModule(R, Integer(3))
        >>> B = M.basis()
        >>> W = M.submodule([x*B[Integer(0)], Integer(2)*B[Integer(1)] - x*B[Integer(2)]]); W
        Free module of degree 3 and rank 2
         over Univariate Polynomial Ring in x over Rational Field
        Echelon basis matrix:
        [ x  0  0]
        [ 0  2 -x]
        >>> W.ambient_module()
        Ambient free module of rank 3 over the principal ideal domain
         Univariate Polynomial Ring in x over Rational Field

    Over a generic ring:

    Sage

        sage: S.<x,y,z> = PolynomialRing(QQ)
        sage: A = S**2
        sage: A.submodule([vector([x - y,z]), vector([y*z, x*z])])
        Submodule of Ambient free module of rank 2 over the integral domain
         Multivariate Polynomial Ring in x, y, z over Rational Field
        Generated by the rows of the matrix:
        [x - y     z]
        [  y*z   x*z]

    Python

        >>> from sage.all import *
        >>> S = PolynomialRing(QQ, names=('x', 'y', 'z',)); (x, y, z,) = S._first_ngens(3)
        >>> A = S**Integer(2)
        >>> A.submodule([vector([x - y,z]), vector([y*z, x*z])])
        Submodule of Ambient free module of rank 2 over the integral domain
         Multivariate Polynomial Ring in x, y, z over Rational Field
        Generated by the rows of the matrix:
        [x - y     z]
        [  y*z   x*z]

  zero()

    Return the zero vector in this module.

    EXAMPLES:

    Sage

        sage: M = FreeModule(ZZ, 2)
        sage: M.zero()
        (0, 0)
        sage: M.span([[1,1]]).zero()
        (0, 0)
        sage: M.zero_submodule().zero()
        (0, 0)
        sage: M.zero_submodule().zero().is_mutable()
        False

    Python

        >>> from sage.all import *
        >>> M = FreeModule(ZZ, Integer(2))
        >>> M.zero()
        (0, 0)
        >>> M.span([[Integer(1),Integer(1)]]).zero()
        (0, 0)
        >>> M.zero_submodule().zero()
        (0, 0)
        >>> M.zero_submodule().zero().is_mutable()
        False

  zero_submodule()

    Return the zero submodule of this module.

    EXAMPLES:

    Sage

        sage: S.<x,y,z> = PolynomialRing(QQ)
        sage: M = S**2
        sage: M.zero_submodule()
        Submodule of Ambient free module of rank 2 over the integral domain Multivariate Polynomial Ring in x, y, z over Rational Field
        Generated by the rows of the matrix:
        []

    Python

        >>> from sage.all import *
        >>> S = PolynomialRing(QQ, names=('x', 'y', 'z',)); (x, y, z,) = S._first_ngens(3)
        >>> M = S**Integer(2)
        >>> M.zero_submodule()
        Submodule of Ambient free module of rank 2 over the integral domain Multivariate Polynomial Ring in x, y, z over Rational Field
        Generated by the rows of the matrix:
        []

  zero_vector()

    Return the zero vector in this module.

    EXAMPLES:

    Sage

        sage: M = FreeModule(ZZ, 2)
        sage: M.zero_vector()
        (0, 0)
        sage: M(0)
        (0, 0)
        sage: M.span([[1,1]]).zero_vector()
        (0, 0)
        sage: M.zero_submodule().zero_vector()
        (0, 0)

    Python

        >>> from sage.all import *
        >>> M = FreeModule(ZZ, Integer(2))
        >>> M.zero_vector()
        (0, 0)
        >>> M(Integer(0))
        (0, 0)
        >>> M.span([[Integer(1),Integer(1)]]).zero_vector()
        (0, 0)
        >>> M.zero_submodule().zero_vector()
        (0, 0)

class sage.modules.free_module.RealDoubleVectorSpace_class(n)

  Bases: `FreeModule_ambient_field`

  coordinates(v)

sage.modules.free_module.VectorSpace(K, dimension_or_basis_keys, sparse, inner_product_matrix, with_basis=None, dimension=False, basis_keys=None, **args)

  EXAMPLES:

  The base can be complicated, as long as it is a field.

  Sage

      sage: V = VectorSpace(FractionField(PolynomialRing(ZZ,'x')),3)
      sage: V
      Vector space of dimension 3 over Fraction Field of Univariate Polynomial Ring in x over Integer Ring
      sage: V.basis()
      [(1, 0, 0), (0, 1, 0), (0, 0, 1)]

  Python

      >>> from sage.all import *
      >>> V = VectorSpace(FractionField(PolynomialRing(ZZ,'x')),Integer(3))
      >>> V
      Vector space of dimension 3 over Fraction Field of Univariate Polynomial Ring in x over Integer Ring
      >>> V.basis()
      [(1, 0, 0), (0, 1, 0), (0, 0, 1)]

  The base must be a field or a `TypeError` is raised.

  Sage

      sage: VectorSpace(ZZ,5)
      Traceback (most recent call last):
      ...
      TypeError: Argument K (= Integer Ring) must be a field.

  [Python]

      >>> from sage.all import *
      >>> VectorSpace(ZZ,Integer(5))
      Traceback (most recent call last):
      ...
      TypeError: Argument K (= Integer Ring) must be a field.

sage.modules.free_module.basis_seq(V, vecs)

  This converts a list vecs of vectors in V to a Sequence of immutable vectors.

  Should it? I.e. in most `other` parts of the system the return type of basis or generators is a tuple.

  EXAMPLES:

  Sage

      sage: V = VectorSpace(QQ,2)
      sage: B = V.gens()
      sage: B
      ((1, 0), (0, 1))
      sage: v = B[0]
      sage: v[0] = 0 # immutable
      Traceback (most recent call last):
      ...
      ValueError: vector is immutable; please change a copy instead (use copy())
      sage: sage.modules.free_module.basis_seq(V, V.gens())
      [(1, 0), (0, 1)]

  Python

      >>> from sage.all import *
      >>> V = VectorSpace(QQ,Integer(2))
      >>> B = V.gens()
      >>> B
      ((1, 0), (0, 1))
      >>> v = B[Integer(0)]
      >>> v[Integer(0)] = Integer(0) # immutable
      Traceback (most recent call last):
      ...
      ValueError: vector is immutable; please change a copy instead (use copy())
      >>> sage.modules.free_module.basis_seq(V, V.gens())
      [(1, 0), (0, 1)]

sage.modules.free_module.element_class(R, is_sparse)

  The class of the vectors (elements of a free module) with base ring R and boolean is_sparse.

  EXAMPLES:

  Sage

      sage: FF = FiniteField(2)
      sage: P = PolynomialRing(FF,'x')
      sage: sage.modules.free_module.element_class(QQ, is_sparse=True)
      <class 'sage.modules.free_module_element.FreeModuleElement_generic_sparse'>
      sage: sage.modules.free_module.element_class(QQ, is_sparse=False)
      <class 'sage.modules.vector_rational_dense.Vector_rational_dense'>
      sage: sage.modules.free_module.element_class(ZZ, is_sparse=True)
      <class 'sage.modules.free_module_element.FreeModuleElement_generic_sparse'>
      sage: sage.modules.free_module.element_class(ZZ, is_sparse=False)
      <class 'sage.modules.vector_integer_dense.Vector_integer_dense'>
      sage: sage.modules.free_module.element_class(FF, is_sparse=True)
      <class 'sage.modules.free_module_element.FreeModuleElement_generic_sparse'>
      sage: sage.modules.free_module.element_class(FF, is_sparse=False)               # needs sage.rings.finite_rings
      <class 'sage.modules.vector_mod2_dense.Vector_mod2_dense'>
      sage: sage.modules.free_module.element_class(GF(7), is_sparse=False)
      <class 'sage.modules.vector_modn_dense.Vector_modn_dense'>
      sage: sage.modules.free_module.element_class(P, is_sparse=True)
      <class 'sage.modules.free_module_element.FreeModuleElement_generic_sparse'>
      sage: sage.modules.free_module.element_class(P, is_sparse=False)
      <class 'sage.modules.free_module_element.FreeModuleElement_generic_dense'>

  Python

      >>> from sage.all import *
      >>> FF = FiniteField(Integer(2))
      >>> P = PolynomialRing(FF,'x')
      >>> sage.modules.free_module.element_class(QQ, is_sparse=True)
      <class 'sage.modules.free_module_element.FreeModuleElement_generic_sparse'>
      >>> sage.modules.free_module.element_class(QQ, is_sparse=False)
      <class 'sage.modules.vector_rational_dense.Vector_rational_dense'>
      >>> sage.modules.free_module.element_class(ZZ, is_sparse=True)
      <class 'sage.modules.free_module_element.FreeModuleElement_generic_sparse'>
      >>> sage.modules.free_module.element_class(ZZ, is_sparse=False)
      <class 'sage.modules.vector_integer_dense.Vector_integer_dense'>
      >>> sage.modules.free_module.element_class(FF, is_sparse=True)
      <class 'sage.modules.free_module_element.FreeModuleElement_generic_sparse'>
      >>> sage.modules.free_module.element_class(FF, is_sparse=False)               # needs sage.rings.finite_rings
      <class 'sage.modules.vector_mod2_dense.Vector_mod2_dense'>
      >>> sage.modules.free_module.element_class(GF(Integer(7)), is_sparse=False)
      <class 'sage.modules.vector_modn_dense.Vector_modn_dense'>
      >>> sage.modules.free_module.element_class(P, is_sparse=True)
      <class 'sage.modules.free_module_element.FreeModuleElement_generic_sparse'>
      >>> sage.modules.free_module.element_class(P, is_sparse=False)
      <class 'sage.modules.free_module_element.FreeModuleElement_generic_dense'>

sage.modules.free_module.span(gens, base_ring=None, check=True, already_echelonized=False)

  Return the span of the vectors in `gens` using scalars from `base_ring`.

  INPUT:

  - `gens` – list of either vectors or lists of ring elements used to generate the span

  - `base_ring` – (default: `None`) a principal ideal domain for the ring of scalars

  - `check` – (default: `True`) passed to the `span()` method of the ambient module

  - `already_echelonized` – (default: `False`) set to `True` if the vectors form the rows of a matrix in echelon form, in order to skip the computation of an echelonized basis for the span.

  OUTPUT:

  A module (or vector space) that is all the linear combinations of the free module elements (or vectors) with scalars from the ring (or field) given by `base_ring`. See the examples below describing behavior when the base ring is not specified and/or the module elements are given as lists that do not carry explicit base ring information.

  EXAMPLES:

  The vectors in the list of generators can be given as lists, provided a base ring is specified and the elements of the list are in the ring (or the fraction field of the ring). If the base ring is a field, the span is a vector space.

  Sage

      sage: V = span([[1,2,5], [2,2,2]], QQ); V
      Vector space of degree 3 and dimension 2 over Rational Field
      Basis matrix:
      [ 1  0 -3]
      [ 0  1  4]

      sage: span([V.gen(0)], QuadraticField(-7,'a'))                                  # needs sage.rings.number_field
      Vector space of degree 3 and dimension 1 over Number Field in a
       with defining polynomial x^2 + 7 with a = 2.645751311064591?*I
      Basis matrix:
      [ 1  0 -3]

      sage: span([[1,2,3], [2,2,2], [1,2,5]], GF(2))
      Vector space of degree 3 and dimension 1 over Finite Field of size 2
      Basis matrix:
      [1 0 1]

  Python

      >>> from sage.all import *
      >>> V = span([[Integer(1),Integer(2),Integer(5)], [Integer(2),Integer(2),Integer(2)]], QQ); V
      Vector space of degree 3 and dimension 2 over Rational Field
      Basis matrix:
      [ 1  0 -3]
      [ 0  1  4]

      >>> span([V.gen(Integer(0))], QuadraticField(-Integer(7),'a'))                                  # needs sage.rings.number_field
      Vector space of degree 3 and dimension 1 over Number Field in a
       with defining polynomial x^2 + 7 with a = 2.645751311064591?*I
      Basis matrix:
      [ 1  0 -3]

      >>> span([[Integer(1),Integer(2),Integer(3)], [Integer(2),Integer(2),Integer(2)], [Integer(1),Integer(2),Integer(5)]], GF(Integer(2)))
      Vector space of degree 3 and dimension 1 over Finite Field of size 2
      Basis matrix:
      [1 0 1]

  If the base ring is not a field, then a module is created. The entries of the vectors can lie outside the ring, if they are in the fraction field of the ring.

  Sage

      sage: span([[1,2,5], [2,2,2]], ZZ)
      Free module of degree 3 and rank 2 over Integer Ring
      Echelon basis matrix:
      [ 1  0 -3]
      [ 0  2  8]

      sage: span([[1,1,1], [1,1/2,1]], ZZ)
      Free module of degree 3 and rank 2 over Integer Ring
      Echelon basis matrix:
      [  1   0   1]
      [  0 1/2   0]

      sage: R.<x> = QQ[]
      sage: M= span( [[x, x^2+1], [1/x, x^3]], R); M
      Free module of degree 2 and rank 2 over Univariate Polynomial Ring in x over Rational Field
      Echelon basis matrix:
      [          1/x           x^3]
      [            0 x^5 - x^2 - 1]
      sage: M.basis()[0][0].parent()
      Fraction Field of Univariate Polynomial Ring in x over Rational Field

  [Python]

      >>> from sage.all import *
      >>> span([[Integer(1),Integer(2),Integer(5)], [Integer(2),Integer(2),Integer(2)]], ZZ)
      Free module of degree 3 and rank 2 over Integer Ring
      Echelon basis matrix:
      [ 1  0 -3]
      [ 0  2  8]

      >>> span([[Integer(1),Integer(1),Integer(1)], [Integer(1),Integer(1)/Integer(2),Integer(1)]], ZZ)
      Free module of degree 3 and rank 2 over Integer Ring
      Echelon basis matrix:
      [  1   0   1]
      [  0 1/2   0]

      >>> R = QQ['x']; (x,) = R._first_ngens(1)
      >>> M= span( [[x, x**Integer(2)+Integer(1)], [Integer(1)/x, x**Integer(3)]], R); M
      Free module of degree 2 and rank 2 over Univariate Polynomial Ring in x over Rational Field
      Echelon basis matrix:
      [          1/x           x^3]
      [            0 x^5 - x^2 - 1]
      >>> M.basis()[Integer(0)][Integer(0)].parent()
      Fraction Field of Univariate Polynomial Ring in x over Rational Field

  A base ring can be inferred if the generators are given as a list of vectors.

  Sage

      sage: span([vector(QQ, [1,2,3]), vector(QQ, [4,5,6])])
      Vector space of degree 3 and dimension 2 over Rational Field
      Basis matrix:
      [ 1  0 -1]
      [ 0  1  2]
      sage: span([vector(QQ, [1,2,3]), vector(ZZ, [4,5,6])])
      Vector space of degree 3 and dimension 2 over Rational Field
      Basis matrix:
      [ 1  0 -1]
      [ 0  1  2]
      sage: span([vector(ZZ, [1,2,3]), vector(ZZ, [4,5,6])])
      Free module of degree 3 and rank 2 over Integer Ring
      Echelon basis matrix:
      [1 2 3]
      [0 3 6]

  Python

      >>> from sage.all import *
      >>> span([vector(QQ, [Integer(1),Integer(2),Integer(3)]), vector(QQ, [Integer(4),Integer(5),Integer(6)])])
      Vector space of degree 3 and dimension 2 over Rational Field
      Basis matrix:
      [ 1  0 -1]
      [ 0  1  2]
      >>> span([vector(QQ, [Integer(1),Integer(2),Integer(3)]), vector(ZZ, [Integer(4),Integer(5),Integer(6)])])
      Vector space of degree 3 and dimension 2 over Rational Field
      Basis matrix:
      [ 1  0 -1]
      [ 0  1  2]
      >>> span([vector(ZZ, [Integer(1),Integer(2),Integer(3)]), vector(ZZ, [Integer(4),Integer(5),Integer(6)])])
      Free module of degree 3 and rank 2 over Integer Ring
      Echelon basis matrix:
      [1 2 3]
      [0 3 6]