% This file was created automatically from magma.msk.
% DO NOT EDIT!
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%A  magma.msk                  GAP documentation                Thomas Breuer
%%
%A  @(#)$Id: magma.msk,v 1.10 2002/04/15 10:02:30 sal Exp $
%%
%Y  (C) 1998 School Math and Comp. Sci., University of St.  Andrews, Scotland
%Y  Copyright (C) 2002 The GAP Group
%%
\Chapter{Magmas}

This chapter deals with domains (see~"Domains and their Elements")
that are closed under multiplication `\*'.
Following~\cite{Bourbaki70}, we call them *magmas* in {\GAP}.
Together with the domains closed under addition `+', (see~"Additive Magmas"),
they are the basic algebraic structures;
every semigroup (see~"Semigroups"), monoid (see~"Monoids"),
group (see~"Groups"), ring (see~"Rings"),
or field (see~"Fields and Division Rings") is a magma.
In the cases of a *magma-with-one* or *magma-with-inverses*,
additional multiplicative structure is present, see~"Magma Categories".
For functions to create free magmas, see~"Free Magmas".


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Magma Categories}

\>IsMagma( <obj> ) C

A *magma* in {\GAP} is a domain $M$ with (not necessarily associative)
multiplication `\*'$: M \times M \rightarrow M$.


\>IsMagmaWithOne( <obj> ) C

A *magma-with-one* in {\GAP} is a magma $M$ with an operation `^0'
(or `One') that yields the identity of $M$.

So a magma-with-one <M> does always contain a unique multiplicatively
neutral element <e>, i.e., `<e> \* <m> = <m> = <m> \* <e>' holds for all 
`<m> $\in$ <M>'
(see~"MultiplicativeNeutralElement").
This element <e> can be computed with the operation `One' (see~"One")
as `One( <M> )', and <e> is also equal to `One( <elm> )' and to
`<elm>^0' for each element <elm> in <M>.

*Note* that a magma may contain a multiplicatively neutral element
but *not* an identity (see~"One"),
and a magma containing an identity may *not* lie in the category
`IsMagmaWithOne' (see~"Domain Categories").


\>IsMagmaWithInversesIfNonzero( <obj> ) C

An object in this {\GAP} category is a magma-with-one $M$
with an operation
`^-1'$: M\setminus Z \rightarrow M \setminus Z$
that maps each element <m> of $M\setminus Z$ to its inverse `<m>^-1'
(or `Inverse( <m> )', see~"Inverse"),
where $Z$ is either empty or consists exactly of one element of $M$.

This category was introduced mainly to describe division rings,
since the nonzero elements in a division ring form a group;
So an object $M$ in `IsMagmaWithInversesIfNonzero' will usually have both
a multiplicative and an additive structure (see~"Additive Magmas"),
and the set $Z$, if it is nonempty, contains exactly the zero element
(see~"Zero") of $M$.


\>IsMagmaWithInverses( <obj> ) C

A *magma-with-inverses* in {\GAP} is a magma-with-one $M$ with an
operation `^-1'$: M \rightarrow M$ that maps each element <m> of $M$ to
its inverse `<m>^-1' (or `Inverse( <m> )', see~"Inverse").

Note that not every trivial magma is a magma-with-one,
but every trivial magma-with-one is a magma-with-inverses.
This holds also if the identity of the magma-with-one is a zero element.
So a magma-with-inverses-if-nonzero can be a magma-with-inverses
if either it contains no zero element or consists of a zero element that
has itself as zero-th power.




%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Magma Generation}

\>Magma( <gens> ) F
\>Magma( <Fam>, <gens> ) F

returns the magma $M$ that is generated by the elements
in the list <gens>, that is,
the closure of <gens> under multiplication `\*'.
The family <Fam> of $M$ can be entered as first argument;
this is obligatory if <gens> is empty (and hence also $M$ is empty).


\>MagmaWithOne( <gens> ) F
\>MagmaWithOne( <Fam>, <gens> ) F

returns the magma-with-one $M$ that is generated by the elements
in the list <gens>, that is,
the closure of <gens> under multiplication `\*' and `One'.
The family <Fam> of $M$ can be entered as first argument;
this is obligatory if <gens> is empty (and hence $M$ is trivial).


\>MagmaWithInverses( <gens> ) F
\>MagmaWithInverses( <Fam>, <gens> ) F

returns the magma-with-inverses $M$ that is generated by the elements
in the list <gens>, that is,
the closure of <gens> under multiplication `\*', `One', and `Inverse'.
The family <Fam> of $M$ can be entered as first argument;
this is obligatory if <gens> is empty (and hence $M$ is trivial).



The underlying operations for which methods can be installed are the
following.

\>MagmaByGenerators( <gens> ) O
\>MagmaByGenerators( <Fam>, <gens> ) O


\>MagmaWithOneByGenerators( <gens> ) O
\>MagmaWithOneByGenerators( <Fam>, <generators> ) O


\>MagmaWithInversesByGenerators( <generators> ) O
\>MagmaWithInversesByGenerators( <Fam>, <generators> ) O



