From 5fae321a89149eb1e644b4cd97e37bda1660ed8f Mon Sep 17 00:00:00 2001
From: Finn <finneganlbuck@gmail.com>
Date: Wed, 30 Mar 2022 15:58:24 +0100
Subject: [PATCH] Added documentation.

---
 doc/oper.xml    | 80 +++++++++++++++++++++++++++++++++++++++++++++++++
 doc/z-chap2.xml |  2 ++
 2 files changed, 82 insertions(+)

diff --git a/doc/oper.xml b/doc/oper.xml
index 324951db2..9e0db3449 100644
--- a/doc/oper.xml
+++ b/doc/oper.xml
@@ -2227,3 +2227,83 @@ true
   </Description>
 </ManSection>
 <#/GAPDoc>
+
+<#GAPDoc Label="AmalgamDigraphs">
+<ManSection>
+  <Oper Name="AmalgamDigraphs" Arg="D1, D2,
+    subdigraphVertices1, subdigraphVertices2"/>
+  <Returns>An immutable digraph and a record.</Returns>
+  <Description>
+
+  <C>AmalgamDigraphs</C> takes as input two digraphs <A>D1</A> and <A>D2</A>
+  and two lists of vertices <A>subdigraphVertices1</A> and
+  <A>subdigraphVertices2</A>, which correspond to two identical subdigraphs
+  of <A>D1</A> and <A>D2</A>. It returns a new digraph, the <E>amalgam
+  digraph</E> <C>AD</C>, which consists of <A>D1</A> and <A>D2</A> joined
+  together by their common subdigraph in such a way that the edge connectivity
+  between the vertices of <C>AD</C> matches the edge connectivity of
+  <A>D1</A> and <A>D2</A>.<P/>
+
+  It returns a <E>tuple</E> of size two, with the first element being
+  <C>AD</C> and the second element being <C>map</C>, which is a record which
+  maps each vertex's number in <A>D2</A> to the corresponding vertex's number
+  in <C>AD</C>. The mapping of the vertices of <A>D1</A> can be seen as the
+  <E>identity mapping</E>.
+
+  <Example><![CDATA[
+gap> T := Digraph([[2, 3], [1, 3], [1, 2]]);;
+gap> A := AmalgamDigraphs(T, T, [1, 2], [1, 2]);
+[ <immutable digraph with 4 vertices, 10 edges>, 
+  rec( 1 := 1, 2 := 2, 3 := 4 ) ]
+gap> A := AmalgamDigraphs(A[1], T, [1, 2], [1, 2]);
+[ <immutable digraph with 5 vertices, 14 edges>, 
+  rec( 1 := 1, 2 := 2, 3 := 5 ) ]
+gap> P := PetersenGraph();;
+gap> G := Digraph([[2, 3, 4], [1, 3], [1, 2, 5],
+> [1, 6], [3, 6], [4, 5]]);;
+gap> A := AmalgamDigraphs(P, G, [1, 2, 7, 10, 5], [1, 3, 5, 6, 4]);
+[ <immutable digraph with 11 vertices, 34 edges>, 
+  rec( 1 := 1, 2 := 11, 3 := 2, 4 := 5, 5 := 7, 6 := 10 ) ]
+]]></Example>
+</Description>
+</ManSection>
+<#/GAPDoc>
+
+<#GAPDoc Label="AmalgamDigraphsIsomorphic">
+<ManSection>
+  <Oper Name="AmalgamDigraphsIsomorphic" Arg="D1, D2,
+    subdigraphVertices1, subdigraphVertices2"/>
+  <Returns>An immutable digraph and a record.</Returns>
+  <Description>
+
+  <C>AmalgamDigraphsIsomorphic</C> is meant to function very similarly to
+  <C>AmalgamDigraphs</C>. The difference is that in <C>AmalgamDigraphs</C>
+  <A>subdigraphVertices1</A> and <A>subdigraphVertices2</A> need not
+  necessarily describe identical subdigraphs of <A>D1</A> and <A>D2</A>,
+  but need only describe subdigraphs that are isomorphic to one another.
+  <C>AmalgamDigraphsIsomorphic</C> rearranges the entries of
+  <A>subdigraphVertices2</A> to obtain <C>newSubdigraphVertices2</C>
+  in such a way that the induced subdigraph in <A>D2</A> with the
+  vertices <C>newSubdigraphVertices2</C> is identical to the induced
+  subdigraph in <A>D1</A> with the vertices <C>subdigraphVertices1</C>.
+  <C>AmalgamDigraphsIsomorphic</C> then calls <C>AmalgamDigraphs</C>
+  with <C>newSubdigraphVertices2</C> in the place of
+  <A>subdigraphVertices2</A>.
+
+  <Example><![CDATA[
+gap> P := PetersenGraph();;
+gap> G := Digraph([[2, 3, 4], [1, 3],
+> [1, 2, 5], [1, 6], [3, 6], [4, 5]]);;
+gap> A := AmalgamDigraphs(P, G, [1, 2, 7, 10, 5], [1, 3, 5, 6, 4]);
+[ <immutable digraph with 11 vertices, 34 edges>, 
+  rec( 1 := 1, 2 := 11, 3 := 2, 4 := 5, 5 := 7, 6 := 10 ) ]
+gap> A := AmalgamDigraphsIsomorphic(P, G,
+> [1, 2, 7, 10, 5], [1, 4, 6, 3, 5]);
+[ <immutable digraph with 11 vertices, 34 edges>, 
+  rec( 1 := 1, 2 := 11, 3 := 5, 4 := 2, 5 := 10, 6 := 7 ) ]
+gap> A := AmalgamDigraphs(P, G, [1, 2, 7, 10, 5], [1, 4, 6, 3, 5]);
+Error, the two subdigraphs must be equal.
+]]></Example>
+</Description>
+</ManSection>
+<#/GAPDoc>
diff --git a/doc/z-chap2.xml b/doc/z-chap2.xml
index 9de59949e..33a4e3c6e 100644
--- a/doc/z-chap2.xml
+++ b/doc/z-chap2.xml
@@ -74,6 +74,8 @@
     <#Include Label="DistanceDigraph">
     <#Include Label="DigraphClosure">
     <#Include Label="DigraphMycielskian">
+    <#Include Label="AmalgamDigraphs">
+    <#Include Label="AmalgamDigraphsIsomorphic">
   </Section>
 
   <Section><Heading>Random digraphs</Heading>