### Navigation

- index
- modules |
- next |
- previous |
- Modules »

# 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: 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]

    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]

We illustrate the exponent notation for creation of free modules.

    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

Base ring:

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

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

TESTS: We intersect a zero-dimensional vector space with a 1-dimension submodule.

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

We construct subspaces of real and complex double vector spaces and verify that the element types are correct:

    sage: V = FreeModule(RDF, 3); V
    Vector space of dimension 3 over Real Double Field
    sage: V.0
    (1.0, 0.0, 0.0)
    sage: type(V.0)
    <type 'sage.modules.vector_real_double_dense.Vector_real_double_dense'>
    sage: W = V.span([V.0]); W
    Vector space of degree 3 and dimension 1 over Real Double Field
    Basis matrix:
    [1.0 0.0 0.0]
    sage: type(W.0)
    <type 'sage.modules.vector_real_double_dense.Vector_real_double_dense'>
    sage: V = FreeModule(CDF, 3); V
    Vector space of dimension 3 over Complex Double Field
    sage: type(V.0)
    <type 'sage.modules.vector_complex_double_dense.Vector_complex_double_dense'>
    sage: W = V.span_of_basis([CDF.0 * V.1]); W
    Vector space of degree 3 and dimension 1 over Complex Double Field
    User basis matrix:
    [  0.0 1.0*I   0.0]
    sage: type(W.0)
    <type 'sage.modules.vector_complex_double_dense.Vector_complex_double_dense'>

Basis vectors are immutable:

    sage: A = span([[1,2,3], [4,5,6]], ZZ)
    sage: A.0
    (1, 2, 3)
    sage: A.0[0] = 5
    Traceback (most recent call last):
    ...
    ValueError: vector is immutable; please change a copy instead (use copy())

Among other things, this tests that we can save and load submodules and elements:

    sage: M = ZZ^3
    sage: TestSuite(M).run()
    sage: W = M.span_of_basis([[1,2,3],[4,5,19]])
    sage: TestSuite(W).run()
    sage: v = W.0 + W.1
    sage: TestSuite(v).run()

AUTHORS:

- William Stein (2005, 2007)
- David Kohel (2007, 2008)
- Niles Johnson (2010-08): Trac #3893: `random_element()` should pass on `*args` and `**kwds`.
- Simon King (2010-12): Trac #8800: Fixing a bug in `denominator()`.

class `sage.modules.free_module.``ComplexDoubleVectorSpace_class`(n)

  Bases: `sage.modules.free_module.FreeModule_ambient_field`

  `coordinates`(v)

    x.__init__(...) initializes x; see help(type(x)) for signature

class `sage.modules.free_module.``FreeModuleFactory`

  Bases: `sage.structure.factory.UniqueFactory`

  Create the free module over the given commutative ring of the given rank.

  INPUT:

  - `base_ring` - a commutative ring
  - `rank` - a nonnegative integer
  - `sparse` - bool; (default False)
  - `inner_product_matrix` - the inner product matrix (default None)

  OUTPUT: a free module

  Note

  In Sage it is the case that there is only one dense and one sparse free ambient module of rank \(n\) over \(R\).

  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: FreeModule(Integers(8),10)
      Ambient free module of rank 10 over Ring of integers modulo 8
      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

  Of course we can make rank 0 free modules:

      sage: FreeModule(RealField(100),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: M = FreeModule(ZZ,200,sparse=True)
      sage: M.is_sparse()
      True
      sage: type(M.0)
      <type 'sage.modules.free_module_element.FreeModuleElement_generic_sparse'>

  The default is dense.

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

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

      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

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

      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

  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: 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]

  Todo

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

  `create_key`(base_ring, rank, sparse=False, inner_product_matrix=None)

    TESTS:

        sage: loads(dumps(ZZ^6)) is ZZ^6
        True
        sage: loads(dumps(RDF^3)) is RDF^3
        True

    TODO: replace the above by `TestSuite(...).run()`, once `_test_pickling()` will test unique representation and not only equality.

  `create_object`(version, key)

    x.__init__(...) initializes x; see help(type(x)) for signature