Substructures of a magma can be formed as follows.

\>Submagma( <D>, <gens> ) F
\>SubmagmaNC( <D>, <gens> ) F

`Submagma' returns the magma generated by
the elements in the list <gens>, with parent the domain <D>.
`SubmagmaNC' does the same, except that it is not checked
whether the elements of <gens> lie in <D>.


\>SubmagmaWithOne( <D>, <gens> ) F
\>SubmagmaWithOneNC( <D>, <gens> ) F

`SubmagmaWithOne' returns the magma-with-one generated by
the elements in the list <gens>, with parent the domain <D>.
`SubmagmaWithOneNC' does the same, except that it is not checked
whether the elements of <gens> lie in <D>.


\>SubmagmaWithInverses( <D>, <gens> ) F
\>SubmagmaWithInversesNC( <D>, <gens> ) F

`SubmagmaWithInverses' returns the magma-with-inverses generated by
the elements in the list <gens>, with parent the domain <D>.
`SubmagmaWithInversesNC' does the same, except that it is not checked
whether the elements of <gens> lie in <D>.



The following functions can be used to regard a collection as a magma.

\>AsMagma( <C> ) A

For a collection <C> whose elements form a magma,
`AsMagma' returns this magma.
Otherwise `fail' is returned.


\>AsSubmagma( <D>, <C> ) O

Let <D> be a domain and <C> a collection.
If <C> is a subset of <D> that forms a magma then `AsSubmagma' returns
this magma, with parent <D>.
Otherwise `fail' is returned.




The following function creates a new magma which is the original
magma with a zero adjoined.
\>InjectionZeroMagma( <M> ) A

The canonical homomorphism <i> from the  magma
<M> into the magma formed from <M> with a single new element 
which is a multiplicative zero for the resulting magma.

The elements of the new magma form a family of elements in the 
category IsMultiplicativeElementWithZero, and the
new magma is obtained as Range(<i>).




%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Magmas Defined by Multiplication Tables}

The most elementary (but of course usually not recommended) way to implement
a magma with only few elements is via a multiplication table.

\>MagmaByMultiplicationTable( <A> ) F

For a square matrix <A> with $n$ rows such that all entries of <A> are
in the range $[ 1 \.\. n ]$, `MagmaByMultiplicationTable' returns a magma
$M$ with multiplication `\*' defined by $A$.
That is, $M$ consists of the elements $m_1, m_2, \ldots, m_n$,
and $m_i \* m_j = m_{A[i][j]}$.

The ordering of elements is defined by $m_1 \< m_2 \< \cdots \< m_n$,
so $m_i$ can be accessed as `MagmaElement( <M>, <i> )',
see~"MagmaElement".


\>MagmaWithOneByMultiplicationTable( <A> ) F

The only differences between `MagmaByMultiplicationTable' and
`MagmaWithOneByMultiplicationTable' are that the latter returns a
magma-with-one (see~"MagmaWithOne") if the magma described by the matrix
<A> has an identity,
and returns `fail' if not.


\>MagmaWithInversesByMultiplicationTable( <A> ) F

`MagmaByMultiplicationTable' and `MagmaWithInversesByMultiplicationTable'
differ only in that the latter returns
magma-with-inverses (see~"MagmaWithInverses") if each element in the
magma described by the matrix <A> has an inverse,
and returns `fail' if not.


\>MagmaElement( <M>, <i> ) F

For a magma <M> and a positive integer <i>, `MagmaElement' returns the
<i>-th element of <M>, w.r.t.~the ordering `\<'.
If <M> has less than <i> elements then `fail' is returned.


\>MultiplicationTable( <elms> ) A
\>MultiplicationTable( <M> ) A

For a list <elms> of elements that form a magma $M$,
`MultiplicationTable' returns a square matrix $A$ of positive integers
such that $A[i][j] = k$ holds if and only if
`<elms>[i] \* <elms>[j] = <elms>[k]'.
This matrix can be used to construct a magma isomorphic to $M$,
using `MagmaByMultiplicationTable'.

For a magma <M>, `MultiplicationTable' returns the multiplication table
w.r.t.~the sorted list of elements of <M>.


\beginexample
gap> l:= [ (), (1,2)(3,4), (1,3)(2,4), (1,4)(2,3) ];;
gap> a:= MultiplicationTable( l );
[ [ 1, 2, 3, 4 ], [ 2, 1, 4, 3 ], [ 3, 4, 1, 2 ], [ 4, 3, 2, 1 ] ]
gap> m:= MagmaByMultiplicationTable( a );
<magma with 4 generators>
gap> One( m );
m1
gap> elm:= MagmaElement( m, 2 );  One( elm );  elm^2;
m2
m1
m1
gap> Inverse( elm );
m2
gap> AsGroup( m );
<group of size 4 with 2 generators>
gap> a:= [ [ 1, 2 ], [ 2, 2 ] ];
[ [ 1, 2 ], [ 2, 2 ] ]
gap> m:= MagmaByMultiplicationTable( a );
<magma with 2 generators>
gap> One( m );  Inverse( MagmaElement( m, 2 ) );
m1
fail
\endexample


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Attributes and Properties for Magmas}

