Free modules#

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

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

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

EXAMPLES:

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

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

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

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

We illustrate the exponent notation for creation of free modules.

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

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

Base ring:

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

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

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

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

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

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

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

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

AUTHORS:

  • William Stein (2005, 2007)

  • David Kohel (2007, 2008)

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

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

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

class sage.modules.free_module.ComplexDoubleVectorSpace_class(n)[source]#

Bases: FreeModule_ambient_field

coordinates(v)[source]#
class sage.modules.free_module.EchelonMatrixKey(obj)[source]#

Bases: object

A total ordering on free modules for sorting.

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

INPUT:

  • obj – a free module

EXAMPLES:

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

>>> from sage.all import *
>>> V = span([[Integer(1),Integer(2),Integer(3)], [Integer(5),Integer(6),Integer(7)], [Integer(8),Integer(9),Integer(10)]], QQ)
>>> W = span([[Integer(5),Integer(6),Integer(7)], [Integer(8),Integer(9),Integer(10)]], QQ)
>>> X = span([[Integer(5),Integer(6),Integer(7)]], ZZ).scale(Integer(1)/Integer(11))
>>> Y = CC**Integer(3)
>>> Z = ZZ**Integer(2)
>>> modules = [V,W,X,Y,Z]
>>> modules_sorted = [Z,X,V,W,Y]
>>> from sage.modules.free_module import EchelonMatrixKey
>>> modules.sort(key=EchelonMatrixKey)
>>> modules == modules_sorted
True
sage.modules.free_module.FreeModule(base_ring, rank_or_basis_keys, sparse, inner_product_matrix, with_basis=None, rank=False, basis_keys=None, **args)[source]#

Create a free module over the given commutative base_ring

FreeModule can be called with the following positional arguments:

  • FreeModule(base_ring, rank, ...)

  • FreeModule(base_ring, basis_keys, ...)

INPUT:

  • base_ring – a commutative ring

  • rank – a nonnegative integer

  • basis_keys – a finite or enumerated family of arbitrary objects

  • sparse – boolean (default False)

  • inner_product_matrix – the inner product matrix (default None)

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

  • further options may be accepted by various implementation classes

OUTPUT: a free module

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

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

    EXAMPLES:

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

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

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

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

    EXAMPLES:

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

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

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

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

    EXAMPLES:

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

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

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

EXAMPLES:

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

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

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

Of course we can make rank 0 free modules:

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

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

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

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

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

The default is dense.

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

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

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

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

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

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

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

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

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

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

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

Todo

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

EXAMPLES:

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

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

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

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

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

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

Bases: UniqueFactory

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

create_key(base_ring, rank, sparse=False, inner_product_matrix=None)[source]#
create_object(version, key)[source]#
class sage.modules.free_module.FreeModule_ambient(base_ring, rank, sparse=False, coordinate_ring=None, category=None)[source]#

Bases: FreeModule_generic

Ambient free module over a commutative ring.

ambient_module()[source]#

Return self, since self is ambient.

EXAMPLES:

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

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

Return a basis for this ambient free module.

OUTPUT:

  • Sequence – an immutable sequence with universe this ambient free module

EXAMPLES:

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

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

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

This also preserves the sparsity.

EXAMPLES:

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

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

For ambient modules any change of rings is defined:

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

>>> from sage.all import *
>>> A = GF(Integer(5))**Integer(3); A.change_ring(QQ)
Vector space of dimension 3 over Rational Field
coordinate_vector(v, check=True)[source]#

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

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

\[\sum c_i B_i = v.\]

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

EXAMPLES:

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

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

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

INPUT:

  • v – vector

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

OUTPUT: list

EXAMPLES:

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

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

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

EXAMPLES:

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

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

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

EXAMPLES:

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

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

The echelonized basis matrix of self.

EXAMPLES:

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

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

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

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

INPUT:

  • \(i\) – an integer (default 0)

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

EXAMPLES:

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

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

Return True since this module is an ambient module.

EXAMPLES:

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

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

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

INPUT:

  • v – list

EXAMPLES:

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

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

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

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

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

Returns a random element of self.

INPUT:

  • prob – float. Each coefficient will be set to zero with

    probability \(1-prob\). Otherwise coefficients will be chosen randomly from base ring (and may be zero).

  • *args, **kwds – passed on to random_element function of base

    ring.

