Basic Creation and Access

An ambient free module \(M=R^k\) is created by giving the base ring \(R\) (see introduction above), the degree \(r\) or a sequence \(W\) of \(r\) integers for the column weights, and, optionally, an argument specifying the type of module monomial order.

Creation of Ambient Embedded Modules

The following functions create ambient embedded modules.

EModule(R, k): Rng, RngIntElt -> ModMPol: Given a ring \(R\), create the ambient embedded module \(R^k\) with the default TOP module monomial order.

EModule(R, k, order): Rng, RngIntElt, MonStgElt, ... -> ModMPol: Given a ring \(R\), create the ambient embedded module \(R^k\) with the module monomial order described by the given order order. See Section Monomial Orders for the valid values for order.

EModule(R, W): Rng, [ RngIntElt ] -> ModMPol: Given a ring \(R\) and a sequence \(W\) of \(k\) integers, create the ambient embedded module \(R^k\) with column weights given by \(W\) and with the TOPW module monomial order with weights \(W\).

EModule(R, W, order): Rng, [ RngIntElt ], MonStgElt, ... -> ModMPol: Given a ring \(R\) and a sequence \(W\) of \(k\) integers, create the ambient embedded module \(R^k\) with column weights given by \(W\) and with the module monomial order described by the given order order. See Section Monomial Orders for the valid values for order.

Creation of Reduced Modules

The following functions create reduced modules, which are always ambient.

RModule(R, k): Rng, RngIntElt -> ModMPol: Given a ring \(R\), create the reduced module \(R^k\) with zero column weights.

RModule(R, W): Rng, [ RngIntElt ] -> ModMPol: Given a ring \(R\) and a sequence \(W\) of \(k\) integers, create the reduced module \(R^k\) with column weights given by \(W\).

GradedModule(R, k): Rng, RngIntElt -> ModMPol: Given a ring \(R\), create the reduced graded module \(R^k\) with zero column weights. The resulting module has type ModMPolGrd, so submodules and quotient modules of it may only be generated by homogeneous elements. Note also that in general it is preferable if possible that the base ring \(R\) has a degree ordering (such as the grevlex or grevlexw orders) so that associated Gröbner bases of derived modules will be easier to compute.

GradedModule(R, W): Rng, [ RngIntElt ] -> ModMPol: Given a ring \(R\) and a sequence \(W\) of \(k\) integers, create the reduced graded module \(R^k\) with column weights given by \(W\). The resulting module has type ModMPolGrd, so submodules and quotient modules of it may only be generated by homogeneous elements.

Localization

Localization(M): ModMPol -> ModMPol: Given an \(R\)-module \(M\), where \(R=K[x_1, \ldots, x_n]\) for a field \(K\), return the corresponding \(S\)-module \(M_{\langle x_1, \ldots, x_n\rangle}\), where \(S=K[x_1, \ldots, x_n]_{\langle x_1, \ldots, x_n\rangle}\) is the localization of \(R\). See Chapter Local Polynomial Rings for more information.

Basic Invariants

The following functions access simple defining invariants of a module \(M\).

Ambient(M): ModMPol -> ModMPol
Generic(M): ModMPol -> ModMPol: Given a module \(M\), return the ambient (or generic) module \(A\) in which \(M\) is embedded. The only case in which \(A\) differs from \(M\) is when \(M\) is a proper submodule of an ambient embedded module. So if \(M\) is reduced, \(A\) will always equal \(M\).

IsAmbient(M): ModMPol -> BoolElt: Given a module \(M\), return whether \(M\) is ambient.

IsEmbedded(M): ModMPol -> BoolElt: Given a module \(M\), return whether \(M\) is embedded.

IsReduced(M): ModMPol -> BoolElt: Given a module \(M\), return whether \(M\) is reduced.

IsRoot(M): ModMPol -> BoolElt: Given a module \(M\), return whether \(M\) is a root (an independent module, not derived via sub- or quotient constructions from another module).

