Help on FreeModule_ambient_field_with_category in module sage.modules.free_module object:
class FreeModule_ambient_field_with_category(FreeModule_ambient_field, sage.categories.category.JoinCategory.parent_class)
 Method resolution order:
 FreeModule_ambient_field_with_category
 FreeModule_ambient_field
 FreeModule_generic_field
 FreeModule_ambient_pid
 FreeModule_generic_pid
 FreeModule_ambient_domain
 FreeModule_ambient
 FreeModule_generic
 sage.modules.module.Module
 sage.structure.parent.Parent
 sage.structure.category_object.CategoryObject
 sage.structure.sage_object.SageObject
 sage.categories.category.JoinCategory.parent_class
 sage.categories.finite_dimensional_modules_with_basis.FiniteDimensionalModulesWithBasis.parent_class
 sage.categories.vector_spaces.VectorSpaces.WithBasis.parent_class
 sage.categories.modules_with_basis.ModulesWithBasis.parent_class
 sage.categories.modules.Modules.FiniteDimensional.parent_class
 sage.categories.vector_spaces.VectorSpaces.parent_class
 sage.categories.modules.Modules.parent_class
 sage.categories.bimodules.Bimodules.parent_class
 sage.categories.right_modules.RightModules.parent_class
 sage.categories.left_modules.LeftModules.parent_class
 sage.categories.commutative_additive_groups.CommutativeAdditiveGroups.parent_class
 sage.categories.additive_groups.AdditiveGroups.parent_class
 sage.categories.additive_magmas.AdditiveMagmas.AdditiveUnital.AdditiveInverse.parent_class
 sage.categories.commutative_additive_monoids.CommutativeAdditiveMonoids.parent_class
 sage.categories.additive_monoids.AdditiveMonoids.parent_class
 sage.categories.additive_magmas.AdditiveMagmas.AdditiveUnital.parent_class
 sage.categories.commutative_additive_semigroups.CommutativeAdditiveSemigroups.parent_class
 sage.categories.additive_magmas.AdditiveMagmas.AdditiveCommutative.parent_class
 sage.categories.additive_semigroups.AdditiveSemigroups.parent_class
 sage.categories.additive_magmas.AdditiveMagmas.parent_class
 sage.categories.sets_cat.Sets.parent_class
 sage.categories.sets_with_partial_maps.SetsWithPartialMaps.parent_class
 sage.categories.objects.Objects.parent_class
 __builtin__.object

 Methods inherited from FreeModule_ambient_field:

 __init__(self, base_field, dimension, sparse=False)
 Create the ambient vector space of given dimension over the given
 field.

 INPUT:


  ``base_field``  a field

  ``dimension``  a nonnegative integer

  ``sparse``  bool (default: False)


 EXAMPLES::

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

 ambient_vector_space(self)
 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(self)
 Returns the base field of this vector space.

 EXAMPLES::

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

 
 Methods inherited from FreeModule_generic_field:

 __add__(self, other)
 Return the sum of self and other.

 EXAMPLES::

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

 __truediv__(self, sub)
 Return the quotient of self by the given subspace sub.

 EXAMPLES::

 sage: V = RDF^3; W = V.span([[1,0,1], [1,1,0]])
 sage: Q = V/W; Q
 Vector space quotient V/W of dimension 1 over Real Double Field where
 V: Vector space of dimension 3 over Real Double Field
 W: Vector space of degree 3 and dimension 2 over Real Double Field
 Basis matrix:
 [ 1.0 0.0 1.0]
 [ 0.0 1.0 1.0]
 sage: type(Q)
 <class 'sage.modules.quotient_module.FreeModule_ambient_field_quotient_with_category'>
 sage: V([1,2,3])
 (1.0, 2.0, 3.0)
 sage: Q == V.quotient(W)
 True
 sage: Q(W.0)
 (0.0)

 complement(self)
 Return the complement of ``self`` in the
 :meth:`~sage.modules.free_module.FreeModule_ambient_field.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(self)
 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(self, other)
 Return the intersection of self and other, which must be
 Rsubmodules 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(self, 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(self, 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 nonzero entries and a qualitative
 disposition to having zeros in the lowindex entries. With ``zeros`` set
 to ``'right'`` the situation is reversed with a qualitative disposition
 for zeros in the highindex 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
 nontrivial 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(self, 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(self, 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(self, 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(self, gens, base_ring=None, check=True, already_echelonized=False)
 Return the Kspan of the given list of gens, where K is the
 base field of self or the userspecified 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, log(2))); v
 (1.0, 3.141592653589793, 0.6931471805599453)
 sage: W.span([v], base_ring=GF(7))
 Traceback (most recent call last):
 ...
 ValueError: Argument gens (= [(1.0, 3.141592653589793, 0.6931471805599453)]) 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(self, basis, base_ring=None, check=True, already_echelonized=False)
 Return the free Kmodule 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 a
 ``ValueError`` 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(self, 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 1dimensional 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(self, gens, check=True, already_echelonized=False)
 Same as ``self.submodule_with_basis(...)``.

 EXAMPLES:

 We create a subspace with a userdefined 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 userdefined 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(self, 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(self, 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(self)
 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(self)
 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:
 []

 
 Methods inherited from FreeModule_generic_pid:

 __radd__(self, other)
 EXAMPLES::

 sage: int(0) + QQ^3
 Vector space of dimension 3 over Rational Field
 sage: sum([QQ^3, QQ^3])
 Vector space of degree 3 and dimension 3 over Rational Field
 Basis matrix:
 [1 0 0]
 [0 1 0]
 [0 0 1]

 denominator(self)
 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(self, 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(self)
 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

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

 EXAMPLES:

 We create a 1dimensional 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 nonintegral 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]

 submodule(self, gens, check=True, already_echelonized=False)
 Create the Rsubmodule 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(self, basis, check=True, already_echelonized=False)
 Create the Rsubmodule 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 Rspan of vectors in the
 ambient space, or override 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(self, 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(self, 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 userspecified 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]

 
 Methods inherited from FreeModule_ambient_domain:

 coordinate_vector(self, 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.

 [...]