<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<title>GAP (Circle) - Chapter 2: Implementing circle objects</title>
<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
<meta name="generator" content="GAPDoc2HTML" />
<link rel="stylesheet" type="text/css" href="manual.css" />
</head>
<body>
<div class="chlinktop"><span class="chlink1">Goto Chapter: </span><a href="chap0.html">Top</a> <a href="chap1.html">1</a> <a href="chap2.html">2</a> <a href="chap3.html">3</a> <a href="chap4.html">4</a> <a href="chapBib.html">Bib</a> <a href="chapInd.html">Ind</a> </div>
<div class="chlinkprevnexttop"> <a href="chap0.html">Top of Book</a> <a href="chap1.html">Previous Chapter</a> <a href="chap3.html">Next Chapter</a> </div>
<p><a id="X8404D6997A466953" name="X8404D6997A466953"></a></p>
<div class="ChapSects"><a href="chap2.html#X8404D6997A466953">2 <span class="Heading">Implementing circle objects</span></a>
<div class="ContSect"><span class="nocss"> </span><a href="chap2.html#X86492955868108EC">2.1 <span class="Heading">First attempts</span></a>
</div>
<div class="ContSect"><span class="nocss"> </span><a href="chap2.html#X852C1F3281137DD6">2.2 <span class="Heading">Defining circle objects</span></a>
</div>
<div class="ContSect"><span class="nocss"> </span><a href="chap2.html#X85B1413E7FBC8ACB">2.3 <span class="Heading">Installing operations for circle objects</span></a>
</div>
</div>
<h3>2 <span class="Heading">Implementing circle objects</span></h3>
<p>In this chapter we explain how the <strong class="pkg">GAP</strong> system may be extended with new objects using the circle multiplication as an example. We follow the guidelines given in the last two chapters of the <strong class="pkg">GAP</strong> Programming Tutorial and refer to them for more details.</p>
<p><a id="X86492955868108EC" name="X86492955868108EC"></a></p>
<h4>2.1 <span class="Heading">First attempts</span></h4>
<p>Of course, having two ring elements, you can straightforwardly compute their circle product defined as r * s = r + s + rs. You can do this in a command line, and it is a trivial task to write a simplest function of two arguments that will do this:</p>
<table class="example">
<tr><td><pre>
gap> CircleMultiplication := function(a,b)
> return a+b+a*b;
> end;
function( a, b ) ... end
gap> CircleMultiplication(2,3);
11
gap> CircleMultiplication( ZmodnZObj(2,8), ZmodnZObj(5,8) );
ZmodnZObj( 1, 8 )
</pre></td></tr></table>
<p>However, there is no check whether both arguments belong to the same ring and whether they are ring elements at all, so it is easy to obtain some meaningless results:</p>
<table class="example">
<tr><td><pre>
gap> CircleMultiplication( 3, ZmodnZObj(3,8) );
ZmodnZObj( 7, 8 )
gap> CircleMultiplication( [1], [2,3] );
[ 5, 5 ]
</pre></td></tr></table>
<p>You can include some tests for arguments, and maybe the best way of doing this would be declaring a new operation for two ring elements, and installing the previous function as a method for this operation. This will check automatically if the arguments are ring elements from the common ring:</p>
<table class="example">
<tr><td><pre>
gap> DeclareOperation( "BetterCircleMultiplication",
> [IsRingElement,IsRingElement] );
gap> InstallMethod( BetterCircleMultiplication,
> IsIdenticalObj,
> [IsRingElement,IsRingElement],
> CircleMultiplication );
gap> BetterCircleMultiplication(2,3);
11
gap> BetterCircleMultiplication( ZmodnZObj(2,8), ZmodnZObj(5,8) );
ZmodnZObj( 1, 8 )
</pre></td></tr></table>
<p>Nevertheless, the functionality gained from such operation would be rather limited. You will not be able to compute circle product via the infix operator <code class="code">*</code>, and, moreover, you will not be able to create higher level objects such as semigroups and groups with respect to the circle multiplication.</p>
<p>In order to "integrate" the circle multiplication into the <strong class="pkg">GAP</strong> library properly, instead of defining <em>new</em> operations for existing objects, we should define <em>new</em> objects for which the infix operator <code class="code">*</code> will perform the circle multiplication. This approach is explained in the next two sections.</p>
<p><a id="X852C1F3281137DD6" name="X852C1F3281137DD6"></a></p>
<h4>2.2 <span class="Heading">Defining circle objects</span></h4>
<p>Thus, we are going to implement <em>circle objects</em>, for which we can envisage the following functionality:</p>
<table class="example">
<tr><td><pre>
gap> CircleObject( 2 ) * CircleObject( 3 );
CircleObject( 11 )
</pre></td></tr></table>
<p>First we need to distinguish these new objects from other <strong class="pkg">GAP</strong> objects. This is done via the <em>type</em> of the objects, that is mainly determined by their <em>category</em>, <em>representation</em> and <em>family</em>.</p>
<p>We start with declaring the category <code class="code">IsCircleObject</code> as a subcategory of <code class="code">IsMultiplicativeElementWithInverse</code>. Thus, each circle object will "know" that it is <code class="code">IsMultiplicativeElementWithInverse</code>, and this will make it possible to apply to circle objects such operations as <code class="code">One</code> and <code class="code">Inverse</code> (the latter is allowed to return <code class="keyw">fail</code> for a given circle object).</p>
<table class="example">
<tr><td><pre>
gap> DeclareCategory( "IsCircleObject", IsMultiplicativeElementWithInverse );
</pre></td></tr></table>
<p>Further we would like to create semigroups and groups generated by circle objects. Such structures will be <em>collections</em> of circle objects, so they will be in the category <code class="code">CategoryCollections( IsCircleObject )</code>. This is why immediately after we declare the underlying category of circle objects, we need also to declare the category of their collections:</p>
<table class="example">
<tr><td><pre>
gap> DeclareCategoryCollections( "IsCircleObject" );
</pre></td></tr></table>
<p>On the next step we should think about the internal representation of circle objects. A natural way would be to store the underlying ring element in a list-like structure at its first position. We do not foresee any other data that we need to store internally in the circle object. This is quite common situation, so we may define first <code class="code">IsPositionalObjectOneSlotRep</code> that is the list-like representation with only one position in the list, and then declare a synonym <code class="code">IsDefaultCircleObject</code> that means that we are dealing with a circle object in one-slot representation:</p>
<table class="example">
<tr><td><pre>
gap> DeclareRepresentation( "IsPositionalObjectOneSlotRep",
> IsPositionalObjectRep, [ 1 ] );
gap> DeclareSynonym( "IsDefaultCircleObject",
> IsCircleObject and IsPositionalObjectOneSlotRep );
</pre></td></tr></table>
<p>Until now we are still unable to create circle objects, because we did not specify to which family they will belong. Naturally, having a ring, we want to have all circle objects for elements of this ring in the same family to be able to multiply them, and we expect circle objects for elements of different rings to be placed in different families. Thus, it would be nice to establish one-to-one correspondence between the family of ring elements and a family of circle elements for this ring. We can store the corresponding circle family as an attribute of the ring elements family. To do this first we declare an attribute <code class="code">CircleFamily</code> for families:</p>
<table class="example">
<tr><td><pre>
gap> DeclareAttribute( "CircleFamily", IsFamily );
</pre></td></tr></table>
<p>Now we install the method that stores the corresponding circle family in this attribute:</p>
<table class="example">
<tr><td><pre>
gap> InstallMethod( CircleFamily,
> "for a family",
> [ IsFamily ],
> function( Fam )
> local F;
> # create the family of circle elements
> F:= NewFamily( "CircleFamily(...)", IsCircleObject );
> if HasCharacteristic( Fam ) then
> SetCharacteristic( F, Characteristic( Fam ) );
> fi;
> # store the type of objects in the output
> F!.CircleType:= NewType( F, IsDefaultCircleObject );
> # Return the circle family
> return F;
> end );
</pre></td></tr></table>
<p>Similarly, we want one-to-one correspondence between circle elements and underlying ring elements. We declare an attribute <code class="code">CircleObject</code> for a ring element, and then install the method to create new circle object from the ring element. This method takes the family of the ring element, finds corresponding circle family, extracts from it the type of circle objects and finally creates the new circle object of that type:</p>
<table class="example">
<tr><td><pre>
gap> DeclareAttribute( "CircleObject", IsRingElement );
gap> InstallMethod( CircleObject,
> "for a ring element",
> [ IsRingElement ],
> obj -> Objectify( CircleFamily( FamilyObj( obj ) )!.CircleType,
> [ Immutable( obj ) ] ) );
</pre></td></tr></table>
<p>Only after entering all code above we are able to create some circle object. However, it is displayed just as <code class="code"><object></code>, though we can get the underlying ring element using the "!" operator:</p>
<table class="example">
<tr><td><pre>
gap> a:=CircleObject(2);
<object>
gap> a![1];
2
</pre></td></tr></table>
<p>We can check that the intended relation between families holds:</p>
<table class="example">
<tr><td><pre>
gap> FamilyObj( CircleObject ( 2 ) ) = CircleFamily( FamilyObj( 2 ) );
true
</pre></td></tr></table>
<p>We can not multiply circle objects yet. But before implementing this, first let us improve the output by installing the method for <code class="code">PrintObj</code>:</p>
<table class="example">
<tr><td><pre>
gap> InstallMethod( PrintObj,
> "for object in `IsCircleObject'",
> [ IsDefaultCircleObject ],
> function( obj )
> Print( "CircleObject( ", obj![1], " )" );
> end );
</pre></td></tr></table>
<p>This method will be used by <code class="code">Print</code> function, and also by <code class="code">View</code>, since we did not install special method for <code class="code">ViewObj</code> for circle objects. As a result of this installation, the output became more meaningful:</p>
<table class="example">
<tr><td><pre>
gap> a;
CircleObject( 2 )
</pre></td></tr></table>
<p>We need to avoid the usage of "!" operator, which, in general, is not recommended to the user (for example, if <strong class="pkg">GAP</strong> developers will change the internal representation of some object, all <strong class="pkg">GAP</strong> functions that deal with it must be adjusted appropriately, while if the user's code had direct access to that representation via "!", an error may occur). To do this, we wrap getting the first component of a circle object in the following operation:</p>
<table class="example">
<tr><td><pre>
gap> DeclareOperation("UnderlyingRingElement", [ IsCircleObject] );
gap> InstallMethod( UnderlyingRingElement,
> "for a circle object",
> [ IsCircleObject],
> obj -> obj![1] );
gap> UnderlyingRingElement(a);
2
</pre></td></tr></table>
<p><a id="X85B1413E7FBC8ACB" name="X85B1413E7FBC8ACB"></a></p>
<h4>2.3 <span class="Heading">Installing operations for circle objects</span></h4>
<p>Now we are finally able to install circle multiplication as a default method for the multiplication of circle objects, and perform the computation that we envisaged in the beginning:</p>
<table class="example">
<tr><td><pre>
gap> InstallMethod( \*,
> "for two objects in `IsCircleObject'",
> IsIdenticalObj,
> [ IsDefaultCircleObject, IsDefaultCircleObject ],
> function( a, b )
> return CircleObject( a![1] + b![1] + a![1]*b![1] );
> end );
gap> CircleObject(2)*CircleObject(3);
CircleObject( 11 )
</pre></td></tr></table>
<p>However, this functionality is not enough to form semigroups or groups generated by circle elements. We need to be able to check whether two circle objects are equal, and we need to define ordering for them (for example, to be able to form sets of circle elements). Since we already have both operations for underlying ring elements, this can be implemented in a straightforward way:</p>
<table class="example">
<tr><td><pre>
gap> InstallMethod( \=,
> "for two objects in `IsCircleObject'",
> IsIdenticalObj,
> [ IsDefaultCircleObject, IsDefaultCircleObject ],
> function( a, b )
> return a![1] = b![1];
> end );
gap> InstallMethod( \<,
> "for two objects in `IsCircleObject'",
> IsIdenticalObj,
> [ IsDefaultCircleObject, IsDefaultCircleObject ],
> function( a, b )
> return a![1] < b![1];
> end );
</pre></td></tr></table>
<p>Further, zero element of the ring plays a role of the neutral element for the circle multiplication, and we add this knowledge to our code in a form of a method for <code class="code">OneOp</code> that returns circle object for the corresponding zero object:</p>
<table class="example">
<tr><td><pre>
gap> InstallMethod( OneOp,
> "for an object in `IsCircleObject'",
> [ IsDefaultCircleObject ],
> a -> CircleObject( Zero( a![1] ) ) );
gap> One(a);
CircleObject( 0 )
</pre></td></tr></table>
<p>Now we are already able to create monoids generated by circle objects:</p>
<table class="example">
<tr><td><pre>
gap> S:=Monoid(a);
<monoid with 1 generator>
gap> One(S);
CircleObject( 0 )
gap> S:=Monoid( CircleObject( ZmodnZObj( 2,8) ) );
<monoid with 1 generator>
gap> Size(S);
2
gap> AsList(S);
[ CircleObject( ZmodnZObj( 0, 8 ) ), CircleObject( ZmodnZObj( 2, 8 ) ) ]
</pre></td></tr></table>
<p>Finally, to generate groups using circle objects, we need to add a method for the <code class="code">InverseOp</code>. In our implementation we will assume that the underlying ring is a subring of the ring with one, thus, if the circle inverse for an element x exists, than it can be computed as -x(1+x)^-1:</p>
<table class="example">
<tr><td><pre>
gap> InstallMethod( InverseOp,
> "for an object in `IsCircleObject'",
> [ IsDefaultCircleObject ],
> function( a )
> local x;
> x := Inverse( One( a![1] ) + a![1] );
> if x = fail then
> return fail;
> else
> return CircleObject( -a![1] * x );
> fi;
> end );
gap> CircleObject(-2)^-1;
CircleObject( -2 )
gap> CircleObject(2)^-1;
CircleObject( -2/3 )
</pre></td></tr></table>
<p>The last method already makes it possible to create groups generated by circle objects (the warning may be ignored):</p>
<table class="example">
<tr><td><pre>
gap> Group( CircleObject(2) );
#I default `IsGeneratorsOfMagmaWithInverses' method returns `true' for
[ CircleObject( 2 ) ]
<group with 1 generators>
gap> G:=Group( [CircleObject( ZmodnZObj( 2,8 ) ) ]);
#I default `IsGeneratorsOfMagmaWithInverses' method returns `true' for
[ CircleObject( ZmodnZObj( 2, 8 ) ) ]
<group with 1 generators>
gap> Size(G);
2
gap> AsList(G);
[ CircleObject( ZmodnZObj( 0, 8 ) ), CircleObject( ZmodnZObj( 2, 8 ) ) ]
</pre></td></tr></table>
<p>The <strong class="pkg">GAP</strong> code used in this Chapter, is contained in the files <code class="file">circle/lib/circle.gd</code> and <code class="file">circle/lib/circle.gi</code>. We also refer to last two chapters of the <strong class="pkg">GAP</strong> Programming Tutorial for another examples of implementing new <strong class="pkg">GAP</strong> objects and further details.</p>
<div class="chlinkprevnextbot"> <a href="chap0.html">Top of Book</a> <a href="chap1.html">Previous Chapter</a> <a href="chap3.html">Next Chapter</a> </div>
<div class="chlinkbot"><span class="chlink1">Goto Chapter: </span><a href="chap0.html">Top</a> <a href="chap1.html">1</a> <a href="chap2.html">2</a> <a href="chap3.html">3</a> <a href="chap4.html">4</a> <a href="chapBib.html">Bib</a> <a href="chapInd.html">Ind</a> </div>
<hr />
<p class="foot">generated by <a href="http://www.math.rwth-aachen.de/~Frank.Luebeck/GAPDoc">GAPDoc2HTML</a></p>
</body>
</html>
