<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<!-- %% -->
<!-- %W  arith.tex                 GAP manual                    Thomas Breuer -->
<!-- %% -->
<!-- %% -->

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Chapter Label="An Example -- Designing Arithmetic Operations">
<Heading>An Example &ndash; Designing Arithmetic Operations</Heading>

In this chapter, we give a &ndash;hopefully typical&ndash;
example of extending &GAP; by new objects with prescribed
arithmetic operations (for a simple approach that may be useful
to get started though does not permit to exploit all potential
features, see also <Ref Func="ArithmeticElementCreator"/>).

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="New Arithmetic Operations vs. New Objects">
<Heading>New Arithmetic Operations vs. New Objects</Heading>

A usual procedure in mathematics is the definition of new operations for
given objects;
here are a few typical examples.
The Lie bracket defines an interesting new multiplicative
structure on a given (associative) algebra.
Forming a group ring can be viewed as defining a new addition for the
elements of the given group, and extending the multiplication to sums
of group elements in a natural way.
Forming the exterior algebra of a given vector space can be viewed as
defining a new multiplication for the vectors in a natural way.
<P/>
&GAP; does <E>not</E> support such a procedure.
The main reason for this is that in &GAP;, the multiplication in a group,
a ring etc.&nbsp;is always written as <C>*</C>,
and the addition in a vector space, a ring etc.&nbsp; is always written as <C>+</C>.
Therefore it is not possible to define the Lie bracket as a
<Q>second multiplication</Q> for the elements of a given algebra;
in fact, the multiplication in Lie algebras in &GAP; is denoted by <C>*</C>.
Analogously, constructing the group ring as sketched above is impossible
if an addition is already defined for the elements;
note the difference between the usual addition of matrices and the
addition in the group ring of a matrix group!
(See Chapter&nbsp;<Ref Chap="Magma Rings"/> for an example.)
Similarly, there is already a multiplication defined for row vectors
(yielding the standard scalar product), hence these vectors cannot be
regarded as elements of the exterior algebra of the space.
<P/>
In situations such as the ones mentioned above,
&GAP;'s way to deal with the structures in question is the following.
Instead of defining <E>new</E> operations for the <E>given</E> objects,
<E>new</E> objects are created to which the <E>given</E> arithmetic operations
<C>*</C> and <C>+</C> are then made applicable.
<P/>
With this construction, matrix Lie algebras consist of matrices that are
different from the matrices with associative multiplication;
technically, the type of a matrix determines how it is multiplied with
other matrices (see&nbsp;<Ref Filt="IsMatrix"/>).
A matrix with the Lie bracket as its multiplication can be created with
the function <Ref Attr="LieObject"/>
from a matrix with the usual associative multiplication.
<P/>
Group rings (more general: magma rings,
see Chapter&nbsp;<Ref Chap="Magma Rings"/>)
can be constructed with <Ref Func="FreeMagmaRing"/>
from a coefficient ring and a group.
The elements of the group are not contained in such a group ring,
one has to use an embedding map for creating a group ring element that
corresponds to a given group element.
<P/>
It should be noted that the &GAP; approach to the construction of
Lie algebras from associative algebras is generic in the sense
that all objects in the filter <Ref Filt="IsLieObject"/> use the
same methods for their addition, multiplication etc.,
by delegating to the <Q>underlying</Q> objects of the associative algebra,
no matter what these objects actually are.
Analogously, also the construction of group rings is generic.

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Designing new Multiplicative Objects">
<Heading>Designing new Multiplicative Objects</Heading>