EXAMPLES:

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

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

Passes extra positional or keyword arguments through:

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

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

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

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

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

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

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

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

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

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

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

>>> total = Integer(0)
>>> zeros = Integer(0)
>>> add_sample(prob=RealNumber('0.7'))
>>> expected = Integer(1)/Integer(5) * Integer(7)/Integer(10) + Integer(3)/Integer(10)
>>> while abs(zeros/total - expected) > RealNumber('0.01'):
...     add_sample(prob=RealNumber('0.7'))
class sage.modules.free_module.FreeModule_ambient_domain(base_ring, rank, sparse=False, coordinate_ring=None, category=None)[source]#

Bases: FreeModule_generic_domain, FreeModule_ambient

Ambient free module over an integral domain.

EXAMPLES:

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

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

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

EXAMPLES:

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

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

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

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

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

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

INPUT:

  • v – vector

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

    \(v\) is really in self.

OUTPUT: list

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

\[\sum c_i B_i = v.\]

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

EXAMPLES:

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

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

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

EXAMPLES:

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

>>> from sage.all import *
>>> M = ZZ**Integer(3);  M.vector_space()
Vector space of dimension 3 over Rational Field
class sage.modules.free_module.FreeModule_ambient_field(base_field, dimension, sparse=False, category=None)[source]#

Bases: FreeModule_generic_field, FreeModule_ambient_pid

ambient_vector_space()[source]#

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

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

Returns the base field of this vector space.

EXAMPLES:

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

>>> from sage.all import *
>>> M = QQ**Integer(3)
>>> M.base_field()
Rational Field
class sage.modules.free_module.FreeModule_ambient_pid(base_ring, rank, sparse=False, coordinate_ring=None, category=None)[source]#

Bases: FreeModule_generic_pid, FreeModule_ambient_domain

Ambient free module over a principal ideal domain.

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

Bases: Module_free_ambient

Base class for all free modules.

INPUT:

  • base_ring – a commutative ring

  • rank – a non-negative integer

  • degree – a non-negative integer

  • sparse – boolean (default: False)

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

  • category – category (default: None)

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

EXAMPLES:

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

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

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

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

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

EXAMPLES:

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

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

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

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

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

EXAMPLES:

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

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

Return the basis of this module.

EXAMPLES:

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

>>> from sage.all import *
>>> FreeModule(Integers(Integer(12)),Integer(3)).basis()
[
(1, 0, 0),
(0, 1, 0),
(0, 0, 1)
]
basis_matrix(ring=None)[source]#

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

INPUT:

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

EXAMPLES:

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