class `sage.modules.free_module.``FreeModule_ambient`(base_ring, rank, sparse=False)

  Bases: `sage.modules.free_module.FreeModule_generic`

  Ambient free module over a commutative ring.

  `ambient_module`()

    Return self, since self is ambient.

    EXAMPLES:

        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

  `basis`()

    Return a basis for this ambient free module.

    OUTPUT:

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

    EXAMPLES:

        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

  `change_ring`(R)

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

    EXAMPLES:

        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

    For ambient modules any change of rings is defined.

        sage: A = GF(5)**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, raises an ArithmeticError exception.

    EXAMPLES:

        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

  `echelon_coordinate_vector`(v, check=True)

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

    INPUT:

    - `v` - vector
    - `check` - bool (default: True); if True, also verify that v is really in self.

    OUTPUT: list

    EXAMPLES:

        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)

  `echelon_coordinates`(v, check=True)

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

    EXAMPLES:

        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]]

  `echelonized_basis`()

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

    EXAMPLES:

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

  `echelonized_basis_matrix`()

    The echelonized basis matrix of self.

    EXAMPLES:

        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]

  `is_ambient`()

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

    EXAMPLES:

        sage: A = QQ^5; A.is_ambient()
        True
        sage: A = (QQ^5).span([[1,2,3,4,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.

    INPUTS:

    - `v` - list

    EXAMPLES:

        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)

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

        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

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

    Returns 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: M = FreeModule(ZZ, 3)
        sage: M.random_element()
        (-1, 2, 1)
        sage: M.random_element()
        (-95, -1, -2)
        sage: M.random_element()
        (-12, 0, 0)

    Passes extra positional or keyword arguments through:

        sage: M.random_element(5,10)
        (5, 5, 5)

        sage: M = FreeModule(ZZ, 16)
        sage: M.random_element()
        (-6, 5, 0, 0, -2, 0, 1, -4, -6, 1, -1, 1, 1, -1, 1, -1)
        sage: M.random_element(prob=0.3)
        (0, 0, 0, 0, -3, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, -3)

class `sage.modules.free_module.``FreeModule_ambient_domain`(base_ring, rank, sparse=False)

  Bases: `sage.modules.free_module.FreeModule_ambient`

  Ambient free module over an integral domain.

  `ambient_vector_space`()

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

    EXAMPLES:

        sage: M = ZZ^3;
        sage: 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: 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

  `base_field`()

    Return the fraction field of the base ring of self.

    EXAMPLES:

        sage: M = ZZ^3;  M.base_field()
        Rational Field
        sage: M = PolynomialRing(GF(5),'x')^3;  M.base_field()
        Fraction Field of Univariate Polynomial Ring in x over Finite Field of size 5

  `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` - bool (default: True); if True, also verify that v is really in self.

    OUTPUT: list

    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, raises an ArithmeticError exception.

    EXAMPLES:

        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

  `vector_space`(base_field=None)

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

    EXAMPLES:

        sage: M = ZZ^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)

  Bases: `sage.modules.free_module.FreeModule_generic_field`, `sage.modules.free_module.FreeModule_ambient_pid`

  `ambient_vector_space`()

    Returns self as the ambient vector space.

    EXAMPLES:

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

  `base_field`()

    Returns the base field of this vector space.

    EXAMPLES:

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

class `sage.modules.free_module.``FreeModule_ambient_pid`(base_ring, rank, sparse=False)

  Bases: `sage.modules.free_module.FreeModule_generic_pid`, `sage.modules.free_module.FreeModule_ambient_domain`

  Ambient free module over a principal ideal domain.

class `sage.modules.free_module.``FreeModule_generic`(base_ring, rank, degree, sparse=False)

  Bases: `sage.modules.module.Module_old`

  Base class for all free modules.

  `ambient_module`()

    Return the ambient module associated to this module.

    EXAMPLES:

        sage: R.<x,y> = QQ[]
        sage: M = FreeModule(R,2)
        sage: M.ambient_module()
        Ambient free module of rank 2 over the integral domain Multivariate Polynomial Ring in x, y over Rational Field

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

  `are_linearly_dependent`(vecs)

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

    EXAMPLES:

        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

  `base_extend`(R)

    Return the base extension of self to R. This is the same as `self.change_ring(R)` except that a TypeError is raised if there is no canonical coerce map from the base ring of self to R.

    INPUT:

    - `R` - ring

    EXAMPLES:

        sage: V = ZZ^7
        sage: V.base_extend(QQ)
        Vector space of dimension 7 over Rational Field

  `basis`()

    Return the basis of this module.

    EXAMPLES:

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

  `basis_matrix`()

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

    EXAMPLES:

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

        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]

        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]

  `cardinality`()

    Return the cardinality of the free module.

    OUTPUT:

    Either an integer or `+Infinity`.

    EXAMPLES:

        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

  `construction`()

    The construction functor and base ring for self.

    EXAMPLES:

        sage: R = PolynomialRing(QQ,3,'x')
        sage: V = R^5
        sage: 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: 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)

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

        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]

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

        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]

  `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` - bool (default: True); if True, also verify that v is really in self.

    OUTPUT: list

    EXAMPLES:

        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)

  `coordinates`(v, check=True)

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

    INPUT:

    - `v` - vector
    - `check` - bool (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, raises an `ArithmeticError` exception.

    EXAMPLES:

        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]

  `degree`()

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

    EXAMPLES:

        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

  `dense_module`()

    Return corresponding dense module.

    EXAMPLES:

    We first illustrate conversion with ambient spaces:

        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

    Next we create a subspace:

        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]

  `dimension`()

    Return the dimension of this free module.

    EXAMPLES:

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

  `direct_sum`(other)

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

    EXAMPLES:

        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]

  `discriminant`()

    Return the discriminant of this free module.

    EXAMPLES:

        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

  `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: 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]

    TESTS:

        sage: from sage.modules.free_module import FreeModule_generic
        sage: FreeModule_generic.echelonized_basis_matrix(M)
        Traceback (most recent call last):
        ...
        NotImplementedError

  `element_class`()

    The class of elements for this free module.

    EXAMPLES:

        sage: M = FreeModule(ZZ,20,sparse=False)
        sage: x = M.random_element()
        sage: type(x)
        <type 'sage.modules.vector_integer_dense.Vector_integer_dense'>
        sage: M.element_class()
        <type 'sage.modules.vector_integer_dense.Vector_integer_dense'>
        sage: N = FreeModule(ZZ,20,sparse=True)
        sage: y = N.random_element()
        sage: type(y)
        <type 'sage.modules.free_module_element.FreeModuleElement_generic_sparse'>
        sage: N.element_class()
        <type 'sage.modules.free_module_element.FreeModuleElement_generic_sparse'>

  `free_module`()

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

    EXAMPLES:

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

  `gen`(i=0)

    Return ith generator for self, where i is between 0 and rank-1, inclusive.

    INPUT:

    - `i` - an integer

    OUTPUT: i-th basis vector for self.

    EXAMPLES:

        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

    TESTS:

        sage: (QQ^3).gen(4/3)
        Traceback (most recent call last):
        ...
        TypeError: rational is not an integer

  `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: 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]

  `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: 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

  `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: M = FreeModule(ZZ, 3)
        sage: M.inner_product_matrix()
        [1 0 0]
        [0 1 0]
        [0 0 1]

  `is_ambient`()

    Returns False since this is not an ambient free module.

    EXAMPLES:

        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

  `is_dense`()

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

    EXAMPLES:

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

  `is_finite`()

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

    EXAMPLES:

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

  `is_full`()

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

    EXAMPLES:

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

  `is_sparse`()

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

    EXAMPLES:

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

  `is_submodule`(other)

    Return True if self is a submodule of other.

    EXAMPLES:

        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

    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: 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)

  `matrix`()

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

    EXAMPLES:

        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]

  `ngens`()

    Returns the number of basis elements of this free module.

    EXAMPLES:

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

  `nonembedded_free_module`()

    Returns 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: FreeModule(ZZ, 2).span([[1,1]]).nonembedded_free_module()
        Ambient free module of rank 1 over the principal ideal domain Integer Ring

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

    Returns 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: M = FreeModule(ZZ, 2).span([[1,1]])
        sage: M.random_element()
        (-1, -1)
        sage: M.random_element()
        (2, 2)
        sage: M.random_element()
        (1, 1)

    Passes extra positional or keyword arguments through:

        sage: M.random_element(5,10)
        (9, 9)

  `rank`()

    Return the rank of this free module.

    EXAMPLES:

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

  `sparse_module`()

    Return the corresponding sparse module with the same defining data.

    EXAMPLES:

    We first illustrate conversion with ambient spaces:

        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

    Next we convert a subspace:

        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]

  `uses_ambient_inner_product`()

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

    EXAMPLES:

        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]

        sage: W.gram_matrix()
        [5]

  `zero`()

    Returns the zero vector in this free module.

    EXAMPLES:

        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

  `zero_vector`()

    Returns the zero vector in this free module.

    EXAMPLES:

        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)

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

  Bases: `sage.modules.free_module.FreeModule_generic_pid`

  Base class for all free modules over fields.

  `complement`()

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

    EXAMPLES:

        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

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

        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]

    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: F2 = GF(2,x)
        sage: V = F2^6
        sage: W = V.span([[1,1,0,0,0,0]])
        sage: 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]

  `echelonized_basis_matrix`()

    Return basis matrix for self in row echelon form.

    EXAMPLES:

        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]

  `intersection`(other)

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

    EXAMPLES:

        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:
        []

  `is_subspace`(other)

    True if this vector space is a subspace of other.

    EXAMPLES:

        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

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

    Returns 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` - A 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 1’s in their first non-zero 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: 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])
        [
        <BLANKLINE>
        ]

        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

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

        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
        [
        <BLANKLINE>
        ]
        sage: 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: 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)
        ]

    TESTS:

    With `check=True` (the default) a mismatch between vectors and the vector space is caught.

        sage: v1 = vector(RR, [1,2,3])
        sage: v2 = vector(RR, [1,2,3,4])
        sage: (RR^3).linear_dependence([v1,v2], check=True)
        Traceback (most recent call last):
        ...
        ValueError: vector (1.00000000000000, 2.00000000000000, 3.00000000000000, 4.00000000000000) is not an element of Vector space of dimension 3 over Real Field with 53 bits of precision

    The `zeros` keyword is checked.

        sage: (QQ^3).linear_dependence([vector(QQ,[1,2,3])], zeros='bogus')
        Traceback (most recent call last):
        ...
        ValueError: 'zeros' keyword must be 'left' or 'right', not 'bogus'

    An empty input set is linearly independent, vacuously.

        sage: (QQ^3).linear_dependence([]) == []
        True

  `quotient`(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` - (default: True) whether or not to check that sub is a submodule.

    EXAMPLES:

        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)

    We illustrate the the base rings must be the same:

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

  `quotient_abstract`(sub, check=True)

    Returns 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` - (default: True) whether or not to check that sub is a submodule.

    OUTPUT:

    - `U` - the quotient as an abstract ambient free module
    - `pi` - projection map to the quotient
    - `lift` - lifting map back from quotient

    EXAMPLES:

        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)

    Another example involving a quotient of one subspace by another.

        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]

  `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: 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:
        []

        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:
        []

        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:
        []

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

    Return the K-span of the given list of gens, where K is the base field of self or the 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:

    - `gens` - list of vectors
    - `check` - bool (default: True): whether or not to coerce entries of gens into base field
    - `already_echelonized` - bool (default: False): set this if you know the gens are already in echelon form

    EXAMPLES:

        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]

    TESTS:

        sage: V = FreeModule(RDF,3)
        sage: W = V.submodule([V.gen(0)])
        sage: W.span([V.gen(1)], base_ring=GF(7))
        Vector space of degree 3 and dimension 1 over Finite Field of size 7
        Basis matrix:
        [0 1 0]
        sage: v = V((1, pi, e)); v
        (1.0, 3.141592653589793, 2.718281828459045)
        sage: W.span([v], base_ring=GF(7))
        Traceback (most recent call last):
        ...
        ValueError: Argument gens (= [(1.0, 3.141592653589793, 2.718281828459045)]) is not compatible with base_ring (= Finite Field of size 7).
        sage: W = V.submodule([v])
        sage: W.span([V.gen(2)], base_ring=GF(7))
        Vector space of degree 3 and dimension 1 over Finite Field of size 7
        Basis matrix:
        [0 0 1]

  `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` - bool (default: True): whether or not to coerce entries of gens into base field
    - `already_echelonized` - bool (default: False): set this if you know the gens are already in echelon form

    EXAMPLES:

        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]

    The basis vectors must be linearly independent or an ArithmeticError exception is raised.

        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.

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

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

    INPUT:

    - `gens` - list of vectors
    - `check` - bool (default: True) verify that gens are all in self.
    - `already_echelonized` - bool (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: 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]

    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: 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]

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

        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.

  `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: 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]

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

        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]

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

        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]

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

        sage: W1 == W2
        True

  `subspaces`(dim)

    Iterate over all subspaces of dimension dim.

    INPUT:

    - `dim` - int, dimension of subspaces to be generated

    EXAMPLE:

        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

        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]]

  `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: 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]

  `zero_submodule`()

    Return the zero submodule of self.

    EXAMPLES:

        sage: (QQ^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: (QQ^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)

  Bases: `sage.modules.free_module.FreeModule_generic`

  Base class for all free modules over a PID.

  `base_field`()

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

    EXAMPLES:

        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

  `basis_matrix`()

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

    EXAMPLES:

        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]

    See trac ticket #3699:

        sage: K = FreeModule(ZZ, 2000)
        sage: I = K.basis_matrix()

  `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: 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

  `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: L1 = span([[1,2]], ZZ)
        sage: L2 = span([[3,6]], ZZ)
        sage: L2.index_in(L1)
        3

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

        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

    The index of a lattice of infinite index is infinite.

        sage: L1 = FreeModule(ZZ, 2)
        sage: L2 = span([[1,2]], ZZ)
        sage: 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: 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

  `intersection`(other)

    Return the intersection of self and other.

    EXAMPLES:

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

        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

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

        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]

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

        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]

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

        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]

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

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

  `is_submodule`(other)

    True if this module is a submodule of other.

    EXAMPLES:

        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

  `quotient`(sub, check=True)

    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` - (default: True) whether or not to check that sub is a submodule.

    EXAMPLES:

        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)

  `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: 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]

    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: 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

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

        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]

  `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: 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]

        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]

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

    Return the R-span of the given list of gens, where R = 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.

    EXAMPLES:

        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]

    It also works with other things than integers:

        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]

    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: 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]

  `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: M = FreeModule(ZZ,3)
        sage: W = M.span_of_basis([M([1,2,3])])

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

        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]

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

        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]

    Of course the input basis vectors must be linearly independent.

        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.

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

    Create the R-submodule of the ambient vector space with given generators, where R is the base ring of self.

    INPUT:

    - `gens` - a list of free module elements or a free module
    - `check` - (default: True) whether or not to verify that the gens are in self.

    OUTPUT:

    - `FreeModule` - the submodule spanned by the vectors in the list gens. The basis for the subspace is always put in reduced row echelon form.

    EXAMPLES:

    We create a submodule of \(\ZZ^3\):

        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]

    We create a submodule of a submodule.

        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]

    We try to create a submodule that isn’t really a submodule, which results in an ArithmeticError exception:

        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.

    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: 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

  `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` - a 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: 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]

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

        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.

    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: 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

    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: 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]

  `vector_space_span`(gens, check=True)

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

    INPUT:

    - `gens` - a 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: 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]

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

        sage: R.<x> = QQ[]
        sage: K = NumberField(x^2 + 1, 'a'); a = K.gen()
        sage: V = VectorSpace(K, 3)
        sage: V.vector_space_span([2*V.gen(0) + 3*V.gen(2)])
        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: 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]

  `vector_space_span_of_basis`(basis, check=True)

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

    INPUT:

    - `basis` - a 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: 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]

  `zero_submodule`()

    Return the zero submodule of this module.

    EXAMPLES:

        sage: V = FreeModule(ZZ,2)
        sage: 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)

  Bases: `sage.modules.free_module.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: 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]

      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)

  `coordinate_vector`(v, check=True)

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

    INPUT:

    - `v` - vector
    - `check` - bool (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, raises an `ArithmeticError` exception.

    EXAMPLES:

        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)

        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)

  `echelon_coordinates`(v, check=True)

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

    INPUT:

    - `v` - vector
    - `check` - bool (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, raises an `ArithmeticError` exception.

    EXAMPLES:

        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]

        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)

  `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: 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

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

  Bases: `sage.modules.free_module.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: 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]

  Generic tests, including saving and loading submodules and elements:

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

  `coordinate_vector`(v, check=True)

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

    INPUT:

    - `v` - vector
    - `check` - bool (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, raises an `ArithmeticError` exception.

    EXAMPLES:

        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)

  `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: 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

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

  Bases: `sage.modules.free_module.FreeModule_generic_field`, `sage.modules.free_module.FreeModule_submodule_with_basis_pid`

  An embedded vector subspace with a distinguished user basis.

  EXAMPLES:

      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]

  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: V = QQ^3

      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]

      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)

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

  Generic tests, including saving and loading submodules and elements:

      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()

  `is_ambient`()

    Return False since this is not an ambient module.

    EXAMPLES:

        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

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

  Bases: `sage.modules.free_module.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` – (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` – (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: 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]

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

      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]

  `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: 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

  `ambient_vector_space`()

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

    EXAMPLES:

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

        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

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

        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

  `basis`()

    Return the user basis for this free module.

    EXAMPLES:

        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)
        ]

  `change_ring`(R)

    Return the free module over R obtained by coercing each element of self into a vector over the fraction field of R, then taking the resulting R-module. Raises a TypeError if coercion is not possible.

    INPUT:

    - `R` - a principal ideal domain

    EXAMPLES:

        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]

  `construction`()

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

    EXAMPLE:

        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

  `coordinate_vector`(v, check=True)

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

    INPUT:

    - `v` - vector
    - `check` - bool (default: True); if True, also verify that v is really in self.

    OUTPUT: list

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

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

    EXAMPLES:

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

  `echelon_coordinate_vector`(v, check=True)

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

    INPUT:

    - `v` - vector
    - `check` - bool (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, raises an `ArithmeticError` exception.

    EXAMPLES:

        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)

  `echelon_coordinates`(v, check=True)

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

    INPUT:

    - `v` - vector
    - `check` - bool (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, raises an `ArithmeticError` exception.

    EXAMPLES:

        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)

    We do an example with a sparse vector space:

        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]

  `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: 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]

    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: 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)

  `echelonized_basis`()

    Return the basis for self in echelon form.

    EXAMPLES:

        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

  `echelonized_basis_matrix`()

    Return basis matrix for self in row echelon form.

    EXAMPLES:

        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]

  `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: 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

  `linear_combination_of_basis`(v)

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

    INPUTS:

    - `v` - list

    EXAMPLES:

        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)

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

        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

  `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: 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]

    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: 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)

  `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: 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]

