Add distance metrics DigraphRadius, DigraphCentre, and DigraphPeriphery

doc/attr.xml

@@ -944,21 +944,44 @@ gap> DigraphShortestDistances(D);
 </ManSection>
 <#/GAPDoc>
 
+<#GAPDoc Label="DigraphEccentricities">
+<ManSection>
+  <Attr Name="DigraphEccentricities" Arg="digraph"/>
+  <Returns>A list of non-negative integers or <C>fail</C>.</Returns>
+  <Description>
+    This function returns a list of the eccentricities of each vertex in
+    <A>digraph</A>. If <A>digraph</A> is strongly connected and has at least 1
+    vertex, then the <E>eccentricity</E> of a vertex <A>v</A> is the maximum
+    shortest distance between <A>v</A> and any other vertex; see
+    <Ref Oper="DigraphShortestDistance"
+    Label="for a digraph and two vertices"/>. <P/>
+
+    If <A>digraph</A> is not strongly connected, then the value <C>fail</C>
+    is returned.
+    <Example><![CDATA[
+gap> DigraphEccentricities(Digraph([[2], [1, 3], [2]]));
+[ 2, 1, 2 ]
+gap> DigraphEccentricities(CycleDigraph(3));
+[ 2, 2, 2 ]
+gap> DigraphEccentricities(ChainDigraph(2));
+fail
+gap> DigraphEccentricities(EmptyDigraph(0));
+fail
+]]></Example>
+  </Description>
+</ManSection>
+<#/GAPDoc>
+
 <#GAPDoc Label="DigraphDiameter">
 <ManSection>
   <Attr Name="DigraphDiameter" Arg="digraph"/>
-  <Returns>An integer or <C>fail</C>.</Returns>
+  <Returns>A non-negative integer or <C>fail</C>.</Returns>
   <Description>
