<?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 (orb) - Chapter 8: Orbit enumeration by suborbits</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="chap5.html">5</a> <a href="chap6.html">6</a> <a href="chap7.html">7</a> <a href="chap8.html">8</a> <a href="chap9.html">9</a> <a href="chap10.html">10</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="chap7.html">Previous Chapter</a> <a href="chap9.html">Next Chapter</a> </div>
<p><a id="X7CC7EC257DD466E3" name="X7CC7EC257DD466E3"></a></p>
<div class="ChapSects"><a href="chap8.html#X7CC7EC257DD466E3">8 <span class="Heading">Orbit enumeration by suborbits</span></a>
<div class="ContSect"><span class="nocss"> </span><a href="chap8.html#X819508B17A733D53">8.1 <span class="Heading"><code class="code">OrbitBySuborbits</code> and its resulting objects</span></a>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap8.html#X79B161FD84AB8C68">8.1-1 OrbitBySuborbit</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap8.html#X86CCD9B98156155E">8.1-2 OrbitBySuborbitKnownSize</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap8.html#X83C66D4A8603CA56">8.1-3 Size</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap8.html#X7EBEA64D7A5F78E3">8.1-4 Seed</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap8.html#X80B78B657E77A485">8.1-5 SuborbitsDb</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap8.html#X7B5E783478A337C9">8.1-6 WordsToSuborbits</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap8.html#X7926C96485985614">8.1-7 Memory</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap8.html#X840AFA7987535AC5">8.1-8 Stabilizer</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap8.html#X7F496D9B7C44DAAB">8.1-9 StabWords</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap8.html#X802068267DACF3F6">8.1-10 SavingFactor</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap8.html#X79DB081F827B53CB">8.1-11 TotalLength</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap8.html#X81ABF8407AF16C34">8.1-12 Representatives</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap8.html#X79552A1086449062">8.1-13 SavingFactor</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap8.html#X7A96D6D37F0EC46A">8.1-14 OrigSeed</a></span>
</div>
<div class="ContSect"><span class="nocss"> </span><a href="chap8.html#X7C0335D97C990559">8.2 <span class="Heading">Preparation functions for <code class="func">OrbitBySuborbit</code> (<a href="chap8.html#X79B161FD84AB8C68"><b>8.1-1</b></a>)</span></a>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap8.html#X830E221D84E44A64">8.2-1 OrbitBySuborbitBootstrapForVectors</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap8.html#X799056597EA62513">8.2-2 OrbitBySuborbitBootstrapForLines</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap8.html#X7919B1AB7D68780D">8.2-3 OrbitBySuborbitBootstrapForSpaces</a></span>
</div>
<div class="ContSect"><span class="nocss"> </span><a href="chap8.html#X80F036B378A3FD32">8.3 <span class="Heading">Data structures for orbit-by-suborbits</span></a>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap8.html#X7CFD48C17B48CDDD">8.3-1 IsOrbitBySuborbitSetup</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap8.html#X855663F5790EA2D0">8.3-2 <span class="Heading">The global record <code class="code">ORB</code></span></a>
</span>
</div>
<div class="ContSect"><span class="nocss"> </span><a href="chap8.html#X8696CFD08768508D">8.4 <span class="Heading">Lists of orbit-by-suborbit objects</span></a>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap8.html#X7FB77D827E31AE24">8.4-1 InitOrbitBySuborbitList</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap8.html#X87CB441882F43F62">8.4-2 IsVectorInOrbitBySuborbitList</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap8.html#X7D82CE2579A50B2C">8.4-3 OrbitsFromSeedsToOrbitList</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap8.html#X83A306918461D700">8.4-4 VerifyDisjointness</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap8.html#X7ED405017E3A56CD">8.4-5 Memory</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap8.html#X7D52885787865E81">8.4-6 TotalLength</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap8.html#X7C4255287D394742">8.4-7 Size</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap8.html#X7BFE12DE85CCE143">8.4-8 SavingFactor</a></span>
</div>
</div>
<h3>8 <span class="Heading">Orbit enumeration by suborbits</span></h3>
<p>The code described in this chapter is quite complicated and one has to understand quite a lot of theory to use it. The reason for this is that a lot of preparatory data has to be found and supplied by the user in order for this code to run at all. Also the situations in which it can be used are quite special. However, in such a situation, the user is rewarded with impressive performance.</p>
<p>The main reference for the theory is <a href="chapBib.html#biBMNW">[MNW07]</a>. We briefly recall the basic setup: Let G be a group acting from the right on some set X. Let k be a natural number, set X_{k+1} := X, and let</p>
<p class="pcenter"> U_1 < U_2 < \cdots < U_k < U_{{k+1}} = G </p>
<p>be a chain of "helper" subgroups. Further, for 1 le i le k let X_i be a U_i set and let pi_i : X_{i+1} -> X_i be a homomorphism of U_i-sets.</p>
<p>This chapter starts with a section about the main orbit enumeration function and the corresponding preparation functions. It then proceeds with a section on the used data structures, which will necessarily be rather technical. Finally, the chapter concludes with a section on higher level data structures like lists of orbit-by-suborbit objects and their administration. Note that there are quite a few examples in Chapter <a href="chap10.html#X7A489A5D79DA9E5C"><b>10</b></a>.</p>
<p><a id="X819508B17A733D53" name="X819508B17A733D53"></a></p>
<h4>8.1 <span class="Heading"><code class="code">OrbitBySuborbits</code> and its resulting objects</span></h4>
<p><a id="X79B161FD84AB8C68" name="X79B161FD84AB8C68"></a></p>
<h5>8.1-1 OrbitBySuborbit</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">> OrbitBySuborbit</code>( <var class="Arg">setup, p, j, l, i, percentage</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><b>Returns: </b>an orbit-by-suborbit object</p>
<p>This is the main function in the whole business. All notations from the beginning of this Chapter <a href="chap8.html#X7CC7EC257DD466E3"><b>8</b></a> remain in place. The argument <var class="Arg">setup</var> must be a setup record lying in the filter <code class="func">IsOrbitBySuborbitSetup</code> (<a href="chap8.html#X7CFD48C17B48CDDD"><b>8.3-1</b></a>) described in detail in Section <a href="chap8.html#X80F036B378A3FD32"><b>8.3</b></a> and produced for example by <code class="func">OrbitBySuborbitBootstrapForVectors</code> (<a href="chap8.html#X830E221D84E44A64"><b>8.2-1</b></a>) or <code class="func">OrbitBySuborbitBootstrapForLines</code> (<a href="chap8.html#X799056597EA62513"><b>8.2-2</b></a>) described below. In particular, it contains all the generators for G and the helper subgroups acting on the various sets. The argument <var class="Arg">p</var> must be the starting point of the orbit. Note that the function possibly does not take <var class="Arg">p</var> itself as starting point but rather its U_k-minimalisation, which is a point in the same U_k-orbit as <var class="Arg">p</var>. This information is important for the resulting stabiliser and words representing the U_k-suborbits.</p>
<p>The integers <var class="Arg">j</var>, <var class="Arg">l</var>, and <var class="Arg">i</var>, for which k+1 ge <var class="Arg">j</var> ge <var class="Arg">l</var> > <var class="Arg">i</var> ge 1 must hold, determine the running mode. <var class="Arg">j</var> indicates in which set X_j the point <var class="Arg">p</var> lies and thus in which set the orbit enumeration takes place, with j=k+1 indicating the original set X. The value <var class="Arg">l</var> indicates which group to use for orbit enumeration. So the result will be a U_l orbit, with <var class="Arg">l</var>=<var class="Arg">k</var>+1 indicating a G-orbit. Finally, the value <var class="Arg">i</var> indicates which group to use for the "by suborbit" part, that is, the orbit will be enumerated "by U_<var class="Arg">i</var>-orbits". Note that nearly all possible combinations of these parameters actually occur, because this function is also used in the "on-the-fly" precomputation happening behind the scenes. The most common usage of this function for the user is <var class="Arg">j</var>=<var class="Arg">l</var>=<var class="Arg">k</var>+1 and <var class="Arg">i</var>=k.</p>
<p>Finally, the integer <var class="Arg">percentage</var> says, how much of the full orbit should be enumerated, the value is in percent, thus 100 means the full orbit. Usually, only values greater than 50 are sensible, because one can only prove the size of the orbit after enumerating at least half of it.</p>
<p>The result is an "orbit-by-suborbit" object. For such an object in particular the operations <code class="func">Size</code> (<a href="chap8.html#X83C66D4A8603CA56"><b>8.1-3</b></a>), <code class="func">Seed</code> (<a href="chap8.html#X7EBEA64D7A5F78E3"><b>8.1-4</b></a>), <code class="func">SuborbitsDb</code> (<a href="chap8.html#X80B78B657E77A485"><b>8.1-5</b></a>), <code class="func">WordsToSuborbits</code> (<a href="chap8.html#X7B5E783478A337C9"><b>8.1-6</b></a>), <code class="func">Memory</code> (<a href="chap8.html#X7926C96485985614"><b>8.1-7</b></a>), <code class="func">Stabilizer</code> (<a href="chap8.html#X840AFA7987535AC5"><b>8.1-8</b></a>), and <code class="func">Seed</code> (<a href="chap8.html#X7EBEA64D7A5F78E3"><b>8.1-4</b></a>) are defined, see below.</p>
<p><a id="X86CCD9B98156155E" name="X86CCD9B98156155E"></a></p>
<h5>8.1-2 OrbitBySuborbitKnownSize</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">> OrbitBySuborbitKnownSize</code>( <var class="Arg">setup, p, j, l, i, percentage, knownsize</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><b>Returns: </b>an orbit-by-suborbit object</p>
<p>Basically does the same as <code class="func">OrbitBySuborbit</code> (<a href="chap8.html#X79B161FD84AB8C68"><b>8.1-1</b></a>) but does not compute the stabiliser by evaluating Schreier words. Instead, the size of the orbit to enumerate must already be known and be given in the argument <var class="Arg">knownsize</var>. The other arguments are as for the function <code class="func">OrbitBySuborbit</code> (<a href="chap8.html#X79B161FD84AB8C68"><b>8.1-1</b></a>).</p>
<p><a id="X83C66D4A8603CA56" name="X83C66D4A8603CA56"></a></p>
<h5>8.1-3 Size</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">> Size</code>( <var class="Arg">orb</var> )</td><td class="tdright">( method )</td></tr></table></div>
<p><b>Returns: </b>an integer</p>
<p>Returns the number of points in the orbit-by-suborbit <var class="Arg">orb</var>.</p>
<p><a id="X7EBEA64D7A5F78E3" name="X7EBEA64D7A5F78E3"></a></p>
<h5>8.1-4 Seed</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">> Seed</code>( <var class="Arg">orb</var> )</td><td class="tdright">( method )</td></tr></table></div>
<p><b>Returns: </b>a point in the orbit</p>
<p>Returns the starting point of the orbit-by-suborbit <var class="Arg">orb</var>. It is the U_i-minimalisation of the starting point given to <code class="func">OrbitBySuborbit</code> (<a href="chap8.html#X79B161FD84AB8C68"><b>8.1-1</b></a>).</p>
<p><a id="X80B78B657E77A485" name="X80B78B657E77A485"></a></p>
<h5>8.1-5 SuborbitsDb</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">> SuborbitsDb</code>( <var class="Arg">orb</var> )</td><td class="tdright">( operation )</td></tr></table></div>
<p><b>Returns: </b>a database of suborbits</p>
<p>Returns the data base of suborbits of the orbit-by-suborbit object <var class="Arg">orb</var>. In particular, such a database object has methods for the operations <code class="func">Memory</code> (<a href="chap8.html#X7926C96485985614"><b>8.1-7</b></a>), <code class="func">TotalLength</code> (<a href="chap8.html#X79DB081F827B53CB"><b>8.1-11</b></a>), and <code class="func">Representatives</code> (<a href="chap8.html#X81ABF8407AF16C34"><b>8.1-12</b></a>). For descriptions see below.</p>
<p><a id="X7B5E783478A337C9" name="X7B5E783478A337C9"></a></p>
<h5>8.1-6 WordsToSuborbits</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">> WordsToSuborbits</code>( <var class="Arg">orb</var> )</td><td class="tdright">( operation )</td></tr></table></div>
<p><b>Returns: </b>a list of words</p>
<p>Returns a list of words in the groups U_* reaching each of the suborbits in the orbit-by-suborbit <var class="Arg">orb</var>. Here a word is a list of integers. Positive numbers index generators in following numbering: The first few numbers are numbers of generators of U_1 the next few adjacent numbers index the generators of U_2 and so on until the generators of G in the end. Negative numbers indicate the corresponding inverses of these generators.</p>
<p>Note that <code class="func">OrbitBySuborbit</code> (<a href="chap8.html#X79B161FD84AB8C68"><b>8.1-1</b></a>) takes the U_i-minimalisation of the starting point as its starting point and the words here are all relative to this new starting point.</p>
<p><a id="X7926C96485985614" name="X7926C96485985614"></a></p>
<h5>8.1-7 Memory</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">> Memory</code>( <var class="Arg">ob</var> )</td><td class="tdright">( operation )</td></tr></table></div>
<p><b>Returns: </b>an integer</p>
<p>Returns the amount of memory needed by the object <var class="Arg">ob</var>, which can be either an orbit-by-suborbit object, a suborbit database object, or an object in the filter <code class="func">IsOrbitBySuborbitSetup</code> (<a href="chap8.html#X7CFD48C17B48CDDD"><b>8.3-1</b></a>). The amount of memory used is given in bytes. Note that this includes all hashes, databases, and preparatory data of substantial size. For orbit-by-suborbits the memory needed for the precomputation is not included, ask the setup object for that.</p>
<p><a id="X840AFA7987535AC5" name="X840AFA7987535AC5"></a></p>
<h5>8.1-8 Stabilizer</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">> Stabilizer</code>( <var class="Arg">orb</var> )</td><td class="tdright">( method )</td></tr></table></div>
<p><b>Returns: </b>a permutation group</p>
<p>Returns the stabiliser of the starting point of the orbit-by-suborbit in <var class="Arg">orb</var> in form of a permutation group, using the given faithful permutation representation in the setup record.</p>
<p>Note that <code class="func">OrbitBySuborbit</code> (<a href="chap8.html#X79B161FD84AB8C68"><b>8.1-1</b></a>) takes the U_i-minimalisation of the starting point as its starting point and the stabiliser returned here is the one of this new starting point.</p>
<p><a id="X7F496D9B7C44DAAB" name="X7F496D9B7C44DAAB"></a></p>
<h5>8.1-9 StabWords</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">> StabWords</code>( <var class="Arg">orb</var> )</td><td class="tdright">( operation )</td></tr></table></div>
<p><b>Returns: </b>a list of words</p>
<p>Returns generators for the stabiliser of the starting point of the orbit-by-suborbit in <var class="Arg">orb</var> in form of words as described with the operation <code class="func">WordsToSuborbits</code> (<a href="chap8.html#X7B5E783478A337C9"><b>8.1-6</b></a>). Note again that <code class="func">OrbitBySuborbit</code> (<a href="chap8.html#X79B161FD84AB8C68"><b>8.1-1</b></a>) takes the U_i-minimalisation of the starting point as its starting point and the stabiliser returned here is the one of this new starting point.</p>
<p><a id="X802068267DACF3F6" name="X802068267DACF3F6"></a></p>
<h5>8.1-10 SavingFactor</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">> SavingFactor</code>( <var class="Arg">orb</var> )</td><td class="tdright">( operation )</td></tr></table></div>
<p><b>Returns: </b>an integer</p>
<p>Returns the quotient of the total number of points stored in the orbit-by-suborbit <var class="Arg">orb</var> and the total number of U-minimal points stored. Note that the memory for the precomputations is not considered here!</p>
<p>The following operations apply to orbit-by-suborbit database objects:</p>
<p><a id="X79DB081F827B53CB" name="X79DB081F827B53CB"></a></p>
<h5>8.1-11 TotalLength</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">> TotalLength</code>( <var class="Arg">db</var> )</td><td class="tdright">( operation )</td></tr></table></div>
<p><b>Returns: </b>an integer</p>
<p>Returns the total number of points stored in all suborbits in the orbit-by-suborbit database <var class="Arg">db</var>.</p>
<p><a id="X81ABF8407AF16C34" name="X81ABF8407AF16C34"></a></p>
<h5>8.1-12 Representatives</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">> Representatives</code>( <var class="Arg">db</var> )</td><td class="tdright">( operation )</td></tr></table></div>
<p><b>Returns: </b>a list of points</p>
<p>Returns a list of representatives of the suborbits stored in the orbit-by-suborbit database <var class="Arg">db</var>.</p>
<p><a id="X79552A1086449062" name="X79552A1086449062"></a></p>
<h5>8.1-13 SavingFactor</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">> SavingFactor</code>( <var class="Arg">db</var> )</td><td class="tdright">( operation )</td></tr></table></div>
<p><b>Returns: </b>an integer</p>
<p>Returns the quotient of the total number of points stored in the suborbit database <var class="Arg">db</var> and the total number of U-minimal points stored. Note that the memory for the precomputations is not considered here!</p>
<p><a id="X7A96D6D37F0EC46A" name="X7A96D6D37F0EC46A"></a></p>
<h5>8.1-14 OrigSeed</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">> OrigSeed</code>( <var class="Arg">orb</var> )</td><td class="tdright">( operation )</td></tr></table></div>
<p><b>Returns: </b>a point</p>
<p>Returns the original starting point for the orbit, not yet minimalised.</p>
<p><a id="X7C0335D97C990559" name="X7C0335D97C990559"></a></p>
<h4>8.2 <span class="Heading">Preparation functions for <code class="func">OrbitBySuborbit</code> (<a href="chap8.html#X79B161FD84AB8C68"><b>8.1-1</b></a>)</span></h4>
<p><a id="X830E221D84E44A64" name="X830E221D84E44A64"></a></p>
<h5>8.2-1 OrbitBySuborbitBootstrapForVectors</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">> OrbitBySuborbitBootstrapForVectors</code>( <var class="Arg">gens, permgens, sizes, codims, opt</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><b>Returns: </b>a setup record in the filter <code class="func">IsOrbitBySuborbitSetup</code> (<a href="chap8.html#X7CFD48C17B48CDDD"><b>8.3-1</b></a>)</p>
<p>All notations from the beginning of this Chapter <a href="chap8.html#X7CC7EC257DD466E3"><b>8</b></a> remain in place. This function is for the action of matrices on row vectors, so all generators must be matrices. The set X thus is a row space usually over a finite field and the sets X_i are quotient spaces. The matrix generators for the various groups have to be adjusted with a base change, such that the canonical projection onto X_i is just to take the first few entries in a vector, which means, that the submodules divided out are generated by the last standard basis vectors.</p>
<p>The first argument <var class="Arg">gens</var> must be a list of lists of generators. The outer list must have length k+1 with entry i being a list of matrices generating U_i, given in the action on X=X_{k+1}. The above mentioned base change must have been done. The second argument <var class="Arg">permgens</var> must be an analogous list with generator lists for the U_i, but here we have to have permutation representations. These permutation representations are used to compute membership and group orders of stabilisers. The argument <var class="Arg">sizes</var> must be a list of length k+1 and entry i must be the group order of U_i (again with U_{k+1} being G). Finally, the argument <var class="Arg">codims</var> must be a list of length k containing integers with the ith entry being the codimension of the U_i-invariant subspace Y_i of X with X_i = X/Y_i. These codimensions must not decrease for obvious reasons, but some of them may be equal. The last argument <var class="Arg">opt</var> is an options record. See below for possible entries.</p>
<p>The function does all necessary steps to fill a setup record (see <a href="chap8.html#X80F036B378A3FD32"><b>8.3</b></a>) to be used with <code class="func">OrbitBySuborbit</code> (<a href="chap8.html#X79B161FD84AB8C68"><b>8.1-1</b></a>). For details see the code.</p>
<p>Currently, the following components in the options record <var class="Arg">opt</var> have a meaning:</p>
<dl>
<dt><strong class="Mark"><code class="code">regvecfachints</code></strong></dt>
<dd><p>If bound it must be a list. In position i for i>1 there may be a list of vectors in the i-th quotient space X_i that can be used to distinguish the left U_{i-1} cosets in U_i. All vectors in this list are tried and the first one that actually works is used.</p>
</dd>
<dt><strong class="Mark"><code class="code">regvecfullhints</code></strong></dt>
<dd><p>If bound it must be a list. In position i for i>1 there may be a list of vectors in the full space X that can be used to distinguish the left U_{i-1} cosets in U_i. All vectors in this list are tried and the first one that actually works is used.</p>
</dd>
<dt><strong class="Mark"><code class="code">stabchainrandom</code></strong></dt>
<dd><p>If bound the value is copied into the <code class="code">stabchainrandom</code> component of the setup record.</p>
</dd>
</dl>
<p><a id="X799056597EA62513" name="X799056597EA62513"></a></p>
<h5>8.2-2 OrbitBySuborbitBootstrapForLines</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">> OrbitBySuborbitBootstrapForLines</code>( <var class="Arg">gens, permgens, sizes, codims, opt</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><b>Returns: </b>a setup record in the filter <code class="func">IsOrbitBySuborbitSetup</code> (<a href="chap8.html#X7CFD48C17B48CDDD"><b>8.3-1</b></a>)</p>
<p>All notations from the beginning of this Chapter <a href="chap8.html#X7CC7EC257DD466E3"><b>8</b></a> remain in place. This does exactly the same as <code class="func">OrbitBySuborbitBootstrapForVectors</code> (<a href="chap8.html#X830E221D84E44A64"><b>8.2-1</b></a>) except that it handles the case of matrices acting on one-dimensional subspaces. Those one-dimensional subspaces are represented by normalised vectors, where a vector is normalised if its first non-vanishing entry is equal to 1.</p>
<p><a id="X7919B1AB7D68780D" name="X7919B1AB7D68780D"></a></p>
<h5>8.2-3 OrbitBySuborbitBootstrapForSpaces</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">> OrbitBySuborbitBootstrapForSpaces</code>( <var class="Arg">gens, permgens, sizes, codims, spcdim, opt</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><b>Returns: </b>a setup record in the filter <code class="func">IsOrbitBySuborbitSetup</code> (<a href="chap8.html#X7CFD48C17B48CDDD"><b>8.3-1</b></a>)</p>
<p>All notations from the beginning of this Chapter <a href="chap8.html#X7CC7EC257DD466E3"><b>8</b></a> remain in place. This does exactly the same as <code class="func">OrbitBySuborbitBootstrapForVectors</code> (<a href="chap8.html#X830E221D84E44A64"><b>8.2-1</b></a>) except that it handles the case of matrices acting on <var class="Arg">spcdim</var>-dimensional subspaces. Those subspaces are represented by fully echelonised bases.</p>
<p><a id="X80F036B378A3FD32" name="X80F036B378A3FD32"></a></p>
<h4>8.3 <span class="Heading">Data structures for orbit-by-suborbits</span></h4>
<p>The description in this section is necessarily technical. It is meant more as extended annotations to the source code than as user documentation. Usually it should not be necessary for the user to know the details presented here. The function <code class="func">OrbitBySuborbit</code> (<a href="chap8.html#X79B161FD84AB8C68"><b>8.1-1</b></a>) needs an information record of the following form:</p>
<p><a id="X7CFD48C17B48CDDD" name="X7CFD48C17B48CDDD"></a></p>
<h5>8.3-1 IsOrbitBySuborbitSetup</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">> IsOrbitBySuborbitSetup</code>( <var class="Arg">ob</var> )</td><td class="tdright">( category )</td></tr></table></div>
<p><b>Returns: </b><code class="keyw">true</code> or <code class="keyw">false</code></p>
<p>Objects in this category are also in <code class="code">IsComponentObjRep</code>. We describe the components, refering to the setup at the beginning of this Chapter <a href="chap8.html#X7CC7EC257DD466E3"><b>8</b></a>.</p>
<dl>
<dt><strong class="Mark"><code class="code">k</code></strong></dt>
<dd><p>The number of helper subgroups.</p>
</dd>
<dt><strong class="Mark"><code class="code">size</code></strong></dt>
<dd><p>A list of length k+1 containing the orders of the groups U_i, including U_{k+1} = G.</p>
</dd>
<dt><strong class="Mark"><code class="code">index</code></strong></dt>
<dd><p>A list of length k with the index [U_i:U_{i-1}] in position i (U_0 = 1).</p>
</dd>
<dt><strong class="Mark"><code class="code">els</code></strong></dt>
<dd><p>A list of length k+1 containing generators of the groups in their action on various sets. In position i we store all the generators for all groups acting on X_i, that is for the groups U_1, ..., U_i (where position k+1 includes the generators for G. In each position the generators of all those groups are concatentated starting with U_1 and ending with U_i.</p>
</dd>
<dt><strong class="Mark"><code class="code">elsinv</code></strong></dt>
<dd><p>The inverses of all the elements in the <code class="code">els</code> component in the same arrangement.</p>
</dd>
<dt><strong class="Mark"><code class="code">trans</code></strong></dt>
<dd><p>A list of length k in which position i for i>1 contains a list of words in the generators for a transversal of U_{i-1} in U_i (with U_0 = 1).</p>
</dd>
<dt><strong class="Mark"><code class="code">pifunc</code></strong></dt>
<dd><p>Projection functions. This is a list of length k+1 containing in position j a list of length j-1 containing in position i a <strong class="pkg">GAP</strong> function doing the projection X_j -> X_i. These <strong class="pkg">GAP</strong> functions take two arguments, namely the point to map and secondly the value of the <code class="code">pi</code> component at positions <code class="code">[j][i]</code>. Usually <code class="code">pifunc</code> is just the slicing operator in <strong class="pkg">GAP</strong> and <code class="code">pi</code> contains the components to project onto as a range object.</p>
</dd>
<dt><strong class="Mark"><code class="code">pi</code></strong></dt>
<dd><p>See the description of the <code class="code">pifunc</code> component.</p>
</dd>
<dt><strong class="Mark"><code class="code">op</code></strong></dt>
<dd><p>A list of k+1 <strong class="pkg">GAP</strong> operation functions, each taking a point p and a generator g in the action given by the index and returning pg.</p>
</dd>
<dt><strong class="Mark"><code class="code">info</code></strong></dt>
<dd><p>A list of length k containing a hash table with the minimalisation lookup data. These hash tables grow during orbit enumerations as precomputations are done behind the scenes.</p>
<p><code class="code">info[1]</code> contains precomputation data for X_1. Assume x in X_1 to be U_1-minimal. For all z in xU_1 with z <> x we store the number of an element in the <code class="code">wordcache</code> mapping z to x. For z=x we store a record with two components <code class="code">gens</code> and <code class="code">size</code>, where <code class="code">gens</code> stores generators for the stabiliser Stab_{U_1}(x) as words in the group generators and <code class="code">size</code> stores the size of that stabiliser.</p>
<p><code class="code">info[i]</code> for i>1 contains precomputation data for X_i. Assume x in X_i to be U_i-minimal. For all U_{i-1}-minimal z in xU_i \ xU_{i-1} we store the number of an element in <code class="code">trans[i]</code> mapping z into xU_{i-1}. For all U_{i-1}-minimal z in xU_{i-1} with z <> x we store the negative of the number of a word in <code class="code">wordcache</code> that is in the generators of U_{i-1} and maps z to x. For z=x we store the stabiliser information as in the case i=1.</p>
<p>This information together with the information in the following componente allows the minimalisation function to do its job.</p>
</dd>
<dt><strong class="Mark"><code class="code">cosetrecog</code></strong></dt>
<dd><p>A list of length k beginning with the index 1. The entry at position i is bound to a function taking 3 arguments, namely i itself, a word in the group generators of U_1, ..., U_k which lies in U_i, and the setup record. The function computes the number <code class="code">j</code> of an element in <code class="code">trans[i]</code>, such that the element of U_i described by the word lies in <code class="code">trans[i][j] U_{{i-1}}</code>.</p>
</dd>
<dt><strong class="Mark"><code class="code">cosetinfo</code></strong></dt>
<dd><p>A list of things that can be used by the functions in <code class="code">cosetrecog</code>.</p>
</dd>
<dt><strong class="Mark"><code class="code">suborbnr</code></strong></dt>
<dd><p>A list of length k that contains in position i the number of U_i-orbits in X_i archived in <code class="code">info[i]</code> during precomputation.</p>
</dd>
<dt><strong class="Mark"><code class="code">sumstabl</code></strong></dt>
<dd><p>A list of length k that contains in position i the sum of the point stabiliser sizes of all U_i-orbits X_i archived in <code class="code">info[i]</code> during precomputation.</p>
</dd>
<dt><strong class="Mark"><code class="code">permgens</code></strong></dt>
<dd><p>A list of length k+1 containing in position i generators for U_1, ..., U_i in a faithful permutation representation of U_i. Generators fit to the generators in <code class="code">els</code>. For the variant <code class="func">OrbitBySuborbitKnownSize</code> (<a href="chap8.html#X86CCD9B98156155E"><b>8.1-2</b></a>) the k+1 entry can be unbound.</p>
</dd>
<dt><strong class="Mark"><code class="code">permgensinv</code></strong></dt>
<dd><p>The inverses of the generators in <code class="code">permgens</code> in the same arrangement.</p>
</dd>
<dt><strong class="Mark"><code class="code">sample</code></strong></dt>
<dd><p>A list of length k+1 containing sample points in the sets X_i.</p>
</dd>
<dt><strong class="Mark"><code class="code">stabchainrandom</code></strong></dt>
<dd><p>The value is used as the value for the <code class="code">random</code> option for <code class="code">StabChain</code> calculations to determine stabiliser sizes. Note that the algorithms are randomized if you use this feature with a value smaller than 1000.</p>
</dd>
<dt><strong class="Mark"><code class="code">wordhash</code></strong></dt>
<dd><p>A hash to quickly recognise already used words. For every word in the hash the position of that word in the <code class="code">wordcache</code> list is stored as value in the hash.</p>
</dd>
<dt><strong class="Mark"><code class="code">wordcache</code></strong></dt>
<dd><p>A list of words in the wordcache for indexing purposes.</p>
</dd>
<dt><strong class="Mark"><code class="code">hashlen</code></strong></dt>
<dd><p>Initial length of hash tables used for the enumeration of lists of U_i-minimal points.</p>
</dd>
<dt><strong class="Mark"><code class="code">staborblenlimit</code></strong></dt>
<dd><p>This contains the limit, up to which orbits of stabilisers are computed using word action. After this limit, the stabiliser elements are actually evaluated in the group.</p>
</dd>
<dt><strong class="Mark"><code class="code">stabsizelimitnostore</code></strong></dt>
<dd><p>If the stabiliser in the quotient is larger than this limit, the suborbit is not stored.</p>
</dd>
<dt><strong class="Mark"><code class="code">cache</code></strong></dt>
<dd><p>A linked list cache object (see <code class="func">LinkedListCache</code> (<a href="chap5.html#X7FF40AE981FE6F75"><b>5.2-1</b></a>)) to store already computed transversal elements. The cache nodes are referenced in the <code class="code">transcache</code> component and are stored in the cache <code class="code">cache</code>.</p>
</dd>
<dt><strong class="Mark"><code class="code">transcache</code></strong></dt>
<dd><p>This is a list of lists of weak pointer objects. The weak pointer object at position <code class="code">[i][j]</code> holds references to cache nodes of transversal elements of U_i-1 in U_i in representation j.</p>
</dd>
</dl>
<p><a id="X855663F5790EA2D0" name="X855663F5790EA2D0"></a></p>
<h5>8.3-2 <span class="Heading">The global record <code class="code">ORB</code></span></h5>
<p>In this section we describe the global record <code class="code">ORB</code>, which contains some entries that can tune the behaviour of the orbit-by-suborbit functions. The record has the following components:</p>
<dl>
<dt><strong class="Mark"><code class="code">MINSHASHLEN</code></strong></dt>
<dd><p>This positive integer is the initial value of the hash size when enumerating orbits of stored stabilisers to find all or search through U_{i-1}-minimal vectors in an U_i-orbit. The default value is 1000.</p>
</dd>
<dt><strong class="Mark"><code class="code">ORBITBYSUBORBITDEPTH</code></strong></dt>
<dd><p>This integer indicates how many recursive calls to <code class="code">OrbitBySubOrbitInner</code> have been done. The initial value is 0 to indicate that no such call has happened. This variable is necessary since the minimalisation routine sometimes uses <code class="code">OrbitBySubOrbitInner</code> recursively to complete some precomputation "on the fly" during some other orbit-by-suborbit enumeration. This component is always set to 0 automatically when calling <code class="func">OrbitBySuborbit</code> (<a href="chap8.html#X79B161FD84AB8C68"><b>8.1-1</b></a>) or <code class="func">OrbitBySuborbitKnownSize</code> (<a href="chap8.html#X86CCD9B98156155E"><b>8.1-2</b></a>) so the user should usually not have to worry about it at all.</p>
</dd>
<dt><strong class="Mark"><code class="code">PATIENCEFORSTAB</code></strong></dt>
<dd><p>This integer indicates how many Schreier generators for the stabiliser are tried before assuming that the stabiliser is complete. Whenever a new generator for the stabiliser is found that increases the size of the currently known stabiliser, the count is reset to 0 that is, only when <code class="code">ORB.PATIENCEFORSTAB</code> unsuccessful Schreier generators have been tried no more Schreier generators are created. The default value for this component is 1000. This feature is purely heuristical and therefore this value has to be adjusted for some orbit enumerations.</p>
</dd>
<dt><strong class="Mark"><code class="code">PLEASEEXITNOW</code></strong></dt>
<dd><p>This value is usually set to <code class="keyw">false</code>. Setting it to <code class="keyw">true</code> in a break loop tells the orbit-by-suborbit routines to exit gracefully at the next possible time. Simply leaving such a break loop with <code class="keyw">quit;</code> is not safe, since the routines might be in the process of updating precomputation data and the data structures might be left corrupt. Always use this component to leave an orbit enumeration prematurely.</p>
</dd>
<dt><strong class="Mark"><code class="code">REPORTSUBORBITS</code></strong></dt>
<dd><p>This positive integer governs how often information messages about newly found suborbits are printed. The default value is 1000 saying that after every 1000 suborbits a message is printed, if the info level is at its default value 1. If the info level is increased, then this component does no longer affect the printing and all found suborbits are reported.</p>
</dd>
<dt><strong class="Mark"><code class="code">TRIESINQUOTIENT</code> and <code class="code">TRIESINWHOLESPACE</code></strong></dt>
<dd><p>The bootstrap routines <code class="func">OrbitBySuborbitBootstrapForVectors</code> (<a href="chap8.html#X830E221D84E44A64"><b>8.2-1</b></a>), <code class="func">OrbitBySuborbitBootstrapForLines</code> (<a href="chap8.html#X799056597EA62513"><b>8.2-2</b></a>) and <code class="func">OrbitBySuborbitBootstrapForSpaces</code> (<a href="chap8.html#X7919B1AB7D68780D"><b>8.2-3</b></a>) all need to compute transversals of one helper subgroup in the next one. They use orbit enumerations in various spaces to achieve this. The component <code class="code">TRIESINQUOTIENT</code> must be a non-negative integer and indicates how often a random vector in the corresponding quotient space is tried to find an orbit that can distinguish between cosets. The other component <code class="code">TRIESINWHOLESPACE</code> also must be a non-negative integer and indicates how often a random vector in the whole space is tried. The default values are 3 and 20 resepectively.</p>
</dd>
</dl>
<p><a id="X8696CFD08768508D" name="X8696CFD08768508D"></a></p>
<h4>8.4 <span class="Heading">Lists of orbit-by-suborbit objects</span></h4>
<p>There are a few functions that help to administrate lists of orbit-by-suborbits.</p>
<p><a id="X7FB77D827E31AE24" name="X7FB77D827E31AE24"></a></p>
<h5>8.4-1 InitOrbitBySuborbitList</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">> InitOrbitBySuborbitList</code>( <var class="Arg">setup, nrrandels</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><b>Returns: </b>a list of orbit-by-suborbits object</p>
<p>Creates an object that stores a list of orbit-by-suborbits. The argument <var class="Arg">setup</var> must be an orbit-by-suborbit setup record and <var class="Arg">nrrandels</var> must be an integer. It indicates how many random elements in G should be used to do a probabilistic check for membership in case an orbit-by-suborbit is only partially known.</p>
<p><a id="X87CB441882F43F62" name="X87CB441882F43F62"></a></p>
<h5>8.4-2 IsVectorInOrbitBySuborbitList</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">> IsVectorInOrbitBySuborbitList</code>( <var class="Arg">v, obsol</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><b>Returns: </b><code class="keyw">fail</code> or an integer</p>
<p>Checks probabilistically, if the element <var class="Arg">v</var> lies in one of the partially enumerated orbit-by-suborbits in the orbit-by-suborbit list object <var class="Arg">obsol</var>. If yes, the number of that orbit-by-suborbit is returned and the answer is guaranteed to be correct. If the answer is <code class="keyw">fail</code> there is a small probability that the point actually lies in one of the orbits but this could not be shown.</p>
<p><a id="X7D82CE2579A50B2C" name="X7D82CE2579A50B2C"></a></p>
<h5>8.4-3 OrbitsFromSeedsToOrbitList</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">> OrbitsFromSeedsToOrbitList</code>( <var class="Arg">obsol, li</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><b>Returns: </b>nothing</p>
<p>Takes the elements in the list <var class="Arg">li</var> as seeds for orbit-by-suborbits. For each such seed it is first checked whether it lies in one of the orbit-by-suborbits in <var class="Arg">obsol</var>, which must be an orbit-by-suborbit list object. If not found, 51% of the orbit-by-suborbit of the seed is enumerated and added to the list <var class="Arg">obsol</var>.</p>
<p>This function is a good way to quickly enumerate a greater number of orbit-by-suborbits.</p>
<p><a id="X83A306918461D700" name="X83A306918461D700"></a></p>
<h5>8.4-4 VerifyDisjointness</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">> VerifyDisjointness</code>( <var class="Arg">obsol</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><b>Returns: </b><code class="keyw">true</code> or <code class="keyw">false</code></p>
<p>This function checks deterministically, whether the orbit-by-suborbits in the orbit-by-suborbit list object <var class="Arg">obsol</var> are disjoint or not and returns the corresponding boolean value. This is not a Monte-Carlo algorithm. If the answer is <code class="keyw">false</code>, the function writes out, which orbits are in fact identical.</p>
<p><a id="X7ED405017E3A56CD" name="X7ED405017E3A56CD"></a></p>
<h5>8.4-5 Memory</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">> Memory</code>( <var class="Arg">obsol</var> )</td><td class="tdright">( operation )</td></tr></table></div>
<p><b>Returns: </b>an integer</p>
<p>Returns the total memory used for all orbit-by-suborbits in the orbit-by-suborbit-list <var class="Arg">obsol</var>. Precomputation data is not included, ask the setup object instead.</p>
<p><a id="X7D52885787865E81" name="X7D52885787865E81"></a></p>
<h5>8.4-6 TotalLength</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">> TotalLength</code>( <var class="Arg">obsol</var> )</td><td class="tdright">( operation )</td></tr></table></div>
<p><b>Returns: </b>an integer</p>
<p>Returns the total number of points stored in all orbit-by-suborbits in the orbit-by-suborbit-list <var class="Arg">obsol</var>.</p>
<p><a id="X7C4255287D394742" name="X7C4255287D394742"></a></p>
<h5>8.4-7 Size</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">> Size</code>( <var class="Arg">obsol</var> )</td><td class="tdright">( method )</td></tr></table></div>
<p><b>Returns: </b>an integer</p>
<p>Returns the total number of points in the orbit-by-suborbit-list <var class="Arg">obsol</var>.</p>
<p><a id="X7BFE12DE85CCE143" name="X7BFE12DE85CCE143"></a></p>
<h5>8.4-8 SavingFactor</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">> SavingFactor</code>( <var class="Arg">obsol</var> )</td><td class="tdright">( operation )</td></tr></table></div>
<p><b>Returns: </b>an integer</p>
<p>Returns the quotient of the total number of points stored in all orbit-by-suborbits in the orbit-by-suborbit-list <var class="Arg">obsol</var> and the total number of U-minimal points stored, which is the average saving factor considering all orbit-by-suborbits together. Note that the memory for the precomputations is not considered here!</p>
<div class="chlinkprevnextbot"> <a href="chap0.html">Top of Book</a> <a href="chap7.html">Previous Chapter</a> <a href="chap9.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="chap5.html">5</a> <a href="chap6.html">6</a> <a href="chap7.html">7</a> <a href="chap8.html">8</a> <a href="chap9.html">9</a> <a href="chap10.html">10</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>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
91213ddcfbe7f54821d42c2d9e091326
>
files
>
2148
