---
title: "Construction of Elements"
canonical: "https://docs.magma-maths.org/v2.30-1/Modules/FreeModules/creation.html"
source: "https://docs.magma-maths.org/v2.30-1/Modules/FreeModules/creation.md"
part: "Modules"
chapter: "Free Modules"
breadcrumbs:
  - {"title": "Magma Handbook", "source": "https://docs.magma-maths.org/v2.30-1/index.md"}
  - {"title": "Modules", "source": "https://docs.magma-maths.org/v2.30-1/Modules/index-modules.md"}
  - {"title": "Free Modules", "source": "https://docs.magma-maths.org/v2.30-1/Modules/FreeModules/index-free-modules.md"}
prev: {"title": "Standard Constructions", "source": "https://docs.magma-maths.org/v2.30-1/Modules/FreeModules/operation.md"}
next: {"title": "Bases", "source": "https://docs.magma-maths.org/v2.30-1/Modules/FreeModules/basis.md"}
intrinsics:
  - {"name": "elt", "signature": "elt< M | a₁, ..., aₙ >: ModTupRng, List -> ModTupRngElt"}
  - {"name": "!", "signature": "M ! Q: ModTupRng, [RngElt] -> ModTupRngElt"}
  - {"name": "CharacteristicVector", "signature": "CharacteristicVector(M, S): ModRng, { RngIntElt } -> ModRngElt"}
  - {"name": "Zero", "signature": "Zero(M): ModRng -> ModRngElt"}
  - {"name": "!", "signature": "M ! 0: ModRng, RngIntElt -> ModRngElt"}
  - {"name": "Random", "signature": "Random(M): ModRng -> ModRngElt"}
  - {"name": "ElementToSequence", "signature": "ElementToSequence(u): ModTupRngElt -> [RngElt]"}
  - {"name": "Eltseq", "signature": "Eltseq(u): ModTupRngElt -> [RngElt]"}
  - {"name": "+", "signature": "u + v: ModTupRngElt, ModTupRngElt -> ModTupRngElt"}
  - {"name": "-", "signature": "- u: ModTupRngElt -> ModTupRngElt"}
  - {"name": "-", "signature": "u - v: ModTupRngElt, ModTupRngElt -> ModTupRngElt"}
  - {"name": "*", "signature": "x * u: RngElt, ModTupRngElt -> ModTupRngElt"}
  - {"name": "*", "signature": "u * x: ModTupRngElt, RngElt -> ModTupRngElt"}
  - {"name": "/", "signature": "u / x: ModTupRngElt, RngElt -> ModTupRngElt"}
  - {"name": "u", "signature": "u[i]: ModTupRngElt, RngIntElt -> RngElt"}
  - {"name": "u[i] := x", "signature": "u[i] := x: ModTupRngElt, RngIntElt, RngElt -> ModTupRngElt"}
  - {"name": "Normalize", "signature": "Normalize(u): ModTupRngElt -> ModTupRngElt"}
  - {"name": "Normalise", "signature": "Normalise(u): ModTupRngElt -> ModTupRngElt"}
  - {"name": "Rotate", "signature": "Rotate(u, k): ModTupRngElt, RngIntElt -> ModTupRngElt"}
  - {"name": "Rotate", "signature": "Rotate(~u, k): ModTupRngElt, RngIntElt"}
  - {"name": "IsZero", "signature": "IsZero(u): ModTupRngElt -> BoolElt"}
  - {"name": "Depth", "signature": "Depth(v): ModTupRngElt -> RngIntElt"}
  - {"name": "Support", "signature": "Support(u): ModTupRngElt -> { RngElt }"}
  - {"name": "Weight", "signature": "Weight(u): ModTupRngElt -> RngIntElt"}
  - {"name": "(u, v)", "signature": "(u, v): ModTupRngElt, ModTupRngElt -> RngElt"}
  - {"name": "InnerProduct", "signature": "InnerProduct(u, v): ModTupRngElt, ModTupRngElt -> RngElt"}
  - {"name": "Norm", "signature": "Norm(u): ModTupRngElt -> RngElt"}
examples:
  - "ex-cd5034"
  - "ex-8a5f2c"
---

# Construction of Elements

<a id="constructor-constructor-elt-modtuprng-list-modtuprngelt"></a>
## `elt< M | a₁, ..., aₙ >: ModTupRng, List -> ModTupRngElt`

Given a module $M$ with base module $S^{(n)}$, and elements $a_1, \ldots, a_n$ belonging to $S$, construct the element $m = (a_1, \ldots, a_n)$ of $M$. Note that if $m$ is not an element of $M$, an error will result.

<a id="operation-op-modtuprng-rngelt"></a>
## `M ! Q: ModTupRng, [RngElt] -> ModTupRngElt`

