Class FreeModule_submodule_with_basis_pid

Create a free module with basis over a PID.

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]

Overrides: FreeModule_generic_pid.__init__

hash(x)

Overrides: FreeModule_generic.__hash__

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

Overrides: FreeModule_generic.construction

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]

Overrides: FreeModule_generic.echelonized_basis_matrix

Compare self and other.

Modules are ordered by their ambient spaces, then by
dimension, then in order by their echelon matrices.

NOTE: Use the \code{is_submodule} to determine if one module
is a submodule of another.

EXAMPLES:
First we compare two equal vector spaces.
    sage: V = span(QQ, [[1,2,3], [5,6,7], [8,9,10]])
    sage: W = span(QQ, [[5,6,7], [8,9,10]])
    sage: V == W
    True
    
Next we compare a one dimensional space to the two dimensional space
defined above. 
    sage: M = span(QQ, [[5,6,7]])
    sage: V == M
    False
    sage: M < V
    True
    sage: V < M
    False

We compare a $\Z$-module to the one-dimensional space above.
    sage: V = span(ZZ, [[5,6,7]]).scale(1/11);  V
    Free module of degree 3 and rank 1 over Integer Ring
    Echelon basis matrix:
    [5/11 6/11 7/11]
    sage: V < M
    True
    sage: M < V
    False

Overrides: FreeModule_generic.__cmp__

Return latex representation of this free module.

EXAMPLES:
    sage: A = ZZ^3
    sage: M = A.span_of_basis([[1,2,3],[4,5,6]])
    sage: M._latex_()
    '\\mbox{\\rm RowSpan}_{\\mathbf{Z}}\\left(\\begin{array}{rrr}\n1 & 2 & 3 \\\\\n4 & 5 & 6\n\\end{array}\\right)'

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

Overrides: FreeModule_generic.ambient_module

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 \code{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]

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)

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)

Return the vector spaces 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]

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

EXAMPLES:
    sage: V = ZZ^3
    sage: M = V.span_of_basis([[1,2,'1/5']])
    sage: M
    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

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

Overrides: FreeModule_generic.basis

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]

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 
        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/8',2,1]])
    sage: M.coordinate_vector([1,16,8])
    (8)

Overrides: FreeModule_generic.coordinate_vector

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

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.

Returns a vector 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)

Return \code{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

Overrides: FreeModule_generic.has_user_basis

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

EXAMPLES:
    sage: V = span(ZZ, [[1,2,3], [4,5,6]]); 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)