-    This function returns the diameter of the digraph <A>digraph</A>.
-    <P/>
-
-    If a digraph <A>digraph</A> is strongly connected and has at least 1
-    vertex, then the <E>diameter</E> is the maximum shortest distance between
-    any pair of distinct vertices. Otherwise then the diameter of
-    <A>digraph</A> is undefined, and this function returns the value
-    <C>fail</C>. <P/>
-
-    See <Ref Attr="DigraphShortestDistances"/>. <P/>
+    This function returns the <E>diameter</E> of <A>digraph</A>. If
+    <A>digraph</A> is strongly connected and has at least 1 vertex, then its
+    diameter is the maximum eccentricity over its vertices; see
+    <Ref Attr="DigraphEccentricities"/>. Otherwise, the diameter of
+    <A>digraph</A> is undefined, and the value <C>fail</C> is returned.
     <Example><![CDATA[
 gap> D := Digraph([[2], [3], [4, 5], [5], [1, 2, 3, 4, 5]]);
 <immutable digraph with 5 vertices, 10 edges>
@@ -979,6 +1002,75 @@ gap> DigraphDiameter(D);
 </ManSection>
 <#/GAPDoc>
 
+<#GAPDoc Label="DigraphRadius">
+<ManSection>
+  <Attr Name="DigraphRadius" Arg="digraph"/>
+  <Returns>A non-negative integer or <C>fail</C>.</Returns>
+  <Description>
+    This function returns the <E>radius</E> of <A>digraph</A>. If
+    <A>digraph</A> is strongly connected and has at least 1 vertex, then its
+    radius is the minimum eccentricity over its vertices; see
+    <Ref Attr="DigraphEccentricities"/>. Otherwise, the radius of
+    <A>digraph</A> is undefined, and the value <C>fail</C> is returned.
+    <Example><![CDATA[
+gap> D := CycleDigraph(5);;
+gap> DigraphRadius(D);
+4
+gap> D := CompleteDigraph(5);;
+gap> DigraphRadius(D);
+1
+]]></Example>
+  </Description>
+</ManSection>
+<#/GAPDoc>
+
+<#GAPDoc Label="DigraphCentre">
+<ManSection>
+  <Attr Name="DigraphCentre" Arg="digraph"/>
+  <Attr Name="DigraphCenter" Arg="digraph"/>
+  <Returns>A list of vertices or <C>fail</C>.</Returns>
+  <Description>
+    This function returns the <E>centre</E> of <A>digraph</A>. If <A>digraph</A> is
+    strongly connected and has at least 1 vertex, then its centre is the
+    set of all vertices whose eccentricities equal the <E>radius</E> of
+    <A>digraph</A>; see <Ref Attr="DigraphRadius"/>. Otherwise, the
+    centre of <A>digraph</A> is undefined, and the value <C>fail</C> is
+    returned. <P/>
+
+    <Ref Attr="DigraphCenter"/> is a synonym for <Ref Attr="DigraphCentre"/>.
+    <Example><![CDATA[
+gap> D := Digraph([[2], [1, 3], [2, 4], [3]]);;
+gap> DigraphRadius(D);
+2
+gap> DigraphCentre(D);
+[ 2, 3 ]
+]]></Example>
+  </Description>
+</ManSection>
+<#/GAPDoc>
+
+<#GAPDoc Label="DigraphPeriphery">
+<ManSection>
+  <Attr Name="DigraphPeriphery" Arg="digraph"/>
+  <Returns>A list of vertices or <C>fail</C>.</Returns>
+  <Description>
+    This function returns the <E>periphery</E> of <A>digraph</A>. If
+    <A>digraph</A> is strongly connected and has at least 1 vertex, then its
+    periphery is the set of all vertices whose eccentricities equal the
+    <E>diameter</E> of <A>digraph</A>; see <Ref Attr="DigraphDiameter"/>.
+    Otherwise, the periphery of <A>digraph</A> is undefined, and the
+    value <C>fail</C> is returned.
+    <Example><![CDATA[
+gap> D := Digraph([[2], [1, 3], [2, 4], [3]]);;
+gap> DigraphDiameter(D);
+3
+gap> DigraphPeriphery(D);
+[ 1, 4 ]
+]]></Example>
+  </Description>
+</ManSection>
+<#/GAPDoc>
+
 <#GAPDoc Label="DigraphGirth">
 <ManSection>
   <Attr Name="DigraphGirth" Arg="digraph"/>

doc/z-chap4.xml

@@ -47,7 +47,11 @@
   </Section>
 
   <Section><Heading>Reachability and connectivity</Heading>
+    <#Include Label="DigraphEccentricities">
     <#Include Label="DigraphDiameter">
+    <#Include Label="DigraphRadius">
+    <#Include Label="DigraphCentre">
+    <#Include Label="DigraphPeriphery">
     <#Include Label="DigraphShortestDistance">
     <#Include Label="DigraphShortestDistances">
     <#Include Label="DigraphLongestDistanceFromVertex">

gap/attr.gd

@@ -49,6 +49,11 @@ DeclareAttribute("DigraphDegeneracyOrdering", IsDigraph);
 DeclareAttribute("DIGRAPHS_Degeneracy", IsDigraph);
 DeclareAttribute("DigraphShortestDistances", IsDigraph);
 DeclareAttribute("DigraphDiameter", IsDigraph);
+DeclareAttribute("DigraphEccentricities", IsDigraph);
+DeclareAttribute("DigraphRadius", IsDigraph);
+DeclareAttribute("DigraphCentre", IsDigraph);
+DeclareSynonymAttr("DigraphCenter", DigraphCentre);
+DeclareAttribute("DigraphPeriphery", IsDigraph);
 DeclareAttribute("DigraphGirth", IsDigraph);
 DeclareAttribute("DigraphOddGirth", IsDigraph);
 DeclareAttribute("DigraphUndirectedGirth", IsDigraph);

gap/attr.gi

@@ -1508,6 +1508,42 @@ function(D)
   return DIGRAPH_DIAMETER(D);
 end);
 
+InstallMethod(DigraphEccentricities, "for a digraph",
+[IsDigraph],
+function(D)
+  if not IsStronglyConnectedDigraph(D) or DigraphNrVertices(D) = 0 then
+    return fail;
+  fi;
+  return List(DigraphShortestDistances(D), Maximum);
+end);
+
+InstallMethod(DigraphRadius, "for a digraph",
+[IsDigraph],
+function(D)
+  if not IsStronglyConnectedDigraph(D) or DigraphNrVertices(D) = 0 then
+    return fail;
+  fi;
+  return Minimum(DigraphEccentricities(D));
+end);
+
+InstallMethod(DigraphCentre, "for a digraph",
+[IsDigraph],
+function(D)
+  if not IsStronglyConnectedDigraph(D) or DigraphNrVertices(D) = 0 then
+    return fail;
+  fi;
+  return Positions(DigraphEccentricities(D), DigraphRadius(D));
+end);
+
+InstallMethod(DigraphPeriphery, "for a digraph",
+[IsDigraph],
+function(D)
+  if not IsStronglyConnectedDigraph(D) or DigraphNrVertices(D) = 0 then
+    return fail;
+  fi;
+  return Positions(DigraphEccentricities(D), DigraphDiameter(D));
+end);
+
 InstallMethod(DigraphUndirectedGirth, "for a digraph", [IsDigraph],
 function(D)
   # This is only defined on undirected graphs (i.e. symmetric digraphs)

tst/standard/attr.tst

@@ -3389,6 +3389,42 @@ true
 gap> B[14, 15] = z;
 true
 
+# DigraphEccentricities, DigraphRadius, DigraphCentre, and DigraphPeriphery
+gap> D := ChainDigraph(2);;
+gap> DigraphEccentricities(D);
+fail
+gap> DigraphRadius(D);
+fail
+gap> DigraphCentre(D);
+fail
+gap> DigraphPeriphery(D);
+fail
+gap> D := EmptyDigraph(0);;
+gap> DigraphEccentricities(D);
+fail
+gap> DigraphRadius(D);
+fail
+gap> DigraphCentre(D);
+fail
+gap> DigraphPeriphery(D);
+fail
+gap> D := Digraph([[2], [1, 3], [2, 4], [3]]);;
+gap> DigraphRadius(D);
+2
+gap> DigraphDiameter(D);
+3
+gap> DigraphCentre(D);
+[ 2, 3 ]
+gap> DigraphPeriphery(D);
+[ 1, 4 ]
+gap> D := Digraph([[1, 1]]);;
+gap> DigraphRadius(D);
+0
+gap> DigraphCentre(D) = DigraphPeriphery(D);
+true
+gap> DigraphCenter = DigraphCenter;
+true
+
 # DigraphAbsorptionProbabilities
 gap> gr := Digraph([[2, 3, 4], [3], [2], []]);
 <immutable digraph with 4 vertices, 5 edges>