# Construction of Elements

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

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

## `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$.

## `Zero(M): ModRng -> ModRngElt`

## `M ! 0: ModRng, RngIntElt -> ModRngElt`

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

## `Random(M): ModRng -> ModRngElt`

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

## `Example: Elements (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

### `ElementToSequence(u): ModTupRngElt -> [RngElt]`

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

#### `u + v: ModTupRngElt, ModTupRngElt -> ModTupRngElt`

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

#### `- u: ModTupRngElt -> ModTupRngElt`

Additive inverse of the element $u$.

#### `u - v: ModTupRngElt, ModTupRngElt -> ModTupRngElt`

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

#### `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$.

#### `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$.

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

#### `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$).

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

#### `Normalize(u): ModTupRngElt -> ModTupRngElt`

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

#### `Rotate(u, k): ModTupRngElt, RngIntElt -> ModTupRngElt`

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

#### `Rotate(~u, k): ModTupRngElt, RngIntElt`

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

#### `Example: Operations (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

### `IsZero(u): ModTupRngElt -> BoolElt`

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

### `Depth(v): ModTupRngElt -> RngIntElt`

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

### `Support(u): ModTupRngElt -> { RngElt }`

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

### `Weight(u): ModTupRngElt -> RngIntElt`

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

## Inner Products

### `(u, v): ModTupRngElt, ModTupRngElt -> RngElt`

### `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}$.

### `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}$.