Given the module $M$ with base module $S^{(n)}$, and elements $a_1, \ldots, a_n$ belonging to $S$, construct the element $m = (a_1, \ldots, a_n)$ of $M$. Note that if $m$ is not an element of $M$, an error will result.

<a id="function-characteristicvector-modrng-rngintelt"></a>
## `CharacteristicVector(M, S): ModRng, { RngIntElt } -> ModRngElt`

Given a submodule $M$ of the module $R^{(n)}$ together with a set $S$ of integers lying in the interval $[1, n]$, return the characteristic number of $S$ as a vector of $R$.

<a id="function-zero-modrng"></a>
## `Zero(M): ModRng -> ModRngElt`

<a id="operation-op-modrng-rngintelt"></a>
## `M ! 0: ModRng, RngIntElt -> ModRngElt`

The zero element for the $R$-module $M$.

<a id="function-random-modrng"></a>
## `Random(M): ModRng -> ModRngElt`

Given a module $M$ defined over a finite ring or field, return a random vector.

<a id="example-ex-cd5034"></a>
## `Example: Elements of a Free Module over Z[x] (ex-cd5034)`

We create the module of $4$-tuples over the polynomial ring ${\mathbb{Z}}[x]$ and define various elements.

```magma
> P<x> := PolynomialRing(IntegerRing());
> M := RModule(P, 4);
> a := elt< M | 1+x, -x, 2+x, 0 >;
> a;
(x + 1    -x x + 2     0)
> b := M ! [ 1+x+x^2, 0, 1-x^7, 2*x ];
> b;
(x^2 + x + 1           0    -x^7 + 1         2*x)
> zero := M ! 0;
> zero;
(0 0 0 0)
```

## Deconstruction of Elements

<a id="function-elementtosequence-modtuprngelt"></a>
### `ElementToSequence(u): ModTupRngElt -> [RngElt]`

<a id="function-eltseq-modtuprngelt"></a>
### `Eltseq(u): ModTupRngElt -> [RngElt]`

Given an element $u$ belonging to the $R$-module $M$, return $u$ in the form of a sequence $Q$ of elements of $R$. Thus, if $u$ is an element of $R^{(n)}$, then $Q[i] = u[i], 1 \leq i \leq n$, while if $u$ is an element of $R^{(m \times n)}$, then $Q[(i-1)n +j] = u[i,j], 1 \leq i \leq m, 1 \leq j \leq n$.

## Operations on Module Elements

### Arithmetic

<a id="operation-op-plus-modtuprngelt-modtuprngelt"></a>
#### `u + v: ModTupRngElt, ModTupRngElt -> ModTupRngElt`

Sum of the elements $u$ and $v$, where $u$ and $v$ lie in the same $R$-module $M$.

<a id="operation-operation-modtuprngelt-modtuprngelt"></a>
#### `- u: ModTupRngElt -> ModTupRngElt`

Additive inverse of the element $u$.

<a id="operation-op-minus-modtuprngelt-modtuprngelt"></a>
#### `u - v: ModTupRngElt, ModTupRngElt -> ModTupRngElt`

Difference of the elements $u$ and $v$, where $u$ and $v$ lie in the same $R$-module $M$.

<a id="operation-op-times-rngelt-modtuprngelt"></a>
#### `x * u: RngElt, ModTupRngElt -> ModTupRngElt`

Given an element $x$ belonging to a ring $R$, and an element $u$ belonging to the left $R$-module $M$, return the (left) scalar product $x * u$ as an element of $M$.

<a id="operation-op-times-modtuprngelt-rngelt"></a>
#### `u * x: ModTupRngElt, RngElt -> ModTupRngElt`

Given an element $x$ belonging to a ring $R$, and an element $u$ belonging to the right $R$-module $M$, return the (right) scalar product $u * x$ as an element of $M$.

<a id="operation-op-div-modtuprngelt-rngelt"></a>
#### `u / x: ModTupRngElt, RngElt -> ModTupRngElt`

Given a non-zero element $x$ belonging to a field $K$, and an element $u$ belonging to the right $K$-module $M$, return the scalar product $u * (1/x)$ as an element of $M$.

### Indexing

<a id="indexed-indexed-u-modtuprngelt-rngintelt-rngelt"></a>
#### `u[i]: ModTupRngElt, RngIntElt -> RngElt`

Given an element $u$ belonging to a submodule $M$ of the $R$-module $R^{(n)}$ and a positive integer $i$, $1 \leq i\leq n$, return the $i$-th component of $u$ (as an element of the ring $R$).

<a id="literal-literal-u-i-x-modtuprngelt-rngintelt-rngelt-modtuprngelt"></a>
#### `u[i] := x: ModTupRngElt, RngIntElt, RngElt -> ModTupRngElt`

