# 20.3 Free abelian monoids

Module: `sage.monoids.free_abelian_monoid`

Free abelian monoids

Author: David Kohel (2005-09)

SAGE supports free abelian monoids on any prescribed finite number of generators. Use the `FreeAbelianMonoid` function to create a free abelian monoid, and the `gen` and `gens` functions to obtain the corresponding generators. You can print the generators as arbitrary strings using the optional `names` argument to the `FreeAbelianMonoid` function.

EXAMPLE 1: It is possible to create an abelian monoid in zero or more variables; the syntax T(1) creates the monoid indentity element even in the rank zero case.

```sage: T = FreeAbelianMonoid(0, '')
sage: T
Free abelian monoid on 0 generators ()
sage: T.gens()
()
sage: T(1)
1
```

EXAMPLE 2: A free abelian monoid uses a multiplicative representation of elements, but the underlying representation is lists of integer exponents.

```sage: F = FreeAbelianMonoid(5,names='a,b,c,d,e')
sage: (a,b,c,d,e) = F.gens()
sage: a*b^2*e*d
a*b^2*d*e
sage: x = b^2*e*d*a^7
sage: x
a^7*b^2*d*e
sage: x.list()
[7, 2, 0, 1, 1]
```

Module-level Functions

 FreeAbelianMonoid( n, names)
Create the free abelian monoid in generators.

```INPUT:
n -- integer
names -- names of generators

OUTPUT:
free abelian monoid
```

```sage: FreeAbelianMonoid(0, '')
Free abelian monoid on 0 generators ()
sage: F = FreeAbelianMonoid(5,names = list("abcde"))
sage: F
Free abelian monoid on 5 generators (a, b, c, d, e)
sage: F(1)
1
sage: (a, b, c, d, e) = F.gens()
sage: mul([ a, b, a, c, b, d, c, d ], F(1))
a^2*b^2*c^2*d^2
sage: a**2 * b**3 * a**2 * b**4
a^4*b^7
```

 is_FreeAbelianMonoid( x)
Return True if is a free abelian monoid.

```sage: is_FreeAbelianMonoid(5)
False
sage: is_FreeAbelianMonoid(FreeAbelianMonoid(7,'a'))
True
sage: is_FreeAbelianMonoid(FreeMonoid(7,'a'))
False
sage: is_FreeAbelianMonoid(FreeMonoid(0,''))
False
```

Class: `FreeAbelianMonoid_class`

class FreeAbelianMonoid_class
Free abelian monoid on generators.
 FreeAbelianMonoid_class( self, n, names)

Functions: gen, ngens

 gen( self, [i=0])
The -th generator of the abelian monoid.

```sage: F = FreeAbelianMonoid(5,'a')
sage: F.gen(0)
a0
sage: F.gen(2)
a2
```

 ngens( self)
The number of free generators of the abelian monoid.

```sage: F = FreeAbelianMonoid(3000, 'a')
sage: F.ngens()
3000
```

Special Functions: __call__, __contains__, __repr__

 __call__( self, x)
Create an element of this abelian monoid from .

```sage: F = FreeAbelianMonoid(10,'x')
sage: F(F.gen(2))
x2
sage: F(1)
1
```

 __contains__( self, x)
Return True if is an element of this abelian monoid.

```sage: F = FreeAbelianMonoid(10,'b')
sage: F.gen(2)*F.gen(3) in F
True
```

Note that a monoid on generators is not considered a submonoid of one on generators.

```sage: FreeAbelianMonoid(9,'c').gen(2) in F
False
```

However, multiple calls to the monoid constructor do *not* return multiple distinct monoids.

```sage: FreeAbelianMonoid(10,'b').gen(2) in F
True
```