>>> from sage.all import *
>>> FreeModule(Integers(Integer(12)), Integer(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]

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

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

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

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

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

Return the cardinality of the free module.

OUTPUT:

Either an integer or +Infinity.

EXAMPLES:

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

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

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

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

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

>>> (QQ**Integer(3)).cardinality()
+Infinity
codimension()[source]#

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

EXAMPLES:

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

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

The codimension of an ambient space is always zero:

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

>>> from sage.all import *
>>> (QQ**Integer(10)).codimension()
0
construction()[source]#

The construction functor and base ring for self.

EXAMPLES:

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

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

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

Warning

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

EXAMPLES:

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

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

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

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

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

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

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

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

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

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

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

EXAMPLES:

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

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

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

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

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

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

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

INPUT:

  • v – vector

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

    \(v\) is really in self.

OUTPUT: list

EXAMPLES:

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

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

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

INPUT:

  • v – vector

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

    \(v\) is really in self.

OUTPUT: list

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

\[\sum c_i B_i = v.\]

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

EXAMPLES:

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

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

Return corresponding dense module.

EXAMPLES:

We first illustrate conversion with ambient spaces:

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

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

Next we create a subspace:

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

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

Return the dimension of this free module.

EXAMPLES:

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

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

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

EXAMPLES:

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

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

Return the discriminant of this free module.

EXAMPLES:

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

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

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

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

EXAMPLES:

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

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

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

EXAMPLES:

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

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

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

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

INPUT:

  • \(i\) – an integer (default 0)

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

EXAMPLES:

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

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

Return a tuple of basis elements of self.

EXAMPLES:

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

>>> from sage.all import *
>>> FreeModule(Integers(Integer(12)),Integer(3)).gens()
((1, 0, 0), (0, 1, 0), (0, 0, 1))
gram_matrix()[source]#

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

EXAMPLES:

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

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

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

EXAMPLES:

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

>>> from sage.all import *
>>> V = QQ**Integer(3)
>>> W = V.subspace([[Integer(2),'1/2', Integer(1)]])
>>> W.has_user_basis()
False
>>> W = V.subspace_with_basis([[Integer(2),'1/2',Integer(1)]])
>>> W.has_user_basis()
True
hom(im_gens, codomain=None, **kwds)[source]#

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

EXAMPLES:

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

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

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

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

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

EXAMPLES:

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

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

Returns False since this is not an ambient free module.

EXAMPLES:

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

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

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

EXAMPLES:

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

>>> from sage.all import *
>>> FreeModule(ZZ, Integer(2)).is_dense()
True
>>> FreeModule(ZZ, Integer(2), sparse=True).is_dense()
False
is_finite()[source]#

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

EXAMPLES:

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

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

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

EXAMPLES:

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

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

Return True if self is a submodule of other.

EXAMPLES:

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

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

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

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

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

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

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

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

EXAMPLES:

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

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

Returns the number of basis elements of this free module.

EXAMPLES:

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

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

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

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

EXAMPLES:

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

>>> from sage.all import *
>>> FreeModule(ZZ, Integer(2)).span([[Integer(1),Integer(1)]]).nonembedded_free_module()
Ambient free module of rank 1 over the principal ideal domain Integer Ring
random_element(prob=1.0, *args, **kwds)[source]#

Returns a random element of self.

INPUT:

  • prob – float. Each coefficient will be set to zero with

    probability \(1-prob\). Otherwise coefficients will be chosen randomly from base ring (and may be zero).

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

EXAMPLES:

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

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

Small entries are likely:

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

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

Large entries appear as well:

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

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

Passes extra positional or keyword arguments through:

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

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

Return the rank of this free module.

EXAMPLES:

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

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

Return the module of relations of self.

EXAMPLES:

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

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

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

>>> Q = V / W
>>> Q.relations() == W
True
scale(other)[source]#

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

EXAMPLES:

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

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

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

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

Return the corresponding sparse module with the same defining data.

EXAMPLES:

We first illustrate conversion with ambient spaces:

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

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

Next we convert a subspace:

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

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

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

EXAMPLES:

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

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

sage: W.gram_matrix()
[5]

>>> from sage.all import *
>>> W.gram_matrix()
[5]
class sage.modules.free_module.FreeModule_generic_domain(base_ring, rank, degree, sparse=False, coordinate_ring=None, category=None)[source]#

Bases: FreeModule_generic

Base class for free modules over an integral domain.

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

Bases: FreeModule_generic_pid

Base class for all free modules over fields.

complement()[source]#

Return the complement of self in the ambient_vector_space().

EXAMPLES:

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

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

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

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

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

All these complements are only done with respect to the inner product in the usual basis. Over finite fields, this means we can get complements which are only isomorphic to a vector space decomposition complement.

sage: F2 = GF(2, 'x')
sage: V = F2^6
sage: W = V.span([[1,1,0,0,0,0]]); W
Vector space of degree 6 and dimension 1 over Finite Field of size 2
Basis matrix:
[1 1 0 0 0 0]
sage: W.complement()
Vector space of degree 6 and dimension 5 over Finite Field of size 2
Basis matrix:
[1 1 0 0 0 0]
[0 0 1 0 0 0]
[0 0 0 1 0 0]
[0 0 0 0 1 0]
[0 0 0 0 0 1]
sage: W.intersection(W.complement())
Vector space of degree 6 and dimension 1 over Finite Field of size 2
Basis matrix:
[1 1 0 0 0 0]

>>> from sage.all import *
>>> F2 = GF(Integer(2), 'x')
>>> V = F2**Integer(6)
>>> W = V.span([[Integer(1),Integer(1),Integer(0),Integer(0),Integer(0),Integer(0)]]); W
Vector space of degree 6 and dimension 1 over Finite Field of size 2
Basis matrix:
[1 1 0 0 0 0]
>>> W.complement()
Vector space of degree 6 and dimension 5 over Finite Field of size 2
Basis matrix:
[1 1 0 0 0 0]
[0 0 1 0 0 0]
[0 0 0 1 0 0]
[0 0 0 0 1 0]
[0 0 0 0 0 1]
>>> W.intersection(W.complement())
Vector space of degree 6 and dimension 1 over Finite Field of size 2
Basis matrix:
[1 1 0 0 0 0]
echelonized_basis_matrix()[source]#

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]

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

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