The goal of this section is to implement objects with a prescribed
multiplication.
Let us assume that we are given a field <M>F</M>,
and that we want to define a new multiplication <M>*</M> on <M>F</M>
that is given by <M>a * b = a b - a - b + 2</M>;
here <M>a b</M> denotes the ordinary product in <M>F</M>.
<P/>
By the discussion in Section&nbsp;<Ref Sect="New Arithmetic Operations vs. New Objects"/>,
we know that we cannot define a new multiplication on <M>F</M> itself
but have to create new objects.
<P/>
We want to distinguish these new objects from all other &GAP; objects,
in order to describe for example the situation that two of our objects
shall be multiplied.
This distinction is made via the <E>type</E> of the objects.
More precisely, we declare a new <E>filter</E>, a function that will return
<K>true</K> for our new objects, and <K>false</K> for all other &GAP; objects.
This can be done by calling <Ref Func="DeclareFilter"/>,
but since our objects will know about the value already when they are
constructed, the filter can be created with
<Ref Func="DeclareCategory"/> or <Ref Func="NewCategory"/>.
<P/>
<Log><![CDATA[
DeclareCategory( "IsMyObject", IsObject );
]]></Log>
<P/>
The idea is that the new multiplication will be installed only
for objects that <Q>lie in the category <C>IsMyObject</C></Q>.
<P/>
The next question is what internal data our new objects store,
and how they are accessed.
The easiest solution is to store the <Q>underlying</Q> object from the
field <M>F</M>.
&GAP; provides two general possibilities how to store this,
namely record-like and list-like structures
(for examples, see&nbsp;<Ref Sect="Component Objects"/> and&nbsp;<Ref Sect="Positional Objects"/>).
We decide to store the data in a list-like structure, at position 1.
This <E>representation</E> is declared as follows.
<P/>
<Log><![CDATA[
DeclareRepresentation( "IsMyObjectListRep", IsPositionalObjectRep, [ 1 ] );
]]></Log>
<P/>
Of course we can argue that this declaration is superfluous
because <E>all</E> objects in the category <C>IsMyObject</C> will be represented
this way;
it is possible to proceed like that,
but often (in more complicated situations) it turns out to be useful
that several representations are available for <Q>the same element</Q>.
<P/>
For creating the type of our objects, we need to specify to which <E>family</E>
(see&nbsp;<Ref Sect="Families"/>) the objects shall belong.
For the moment, we need not say anything about relations to other &GAP;
objects,
thus the only requirement is that all new objects lie in the <E>same</E> family;
therefore we create a <E>new</E> family.
Also we are not interested in properties that some of our objects have
and others do not have,
thus we need only one type,
and store it in a global variable.
<P/>
<Log><![CDATA[
MyType:= NewType( NewFamily( "MyFamily" ),
                  IsMyObject and IsMyObjectListRep );
]]></Log>
<P/>
The next step is to write a function that creates a new object.
It may look as follows.
<Log><![CDATA[
MyObject:= val -> Objectify( MyType, [ Immutable( val ) ] );
]]></Log>
Note that we store an <E>immutable copy</E> of the argument in the returned
object;
without doing so, for example if the argument would be a mutable matrix
then the corresponding new object would be changed whenever the matrix
is changed
(see&nbsp;<Ref Sect="Mutability and Copyability"/> for more
details about mutability).
<P/>
Having entered the above &GAP; code, we can create some of our objects.
<Log><![CDATA[
gap> a:= MyObject( 3 );  b:= MyObject( 5 );
<object>
<object>
gap> a![1];  b![1];
3
5
]]></Log>
But clearly a lot is missing.
Besides the fact that the desired multiplication is not yet installed,
we see that also the way how the objects are printed is not satisfactory.
<P/>
Let us improve the latter first.
There are two &GAP; functions <Ref Func="View"/> and
<Ref Func="Print"/> for showing objects
on the screen.
<Ref Func="View"/> is thought to show a short and human
readable form of the object,
and <Ref Func="Print"/> is thought to show a not necessarily
short form that is &GAP; readable whenever this makes sense.
We decide to show <C>a</C> as <C><A>3</A></C> by
<Ref Func="View"/>, and to show the construction
<C>MyObject( 3 )</C> by <Ref Func="Print"/>;
the methods are installed for the underlying operations
<Ref Oper="ViewObj"/> and
<Ref Oper="PrintObj"/>.
<Log><![CDATA[
InstallMethod( ViewObj,
    "for object in `IsMyObject'",
    [ IsMyObject and IsMyObjectListRep ],
    function( obj )
    Print( "<", obj![1], ">" );
    end );

InstallMethod( PrintObj,
    "for object in `IsMyObject'",
    [ IsMyObject and IsMyObjectListRep ],
    function( obj )
    Print( "MyObject( ", obj![1], " )" );
    end );
]]></Log>
<P/>
This is the result of the above installations.
<Log><![CDATA[
gap> a; Print( a, "\n" );
<3>
MyObject( 3 )
]]></Log>
<P/>
And now we try to install the multiplication.
<P/>
<Log><![CDATA[
InstallMethod( \*,
    "for two objects in `IsMyObject'",
    [ IsMyObject and IsMyObjectListRep,
      IsMyObject and IsMyObjectListRep ],
    function( a, b )
    return MyObject( a![1] * b![1] - a![1] - b![1] + 2 );
    end );
]]></Log>
<P/>
When we enter the above code, &GAP; runs into an error.
This is due to the fact that the operation <Ref Oper="\*"/>
is declared for two arguments that lie in the category
<Ref Filt="IsMultiplicativeElement"/>.
One could circumvent the check whether the method matches the
declaration of the operation, by calling <Ref Func="InstallOtherMethod"/>
instead of <Ref Func="InstallMethod"/>.
But it would make sense if our objects would lie in
<Ref Filt="IsMultiplicativeElement"/>,
for example because some generic methods
for objects with multiplication would be available then,
such as powering by positive integers via repeated squaring.
So we want that <C>IsMyObject</C> implies
<Ref Filt="IsMultiplicativeElement"/>.
The easiest way to achieve such implications is to use the
implied filter as second argument of the <Ref Func="DeclareCategory"/> call;
but since we do not want to start anew,
we can also install the implication afterwards.
<P/>
<Log><![CDATA[
InstallTrueMethod( IsMultiplicativeElement, IsMyObject );
]]></Log>
<P/>
Afterwards, installing the multiplication works without problems.
Note that <C>MyType</C> and therefore also <C>a</C> and <C>b</C> are <E>not</E>
affected by this implication, so we construct them anew.
<P/>
<Log><![CDATA[
gap> MyType:= NewType( NewFamily( "MyFamily" ),
>                      IsMyObject and IsMyObjectListRep );;
gap> a:= MyObject( 3 );;  b:= MyObject( 5 );;
gap> a*b;  a^27;
<9>
<134217729>
]]></Log>
<P/>
Powering the new objects by negative integers is not possible yet,
because &GAP; does not know how to compute the inverse of an element <M>a</M>,
say, which is defined as the unique element <M>a'</M> such that both
<M>a a'</M> and <M>a' a</M> are <Q>the unique multiplicative neutral
element that belongs to <M>a</M></Q>.
<P/>
And also this neutral element, if it exists,
cannot be computed by &GAP; in our current situation.
It does, however, make sense to ask for the multiplicative neutral
element of a given magma, and for inverses of elements in the magma.
<P/>
But before we can form domains of our objects,
we must define when two objects are regarded as equal;
note that this is necessary in order to decide about the uniqueness
of neutral and inverse elements.
In our situation, equality is defined in the obvious way.
For being able to form sets of our objects,
also an ordering via <Ref Oper="\&lt;"/> is defined for them.
<P/>
<Log><![CDATA[
InstallMethod( \=,
    "for two objects in `IsMyObject'",
    [ IsMyObject and IsMyObjectListRep,
      IsMyObject and IsMyObjectListRep ],
    function( a, b )
    return a![1] = b![1];
    end );

InstallMethod( \<,
    "for two objects in `IsMyObject'",
    [ IsMyObject and IsMyObjectListRep,
      IsMyObject and IsMyObjectListRep ],
    function( a, b )
    return a![1] < b![1];
    end );
]]></Log>
<P/>
Let us look at an example.
We start with finite field elements because then the domains are finite,
hence the generic methods for such domains will have a chance to succeed.
<P/>
<Log><![CDATA[
gap> a:= MyObject( Z(7) );
<Z(7)>
gap> m:= Magma( a );
<magma with 1 generator>
gap> e:= MultiplicativeNeutralElement( m );
<Z(7)^2>
gap> elms:= AsList( m );
[ <Z(7)>, <Z(7)^2>, <Z(7)^5> ]
gap> ForAll( elms, x -> ForAny( elms, y -> x*y = e and y*x = e ) );
true
gap> List( elms, x -> First( elms, y -> x*y = e and y*x = e ) );
[ <Z(7)^5>, <Z(7)^2>, <Z(7)> ]
]]></Log>
<P/>
So a multiplicative neutral element exists,
in fact all elements in the magma <C>m</C> are invertible.
But what about the following.
<P/>
<Log><![CDATA[
gap> b:= MyObject( Z(7)^0 );  m:= Magma( a, b );
<Z(7)^0>
<magma with 2 generators>
gap> elms:= AsList( m );
[ <Z(7)^0>, <Z(7)>, <Z(7)^2>, <Z(7)^5> ]
gap> e:= MultiplicativeNeutralElement( m );
<Z(7)^2>
gap> ForAll( elms, x -> ForAny( elms, y -> x*y = e and y*x = e ) );
false
gap> List( elms, x -> b * x );
[ <Z(7)^0>, <Z(7)^0>, <Z(7)^0>, <Z(7)^0> ]
]]></Log>
<P/>
Here we found a multiplicative neutral element,
but the element <C>b</C> does not have an inverse.
If an addition would be defined for our elements then we would say
that <C>b</C> behaves like a zero element.
<P/>
When we started to implement the new objects,
we said that we wanted to define the new multiplication for elements
of a given field <M>F</M>.
In principle, the current implementation would admit also something
like <C>MyObject( 2 ) * MyObject( Z(7) )</C>.
But if we decide that our initial assumption holds,
we may define the identity and the inverse of the object <C>&lt;a></C> as
<C>&lt;2*e></C> and <C>&lt;a/(a-e)></C>, respectively,
where <C>e</C> is the identity element in <M>F</M> and <C>/</C> denotes the division
in <M>F</M>;
note that the element <C>&lt;e></C> is not invertible,
and that the above definitions are determined by the multiplication
defined for our objects.
Further note that after the installations shown below,
also <C>One( MyObject( 1 ) )</C> is defined.
<P/>
(For technical reasons, we do not install the intended methods for
the attributes <Ref Attr="One"/> and
<Ref Attr="Inverse"/> but for the operations
<Ref Oper="OneOp"/>
and <Ref Oper="InverseOp"/>.
This is because for certain kinds of objects &ndash;mainly matrices&ndash;
one wants to support a method to compute a <E>mutable</E> identity or
inverse, and the attribute needs only a method that takes this
object, makes it immutable, and then returns this object.
As stated above, we only want to deal with immutable objects,
so this distinction is not really interesting for us.)
<P/>
A more interesting point to note is that we should mark our objects
as likely to be invertible,
since we add the possibility to invert them.
Again, this could have been part of the declaration of <C>IsMyObject</C>,
but we may also formulate an implication for the existing category.
<P/>
<Log><![CDATA[
InstallTrueMethod( IsMultiplicativeElementWithInverse, IsMyObject );

InstallMethod( OneOp,
    "for an object in `IsMyObject'",
    [ IsMyObject and IsMyObjectListRep ],
    a -> MyObject( 2 * One( a![1] ) ) );

InstallMethod( InverseOp,
    "for an object in `IsMyObject'",
    [ IsMyObject and IsMyObjectListRep ],
    a -> MyObject( a![1] / ( a![1] - One( a![1] ) ) ) );
]]></Log>
Now we can form groups of our (nonzero) elements.
<Log><![CDATA[
gap> MyType:= NewType( NewFamily( "MyFamily" ),
>                   IsMyObject and IsMyObjectListRep );;
gap>
gap> a:= MyObject( Z(7) );
<Z(7)>
gap> b:= MyObject( 0*Z(7) );  g:= Group( a, b );
<0*Z(7)>
<group with 2 generators>
gap> Size( g );
6
]]></Log>
<P/>
We are completely free to define an <E>addition</E> for our elements,
a natural one is given by <C>&lt;a> + &lt;b> = &lt;a+b-1></C>.
As we did for the multiplication, we first change <C>IsMyObject</C>
such that the additive structure is also known.
<Log><![CDATA[
InstallTrueMethod( IsAdditiveElementWithInverse, IsMyObject );
]]></Log>
Next we install the methods for the addition,
and those to compute the additive neutral element
and the additive inverse.
<P/>
<Log><![CDATA[
InstallMethod( \+,
    "for two objects in `IsMyObject'",
    [ IsMyObject and IsMyObjectListRep,
      IsMyObject and IsMyObjectListRep ],
    function( a, b )
    return MyObject( a![1] + b![1] - 1 );
    end );

InstallMethod( ZeroOp,
    "for an object in `IsMyObject'",
    [ IsMyObject and IsMyObjectListRep ],
    a -> MyObject( One( a![1] ) ) );

InstallMethod( AdditiveInverseOp,
    "for an object in `IsMyObject'",
    [ IsMyObject and IsMyObjectListRep ],
    a -> MyObject( a![1] / ( a![1] - One( a![1] ) ) ) );
]]></Log>
<P/>
Let us try whether the addition works.
<P/>
<Log><![CDATA[
gap> MyType:= NewType( NewFamily( "MyFamily" ),
>                   IsMyObject and IsMyObjectListRep );;
gap> a:= MyObject( Z(7) );;  b:= MyObject( 0*Z(7) );;
gap> m:= AdditiveMagma( a, b );
<additive magma with 2 generators>
gap> Size( m );
7
]]></Log>
<P/>
Similar as installing a multiplication automatically makes
powering by integers available,
multiplication with integers becomes available with the addition.
<P/>
<Log><![CDATA[
gap> 2 * a;
<Z(7)^5>
gap> a+a;
<Z(7)^5>
gap> MyObject( 2*Z(7)^0 ) * a;
<Z(7)>
]]></Log>
<P/>
In particular we see that this multiplication does <E>not</E> coincide
with the multiplication of two of our objects,
that is, an integer <E>cannot</E> be used as a shorthand for one of the
new objects in a multiplication.
<P/>
(It should be possible to create a <E>field</E> with the new multiplication
and addition.
Currently this fails, due to missing methods for computing
several kinds of generators from field generators,
for computing the characteristic in the case that the family does not
know this in advance,
for checking with <Ref Oper="AsField"/> whether a domain
is in fact a field, for computing the closure as a field.)
<P/>
It should be emphasized that the mechanism described above may be not
suitable for the situation that one wants to consider many different
multiplications <Q>on the same set of objects</Q>,
since the installation of a new multiplication requires the declaration
of at least one new filter and the installation of several methods.
But the design of &GAP; is not suitable for such dynamic method
installations.
<P/>
Turning this argument the other way round,
the implementation of the new arithmetics defined by the above
multiplication and addition is available for any field <M>F</M>,
one need not repeat it for each field one is interested in.
<P/>
Similar to the above situation,
the construction of a magma ring <M>RM</M> from a coefficient ring <M>R</M>
and a magma <M>M</M> is implemented only once,
since the definition of the arithmetic operations depends only on the
given multiplication of <M>M</M> and not on <M>M</M> itself.
So the addition is not implemented for the elements in <M>M</M> or
&ndash;more precisely&ndash; for an isomorphic copy.
In some sense, the addition is installed <Q>for the multiplication</Q>,
and as mentioned in Section&nbsp;<Ref Sect="New Arithmetic Operations vs. New Objects"/>,
there is only one multiplication <Ref Oper="\*"/> in &GAP;.

</Section>
</Chapter>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<!-- %% -->
<!-- %E -->