Given an element $u$ belonging to a submodule $M$ of the $R$-module $T = R^{(n)}$, a positive integer $i$, $1 \leq i\leq n$, and an element $x$ of the ring $R$, redefine the $i$-th component of $u$ to be $x$. The parent of $u$ is changed to $T$ (since the modified element $u$ need not lie in $M$).

### Normalization

<a id="function-normalize-modtuprngelt"></a>
#### `Normalize(u): ModTupRngElt -> ModTupRngElt`

<a id="function-normalise-modtuprngelt"></a>
#### `Normalise(u): ModTupRngElt -> ModTupRngElt`

The element $u$ must belong to an $R$-module, where $R$ is either a field, the ring of integers, or a univariate polynomial ring over a field. Assume that the vector $u$ is non-zero. If $R$ is a field then `Normalize` returns ${1\over a}*u$, where $a$ is the first non-zero component of $u$. If $R$ is the ring of integers, `Normalize` returns $\epsilon*u$, where $\epsilon$ is $+1$ if the first non-zero component of $u$ is positive, and $-1$ otherwise. If $R$ is the polynomial ring $K[x]$, $K$ a field, then `Normalize` returns ${1\over a}*u$, where $a$ is the leading coefficient of the first non-zero (polynomial) component of $u$. If $u$ is the zero vector, it is returned as the value of this function.

<a id="function-rotate-modtuprngelt-rngintelt"></a>
#### `Rotate(u, k): ModTupRngElt, RngIntElt -> ModTupRngElt`

Given a vector $u$, return the vector obtained from $u$ by rotating by $k$ coordinate positions.

<a id="procedure-rotate-modtuprngelt-rngintelt-ref"></a>
#### `Rotate(~u, k): ModTupRngElt, RngIntElt`

Given a vector $u$, destructively rotate $u$ by $k$ coordinate positions.

<a id="example-ex-8a5f2c"></a>
#### `Example: Arithmetic on Module Elements (ex-8a5f2c)`

We illustrate the use of the arithmetic operators for module elements by applying them to elements of the module of $4$-tuples over the polynomial ring ${\mathbb{Z}}[x]$.

```magma
> P<x> := PolynomialRing(IntegerRing());
> M := RModule(P, 4);
> a :=  M ! [ 1+x, -x, 2+x, 0 ];
> b := M ! [ 1+x+x^2, 0, 1-x^7, 2*x ];
> a + b;
(x^2 + 2*x + 2    -x    -x^7 + x + 3    2*x)
> -a;
(-x - 1      x -x - 2      0)
> a - b;
(       -x^2          -x x^7 + x + 1        -2*x)
> (1-x + x^2)*a;
(x^3 + 1    -x^3 + x^2 - x    x^3 + x^2 - x + 2    0)
> a*(1-x);
(    -x^2 + 1      x^2 - x -x^2 - x + 2            0)
> a[3];
x + 2
> a[3] := x - 2;
> a;
(x + 1    -x x - 2     0)
> ElementToSequence(a - b);
[
    -x^2,
    -x,
    x^7 + x - 3,
    -2*x
]
> Support(a);
{ 1, 2, 3 }
```

## Properties of Vectors

<a id="function-iszero-modtuprngelt"></a>
### `IsZero(u): ModTupRngElt -> BoolElt`

Returns `true` if the element $u$ of the $R$-module $M$ is the zero element.

<a id="function-depth-modtuprngelt"></a>
### `Depth(v): ModTupRngElt -> RngIntElt`

The index of the first non-zero entry of the vector $v$ (0 if none such).

<a id="function-support-modtuprngelt"></a>
### `Support(u): ModTupRngElt -> { RngElt }`

A set of integers giving the positions of the non-zero components of the vector $u$.

<a id="function-weight-modtuprngelt"></a>
### `Weight(u): ModTupRngElt -> RngIntElt`

The number of non-zero components of the vector $u$.

## Inner Products

<a id="literal-literal-u-v-modtuprngelt-modtuprngelt-rngelt"></a>
### `(u, v): ModTupRngElt, ModTupRngElt -> RngElt`

<a id="function-innerproduct-modtuprngelt-modtuprngelt"></a>
### `InnerProduct(u, v): ModTupRngElt, ModTupRngElt -> RngElt`

Return the inner product of the vectors $u$ and $v$ with respect to the inner product defined on the space. If an inner product matrix $F$ is given when the space is created, then this is defined to be $u\cdot F\cdot v^{tr}$. Otherwise, this is simply $u\cdot v^{tr}$.

<a id="function-norm-modtuprngelt"></a>
### `Norm(u): ModTupRngElt -> RngElt`

Return the norm product of the vector $u$ with respect to the inner product defined on the space. If an inner product matrix $F$ is given when the space is created, then this is defined to be $u\cdot F\cdot u^{tr}$. Otherwise, this is simply $u\cdot u^{tr}$.