EXAMPLES:

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

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

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

>>> from sage.all import *
>>> V = VectorSpace(QQ,Integer(3))
>>> W = V.subspace([V.gen(Integer(0)), V.gen(Integer(0)) + V.gen(Integer(1))])
>>> W2 = V.subspace([V.gen(Integer(1))])
>>> W.is_subspace(V)
True
>>> W2.is_subspace(V)
True
>>> W.is_subspace(W2)
False
>>> W2.is_subspace(W)
True
linear_dependence(vectors, zeros='left', check=True)[source]#

Returns a list of vectors giving relations of linear dependence for the input list of vectors. Can be used to check linear independence of a set of vectors.

INPUT:

  • vectors – A list of vectors, all from the same vector space.

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

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

OUTPUT:

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

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

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

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

EXAMPLES:

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

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

]

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

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

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

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

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

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

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

]
sage: relations == []
True

>>> from sage.all import *
>>> v1 = vector(QQ, [Integer(0),Integer(1),-Integer(3)])
>>> v2 = vector(QQ, [Integer(4),Integer(1),Integer(0)])
>>> V = QQ**Integer(3)
>>> relations = V.linear_dependence([v1, v2]); relations
[
<BLANKLINE>
]
>>> 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)
]

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

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

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

INPUT:

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

  • check – (default: True) whether or not to check that sub is a submodule

  • further named arguments, that are currently ignored.

OUTPUT:

  • U – the quotient as an abstract ambient free module

  • pi – projection map to the quotient

  • lift – lifting map back from quotient

EXAMPLES:

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

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

Another example involving a quotient of one subspace by another:

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

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

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)

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

We illustrate that the base rings must be the same:

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

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

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

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

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

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

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

>>> from sage.all import *
>>> V = QQ**Integer(4); V
Vector space of dimension 4 over Rational Field
>>> V.scale(Integer(3))
Vector space of dimension 4 over Rational Field
>>> V.scale(Integer(0))
Vector space of degree 4 and dimension 0 over Rational Field
Basis matrix:
[]
span_of_basis(basis, base_ring=None, check=True, already_echelonized=False)[source]#

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

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

INPUT:

  • basis – list of vectors

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

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

EXAMPLES:

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

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

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

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

>>> from sage.all import *
>>> W.span_of_basis([[Integer(2),Integer(2),Integer(2)], [Integer(3),Integer(3),Integer(3)]])
Traceback (most recent call last):
...
ValueError: The given basis vectors must be linearly independent.
subspace(gens, check=True, already_echelonized=False)[source]#

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

INPUT:

  • gens – list of vectors

  • check – boolean (default: True) verify that gens are all in self.

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

EXAMPLES:

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

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

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

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

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

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

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

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

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

Same as self.submodule_with_basis(...).

EXAMPLES:

We create a subspace with a user-defined basis.

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

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

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

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

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

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

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

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

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

sage: W1 == W2
True

>>> from sage.all import *
>>> W1 == W2
True
subspaces(dim)[source]#

Iterate over all subspaces of dimension dim.

INPUT:

  • dim – int, dimension of subspaces to be generated

EXAMPLES:

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

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

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

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

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]

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

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

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

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

>>> from sage.all import *
>>> (QQ**Integer(4)).zero_subspace()
Vector space of degree 4 and dimension 0 over Rational Field
Basis matrix:
[]
class sage.modules.free_module.FreeModule_generic_pid(base_ring, rank, degree, sparse=False, coordinate_ring=None, category=None)[source]#

Bases: FreeModule_generic_domain

Base class for all free modules over a PID.

denominator()[source]#

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

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

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

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

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

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

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

The index of a lattice of infinite index is infinite.

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

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

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

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

Return the intersection of self and other.

EXAMPLES:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Return the quotient of self by the given submodule sub.

INPUT:

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

  • check – (default: True) whether or not to check that sub is a submodule

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

EXAMPLES:

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

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

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