CoefficientRing(M): ModMPol -> ModMPol
BaseRing(M): ModMPol -> Rng: Given an \(R\)-module \(M\), return the base ring \(R\) over which \(M\) is defined. Note that one can then call BaseRing(R) to obtain the underlying ring \(S\) in which the base coefficients of elements \(R\) lie.

Degree(M): ModMPol -> RngIntElt: Given an \(R\)-module \(M\), return the degree of \(M\), which is the \(k\) such that the ambient module of \(M\) equals \(R^k/\langle\)relations\(\rangle\). Note that if \(M\) is free and ambient, then the degree of \(M\) equals the rank of \(M\), but otherwise in general the rank of \(M\) may be less than the degree of \(M\) (see the function Rank below).

ColumnWeights(M): ModMPol -> [ RngIntElt ]
Grading(M): ModMPol -> [ RngIntElt ]: Given a module \(M\) of degree \(k\), return the grading of \(M\), which is a sequence of \(k\) integers giving the grading on the columns of \(M\).

RelationModule(M): ModMPol -> [ ModMPol ]: Given an \(R\)-module \(M\) of degree \(k\), return the submodule of the embedded module \(R^k\) which is generated by the defining relations of \(M\).

Relations(M): ModMPol -> [ ModMPol ]: Given an \(R\)-module \(M\) of degree \(k\), return the defining relations of \(M\) as a sorted sequence of elements of the embedded module \(R^k\).

RelationMatrix(M): ModMPol -> ModMatRngElt: Given a module \(M\), return the relation matrix of \(M\), which is the matrix whose rows are the defining relations of \(M\).

Presentation(M): ModMPol -> [ ModMPol ]: Given an \(R\)-module \(M\), return the presentation module \(P\) of \(M\). This is a reduced module isomorphic to \(M\) (and such that automatic coercion between \(M\) and \(P\) is allowed). If \(M\) is reduced, then \(P\) is identical to \(M\).

IsGraded(M): ModMPol -> BoolElt
IsHomogeneous(M): ModMPol -> BoolElt: Given a module \(M\), return whether \(M\) is graded (or equivalently, homogeneous), w.r.t. the grading of \(M\) (given by the weights on the columns of \(M\) and the variables of the base ring of \(M\)). This is true iff the Gröbner basis of \(M\) consists of homogeneous elements only (always true if \(M\) is reduced) and the Gröbner basis of the relation module of \(M\) consists of homogeneous elements alone. Note that a module of type ModMPolGrd is always graded.

Creation of Module Elements

Module elements (internally, multivariate polynomials with columns attached to the monomials) are constructed in general by giving a sequence or vector of elements from the coefficient ring \(R\).

M ! Q: ModMPol, [ RngElt ] -> ModMPolElt: Suppose \(M\) is an \(R\)-module of degree \(r\). Given a sequence \(Q = [a_1, \ldots, a_r]\) of ring elements such that the \(a_i\) are coercible into \(R\), construct the element of \(M\) corresponding to \(Q\).

M ! v: ModMPol, ModTupRngElt -> ModMPolElt: Suppose \(M\) is an \(R\)-module of degree \(r\). Given a vector \(v\) from the \(R\)-space \(R^r\), construct the element of \(M\) corresponding to \(v\).

M ! 0: ModMPol, RngIntElt -> ModMPolElt
Zero(M): ModMPol -> ModMPolElt: Create the zero element of the module \(M\).

UnitVector(M, i): ModMPol, RngIntElt -> ModMPolElt: Suppose \(M\) is an \(R\)-module of degree \(r\). Given an integer \(i\) in the range \([1 .. r]\), construct the \(i\)-th unit vector of \(M\) (the vector with \(1\) in the \(i\)-th column and 0 elsewhere) whose parent is the ambient module of \(M\) (since it may not lie in \(M\) itself). Note that this not the same as the function BasisElement (below) which depends on the current basis of \(M\).

Element Operations

The following functions allow simple access and operations on module elements. Some of them use the module structure and refer to the column structure of an element; others use the polynomial structure and ignore the column structure.

Access