\>GeneratorsOfMagma( <M> ) A

is a list <gens> of elements of the magma <M> that generates <M> as a
magma, that is, the closure of <gens> under multiplication is <M>.


\>GeneratorsOfMagmaWithOne( <M> ) A

is a list <gens> of elements of the magma-with-one <M> that generates <M>
as a magma-with-one,
that is, the closure of <gens> under multiplication and `One' (see~"One")
is <M>.


\>GeneratorsOfMagmaWithInverses( <M> ) A

is a list <gens> of elements of the magma-with-inverses <M>
that generates <M> as a magma-with-inverses,
that is, the closure of <gens> under multiplication and taking inverses
(see~"Inverse") is <M>.



\index{centraliser}\index{center}
\>Centralizer( <M>, <elm> ) O
\>Centralizer( <M>, <S> ) O
\>Centralizer( <class> ) O

For an element <elm> of the magma <M> this operation returns the 
*centralizer* of <elm>.
This is the domain of those elements `<m> $\in$ <M>' that commute 
with <elm>.

For a submagma <S> it returns the domain of those elements that commute
with *all* elements <s> of <S>.

If <class> is a class of objects of a magma (this magma then is stored
as the `ActingDomain' of <class>)
such as given by `ConjugacyClass' (see~"ConjugacyClass"),
`Centralizer' returns the centralizer of
`Representative(<class>)' (which is a slight abuse of the notation).


\beginexample
gap> g:=Group((1,2,3,4),(1,2));;
gap> Centralizer(g,(1,2,3));
Group([ (1,2,3) ])
gap> Centralizer(g,Subgroup(g,[(1,2,3)]));
Group([ (1,2,3) ])
gap> Centralizer(g,Subgroup(g,[(1,2,3),(1,2)]));
Group(())
\endexample


\>Centre( <M> ) A
\>Center( <M> ) A

`Centre' returns the *centre* of the magma <M>, i.e., the domain
of those elements `<m> $\in$ <M>' that commute and associate with all
elements of <M>. That is, the set $\{m\in M;\forall a,b\in M: ma=am,
(ma)b=m(ab), (am)b=a(mb), (ab)m=a(bm)\}$.

`Center' is just a synonym for `Centre'.

For associative magmas we have that 
`Centre( <M> ) = Centralizer( <M>, <M> )', see~"Centralizer".

The centre of a magma is always commutative (see~"IsCommutative").
(When one installs a new method for `Centre', one should set the
`IsCommutative' value of the result to `true',
in order to make this information available.)


\>Idempotents( <M> ) A

The set of elements of <M> which are their own squares.


\>IsAssociative( <M> ) P

A magma <M> is *associative* if for all elements `<a>, <b>, <c> $\in$ <M>'
the equality `(<a> \* <b>) \* <c> = <a> \* (<b> \* <c>)' holds.

An associative magma is called a *semigroup* (see~"Semigroups"),
an associative magma-with-one is called a *monoid* (see~"Monoids"),
and an associative magma-with-inverses is called a *group*
(see~"Groups").


\>IsCentral( <M>, <obj> ) O

`IsCentral' returns `true' if the object <obj>, which must either be an
element or a magma, commutes with all elements in the magma <M>.


\>IsCommutative( <M> ) P
\>IsAbelian( <M> ) P

A magma <M> is *commutative* if for all elements `<a>, <b> $\in$ <M>' the
equality `<a> \* <b> = <b> \* <a>' holds.
`IsAbelian' is a synonym of `IsCommutative'.

Note that the commutativity of the *addition* `+' in an additive
structure can be tested with `IsAdditivelyCommutative',
see~"IsAdditivelyCommutative".


\>MultiplicativeNeutralElement( <M> ) A

returns the element <e> in the magma <M> with the property that
`<e> \* <m> = <m> = <m> \* <e>' holds for all `<m> $\in$ <M>',
if such an element exists.
Otherwise `fail' is returned.

A magma that is not a magma-with-one can have a multiplicative neutral
element $e$; in this case, $e$ *cannot* be obtained as `One( <M> )',
see~"One".


\>MultiplicativeZero( <M> ) A

Returns the multiplicative zero of the magma which is the element
<z> such that for all <m> in <M>, `<z> \* <m> = <m> \* <z> = <z>'.



\>IsMultiplicativeZero( <M>, <z> ) O

returns true iff `<z> \* <m> = <m> \* <z> = <z>' for all <m> in <M>.


\>SquareRoots( <M>, <elm> ) O

is the proper set of all elements <r> in the magma <M>
such that `<r> \* <r> = <elm>' holds.


\>TrivialSubmagmaWithOne( <M> ) A

is the magma-with-one that has the identity of the magma-with-one <M>
as only element.



*Note* that `IsAssociative' and `IsCommutative' always refer to the
multiplication of a domain.
If a magma <M> has also an additive structure, e.g., if <M> is a ring
(see~"Rings"), then the addition `+' is always assumed to be associative and
commutative, see~"Arithmetic Operations for Elements".


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%E