EXAMPLES:

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

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

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

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

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

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

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

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

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

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

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

EXAMPLES:

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

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

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

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

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

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

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

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

Of course the input basis vectors must be linearly independent:

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

>>> from sage.all import *
>>> W.span_of_basis([ [Integer(1),Integer(2),Integer(0)], [Integer(2),Integer(4),Integer(0)] ])
Traceback (most recent call last):
...
ValueError: The given basis vectors must be linearly independent.
submodule_with_basis(basis, check=True, already_echelonized=False)[source]#

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

INPUT:

  • basis – a list of linearly independent vectors

  • check – whether or not to verify that each gen is in

    the ambient vector space

OUTPUT:

  • FreeModule – the \(R\)-submodule with given basis

EXAMPLES:

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

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

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

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

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

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

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

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

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

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

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

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

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]

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

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

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

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

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

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

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

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

INPUT:

  • basis – a list of linearly independent vectors

  • check – whether or not to verify that each gen is in

    the ambient vector space

OUTPUT: a vector subspace with user-specified basis

EXAMPLES:

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

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

Return the zero submodule of this module.

EXAMPLES:

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

>>> from sage.all import *
>>> V = FreeModule(ZZ,Integer(2))
>>> V.zero_submodule()
Free module of degree 2 and rank 0 over Integer Ring
Echelon basis matrix:
[]
class sage.modules.free_module.FreeModule_submodule_field(ambient, gens, check=True, already_echelonized=False, category=None)[source]#

Bases: FreeModule_submodule_with_basis_field

An embedded vector subspace with echelonized basis.

EXAMPLES:

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

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

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

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

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

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

INPUT:

  • v – vector

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

    \(v\) is really in self

OUTPUT: list

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

\[\sum c_i B_i = v.\]

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

EXAMPLES:

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

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

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

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

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

INPUT:

  • v – vector

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

OUTPUT: list

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

\[\sum c_i B_i = v.\]

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

EXAMPLES:

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

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

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

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

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

EXAMPLES:

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

>>> from sage.all import *
>>> V = QQ**Integer(3)
>>> W = V.subspace([[Integer(2),'1/2', Integer(1)]])
>>> W.has_user_basis()
False
>>> W = V.subspace_with_basis([[Integer(2),'1/2',Integer(1)]])
>>> W.has_user_basis()
True
class sage.modules.free_module.FreeModule_submodule_pid(ambient, gens, check=True, already_echelonized=False, category=None)[source]#

Bases: FreeModule_submodule_with_basis_pid

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

EXAMPLES:

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

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

Generic tests, including saving and loading submodules and elements:

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

>>> from sage.all import *
>>> TestSuite(W).run()
>>> v = W.gen(0) + W.gen(1)
>>> TestSuite(v).run()
coordinate_vector(v, check=True)[source]#

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

INPUT:

  • v – vector

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

    \(v\) is really in self.

OUTPUT: list

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

\[\sum c_i B_i = v.\]

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

EXAMPLES:

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

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

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

EXAMPLES:

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

>>> from sage.all import *
>>> A = ZZ**Integer(3); A
Ambient free module of rank 3 over the principal ideal domain Integer Ring
>>> A.has_user_basis()
False
>>> W = A.span_of_basis([[Integer(2),'1/2',Integer(1)]])
>>> W.has_user_basis()
True
>>> W = A.span([[Integer(2),'1/2',Integer(1)]])
>>> W.has_user_basis()
False
class sage.modules.free_module.FreeModule_submodule_with_basis_field(ambient, basis, check=True, echelonize=False, echelonized_basis=None, already_echelonized=False, category=None)[source]#

Bases: FreeModule_generic_field, FreeModule_submodule_with_basis_pid

An embedded vector subspace with a distinguished user basis.

EXAMPLES:

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

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

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

sage: V = QQ^3

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

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

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

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

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

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

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

Generic tests, including saving and loading submodules and elements:

sage: TestSuite(W).run()

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

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

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

Return False since this is not an ambient module.

EXAMPLES:

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

>>> from sage.all import *
>>> V = QQ**Integer(3)
>>> V.is_ambient()
True
>>> W = V.span_of_basis([[Integer(1),Integer(2),Integer(3)],[Integer(4),Integer(5),Integer(6)]])
>>> W.is_ambient()
False
class sage.modules.free_module.FreeModule_submodule_with_basis_pid(ambient, basis, check=True, echelonize=False, echelonized_basis=None, already_echelonized=False, category=None)[source]#