Eltseq(f): ModMPolElt -> [ RngMPolElt ]: Given an element \(f\) of the \(R\)-module of degree \(r\), return the sequence \([f_1, \ldots, f_r]\) of \(r\) elements from \(R\) corresponding to \(f\).

Vector(f): ModMPolElt -> ModTupRngElt: Given an element \(f\) of the module \(M\) over \(R\) and of degree \(r\), return the element of the \(R\)-space of degree \(r\) over \(R\) corresponding to \(f\).

f[i]: ModMPolElt, RngIntElt -> RngMPolElt: Given an element \(f\) of the \(R\)-module of degree \(r\), together with an integer \(i\) in the range \([1 .. r]\), return the \(i\)-th component of \(f\) as an element of \(R\).

Arithmetic

The following functions act on elements of \(R\)-modules. The operations are similar to those for multivariate polynomials or vectors, whenever meaningful. For the binary operations, the elements must be compatible; that is, their parents must have the same ambient module. Note that if quotient relations for \(M\) are present, then the result is reduced to the unique normal form modulo the quotient relations, but if the determination of the relations is delayed, then an element may have a non-unique representation, but all the predicates on elements below do not depend on the representation.

f + g: ModMPolElt, ModMPolElt -> ModMPolElt
f - g: ModMPolElt, ModMPolElt -> ModMPolElt
- f: ModMPolElt -> ModMPolElt
r * f: RngElt, ModMPolElt -> ModMPolElt
f * r: ModMPolElt, RngElt -> ModMPolElt: Basic arithmetic operations. The element \(r\) lies in the base ring \(R\).

f div s: ModMPolElt, RngMPolElt -> ModMPolElt: Given a scalar ring element \(s\) and an element \(f\) of the module \(M\), such that \(s\) is coercible into \(R\) \(s\) divides all components of \(f\), return the quotient of \(f\) by \(s\).

SPolynomial(f, g): ModMPolElt, ModMPolElt -> ModMPolElt: Given elements \(f\) and \(g\) of the module \(M\) such that the leading module monomials of \(f\) and \(g\) have the same column, return the \(S\)-polynomial of \(f\) and \(g\). Note that the result is always reduced to the unique normal form modulo the quotient relations of \(M\).

Normalize(f): ModMPolElt -> ModMPolElt: Given an element \(f\) of the module \(M\), return the normalized form of \(f\) (so that the leading module monomial of \(f\) is normalized).

NormalForm(f, S): ModMPolElt, ModMPol -> ModMPolElt: Given an element \(f\) of the module \(M\), together with a compatible module \(S\), return the normal form of \(f\) with respect to \(S\). This is unique if the base ring \(R\) is not local. In general, \(S\) will be a non-ambient embedded module for this to be useful (otherwise any \(f\) would already be in \(S\) so the result would always be zero).

Coordinates(M, f): ModMPolElt, ModMPol -> [ RngMPolElt ]: Given a \(R\)-module \(M\) and an element \(f\) of the \(R\)-module \(S\), such that \(S\) is compatible with \(M\) and \(f\) is in \(M\), return the coordinates of \(f\) with respect to the Gröbner basis of \(M\) (whose components lie in \(R\)).

Accessing the Underlying Representation

The following functions access simple properties of module elements which are to do with the underlying representation.

Coefficients(f): ModMPolElt -> [RngElt]
Monomials(f): ModMPolElt -> [ModMPolElt]
Terms(f): ModMPolElt -> [ModMPolElt]
LeadingCoefficient(f): ModMPolElt -> RngElt
LeadingMonomial(f): ModMPolElt -> ModMPolElt
LeadingTerm(f): ModMPolElt -> ModMPolElt
CoefficientsAndMonomials(f): ModMPolElt -> [RngElt], [ModMPolElt]: These functions are equivalent to the access functions for multivariate polynomials and access the underlying distributed polynomial representation (with columns added to the monomials); see Section Coefficients, Monomials, and Terms for details.

Column(f): ModMPolElt -> RngIntElt: Given a single-term element \(f\) of a module \(M\), return the column \(c\) of the single monomial-column pair (module monomial) \(s[c]\) which \(f\) has.

