Implemented ^ operator for digraphs to delegate to OnDigraphs (issue #580) (#876)

* Implemented ^ operator for digraphs to delegate to OnDigraphs (issue #580)

* Added ^ declaration for digraph actions with permutations and transformations

* Fixed formating for lint check

* Added Tests for digraph operator '^'

* Fixed lint formatting for oper.tst file

* Made minor changes to formatting

* Made minor changes to formatting

* Fixed tests formatting

* Fixed tests formatting

* Defined local varibales

* Added documentation

* Updated documentation formating for lint

* Added label and updated it in the manual

* Added a note in documentation for \^

* Made changes based on comments on the PR to the doc and tests

Author: devansh2605

doc/oper.xml

@@ -248,6 +248,8 @@ true
     with <C>OnDigraphs(<A>digraph</A>, AsPermutation(<A>trans</A>))</C>.
     <P/>
 
+    Note: <C>OnDigraphs</C> for a digraph and a permutation or transformation can also be used via the <C>\^</C> operator. <P/>
+
     The <Ref Oper="DigraphVertexLabels"/> of <A>digraph</A> will not be retained
     in the returned digraph. <P/>
 
@@ -278,6 +280,48 @@ true
 </ManSection>
 <#/GAPDoc>
 
+<#GAPDoc Label="\^OperatorOnDigraphs">
+<ManSection>
+  <Oper Name="\^" Arg="digraph, permOrTrans" Label="for a digraph and a permutation or transformation"/>
+  <Returns>A digraph.</Returns>
+  <Description>
+    The <C>^</C> operator acts on digraphs with either a permutation or a transformation.
+    For a digraph <A>digraph</A> and a permutation <A>perm</A>,
+    <C>digraph ^ perm</C> gives the same result as
+    <C>OnDigraphs(digraph, perm)</C> — a digraph whose vertices have been relabelled according to the permutation. <P/>
+
+    Similarly, if the second argument is a transformation <A>trans</A>,
+    then <C>digraph ^ trans</C> calls <C>OnDigraphs(digraph, trans)</C>.
+    This allows a simple way to apply vertex relabelling or transformations directly using the <C>^</C> symbol. <P/>
+
+    <Example><![CDATA[
+gap> D := CycleDigraph(5);
+<immutable cycle digraph with 5 vertices>
+gap> p := (1, 5)(2, 4);;
+gap> D ^ p = DigraphReverse(D);
+true
+gap> OnDigraphs(D, p) = D ^ p;
+true
+gap> idp := ();;
+gap> D ^ idp = D;
+true
+gap> q := (1, 2, 3, 4, 5);;
+gap> (D ^ q) ^ (q ^ -1) = D;
+true
+gap> t := Transformation([2, 3, 4, 5, 1]);;
+gap> D ^ t = OnDigraphs(D, t);
+true
+gap> idt := Transformation([1, 2, 3, 4, 5]);;
+gap> D ^ idt = D;
+true
+gap> M := DigraphMutableCopy(D);;
+gap> M ^ p = OnDigraphs(M, p);
+true
+]]></Example>
+  </Description>
+</ManSection>
+<#/GAPDoc>
+
 <#GAPDoc Label="OnMultiDigraphs">
 <ManSection>
   <Oper Name="OnMultiDigraphs" Arg="digraph, pair"/>

doc/z-chap6.xml

@@ -10,6 +10,7 @@ from} $E_a$ \emph{to} $E_b$. In this case we say that $E_a$ and $E_b$ are
 
   <Section><Heading>Acting on digraphs</Heading>
     <#Include Label="OnDigraphs">
+    <#Include Label="\^OperatorOnDigraphs">
     <#Include Label="OnMultiDigraphs">
     <#Include Label="OnTuplesDigraphs">
   </Section>

gap/oper.gd

@@ -62,6 +62,8 @@ DeclareOperation("DIGRAPHS_GraphProduct", [IsDigraph, IsDigraph, IsFunction]);
 DeclareOperation("SwapDigraphs", [IsMutableDigraph, IsMutableDigraph]);
 
 # 4. Actions . . .
+DeclareOperation("^", [IsDigraph, IsPerm]);
+DeclareOperation("^", [IsDigraph, IsTransformation]);
 DeclareOperation("OnDigraphs", [IsDigraph, IsPerm]);
 DeclareOperation("OnDigraphs", [IsDigraph, IsTransformation]);
 DeclareOperation("OnDigraphsNC", [IsDigraph, IsPerm]);

gap/oper.gi

@@ -1138,6 +1138,16 @@ InstallMethod(DomainForAction, "for a digraph, list or collection and function",
 [IsDigraph, IsListOrCollection, IsFunction],
 ReturnTrue);
 
+# Operator action: D^p  and  D^t
+# Allow D ^ p (digraph and permutation) to call OnDigraphs(D, p)
+# and D ^ t (digraph and transformation) to call OnDigraphs(D, t)
+
+InstallMethod(\^, "digraph acted on by a permutation",
+  [IsDigraph, IsPerm], OnDigraphs);
+
+InstallMethod(\^, "digraph acted on by a transformation",
+  [IsDigraph, IsTransformation], OnDigraphs);
+
 #############################################################################
 # 5. Substructures and quotients
 #############################################################################

tst/standard/oper.tst

@@ -16,6 +16,7 @@
 #@local i1, i2, id, idom, in1, in2, in3, iter, j1, j2, m, m1, m2, mat, n, nbs
 #@local out, out1, out2, out3, p1, p2, path, preorder, qr, r, res, rtclosure, t
 #@local tclosure, u1, u2, x
+#@local p, q, idp, idt, M
 gap> START_TEST("Digraphs package: standard/oper.tst");
 gap> LoadPackage("digraphs", false);;
 
@@ -109,6 +110,30 @@ gap> gr := DigraphRemoveEdge(gr, [2, 1]);
 gap> DigraphEdges(gr);
 [ [ 1, 2 ] ]
 
+# Tests for digraph operator "^" (implements D ^ p and D ^ t using OnDigraphs)
+gap> D := CycleDigraph(5);
+<immutable cycle digraph with 5 vertices>
+gap> p := (1, 5)(2, 4);;
+gap> D ^ p = DigraphReverse(D);
+true
+gap> OnDigraphs(D, p) = D ^ p;
+true
+gap> idp := ();;
+gap> D ^ idp = D;
+true
+gap> q := (1, 2, 3, 4, 5);;
+gap> (D ^ q) ^ (q ^ -1) = D;
+true
+gap> t := Transformation([2, 3, 4, 5, 1]);;
+gap> D ^ t = OnDigraphs(D, t);
+true
+gap> idt := Transformation([1, 2, 3, 4, 5]);;
+gap> D ^ idt = D;
+true
+gap> M := DigraphMutableCopy(D);;
+gap> M ^ p = OnDigraphs(M, p);
+true
+
 #  OnDigraphs: for a digraph and a perm
 gap> gr := Digraph([[2], [1], [3]]);
 <immutable digraph with 3 vertices, 3 edges>