Bases: FreeModule_generic_pid

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

INPUT:

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

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

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

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

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

  • already_echelonized – (default: False) if True, basis must be already given in the echelonized form.

OUTPUT:

  • \(R\)-submodule of \(K^n\) with the user-specified basis.

EXAMPLES:

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

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

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

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

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

Return the ambient module or space for self.

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]
sage: W.ambient()
Ambient free module of rank 3 over the principal ideal domain Integer Ring

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

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

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

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

A submodule of a submodule:

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

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

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

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

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

EXAMPLES:

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

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

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

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

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

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

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

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

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

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

INPUT:

  • R – a principal ideal domain

EXAMPLES:

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

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

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

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

The ring must be a principal ideal domain:

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

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

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

EXAMPLES:

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

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

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

INPUT:

  • v – vector

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

    \(v\) is really in self.

OUTPUT: list

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

\[\sum c_i B_i = v.\]

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

EXAMPLES:

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

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

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

INPUT:

  • v – vector

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

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

\[\sum c_i B_i = v.\]

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

EXAMPLES:

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

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

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

INPUT:

  • v – vector

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

OUTPUT: list

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

\[\sum c_i B_i = v.\]

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

EXAMPLES:

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

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

We do an example with a sparse vector space:

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

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

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]

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

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

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

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

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

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

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]

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

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

EXAMPLES:

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

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

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

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

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

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

INPUT:

  • v – list

EXAMPLES:

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

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

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

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

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

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

EXAMPLES:

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

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

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

>>> Q = V / W
>>> Q.relations() == W
True
>>> Q.zero_submodule().relations() == W
True
retract()[source]#

The retract map from the ambient space.

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

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

EXAMPLES:

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

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

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]

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

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

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

>>> from sage.all import *
>>> v0,v1 = M.basis(); v = v0+v1
>>> e0,e1 = M.echelonized_basis()
>>> v
(5, 7, 9)
>>> Integer(5)*e0 + (-Integer(1))*e1
(5, 7, 9)
vector_space(base_field=None)[source]#

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

EXAMPLES:

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

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

Bases: Module

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

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

INPUT:

  • base_ring – a commutative ring

  • degree – a non-negative integer; degree of the ambient free module

  • sparse – boolean (default: False)

  • category – category (default: None)

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

EXAMPLES:

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

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

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

EXAMPLES:

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

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

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

EXAMPLES:

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

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

Return a free resolution of self.

For input options, see FreeResolution.

EXAMPLES:

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

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

Return a graded free resolution of self.

For input options, see GradedFiniteFreeResolution.

EXAMPLES:

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

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

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

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

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

EXAMPLES:

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

>>> from sage.all import *
>>> FreeModule(ZZ, Integer(2)).is_sparse()
False
>>> FreeModule(ZZ, Integer(2), sparse=True).is_sparse()
True
is_submodule(other)[source]#

Return True if self is a submodule of other.

EXAMPLES:

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

The zero module can always be tested:

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

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

It also respects which module it is constructed from:

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

>>> from sage.all import *
>>> Q = M.quotient_module(N)
>>> Q.zero_submodule().is_submodule(M)
False
>>> Q.zero_submodule().is_submodule(N)
False
>>> M.zero_submodule().is_submodule(Q)
False
>>> N.zero_submodule().is_submodule(Q)
False
quotient_module(sub, check=True)[source]#

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

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

Return the matrix of relations of self.

EXAMPLES:

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

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

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

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

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

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

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

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

Return some elements of this free module.

See TestSuite for a typical use case.

OUTPUT:

An iterator.

EXAMPLES:

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

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

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

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

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

>>> F = FreeModule(SR, Integer(2))                                                 # needs sage.symbolic
>>> tuple(F.some_elements())                                              # needs sage.symbolic
((1, 0), (some_variable, some_variable))
span(gens, base_ring=None, check=True, already_echelonized=False)[source]#

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

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

INPUT:

  • gens – a list of vectors

  • base_ring – (optional) a ring

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

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

EXAMPLES:

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

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

Over a general ring:

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

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

Over a PID:

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

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

It also works with other things than integers:

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