# 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](order.md#pmod-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](order.md#pmod-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](../LocalPolynomialRings/index-local-polynomial-rings.md#chaprngmpolloc) 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`](operations.md#function-pmod-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](../../BasicRings/MultivariatePolynomialRings/operation-element.md#rngmpol-coeffs) 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: Create Embedded (ex-ce53cf)`

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.

```magma
> 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.

```magma
> 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

```