class `sage.modules.free_module.``RealDoubleVectorSpace_class`(n)

  Bases: `sage.modules.free_module.FreeModule_ambient_field`

  `coordinates`(v)

    x.__init__(...) initializes x; see help(type(x)) for signature

`sage.modules.free_module.``VectorSpace`(K, dimension, sparse=False, inner_product_matrix=None)

  EXAMPLES:

  The base can be complicated, as long as it is a field.

      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)
      ]

  The base must be a field or a `TypeError` is raised.

      sage: VectorSpace(ZZ,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 an 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: 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)
      ]

`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: FF = FiniteField(2)
      sage: P = PolynomialRing(FF,'x')
      sage: sage.modules.free_module.element_class(QQ, is_sparse=True)
      <type 'sage.modules.free_module_element.FreeModuleElement_generic_sparse'>
      sage: sage.modules.free_module.element_class(QQ, is_sparse=False)
      <type 'sage.modules.vector_rational_dense.Vector_rational_dense'>
      sage: sage.modules.free_module.element_class(ZZ, is_sparse=True)
      <type 'sage.modules.free_module_element.FreeModuleElement_generic_sparse'>
      sage: sage.modules.free_module.element_class(ZZ, is_sparse=False)
      <type 'sage.modules.vector_integer_dense.Vector_integer_dense'>
      sage: sage.modules.free_module.element_class(FF, is_sparse=True)
      <type 'sage.modules.free_module_element.FreeModuleElement_generic_sparse'>
      sage: sage.modules.free_module.element_class(FF, is_sparse=False)
      <type 'sage.modules.vector_mod2_dense.Vector_mod2_dense'>
      sage: sage.modules.free_module.element_class(GF(7), is_sparse=False)
      <type 'sage.modules.vector_modn_dense.Vector_modn_dense'>
      sage: sage.modules.free_module.element_class(P, is_sparse=True)
      <type 'sage.modules.free_module_element.FreeModuleElement_generic_sparse'>
      sage: sage.modules.free_module.element_class(P, is_sparse=False)
      <type 'sage.modules.free_module_element.FreeModuleElement_generic_dense'>

`sage.modules.free_module.``is_FreeModule`(M)

  Return True if M inherits from from FreeModule_generic.

  EXAMPLES:

      sage: from sage.modules.free_module import is_FreeModule
      sage: V = ZZ^3
      sage: is_FreeModule(V)
      True
      sage: W = V.span([ V.random_element() for i in range(2) ])
      sage: is_FreeModule(W)
      True

`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` - a 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: 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'))
      Vector space of degree 3 and dimension 1 over Number Field in a with defining polynomial x^2 + 7
      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]

  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: 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

  A base ring can be inferred if the generators are given as a list of vectors.

      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]

  TESTS:

      sage: span([[1,2,3], [2,2,2], [1,2/3,5]], ZZ)
      Free module of degree 3 and rank 3 over Integer Ring
      Echelon basis matrix:
      [  1   0  13]
      [  0 2/3   6]
      [  0   0  14]
      sage: span([[1,2,3], [2,2,2], [1,2,QQ['x'].gen()]], ZZ)
      Traceback (most recent call last):
      ...
      ValueError: The elements of gens (= [[1, 2, 3], [2, 2, 2], [1, 2, x]]) must be defined over base_ring (= Integer Ring) or its field of fractions.

  For backwards compatibility one can also give the base ring as the first argument.

      sage: span(QQ,[[1,2],[3,4]])
      Vector space of degree 2 and dimension 2 over Rational Field
      Basis matrix:
      [1 0]
      [0 1]

  The base ring must be a principal ideal domain (PID).

      sage: span([[1,2,3]], Integers(6))
      Traceback (most recent call last):
      ...
      TypeError: The base_ring (= Ring of integers modulo 6)
      must be a principal ideal domain.

  Fix trac ticket #5575:

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

  Improve error message from trac ticket #12541:

      sage: span({0:vector([0,1])}, QQ)
      Traceback (most recent call last):
      ...
      TypeError: generators must be lists of ring elements
      or free module elements!

### Navigation

- index
- modules |
- next |
- previous |
- Modules »