/usr/share/gap/doc/ref/chap85.html is in gap-doc 4r8p6-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 | <?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 (ref) - Chapter 85: Function-Operation-Attribute Triples</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" />
<script src="manual.js" type="text/javascript"></script>
<script type="text/javascript">overwriteStyle();</script>
</head>
<body class="chap85" onload="jscontent()">
<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="chap11.html">11</a> <a href="chap12.html">12</a> <a href="chap13.html">13</a> <a href="chap14.html">14</a> <a href="chap15.html">15</a> <a href="chap16.html">16</a> <a href="chap17.html">17</a> <a href="chap18.html">18</a> <a href="chap19.html">19</a> <a href="chap20.html">20</a> <a href="chap21.html">21</a> <a href="chap22.html">22</a> <a href="chap23.html">23</a> <a href="chap24.html">24</a> <a href="chap25.html">25</a> <a href="chap26.html">26</a> <a href="chap27.html">27</a> <a href="chap28.html">28</a> <a href="chap29.html">29</a> <a href="chap30.html">30</a> <a href="chap31.html">31</a> <a href="chap32.html">32</a> <a href="chap33.html">33</a> <a href="chap34.html">34</a> <a href="chap35.html">35</a> <a href="chap36.html">36</a> <a href="chap37.html">37</a> <a href="chap38.html">38</a> <a href="chap39.html">39</a> <a href="chap40.html">40</a> <a href="chap41.html">41</a> <a href="chap42.html">42</a> <a href="chap43.html">43</a> <a href="chap44.html">44</a> <a href="chap45.html">45</a> <a href="chap46.html">46</a> <a href="chap47.html">47</a> <a href="chap48.html">48</a> <a href="chap49.html">49</a> <a href="chap50.html">50</a> <a href="chap51.html">51</a> <a href="chap52.html">52</a> <a href="chap53.html">53</a> <a href="chap54.html">54</a> <a href="chap55.html">55</a> <a href="chap56.html">56</a> <a href="chap57.html">57</a> <a href="chap58.html">58</a> <a href="chap59.html">59</a> <a href="chap60.html">60</a> <a href="chap61.html">61</a> <a href="chap62.html">62</a> <a href="chap63.html">63</a> <a href="chap64.html">64</a> <a href="chap65.html">65</a> <a href="chap66.html">66</a> <a href="chap67.html">67</a> <a href="chap68.html">68</a> <a href="chap69.html">69</a> <a href="chap70.html">70</a> <a href="chap71.html">71</a> <a href="chap72.html">72</a> <a href="chap73.html">73</a> <a href="chap74.html">74</a> <a href="chap75.html">75</a> <a href="chap76.html">76</a> <a href="chap77.html">77</a> <a href="chap78.html">78</a> <a href="chap79.html">79</a> <a href="chap80.html">80</a> <a href="chap81.html">81</a> <a href="chap82.html">82</a> <a href="chap83.html">83</a> <a href="chap84.html">84</a> <a href="chap85.html">85</a> <a href="chap86.html">86</a> <a href="chap87.html">87</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="chap0.html#contents">[Contents]</a> <a href="chap84.html">[Previous Chapter]</a> <a href="chap86.html">[Next Chapter]</a> </div>
<p id="mathjaxlink" class="pcenter"><a href="chap85_mj.html">[MathJax on]</a></p>
<p><a id="X8350247A8501969F" name="X8350247A8501969F"></a></p>
<div class="ChapSects"><a href="chap85.html#X8350247A8501969F">85 <span class="Heading">Function-Operation-Attribute Triples</span></a>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap85.html#X86F03E0D7C18C6B0">85.1 <span class="Heading">Key Dependent Operations</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap85.html#X7CABFDAA8596757E">85.1-1 KeyDependentOperation</a></span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap85.html#X78D4D0FF780C8A85">85.2 <span class="Heading">In Parent Attributes</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap85.html#X7C0E62D8813A4EE6">85.2-1 InParentFOA</a></span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap85.html#X7CD4A0867BD825F7">85.3 <span class="Heading">Operation Functions</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap85.html#X7CA3826A7EBDE208">85.3-1 OrbitsishOperation</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap85.html#X7B23C48482ADB237">85.3-2 OrbitishFO</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap85.html#X834E92F07DD0BF04">85.3-3 <span class="Heading">Example: Orbit and OrbitOp</span></a>
</span>
</div></div>
</div>
<h3>85 <span class="Heading">Function-Operation-Attribute Triples</span></h3>
<p><strong class="pkg">GAP</strong> is eager to maintain information that it has gathered about an object, possibly by lengthy calculations. The most important mechanism for information maintenance is the automatic storage and look-up that takes place for <em>attributes</em>; and this was already mentioned in section <a href="../../doc/tut/chap8.html#X7C701DBF7BAE649A"><span class="RefLink">Tutorial: Attributes</span></a>. In this chapter we will describe further mechanisms that allow storage of results that are not values of attributes.</p>
<p>The idea which is common to all sections is that certain operations, which are not themselves attributes, have an attribute associated with them. To automatically delegate tasks to the attribute, <strong class="pkg">GAP</strong> knows, in addition to the <em>operation</em> and the <em>attributes</em> also a <em>function</em>, which is "wrapped around" the other two. This "wrapper function" is called by the user and decides whether to call the operation or the attribute or possibly both. The whole <em>f</em>unction-<em>o</em>peration-<em>a</em>ttribute triple (or <em>FOA triple</em>) is set up by a single <strong class="pkg">GAP</strong> command which writes the wrapper function and already installs some methods, e.g., for the attribute to fall back on the operation. The idea is then that subsequent methods, which perform the actual computation, are installed only for the operation, whereas the wrapper function remains unaltered, and in general no additional methods for the attribute are required either.</p>
<p><a id="X86F03E0D7C18C6B0" name="X86F03E0D7C18C6B0"></a></p>
<h4>85.1 <span class="Heading">Key Dependent Operations</span></h4>
<p><a id="X7CABFDAA8596757E" name="X7CABFDAA8596757E"></a></p>
<h5>85.1-1 KeyDependentOperation</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ KeyDependentOperation</code>( <var class="Arg">name</var>, <var class="Arg">dom-req</var>, <var class="Arg">key-req</var>, <var class="Arg">key-test</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>There are several functions that require as first argument a domain, e.g., a group, and as second argument something much simpler, e.g., a prime. <code class="func">SylowSubgroup</code> (<a href="chap39.html#X7AA351308787544C"><span class="RefLink">39.13-1</span></a>) is an example. Since its value depends on two arguments, it cannot be an attribute, yet one would like to store the Sylow subgroups once they have been computed.</p>
<p>The idea is to provide an attribute of the group, called <code class="code">ComputedSylowSubgroups</code>, and to store the groups in this list. The name implies that the value of this attribute may change in the course of a <strong class="pkg">GAP</strong> session, whenever a newly-computed Sylow subgroup is put into the list. Therefore, this is a <em>mutable attribute</em> (see <a href="chap79.html#X7A38E7E87CCCEDD1"><span class="RefLink">79.3</span></a>). The list contains primes in each bound odd position and a corresponding Sylow subgroup in the following even position. More precisely, if <code class="code"><var class="Arg">p</var> = ComputedSylowSubgroups( <var class="Arg">G</var> )[ <var class="Arg">even</var> - 1 ]</code> then <code class="code">ComputedSylowSubgroups( <var class="Arg">G</var> )[ <var class="Arg">even</var> ]</code> holds the value of <code class="code">SylowSubgroup( <var class="Arg">G</var>, <var class="Arg">p</var> )</code>. The pairs are sorted in increasing order of <var class="Arg">p</var>, in particular at most one Sylow <var class="Arg">p</var> subgroup of <var class="Arg">G</var> is stored for each prime <var class="Arg">p</var>. This attribute value is maintained by the function <code class="func">SylowSubgroup</code> (<a href="chap39.html#X7AA351308787544C"><span class="RefLink">39.13-1</span></a>), which calls the operation <code class="code">SylowSubgroupOp( <var class="Arg">G</var>, <var class="Arg">p</var> )</code> to do the real work, if the prime <var class="Arg">p</var> cannot be found in the list. So methods that do the real work should be installed for <code class="code">SylowSubgroupOp</code> and not for <code class="func">SylowSubgroup</code> (<a href="chap39.html#X7AA351308787544C"><span class="RefLink">39.13-1</span></a>).</p>
<p>The same mechanism works for other functions as well, e.g., for <code class="func">PCore</code> (<a href="chap39.html#X7CF497C77B1E8938"><span class="RefLink">39.11-3</span></a>), but also for <code class="func">HallSubgroup</code> (<a href="chap39.html#X7EDBA19E828CD584"><span class="RefLink">39.13-3</span></a>), where the second argument is not a prime but a set of primes.</p>
<p><code class="func">KeyDependentOperation</code> declares the two operations and the attribute as described above, with names <var class="Arg">name</var>, <var class="Arg">name</var><code class="code">Op</code>, and <code class="code">Computed</code><var class="Arg">name</var><code class="code">s</code>. <var class="Arg">dom-req</var> and <var class="Arg">key-req</var> specify the required filters for the first and second argument of the operation <var class="Arg">name</var><code class="code">Op</code>, which are needed to create this operation with <code class="func">DeclareOperation</code> (<a href="chap79.html#X843F48137B899BC3"><span class="RefLink">79.18-6</span></a>). <var class="Arg">dom-req</var> is also the required filter for the corresponding attribute <code class="code">Computed</code><var class="Arg">name</var><code class="code">s</code>. The fourth argument <var class="Arg">key-test</var> is in general a function to which the second argument <var class="Arg">info</var> of <code class="code"><var class="Arg">name</var>( <var class="Arg">D</var>, <var class="Arg">info</var> )</code> will be passed. This function can perform tests on <var class="Arg">info</var>, and raise an error if appropriate.</p>
<p>For example, to set up the three objects <code class="func">SylowSubgroup</code> (<a href="chap39.html#X7AA351308787544C"><span class="RefLink">39.13-1</span></a>), <code class="code">SylowSubgroupOp</code>, <code class="code">ComputedSylowSubgroups</code> together, the declaration file <code class="file">lib/grp.gd</code> contains the following line of code.</p>
<div class="example"><pre>
KeyDependentOperation( "SylowSubgroup", IsGroup, IsPosInt, "prime" );
</pre></div>
<p>In this example, <var class="Arg">key-test</var> has the value <code class="code">"prime"</code>, which is silently replaced by a function that tests whether its argument is a prime.</p>
<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">s4 := Group((1,2,3,4),(1,2));;</span>
<span class="GAPprompt">gap></span> <span class="GAPinput">SylowSubgroup( s4, 5 );; ComputedSylowSubgroups( s4 );</span>
[ 5, Group(()) ]
<span class="GAPprompt">gap></span> <span class="GAPinput">SylowSubgroup( s4, 2 );; ComputedSylowSubgroups( s4 );</span>
[ 2, Group([ (3,4), (1,4)(2,3), (1,3)(2,4) ]), 5, Group(()) ]
</pre></div>
<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">SylowSubgroup( s4, 6 );</span>
Error, SylowSubgroup: <p> must be a prime called from
<compiled or corrupted call value> called from
<function>( <arguments> ) called from read-eval-loop
Entering break read-eval-print loop ...
you can 'quit;' to quit to outer loop, or
you can 'return;' to continue
<span class="GAPbrkprompt">brk></span> <span class="GAPinput">quit;</span>
</pre></div>
<p>Thus the prime test need not be repeated in the methods for the operation <code class="code">SylowSubgroupOp</code> (which are installed to do the real work). Note that no methods need be installed for <code class="func">SylowSubgroup</code> (<a href="chap39.html#X7AA351308787544C"><span class="RefLink">39.13-1</span></a>) and <code class="code">ComputedSylowSubgroups</code>. If a method is installed with <code class="func">InstallMethod</code> (<a href="chap78.html#X837EFDAB7BEF290B"><span class="RefLink">78.2-1</span></a>) for a wrapper operation such as <code class="func">SylowSubgroup</code> (<a href="chap39.html#X7AA351308787544C"><span class="RefLink">39.13-1</span></a>) then a warning is signalled provided the <code class="func">InfoWarning</code> (<a href="chap7.html#X7A28F77C82D6A3E0"><span class="RefLink">7.4-7</span></a>) level is at least <code class="code">1</code>. (Use <code class="func">InstallMethod</code> (<a href="chap78.html#X837EFDAB7BEF290B"><span class="RefLink">78.2-1</span></a>) in order to suppress the warning.)</p>
<p><a id="X78D4D0FF780C8A85" name="X78D4D0FF780C8A85"></a></p>
<h4>85.2 <span class="Heading">In Parent Attributes</span></h4>
<p><a id="X7C0E62D8813A4EE6" name="X7C0E62D8813A4EE6"></a></p>
<h5>85.2-1 InParentFOA</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ InParentFOA</code>( <var class="Arg">name</var>, <var class="Arg">super</var>, <var class="Arg">sub</var>, <var class="Arg">AorP</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>This section describes how you can add new "in parent attributes" (see <a href="chap31.html#X7B58FDEF80338DD6"><span class="RefLink">31.8</span></a> and <a href="chap31.html#X7CBDD36E7B7BE286"><span class="RefLink">31.7</span></a>). As an example, we describe how <code class="func">Index</code> (<a href="chap39.html#X86DC933779B1CABD"><span class="RefLink">39.3-2</span></a>) and its related functions are implemented.</p>
<p>There are two operations <code class="func">Index</code> (<a href="chap39.html#X86DC933779B1CABD"><span class="RefLink">39.3-2</span></a>) and <code class="code">IndexOp</code>, and an attribute <code class="code">IndexInParent</code>. They are created together as shown below, and after they have been created, methods need be installed only for <code class="code">IndexOp</code>. In the creation process, <code class="code">IndexInParent</code> already gets one default method installed (in addition to the usual system getter of each attribute, see <a href="chap13.html#X7C701DBF7BAE649A"><span class="RefLink">13.5</span></a>), namely <code class="code">D -> IndexOp( Parent( D ), D )</code>.</p>
<p>The operation <code class="func">Index</code> (<a href="chap39.html#X86DC933779B1CABD"><span class="RefLink">39.3-2</span></a>) proceeds as follows.</p>
<ul>
<li><p>If it is called with the two arguments <var class="Arg">super</var> and <var class="Arg">sub</var>, and if <code class="code">HasParent( <var class="Arg">sub</var> )</code> and <code class="code">IsIdenticalObj( <var class="Arg">super</var>, Parent( <var class="Arg">sub</var> ) )</code> are <code class="keyw">true</code>, <code class="code">IndexInParent</code> is called with argument <var class="Arg">sub</var>, and the result is returned.</p>
</li>
<li><p>Otherwise, <code class="code">IndexOp</code> is called with the same arguments that <code class="func">Index</code> (<a href="chap39.html#X86DC933779B1CABD"><span class="RefLink">39.3-2</span></a>) was called with, and the result is returned.</p>
</li>
</ul>
<p>(Note that it is in principle possible to install even <code class="func">Index</code> (<a href="chap39.html#X86DC933779B1CABD"><span class="RefLink">39.3-2</span></a>) and <code class="code">IndexOp</code> methods for a number of arguments different from two, with <code class="func">InstallOtherMethod</code> (<a href="chap78.html#X7D2C12DB841CE539"><span class="RefLink">78.2-2</span></a>), see <a href="chap79.html#X7A38E7E87CCCEDD1"><span class="RefLink">79.3</span></a>).</p>
<p>The call of <code class="func">InParentFOA</code> declares the operations and the attribute as described above, with names <var class="Arg">name</var>, <var class="Arg">name</var><code class="code">Op</code>, and <var class="Arg">name</var><code class="code">InParent</code>. <var class="Arg">super-req</var> and <var class="Arg">sub-req</var> specify the required filters for the first and second argument of the operation <var class="Arg">name</var><code class="code">Op</code>, which are needed to create this operation with <code class="func">DeclareOperation</code> (<a href="chap79.html#X843F48137B899BC3"><span class="RefLink">79.18-6</span></a>). <var class="Arg">sub-req</var> is also the required filter for the corresponding attribute <var class="Arg">name</var><code class="code">InParent</code>; note that <code class="func">HasParent</code> (<a href="chap31.html#X7BC856CC7F116BB0"><span class="RefLink">31.7-1</span></a>) is <em>not</em> required for the argument <var class="Arg">U</var> of <var class="Arg">name</var><code class="code">InParent</code>, because even without a parent stored, <code class="code">Parent( <var class="Arg">U</var> )</code> is legal, meaning <var class="Arg">U</var> itself (see <a href="chap31.html#X7CBDD36E7B7BE286"><span class="RefLink">31.7</span></a>). The fourth argument must be <code class="func">DeclareProperty</code> (<a href="chap79.html#X7F4602F082682A04"><span class="RefLink">79.18-4</span></a>) if <var class="Arg">name</var><code class="code">InParent</code> takes only boolean values (for example in the case <code class="code">IsNormalInParent</code>), and <code class="func">DeclareAttribute</code> (<a href="chap79.html#X7A00FC8A7A677A56"><span class="RefLink">79.18-3</span></a>) otherwise.</p>
<p>For example, to set up the three objects <code class="func">Index</code> (<a href="chap39.html#X86DC933779B1CABD"><span class="RefLink">39.3-2</span></a>), <code class="code">IndexOp</code>, and <code class="code">IndexInParent</code> together, the declaration file <code class="file">lib/domain.gd</code> contains the following line of code.</p>
<div class="example"><pre>
InParentFOA( "Index", IsGroup, IsGroup, DeclareAttribute );
</pre></div>
<p>Note that no methods need be installed for <code class="func">Index</code> (<a href="chap39.html#X86DC933779B1CABD"><span class="RefLink">39.3-2</span></a>) and <code class="code">IndexInParent</code>.</p>
<p><a id="X7CD4A0867BD825F7" name="X7CD4A0867BD825F7"></a></p>
<h4>85.3 <span class="Heading">Operation Functions</span></h4>
<p>Chapter <a href="chap41.html#X87115591851FB7F4"><span class="RefLink">41</span></a> and, in particular, the Section <a href="chap41.html#X83661AFD7B7BD1D9"><span class="RefLink">41.1</span></a> explain that certain operations such as <a href="chap41.html#X81E0FF0587C54543"><span class="RefLink">41.4</span></a>), besides their usual usage with arguments <var class="Arg">G</var>, <var class="Arg">D</var>, and <var class="Arg">opr</var>, can also be applied to an external set (<span class="SimpleMath">G</span>-set), in which case they can be interpreted as attributes. Moreover, they can also be interpreted as attributes for permutation groups, meaning the natural action on the set of its moved points.</p>
<p>The definition of <a href="chap41.html#X81E0FF0587C54543"><span class="RefLink">41.4</span></a> says that a method should be a function with arguments <var class="Arg">G</var>, <var class="Arg">D</var>, <var class="Arg">gens</var>, <var class="Arg">oprs</var>, and <var class="Arg">opr</var>, as in the case of the operation <code class="func">ExternalSet</code> (<a href="chap41.html#X7C90F648793E47DD"><span class="RefLink">41.12-2</span></a>) when specified via <var class="Arg">gens</var> and <var class="Arg">oprs</var> (see <a href="chap41.html#X7FD3D2D2788709B7"><span class="RefLink">41.12</span></a>). All other syntax variants allowed for <a href="chap41.html#X81E0FF0587C54543"><span class="RefLink">41.4</span></a> (e.g., leaving out <var class="Arg">gens</var> and <var class="Arg">oprs</var>) are handled by default methods.</p>
<p>The default methods for <a href="chap41.html#X81E0FF0587C54543"><span class="RefLink">41.4</span></a> support the following behaviour.</p>
<ol>
<li><p>If the only argument is an external set <var class="Arg">xset</var> and the attribute tester <code class="code">HasOrbits( <var class="Arg">xset</var> )</code> returns <code class="keyw">true</code>, the stored value of that attribute is returned.</p>
</li>
<li><p>If the only argument is an external set <var class="Arg">xset</var> and the attribute value is not known, the default arguments are obtained from the data of <var class="Arg">xset</var>.</p>
</li>
<li><p>If <var class="Arg">gens</var> and <var class="Arg">oprs</var> are not specified, <var class="Arg">gens</var> is set to <code class="code">Pcgs( <var class="Arg">G</var> )</code> if <code class="code">CanEasilyComputePcgs( <var class="Arg">G</var> )</code> is <code class="keyw">true</code>, and to <code class="code">GeneratorsOfGroup( <var class="Arg">G</var> )</code> otherwise; <var class="Arg">oprs</var> is set to <var class="Arg">gens</var>.</p>
</li>
<li><p>The default value of <var class="Arg">opr</var> is <code class="func">OnPoints</code> (<a href="chap41.html#X7FE417DD837987B4"><span class="RefLink">41.2-1</span></a>).</p>
</li>
<li><p>In the case of an operation of a permutation group <var class="Arg">G</var> on <code class="code">MovedPoints( <var class="Arg">G</var> )</code> via <code class="func">OnPoints</code> (<a href="chap41.html#X7FE417DD837987B4"><span class="RefLink">41.2-1</span></a>), if the attribute tester <code class="code">HasOrbits( <var class="Arg">G</var> )</code> returns <code class="keyw">true</code>, the stored attribute value is returned.</p>
</li>
<li><p>The operation is called as <code class="code"><var class="Arg">result</var>:= Orbits( <var class="Arg">G</var>, <var class="Arg">D</var>, <var class="Arg">gens</var>, <var class="Arg">oprs</var>, <var class="Arg">opr</var> )</code>.</p>
</li>
<li><p>In the case of an external set <var class="Arg">xset</var> or a permutation group <var class="Arg">G</var> in its natural action, the attribute setter is called to store <var class="Arg">result</var>.</p>
</li>
<li><p><var class="Arg">result</var> is returned.</p>
</li>
</ol>
<p>The declaration of operations that match the above pattern is done as follows.</p>
<p><a id="X7CA3826A7EBDE208" name="X7CA3826A7EBDE208"></a></p>
<h5>85.3-1 OrbitsishOperation</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ OrbitsishOperation</code>( <var class="Arg">name</var>, <var class="Arg">reqs</var>, <var class="Arg">usetype</var>, <var class="Arg">AorP</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>declares an attribute <code class="code">op</code>, with name <var class="Arg">name</var>. The second argument <var class="Arg">reqs</var> specifies the list of required filters for the usual (five-argument) methods that do the real work.</p>
<p>If the third argument <var class="Arg">usetype</var> is <code class="keyw">true</code>, the function call <code class="code">op( xset )</code> will –if the value of <code class="code">op</code> for <code class="code">xset</code> is not yet known– delegate to the five-argument call of <code class="code">op</code> with second argument <code class="code">xset</code> rather than with <code class="code">D</code>. This allows certain methods for <code class="code">op</code> to make use of the type of <code class="code">xset</code>, in which the types of the external subsets of <code class="code">xset</code> and of the external orbits in <code class="code">xset</code> are stored. (This is used to avoid repeated calls of <code class="func">NewType</code> (<a href="chap79.html#X7CE39E9478AEC826"><span class="RefLink">79.8-1</span></a>) in functions like <code class="code">ExternalOrbits( xset )</code>, which call <code class="code">ExternalOrbit( xset, pnt )</code> for several values of <code class="code">pnt</code>.)</p>
<p>For property testing functions such as <code class="func">IsTransitive</code> (<a href="chap41.html#X79B15750851828CB"><span class="RefLink">41.10-1</span></a>), the fourth argument <var class="Arg">AorP</var> must be <code class="func">NewProperty</code> (<a href="chap79.html#X7F2D6FD979FE23DD"><span class="RefLink">79.3-2</span></a>), otherwise it must be <code class="func">NewAttribute</code> (<a href="chap79.html#X7B9654807858A3B0"><span class="RefLink">79.3-1</span></a>); in the former case, a property is returned, in the latter case an attribute that is not a property.</p>
<p>For example, to set up the operation <code class="func">Orbits</code> (<a href="chap41.html#X81E0FF0587C54543"><span class="RefLink">41.4</span></a>), the declaration file <code class="file">lib/oprt.gd</code> contains the following line of code:</p>
<div class="example"><pre>
OrbitsishOperation( "Orbits", OrbitsishReq, false, NewAttribute );
</pre></div>
<p>The global variable <code class="code">OrbitsishReq</code> contains the standard requirements</p>
<div class="example"><pre>
OrbitsishReq := [ IsGroup, IsList,
IsList,
IsList,
IsFunction ];
</pre></div>
<p>which are usually entered in calls to <code class="func">OrbitsishOperation</code>.</p>
<p>The new operation, e.g., <code class="func">Orbits</code> (<a href="chap41.html#X81E0FF0587C54543"><span class="RefLink">41.4</span></a>), can be called either as <code class="code">Orbits( <var class="Arg">xset</var> )</code> for an external set <var class="Arg">xset</var>, or as <code class="code">Orbits( <var class="Arg">G</var> )</code> for a permutation group <var class="Arg">G</var>, meaning the orbits on the moved points of <var class="Arg">G</var> via <code class="func">OnPoints</code> (<a href="chap41.html#X7FE417DD837987B4"><span class="RefLink">41.2-1</span></a>), or as</p>
<p><code class="code">Orbits( <var class="Arg">G</var>, <var class="Arg">Omega</var>[, <var class="Arg">gens</var>, <var class="Arg">acts</var>][, <var class="Arg">act</var>] )</code>,</p>
<p>with a group <var class="Arg">G</var>, a domain or list <var class="Arg">Omega</var>, generators <var class="Arg">gens</var> of <var class="Arg">G</var>, and corresponding elements <var class="Arg">acts</var> that act on <var class="Arg">Omega</var> via the function <var class="Arg">act</var>; the default of <var class="Arg">gens</var> and <var class="Arg">acts</var> is a list of group generators of <var class="Arg">G</var>, the default of <var class="Arg">act</var> is <code class="func">OnPoints</code> (<a href="chap41.html#X7FE417DD837987B4"><span class="RefLink">41.2-1</span></a>).</p>
<p>Only methods for the five-argument version need to be installed for doing the real work. (And of course methods for one argument in case one wants to define a new meaning of the attribute.)</p>
<p><a id="X7B23C48482ADB237" name="X7B23C48482ADB237"></a></p>
<h5>85.3-2 OrbitishFO</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ OrbitishFO</code>( <var class="Arg">name</var>, <var class="Arg">reqs</var>, <var class="Arg">famrel</var>, <var class="Arg">usetype</var>, <var class="Arg">realenum</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>is used to create operations like <code class="func">Orbit</code> (<a href="chap41.html#X80E0234E7BD79409"><span class="RefLink">41.4-1</span></a>). This function is analogous to <code class="func">OrbitsishOperation</code> (<a href="chap85.html#X7CA3826A7EBDE208"><span class="RefLink">85.3-1</span></a>), but for operations <var class="Arg">orbish</var> like <code class="code">Orbit( <var class="Arg">G</var>, <var class="Arg">Omega</var>, <var class="Arg">pnt</var> )</code>. Since the return values of these operations depend on the additional argument <var class="Arg">pnt</var>, there is no associated attribute.</p>
<p>The call of <code class="func">OrbitishFO</code> declares a wrapper function and its operation, with names <var class="Arg">name</var> and <var class="Arg">name</var><code class="code">Op</code>.</p>
<p>The second argument <var class="Arg">reqs</var> specifies the list of required filters for the operation <var class="Arg">name</var><code class="code">Op</code>.</p>
<p>The third argument <var class="Arg">famrel</var> is used to test the family relation between the second and third argument of <code class="code"><var class="Arg">name</var>( <var class="Arg">G</var>, <var class="Arg">D</var>, <var class="Arg">pnt</var> )</code>. For example, <var class="Arg">famrel</var> is <code class="code">IsCollsElms</code> in the case of <code class="func">Orbit</code> (<a href="chap41.html#X80E0234E7BD79409"><span class="RefLink">41.4-1</span></a>) because <var class="Arg">pnt</var> must be an element of <var class="Arg">D</var>. Similarly, in the call <code class="code">Blocks( <var class="Arg">G</var>, <var class="Arg">D</var>, <var class="Arg">seed</var> )</code>, <var class="Arg">seed</var> must be a subset of <var class="Arg">D</var>, and the family relation must be <code class="func">IsIdenticalObj</code> (<a href="chap12.html#X7961183378DFB902"><span class="RefLink">12.5-1</span></a>).</p>
<p>The fourth argument <var class="Arg">usetype</var> serves the same purpose as in the case of <code class="func">OrbitsishOperation</code> (<a href="chap85.html#X7CA3826A7EBDE208"><span class="RefLink">85.3-1</span></a>). <var class="Arg">usetype</var> can also be an attribute, such as <code class="code">BlocksAttr</code> or <code class="code">MaximalBlocksAttr</code>. In this case, if only one of the two arguments <var class="Arg">Omega</var> and <var class="Arg">pnt</var> is given, blocks with no seed are computed, they are stored as attribute values according to the rules of <code class="func">OrbitsishOperation</code> (<a href="chap85.html#X7CA3826A7EBDE208"><span class="RefLink">85.3-1</span></a>).</p>
<p>If the 5th argument is set to <code class="keyw">true</code>, the action for an external set should use the enumerator, otherwise it uses the <code class="func">HomeEnumerator</code> (<a href="chap41.html#X86A0CC1479A5932A"><span class="RefLink">41.12-5</span></a>) value. This will make a difference for external orbits as part of a larger domain.</p>
<p><a id="X834E92F07DD0BF04" name="X834E92F07DD0BF04"></a></p>
<h5>85.3-3 <span class="Heading">Example: Orbit and OrbitOp</span></h5>
<p>For example, to setup the function <code class="func">Orbit</code> (<a href="chap41.html#X80E0234E7BD79409"><span class="RefLink">41.4-1</span></a>) and its operation <code class="code">OrbitOp</code>, the declaration file <code class="file">lib/oprt.gd</code> contains the following line of code:</p>
<div class="example"><pre>
OrbitishFO( "Orbit", OrbitishReq, IsCollsElms, false, false );
</pre></div>
<p>The variable <code class="code">OrbitishReq</code> contains the standard requirements</p>
<div class="example"><pre>
OrbitishReq := [ IsGroup, IsList, IsObject,
IsList,
IsList,
IsFunction ];
</pre></div>
<p>which are usually entered in calls to <code class="func">OrbitishFO</code> (<a href="chap85.html#X7B23C48482ADB237"><span class="RefLink">85.3-2</span></a>).</p>
<p>The relation test via <var class="Arg">famrel</var> is used to provide a uniform construction of the wrapper functions created by <code class="func">OrbitishFO</code> (<a href="chap85.html#X7B23C48482ADB237"><span class="RefLink">85.3-2</span></a>), in spite of the different syntax of the specific functions. For example, <code class="func">Orbit</code> (<a href="chap41.html#X80E0234E7BD79409"><span class="RefLink">41.4-1</span></a>) admits the calls <code class="code">Orbit( <var class="Arg">G</var>, <var class="Arg">D</var>, <var class="Arg">pnt</var>, <var class="Arg">opr</var> )</code> and <code class="code">Orbit( <var class="Arg">G</var>, <var class="Arg">pnt</var>, <var class="Arg">opr</var> )</code>, i.e., the second argument <var class="Arg">D</var> may be omitted; <code class="func">Blocks</code> (<a href="chap41.html#X84FE699F85371643"><span class="RefLink">41.11-1</span></a>) admits the calls <code class="code">Blocks( <var class="Arg">G</var>, <var class="Arg">D</var>, <var class="Arg">seed</var>, <var class="Arg">opr</var> )</code> and <code class="code">Blocks( <var class="Arg">G</var>, <var class="Arg">D</var>, <var class="Arg">opr</var> )</code>, i.e., the third argument may be omitted. The translation to the appropriate call of <code class="code">OrbitOp</code> or <code class="code">BlocksOp</code>, for either operation with five or six arguments, is handled via <var class="Arg">famrel</var>.</p>
<p>As a consequence, there must not only be methods for <code class="code">OrbitOp</code> with the six arguments corresponding to <code class="code">OrbitishReq</code>, but also methods for only five arguments (i.e., without <var class="Arg">D</var>). Plenty of examples are contained in the implementation file <code class="file">lib/oprt.gi</code>.</p>
<p>In order to handle a few special cases (currently <code class="func">Blocks</code> (<a href="chap41.html#X84FE699F85371643"><span class="RefLink">41.11-1</span></a>) and <code class="func">MaximalBlocks</code> (<a href="chap41.html#X79936EB97AAD1144"><span class="RefLink">41.11-2</span></a>)), also the following form of <code class="func">OrbitishFO</code> (<a href="chap85.html#X7B23C48482ADB237"><span class="RefLink">85.3-2</span></a>) is supported.</p>
<p><code class="code">OrbitishFO( <var class="Arg">name</var>, <var class="Arg">reqs</var>, <var class="Arg">famrel</var>, <var class="Arg">attr</var> )</code></p>
<p>The functions in question depend upon an argument <var class="Arg">seed</var>, so they cannot be regarded as attributes. However, they are most often called without giving <var class="Arg">seed</var>, meaning "choose any minimal resp. maximal block system". In this case, the result can be stored as the value of the attribute <var class="Arg">attr</var> that was entered as fourth argument of <code class="func">OrbitishFO</code> (<a href="chap85.html#X7B23C48482ADB237"><span class="RefLink">85.3-2</span></a>). This attribute is considered by a call <code class="code">Blocks( <var class="Arg">G</var>, <var class="Arg">D</var>, <var class="Arg">opr</var> )</code> (i.e., without <var class="Arg">seed</var>) in the same way as <code class="func">Orbits</code> (<a href="chap41.html#X81E0FF0587C54543"><span class="RefLink">41.4</span></a>) considers <code class="code">OrbitsAttr</code>.</p>
<p>To set this up, the declaration file <code class="file">lib/oprt.gd</code> contains the following lines:</p>
<div class="example"><pre>
DeclareAttribute( "BlocksAttr", IsExternalSet );
OrbitishFO( "Blocks",
[ IsGroup, IsList, IsList,
IsList,
IsList,
IsFunction ], IsIdenticalObj, BlocksAttr, true );
</pre></div>
<p>And this extraordinary FOA triple works as follows:</p>
<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">s4 := Group((1,2,3,4),(1,2));;</span>
<span class="GAPprompt">gap></span> <span class="GAPinput">Blocks( s4, MovedPoints(s4), [1,2] );</span>
[ [ 1, 2, 3, 4 ] ]
<span class="GAPprompt">gap></span> <span class="GAPinput">Tester( BlocksAttr )( s4 );</span>
false
<span class="GAPprompt">gap></span> <span class="GAPinput">Blocks( s4, MovedPoints(s4) ); </span>
[ [ 1, 2, 3, 4 ] ]
<span class="GAPprompt">gap></span> <span class="GAPinput">Tester( BlocksAttr )( s4 ); BlocksAttr( s4 );</span>
true
[ [ 1, 2, 3, 4 ] ]
</pre></div>
<div class="chlinkprevnextbot"> <a href="chap0.html">[Top of Book]</a> <a href="chap0.html#contents">[Contents]</a> <a href="chap84.html">[Previous Chapter]</a> <a href="chap86.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="chap11.html">11</a> <a href="chap12.html">12</a> <a href="chap13.html">13</a> <a href="chap14.html">14</a> <a href="chap15.html">15</a> <a href="chap16.html">16</a> <a href="chap17.html">17</a> <a href="chap18.html">18</a> <a href="chap19.html">19</a> <a href="chap20.html">20</a> <a href="chap21.html">21</a> <a href="chap22.html">22</a> <a href="chap23.html">23</a> <a href="chap24.html">24</a> <a href="chap25.html">25</a> <a href="chap26.html">26</a> <a href="chap27.html">27</a> <a href="chap28.html">28</a> <a href="chap29.html">29</a> <a href="chap30.html">30</a> <a href="chap31.html">31</a> <a href="chap32.html">32</a> <a href="chap33.html">33</a> <a href="chap34.html">34</a> <a href="chap35.html">35</a> <a href="chap36.html">36</a> <a href="chap37.html">37</a> <a href="chap38.html">38</a> <a href="chap39.html">39</a> <a href="chap40.html">40</a> <a href="chap41.html">41</a> <a href="chap42.html">42</a> <a href="chap43.html">43</a> <a href="chap44.html">44</a> <a href="chap45.html">45</a> <a href="chap46.html">46</a> <a href="chap47.html">47</a> <a href="chap48.html">48</a> <a href="chap49.html">49</a> <a href="chap50.html">50</a> <a href="chap51.html">51</a> <a href="chap52.html">52</a> <a href="chap53.html">53</a> <a href="chap54.html">54</a> <a href="chap55.html">55</a> <a href="chap56.html">56</a> <a href="chap57.html">57</a> <a href="chap58.html">58</a> <a href="chap59.html">59</a> <a href="chap60.html">60</a> <a href="chap61.html">61</a> <a href="chap62.html">62</a> <a href="chap63.html">63</a> <a href="chap64.html">64</a> <a href="chap65.html">65</a> <a href="chap66.html">66</a> <a href="chap67.html">67</a> <a href="chap68.html">68</a> <a href="chap69.html">69</a> <a href="chap70.html">70</a> <a href="chap71.html">71</a> <a href="chap72.html">72</a> <a href="chap73.html">73</a> <a href="chap74.html">74</a> <a href="chap75.html">75</a> <a href="chap76.html">76</a> <a href="chap77.html">77</a> <a href="chap78.html">78</a> <a href="chap79.html">79</a> <a href="chap80.html">80</a> <a href="chap81.html">81</a> <a href="chap82.html">82</a> <a href="chap83.html">83</a> <a href="chap84.html">84</a> <a href="chap85.html">85</a> <a href="chap86.html">86</a> <a href="chap87.html">87</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>
|