Degree(f): ModMPolElt -> RngIntElt
WeightedDegree(f): ModMPolElt -> RngIntElt: Given an element \(f\) of a module \(M\), return the weighted degree (abbreviated to ‘degree’ in this chapter) of \(f\), which is the maximum of the weighted degrees of the monomial-column pairs of \(f\). The weighted degree of a monomial-column \(s[c]\) is the weighted degree of \(s\) (in the base ring \(R\)) plus the degree of column \(c\) in the grading of \(M\).

IsHomogeneous(f): ModMPolElt -> BoolElt: Given an element \(f\) of a module \(M\), return whether \(f\) is homogeneous; that is, whether the weighted degrees of all the monomial-columns of \(f\) are equal. (Note that the grading of \(M\) is thus significant.)

Predicates

IsZero(f): ModMPolElt -> BoolElt: Given an element \(f\) of the module \(M\), return whether \(f\) is the zero element of \(M\). Note that if the relations of \(M\) are non-zero this operation may be non-trivial (especially if the relations are not yet computed, but they will be automatically computed if needed).

f eq g: ModMPolElt, ModMPolElt -> BoolElt: Given elements \(f\) and \(g\) of the module \(M\), return whether \(f\) and \(g\) are equal. Note that this may be non-trivial (see the remarks above).

f lt g: ModMPolElt, ModMPolElt -> BoolElt: Given elements \(f\) and \(g\) of the module \(M\), return whether \(f < g\) w.r.t. the underlying module monomial order. The operators le, gt, ge are similarly defined.

f in M: ModMPolElt, ModMPol -> BoolElt: Given an element \(f\) of a module \(S\) together with a compatible module \(M\), return whether \(f\) is in \(M\).

Example: Embedded Modules over a Polynomial Ring (ex-ce53cf)

Run in calculator (opens in a new tab)

We illustrate simple modules over a multivariate polynomial ring. We construct simple ambient embedded modules over \({\mathbb{Q}}[x, y, z]\). The first module has default weights 0 on its columns, while the second has weights 1, 2, and 3 respectively on its columns.

> R<x,y,z> := PolynomialRing(RationalField(), 3, "grevlex");
> M := EModule(R, 3);
> M;
Free Embedded Module R^3
Order: Module TOP: Graded Reverse Lexicographical
> f := M![x, y, z^2];
> g := M![z, y^3, x + 1];
> f;
[x, y, z^2]
> g;
[z, y^3, x + 1]
> f + g;
[x + z, y^3 + y, z^2 + x + 1]
> Terms(f);
[
    [0, 0, z^2],
    [x, 0, 0],
    [0, y, 0]
]
> Degree(f);
2
> [Degree(m): m in Monomials(f)];
[ 2, 1, 1 ]
> LeadingMonomial(f);
[0, 0, z^2]
> M2 := EModule(R, [10, 5, 1]);
Free Embedded Module R^3 with grading [10, 5, 1]
Order: Module TOP with column weights [10, 5, 1]: Graded Reverse Lexicographical
> f := M2![x, y, z^2];
> f;
[x, y, z^2]
> Terms(f);
[
    [x, 0, 0],
    [0, y, 0],
    [0, 0, z^2]
]
> Degree(f);
11
> [Degree(m): m in Monomials(f)];
[ 11, 6, 3 ]

Similar operations can be done with reduced modules. There is no difference for the elements.

> M := RModule(R, 3);
> M;
Free RModule R^3
> M := GradedModule(R, [10, 5, 1]);
> M;
Free Graded Module R^3 with grading [10, 5, 1]
> Grading(M);
[ 10, 5, 1 ]
> f := M![x, y^6, z^10];
> f;
[x, y^6, z^10]
> IsHomogeneous(f);
true

Run in calculator (opens in a new tab)

Basic Creation and Access#

Creation of Ambient Embedded Modules#

Creation of Reduced Modules#

Localization#

Basic Invariants#

Creation of Module Elements#

Element Operations#

Access#

Arithmetic#

Accessing the Underlying Representation#

Predicates#