19.1 Free modules

Module: sage.modules.free_module

SAGE supports computation with free modules over an arbitrary commutative ring. Nontrivial functionality is available over $ \mathbf{Z}$ and 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, Rn also creates that free module.

The following example illustrates the creation of both a vector spaces 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.

sage: V = VectorSpace(RationalField(),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: Z = Integers(); Q = Rationals(); R = Reals()
sage: Z^4
Ambient free module of rank 4 over the principal ideal domain Integer Ring
sage: Q^2
Vector space of dimension 2 over Rational Field
sage: R^3
Vector space of dimension 3 over Real Field with 53 bits of precision

Module-level Functions

FreeModule( base_ring, rank, [sparse=None], [inner_product_matrix=False])

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 not the case that there is only one free ambient module of rank $ n$ over $ R$ . If you create $ R^n$ twice SAGE creates two separate objects. This is because one can change the inner product on an ambient free module at any time.

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(RationalField(),10)
Vector space of dimension 10 over Rational Field
sage: FreeModule(IntegerRing(),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(RationalField()),5)
Ambient free module of rank 5 over the principal ideal domain Univariate
Polynomial Ring in x over Rational Field
sage: FreeModule(PolynomialRing(IntegerRing()),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(IntegerRing(),200,sparse=True)
sage: M.is_sparse()
True
sage: type(M.gen(0))
<class 'sage.modules.free_module_element.FreeModuleElement_generic_sparse'>

The default is dense.

sage: M = ZZ^200
sage: type(M.gen(0))
<class 'sage.modules.free_module_element.FreeModuleElement_generic_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: Z = IntegerRing()
sage: A = MatrixSpace(Z,2)([[1,0],[0,-1]])
sage: M = FreeModule(IntegerRing(),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(IntegerRing(),2,inner_product_matrix=1).inner_product_matrix()
[1 0]
[0 1]
sage: FreeModule(IntegerRing(),2,inner_product_matrix=[1,2,3,4]).inner_product_matrix()
[1 2]
[3 4]
sage: FreeModule(IntegerRing(),2,inner_product_matrix=[[1,2],[3,4]]).inner_product_matrix()
[1 2]
[3 4]

VectorSpace( K, dimension, [sparse=None], [inner_product_matrix=False])

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

sage: V = VectorSpace(FractionField(PolynomialRing(IntegerRing())),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(IntegerRing(),5)
Traceback (most recent call last):
...
TypeError: K must be a field

basis_seq( V, w)

is_FreeModule( x)

span( R, gens, [check=False], [already_echelonized=True])

Return the $ R$ -span of gens.

sage: V = span(RationalField(), [[1,2,5], [2,2,2]]); V
Vector space of degree 3 and dimension 2 over Rational Field
Basis matrix:
[ 1  0 -3]
[ 0  1  4]
sage: span(QuadraticField(-7), [V.gen(0)])
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(GF(2), [[1,2,3], [2,2,2], [1,2,5]])
Vector space of degree 3 and dimension 1 over Finite Field of size 2
Basis matrix:
[1 0 1]

Class: FreeModule_ambient

class FreeModule_ambient
Ambient free module over a commutative ring.
FreeModule_ambient( self, base_ring, rank, [sparse=None], [inner_product_matrix=False])

The free module of given rank over the given base_ring.

INPUT:
    base_ring -- a commutative ring
    rank -- a non-negative integer

sage: FreeModule(Integers(), 4)
Ambient free module of rank 4 over the principal ideal domain Integer Ring

Functions: ambient_module,$  $ basis,$  $ change_ring,$  $ coordinate_vector,$  $ echelon_coordinate_vector,$  $ echelonized_basis,$  $ is_ambient,$  $ linear_combination_of_basis

ambient_module( self)

Return self, since self is ambient.

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

Return a basis for this ambient free module.

OUTPUT: Sequence - an immutable sequence with universe this ambient free module

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

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

sage: A = ZZ^3; A.change_ring(Rationals())
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(Rationals())
Vector space of dimension 3 over Rational Field

coordinate_vector( self, v)

Write $ v$ in terms of the standard basis for self and return the resulting coeffcients 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.

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

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

echelonized_basis( self)

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

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

is_ambient( self)

Return True since this module is an ambient module.

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

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

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

Special Functions: __cmp__,$  $ _latex_,$  $ _repr_

__cmp__( self, other)

Compare self and other.

We compare rank three free modules over the integers and rationals:

sage: Q = Rationals(); Z = Integers()
sage: Q**3 > Z**3
True
sage: Q**3 < Z**3
False
sage: Z**3 < Q**3
True
sage: Z**3 > Q**3
False
sage: Q**3 == Z**3
False
sage: Q**3 == Q**3
True

sage: V = span(Rationals(), [[1,2,3], [5,6,7], [8,9,10]])
sage: V
Vector space of degree 3 and dimension 2 over Rational Field
Basis matrix:
[ 1  0 -1]
[ 0  1  2]
sage: A = QQ^3
sage: V < A
True
sage: A < V
False

_latex_( self)

Return a latex representation of this ambient free module.

sage: A = QQ^3
sage: A._latex_()
'\\mbox{\\bf{}Q}^{3}'

sage: A = GF(5)**20; A._latex_()
'(\\mbox{\\rm F}_{5})^{20}'

sage: A = MPolynomialRing(Rationals(),3)**20; A._latex_()
'(\\mbox{\\bf{}Q}[x_{0}, x_{1}, x_{2}])^{20}'

Class: FreeModule_ambient_domain

class FreeModule_ambient_domain
Ambient free module over an integral domain.
FreeModule_ambient_domain( self, base_ring, rank, [sparse=None], [inner_product_matrix=False])

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

Functions: ambient_vector_space,$  $ base_field,$  $ coordinate_vector,$  $ vector_space

ambient_vector_space( self)

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

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

base_field( self)

Return the fraction field of the base ring of self.

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

coordinate_vector( self, v)

Write $ v$ in terms of the standard basis for self and return the resulting coeffcients 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.

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

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

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

Special Functions: _repr_

Class: FreeModule_ambient_field

class FreeModule_ambient_field
FreeModule_ambient_field( self, base_field, dimension, [sparse=None], [inner_product_matrix=False])

Functions: ambient_vector_space,$  $ base_field

ambient_vector_space( self)

Returns the ambient vector space.

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.

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

Special Functions: _repr_

Class: FreeModule_ambient_pid

class FreeModule_ambient_pid
Ambient free module over a principal ideal domain.
FreeModule_ambient_pid( self, base_ring, rank, [sparse=None], [inner_product_matrix=False])

Create the ambient free module of given rank over the given principal ideal domain

INPUT:
    base_ring -- a principal ideal domain
    rank -- a non-negative integer
    sparse -- bool (default: False)
    inner_product_matrix -- bool (default: None)

sage: ZZ^3
Ambient free module of rank 3 over the principal ideal domain Integer Ring

Special Functions: _repr_

Class: FreeModule_generic

class FreeModule_generic
Base class for all free modules.
FreeModule_generic( self, base_ring, rank, degree, [sparse=None], [inner_product_matrix=False])

Create the free module of given rank over the given base_ring.

INPUT:
    base_ring -- a commutative ring
    rank -- a non-negative integer

Functions: ambient_module,$  $ base_ring,$  $ basis,$  $ basis_matrix,$  $ category,$  $ coordinate_vector,$  $ coordinates,$  $ degree,$  $ dimension,$  $ discriminant,$  $ echelonized_basis_matrix,$  $ free_module,$  $ gen,$  $ has_user_basis,$  $ inner_product_matrix,$  $ is_ambient,$  $ is_dense,$  $ is_finite,$  $ is_full,$  $ is_sparse,$  $ matrix,$  $ ngens,$  $ nonembedded_free_module,$  $ random_element,$  $ rank,$  $ set_inner_product_matrix,$  $ unset_inner_product_matrix,$  $ uses_ambient_inner_product,$  $ zero_vector

ambient_module( self)

Return the ambient module associated to this module.

sage: R = MPolynomialRing(RationalField(),2); x,y = R.gens()
sage: M = FreeModule(R,2)
sage: M.ambient_module()
Ambient free module of rank 2 over the integral domain Polynomial Ring in
x0, x1 over Rational Field

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

base_ring( self)

Return the base ring of this module.

sage: R = MPolynomialRing(RationalField(),2); x,y = R.gens()
sage: M = FreeModule(R,2)
sage: M.base_ring()
Polynomial Ring in x0, x1 over Rational Field

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

basis( self)

Return the basis of this module.

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

basis_matrix( self)

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

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]

category( self)

Return the category to which this free module belongs. This is the category of all free modules over the base ring.

sage: FreeModule(GF(7),3).category()
Category of vector spaces over Finite Field of size 7

coordinate_vector( self, v)

Return the a vector whose cofficients give $ v$ as a linear combination of the basis for self.

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

coordinates( self, v)

Write $ v$ in terms of the basis for self.

Returns a list $ c$ such that if $ B$ is the basis for self, then

$\displaystyle \sum c_i B_i = v.
$

If $ v$ is not in self, raises an ArithmeticError exception.

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

degree( self)

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

sage: M = FreeModule(IntegerRing(), 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

dimension( self)

Return the dimension of this free module.

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

discriminant( self)

Return the discriminant of this free module.

sage: M = FreeModule(Integers(), 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( self)

Return basis matrix for self in row echelon form.

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

free_module( self)

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

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

has_user_basis( self)

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

sage: V = Rationals()^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( self)

Return the inner product matrix associated to this free module.

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

sage: FreeModule(IntegerRing(),2,inner_product_matrix=[[1,-1],[2,5]]).inner_product_matrix()
[ 1 -1]
[ 2  5]

is_ambient( self)

Returns False sense this is not an ambient free module.

sage: M = FreeModule(IntegerRing(), 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( self)

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

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

is_finite( self)

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

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

is_full( self)

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

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

is_sparse( self)

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

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

matrix( self)

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

sage: M = FreeModule(IntegerRing(), 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( self)

Returns the number of basis elements of this free module.

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

nonembedded_free_module( self)

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.

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

random_element( self, [bound=1.0], [prob=2])

Returns a random element of self.

INPUT:
    bound -- integer; coefficients of linear combination of basis are
chosen
             from the closed interval [-bound,bound]
    prob -- float; probability that given coefficient is nonzero.

sage: M = FreeModule(IntegerRing(), 2).span([[1,1]])
sage: x = M.random_element()
sage: x
(1, 1)
sage: M.random_element()
(-2, -2)
sage: M.random_element()
(-1, -1)

rank( self)

Return the rank of this free module.

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

set_inner_product_matrix( self, A)

Sets the inner product matrix of this module to the matrix A.

We change the inner product matrix over an ambient free module.

sage: M = FreeModule(IntegerRing(), 2)
sage: M.inner_product_matrix()
[1 0]
[0 1]
sage: M.set_inner_product_matrix([0,-1,-1,0])
sage: M.inner_product_matrix()
[ 0 -1]
[-1  0]
sage: (M.0).inner_product(M.1)
-1

We can also set the inner product matrix of a submodule:

sage: W = M.submodule([[1,2]])
sage: W.set_inner_product_matrix([2])
sage: W
Free module of degree 2 and rank 1 over Integer Ring
Echelon basis matrix:
[1 2]
sage: W.inner_product_matrix()
[2]
sage: v = W.gen(0)
sage: v.inner_product(v)
2

unset_inner_product_matrix( self)

If an inner product was set on this module using self.set_inner_product_matrix(...), this function unsets that inner product, thus reverting to the inner product induced from that on the ambient module.

sage: M = FreeModule(RationalField(), 2)
sage: M.set_inner_product_matrix([-1,0,0,-1])
sage: (M.0).inner_product(M.0)
-1

We set and unset an inner product matrix on a submodule. Note that unsetting the inner product on the submodule switches back to using the ambient inner product.

sage: M2 = M.submodule([[1,1]])
sage: M2.gen(0).inner_product(M2.gen(0))
-2
sage: M2.set_inner_product_matrix([1])
sage: M2.gen(0).inner_product(M2.gen(0))
1
sage: M2.unset_inner_product_matrix()
sage: M2.gen(0).inner_product(M2.gen(0))
-2

Changing the ambient inner product changes that on the submodule, since the submodule uses the ambient product after calling unset_inner_product_matrix.

sage: M.unset_inner_product_matrix()
sage: M2.gen(0).inner_product(M2.gen(0))
2

uses_ambient_inner_product( self)

Return True if the inner product on this module is the one induced by the ambient inner product. This is True exactly if self.set_inner_product_matrix(...) has not been called (or self.unset_inner_product_matrix() was subsequently called).

sage: M = FreeModule(IntegerRing(), 2)
sage: W = M.submodule([[1,2]])
sage: W.uses_ambient_inner_product()
True
sage: W.inner_product_matrix()
[5]
sage: W.set_inner_product_matrix([2])
sage: W.uses_ambient_inner_product()
False
sage: W.inner_product_matrix()
[2]

zero_vector( self)

Returns the zero vector in this free module.

sage: M = FreeModule(Integers(), 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)

Special Functions: __call__,$  $ __cmp__,$  $ __contains__,$  $ __iter__,$  $ __len__,$  $ _inner_product_is_dot_product

__contains__( self, v)

We create the module $ \mathbf{Z}^3$ , and the submodule generated by one vector $ (1,1,0)$ , and check whether certain elements are in the submodule.

sage: R = FreeModule(IntegerRing(), 3)
sage: V = R.submodule([R.gen(0) + R.gen(1)])
sage: R.gen(0) + R.gen(1) in V
True
sage: R.gen(0) + 2*R.gen(1) in V
False

sage: Q = RationalField()
sage: w = Q('1/2')*(R.gen(0) + R.gen(1))
sage: w
(1/2, 1/2, 0)
sage: w.parent()
Vector space of dimension 3 over Rational Field
sage: w in V
False
sage: V.coordinates(w)
[1/2]

__iter__( self)

Return iterator over the elements of this free module.

sage: V = VectorSpace(GF(4),2)
sage: [x for x in V]
[(0, 0), (1, 0), (a, 0), (a + 1, 0), (0, 1), (1, 1), (a, 1), (a + 1, 1),
(0, a), (1, a), (a, a), (a + 1, a), (0, a + 1), (1, a + 1), (a, a + 1), (a
+ 1, a + 1)]

sage: W = V.subspace([V([1,1])])
sage: print [x for x in W]
[(0, 0), (1, 1), (a, a), (a + 1, a + 1)]

_inner_product_is_dot_product( self)

Return whether or not the inner product on this module is induced by the dot product on the ambient vector space. This is used internally by the inner_product function for optimization.

sage: FreeModule(Integers(), 3)._inner_product_is_dot_product()
True
sage: FreeModule(Integers(), 3, inner_product_matrix=1)._inner_product_is_dot_product()
True
sage: FreeModule(Integers(), 2, inner_product_matrix=[1,0,-1,0])._inner_product_is_dot_product()
False

sage: M = FreeModule(RationalField(), 3)
sage: M2 = M.span([[1,2,3]])
sage: M2._inner_product_is_dot_product()
True
sage: M2.set_inner_product_matrix([-1])
sage: M2._inner_product_is_dot_product()
False
sage: M2.set_inner_product_matrix([1])
sage: M2._inner_product_is_dot_product()
False
sage: M2.unset_inner_product_matrix()
sage: M2._inner_product_is_dot_product()
True

Class: FreeModule_generic_field

class FreeModule_generic_field
Base class for all free modules over fields.
FreeModule_generic_field( self, base_field, dimension, degree, [sparse=None], [inner_product_matrix=False])

Functions: category,$  $ intersection,$  $ is_subspace,$  $ span,$  $ span_of_basis,$  $ subspace,$  $ subspace_with_basis,$  $ vector_space,$  $ zero_submodule,$  $ zero_subspace

category( self)

Return the category to which this vector space belongs.

sage: V = QQ^4; V.category()
Category of vector spaces over Rational Field
sage: V = GF(5)**20; V.category()
Category of vector spaces over Finite Field of size 5

intersection( self, other)

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

sage: V  = VectorSpace(RationalField(),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.

sage: V = VectorSpace(RationalField(),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

span( self, gens, [check=False], [already_echelonized=True])

Return the K-span of the given list of gens, where K is the base field of self. Note that this span is a subspace of the ambient vector space, but need not be a suspace 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

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]

span_of_basis( self, basis, [check=False], [already_echelonized=True])

Return the free K-module with the given basis, where K is the base field of self. Note that this span is a subspace of the ambient vector space, but need not be a suspace 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

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):
...
ArithmeticError: basis vectors must be linearly independent.

subspace( self, gens, [check=False], [already_echelonized=True])

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.

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: gens does not generate a submodule of self

subspace_with_basis( self, gens, [check=False], [already_echelonized=True])

Same as self.submodule_with_basis(...).

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

vector_space( self)

Return the vector space associated to self. Since self is a vector space this function simply returns self.

sage: V = span(Rationals(), [[1,2,3]]); 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.

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.

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

Special Functions: __add__,$  $ __mul__,$  $ __rmul__

__add__( self, other)

Return the sum of self and other.

sage: V = VectorSpace(RationalField(),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]

__mul__( 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.

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

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

__rmul__( self, left)

Return the product left*self.

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

Class: FreeModule_generic_pid

class FreeModule_generic_pid
Base class for all free modules over a PID.
FreeModule_generic_pid( self, base_ring, rank, degree, [sparse=None], [inner_product_matrix=False])

Create a free module over a PID.

sage: FreeModule(Integers(), 2)
Ambient free module of rank 2 over the principal ideal domain Integer Ring
sage: FreeModule(PolynomialRing(GF(7)), 2)
Ambient free module of rank 2 over the principal ideal domain Univariate
Polynomial Ring in x over Finite Field of size 7

Functions: base_field,$  $ basis_matrix,$  $ index,$  $ intersection,$  $ is_submodule,$  $ saturation,$  $ span,$  $ span_of_basis,$  $ submodule,$  $ submodule_with_basis,$  $ vector_space_span,$  $ vector_space_span_of_basis,$  $ zero_submodule

base_field( self)

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

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

basis_matrix( self)

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

sage: M = FreeModule(Rationals(),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]

index( self, other)

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

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

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

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

The index of a lattice of infinite index is infinite.

sage: L1 = FreeModule(Integers(), 2)
sage: L2 = span(Integers(), [[1,2]])
sage: L1.index(L2)
Infinity

intersection( self, other)

Return the intersection of self and other.

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]

We intersection two submodules of $ \mathbf{Z}^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 $ \mathbf{Z}$ -modules that are not submodules of $ \mathbf{Z}^2$ .

sage: A = ZZ^2
sage: Q = Rationals()
sage: M1 = Q('1/6')*A.span([[1,2]])
sage: M2 = Q('1/15')*A.span([[1,2]])
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 $ \mathbf{Z}$ -module with a $ \mathbf{Q}$ -vector space.

sage: A = ZZ^3
sage: L = ZZ^3
sage: V = Rationals()^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]

is_submodule( self, other)

True if this module is a submodule of other.

sage: M = FreeModule(Integers(),2)
sage: M.is_submodule(M)
True
sage: N = 2*M
sage: N.is_submodule(M)
True
sage: M.is_submodule(N)
False
sage: N = Rationals()('1/2') * M
sage: N.is_submodule(M)
False
sage: M.is_submodule(N)
True

saturation( self)

Return the saturated submodule of $ R^n$ that spans the same vector space as self.

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

sage: L = span(Integers(), [[9,9,6]]); 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. Comptuation 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(Integers(), [[1,2,3], [4,5,6]])
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(Integers(), [['1/2',1,3]])
sage: L.saturation()
Free module of degree 3 and rank 1 over Integer Ring
Echelon basis matrix:
[1 2 6]

span( self, gens, [check=False], [already_echelonized=True])

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

sage: V = FreeModule(IntegerRing(),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: gens does not generate a submodule of self

span_of_basis( self, basis, [check=False], [already_echelonized=True])

Return the free R-module with the given basis, where R is the base ring of self. 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.

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

Next we create two free $ \mathbf{Z}$ -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 even in the ambient space.

sage: Q = RationalField()
sage: W.span_of_basis([ Q('1/5')*M([1,2,0]), Q('1/7')*M([1,1,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):
...
ArithmeticError: basis vectors must be linearly independent.

submodule( self, gens, [check=False], [already_echelonized=True])

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.

We create a submodule of $ \mathbf{Z}^3$ :

sage: M = FreeModule(IntegerRing(), 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: gens does not generate a submodule of self

submodule_with_basis( self, basis, [check=False], [already_echelonized=True])

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

First we create a submodule of $ \mathbf{Z}^3$ :

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

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

We create a $ 2$ -dimensional subspace of a $ \mathbf{Q}^3$ .

sage: V = VectorSpace(RationalField(), 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 $ \mathbf{Q}(i)$ .

sage: x = PolynomialRing(RationalField()).gen()
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 $ \mathbf{Z}^3$ .

sage: M = FreeModule(IntegerRing(),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 user-specified basis

sage: V = VectorSpace(RationalField(), 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( self)

Return the zero submodule of this module.

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

Special Functions: __add__,$  $ __mul__,$  $ __rmul__

__add__( self, other)

Return the sum of self and other, where both self and other must be submodules of the ambient vector space.

We add two vector spaces:

sage: V  = VectorSpace(RationalField(), 3)
sage: W  = V.subspace([V([1,1,0])])
sage: W2 = V.subspace([V([1,-1,0])])
sage: W + W2
Vector space of degree 3 and dimension 2 over Rational Field
Basis matrix:
[1 0 0]
[0 1 0]

We add two free $ \mathbf{Z}$ -modules.

sage: M = FreeModule(IntegerRing(), 3)
sage: W = M.submodule([M([1,0,2])])
sage: W2 = M.submodule([M([2,0,-4])])
sage: W + W2
Free module of degree 3 and rank 2 over Integer Ring
Echelon basis matrix:
[1 0 2]
[0 0 8]

We can also add free $ \mathbf{Z}$ -modules embedded non-integrally into an ambient space.

sage: V = VectorSpace(RationalField(), 3)
sage: W = M.span([Q('1/2')*V.gen(0) - Q('1/3')*V.gen(1)])

Here the command M.span(...) creates the span of the indicated vectors over the base ring of $ M$ .

sage: W2 = M.span([Q('1/3')*V.gen(0) + V.gen(1)])
sage: W + W2
Free module of degree 3 and rank 2 over Integer Ring
Echelon basis matrix:
[ 1/6  7/3    0]
[   0 11/3    0]

We add two modules over $ \mathbf{Z}$ :

sage: A = Matrix(ZZ, 3, 3, [3, 0, -1, 0, -2, 0, 0, 0, -2])
sage: V = (A+2).kernel()
sage: W = (A-3).kernel()
sage: V+W
Free module of degree 3 and rank 3 over Integer Ring
Echelon basis matrix:
[5 0 0]
[0 1 0]
[0 0 1]

__mul__( self, other)

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

sage: M = FreeModule(IntegerRing(), 3)
sage: M*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 = RationalField()('1/3')
sage: M*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]

__rmul__( self, left)

Return the product of the scalar left times this module.

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

sage: RationalField()('1/2')*M
Free module of degree 2 and rank 2 over Integer Ring
Echelon basis matrix:
[1/2   0]
[  0 1/2]

sage: M = FreeModule(Rationals(), 2)
sage: 2*M
Vector space of dimension 2 over Rational Field
sage: Rationals()('1/2')*M
Vector space of dimension 2 over Rational Field

Class: FreeModule_submodule_field

class FreeModule_submodule_field
An embedded vector subspace with echelonized basis.
FreeModule_submodule_field( self, ambient, gens, [check=False], [inner_product_matrix=None], [already_echelonized=True])

Create an embedded vector subspace with echelonized basis.

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]

Functions: coordinate_vector,$  $ echelon_coordinates,$  $ has_user_basis

coordinate_vector( self, v)

Write $ v$ in terms of the user basis for self.

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.

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: W.coordinate_vector([1,5,9])
(1, 5)

echelon_coordinates( self, v)

Write $ v$ in terms of the user basis for self.

Returns a list $ c$ such that if $ B$ is the basis for self, then

$\displaystyle \sum c_i B_i = v.
$

If $ v$ is not in self, raises an ArithmeticError exception.

An embedded vector subspace with echelonized basis.

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: W.echelon_coordinates([1,5,9])
[1, 5]

has_user_basis( self)

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

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

Special Functions: _repr_

Class: FreeModule_submodule_pid

class FreeModule_submodule_pid
An $ R$ -submodule of $ K^n$ where $ K$ is the fraction field of a principal ideal domain $ R$ .

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

We can save and load submodules and elements.

sage: loads(W.dumps()) == W
True
sage: v = W.0 + W.1
sage: loads(v.dumps()) == v
True

FreeModule_submodule_pid( self, ambient, gens, [check=False], [inner_product_matrix=None], [already_echelonized=True])

Create an embedded free module over a PID.

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

Functions: coordinate_vector,$  $ has_user_basis

coordinate_vector( self, v)

Write $ v$ in terms of the user basis for self.

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.

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

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

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

Special Functions: _repr_

Class: FreeModule_submodule_with_basis_field

class FreeModule_submodule_with_basis_field
A vector subspace with distinguished basis.

sage: M = Q^3; W = M.span([[1,2,3],[4,5,19]]); W
Vector space of degree 3 and dimension 2 over Rational Field
Basis matrix:
[   1    0 23/3]
[   0    1 -7/3]

We can load and save submodules:

sage: loads(W.dumps()) == W
True

sage: K, x = FractionField(PolynomialRing(Q)).objgen()
sage: M = K^3; W = M.span_of_basis([[1,1,x]])
sage: loads(W.dumps()) == W
True

FreeModule_submodule_with_basis_field( self, ambient, basis, [check=False], [echelonize=None], [inner_product_matrix=None], [echelonized_basis=False], [already_echelonized=True])

Create a vector space with given basis.

sage: V = QQ^3
sage: W = V.span_of_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]

Functions: is_ambient

is_ambient( self)

Return False since this is not an ambient module.

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

Special Functions: _denominator,$  $ _echelonize,$  $ _repr_

Class: FreeModule_submodule_with_basis_pid

class FreeModule_submodule_with_basis_pid
An $ R$ -submodule of $ K^n$ with distinguished basis, where $ K$ is the fraction field of a principal ideal domain $ R$ .
FreeModule_submodule_with_basis_pid( self, ambient, basis, [check=False], [echelonize=None], [inner_product_matrix=None], [echelonized_basis=False], [already_echelonized=True])

Create a free module with basis over a PID.

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]

Functions: ambient_module,$  $ ambient_vector_space,$  $ basis,$  $ change_ring,$  $ coordinate_vector,$  $ echelon_coordinate_vector,$  $ echelon_coordinates,$  $ echelon_to_user_matrix,$  $ echelonized_basis,$  $ has_user_basis,$  $ linear_combination_of_basis,$  $ user_to_echelon_matrix,$  $ vector_space

ambient_module( self)

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.

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
sage: M <= M.ambient_module()
False
sage: M.ambient_module() <= M
False

ambient_vector_space( self)

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

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

basis( self)

Return the user basis for this free module.

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

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]

coordinate_vector( self, v)

Write $ v$ in terms of the user basis for self.

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.

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

Write $ v$ in terms of the user basis for 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.

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

Write $ v$ in terms of the echelonized basis for self.

Returns a list $ c$ such that if $ B$ is the basis for self, then

$\displaystyle \sum c_i B_i = v.
$

If $ v$ is not in self, raises an ArithmeticError exception.

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)

echelon_to_user_matrix( self)

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.

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

Return the basis for self in echelon form.

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

has_user_basis( self)

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

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

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

sage: V = span(Integers(), [[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)

user_to_echelon_matrix( self)

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.

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

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

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]

Special Functions: __cmp__,$  $ _denominator,$  $ _echelonize,$  $ _latex_,$  $ _repr_

__cmp__( self, other)

Compare self and other. If self and other are in a common ambient space, then self <= other precisely if self is contained in other.

First we compare two equal vector spaces.

sage: V = span(Rationals(), [[1,2,3], [5,6,7], [8,9,10]])
sage: W = span(Rationals(), [[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(Rationals(), [[5,6,7]])
sage: V == M
False
sage: M < V
True
sage: V < M
False

We compare a $ \mathbf{Z}$ -module to the one-dimensional space above.

sage: V = Rationals()('1/11') * span(Integers(), [[5,6,7]])
sage: 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

_latex_( self)

Return latex representation of this free module.

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

See About this document... for information on suggesting changes.