  
  [1X1 [33X[0;0YThe [5XDigraphs[105X[101X[1X package[133X[101X
  
  
  [1X1.1 [33X[0;0YIntroduction[133X[101X
  
  [33X[0;0YThis  is  the manual for version 1.6.1 of the [5XDigraphs[105X package. This package
  was developed at the University of St Andrews by:[133X
  
  [30X    [33X[0;6YJan De Beule,[133X
  
  [30X    [33X[0;6YJulius Jonušas,[133X
  
  [30X    [33X[0;6YJames D. Mitchell,[133X
  
  [30X    [33X[0;6YMaria Tsalakou,[133X
  
  [30X    [33X[0;6YWilf A. Wilson, and[133X
  
  [30X    [33X[0;6YMichael C. Young.[133X
  
  [33X[0;0YAdditional contributions were made by:[133X
  
  [30X    [33X[0;6YMarina Anagnostopoulou-Merkouri,[133X
  
  [30X    [33X[0;6YFinn Buck,[133X
  
  [30X    [33X[0;6YStuart Burrell,[133X
  
  [30X    [33X[0;6YReinis Cirpons,[133X
  
  [30X    [33X[0;6YTom Conti-Leslie,[133X
  
  [30X    [33X[0;6YLuke Elliott,[133X
  
  [30X    [33X[0;6YEwan Gilligan,[133X
  
  [30X    [33X[0;6YMax Horn,[133X
  
  [30X    [33X[0;6YChristopher Jefferson,[133X
  
  [30X    [33X[0;6YMarkus Pfeiffer,[133X
  
  [30X    [33X[0;6YLea Racine,[133X
  
  [30X    [33X[0;6YChristopher Russell,[133X
  
  [30X    [33X[0;6YFinn Smith,[133X
  
  [30X    [33X[0;6YBen Spiers, and[133X
  
  [30X    [33X[0;6YMurray Whyte.[133X
  
  [33X[0;0YThe  [5XDigraphs[105X package contains a variety of methods for efficiently creating
  and  storing  mutable and immutable digraphs and computing information about
  them.  Full  explanations  of all the functions contained in the package are
  provided below.[133X
  
  [33X[0;0YIf the [5XGrape[105X package is available, it will be loaded automatically. Digraphs
  created  with  the  [5XDigraphs[105X  package  can be converted to [5XGrape[105X graphs with
  [2XGraph[102X  ([14X3.2-3[114X),  and  conversely  [5XGrape[105X  graphs can be converted to [5XDigraphs[105X
  objects with [2XDigraph[102X ([14X3.1-7[114X). [5XGrape[105X is not required for [5XDigraphs[105X to run.[133X
  
  [33X[0;0YThe [5Xbliss[105X tool [JK07] is included in this package. It is an open-source tool
  for  computing automorphism groups and canonical forms of graphs, written by
  Tommi  Junttila  and  Petteri  Kaski. Several of the methods in the [5XDigraphs[105X
  package  rely  on  [5Xbliss[105X.  If  the  [5XNautyTracesInterface[105X  package for GAP is
  available  then  it  is  also  possible  to  use  [5Xnauty[105X [MP14] for computing
  automorphism  groups  and  canonical  forms in [5XDigraphs[105X. See Section [14X7.2[114X for
  more details.[133X
  
  [33X[0;0YThe  [5Xedge-addition-planarity-suite[105X is also included in [5XDigraphs[105X; see [BM04],
  [Boy06],  [BM06],  and  [Boy12]  .  The  [5Xedge-addition-planarity-suite[105X is an
  open-source  implementation  of  the  edge  addition  planar graph embedding
  algorithm  and related algorithms by John M. Boyer. See Section [14X6.6[114X for more
  details.[133X
  
  [33X[0;0YFrom  version  1.0.0  of  this  package,  digraphs  can be either mutable or
  immutable.  Mutable  digraphs can be changed in-place by many of the methods
  in  the package, which avoids unnecessary copying. Immutable digraphs cannot
  be  changed  in-place, but their advantage is that the value of an attribute
  of  an immutable digraph is only ever computed once. Mutable digraphs can be
  converted  into  immutable digraphs in-place using [2XMakeImmutable[102X ([14XReference:
  MakeImmutable[114X).  One  of the motivations for introducing mutable digraphs in
  version  1.0.0  was  that  in  practice the authors often wanted to create a
  digraph  and  immediately  modify  it (removing certain edges, loops, and so
  on).  Before version 1.0.0, this involved copying the digraph several times,
  with  each copy being discarded almost immediately. From version 1.0.0, this
  unnecessary  copying  can be eliminated by first creating a mutable digraph,
  then  changing it in-place, and finally converting the mutable digraph to an
  immutable one in-place (if desirable).[133X
  
  
  [1X1.1-1 [33X[0;0YDefinitions[133X[101X
  
  [33X[0;0YFor  the  purposes  of  this  package  and  its documentation, the following
  definitions apply:[133X
  
  [33X[0;0YA [13Xdigraph[113X [22XE=(E^0,E^1,r,s)[122X, also known as a [13Xdirected graph[113X, consists of a set
  of  vertices [22XE^0[122X and a set of edges [22XE^1[122X together with functions [22Xs, r: E^1 ->
  E^0[122X,  called  the [13Xsource[113X and [13Xrange[113X, respectively. The source and range of an
  edge  is  respectively  the values of [22Xs, r[122X at that edge. An edge is called a
  [13Xloop[113X  if  its  source  and  range  are  the  same.  A  digraph  is  called a
  [13Xmultidigraph[113X  if  there exist two or more edges with the same source and the
  same range.[133X
  
  [33X[0;0YA [13Xdirected walk[113X on a digraph is a sequence of alternating vertices and edges
  [22X(v_1, e_1, v_2, e_2, ..., e_n-1, v_n)[122X such that each edge [22Xe_i[122X has source [22Xv_i[122X
  and  range  [22Xv_i+1[122X.  A  [13Xdirected path[113X is a directed walk where no vertex (and
  hence  no edge) is repeated. A [13Xdirected circuit[113X is a directed walk where [22Xv_1
  =  v_n[122X,  and a [13Xdirected cycle[113X is a directed circuit where where no vertex is
  repeated, except for [22Xv_1 = v_n[122X.[133X
  
  [33X[0;0YThe [13Xlength[113X of a directed walk [22X(v_1, e_1, v_2, e_2, ..., e_n-1, v_n)[122X is equal
  to  [22Xn-1[122X,  the  number  of edges it contains. A directed walk (or path) [22X(v_1,
  e_1,  v_2,  e_2,  ...,  e_n-1,  v_n)[122X is sometimes called a directed walk (or
  path)  [13Xfrom vertex [22Xv_1[122X to vertex [22Xv_n[122X[113X. A directed walk of zero length, i.e. a
  sequence  [22X(v)[122X  for some vertex [22Xv[122X, is called [13Xtrivial[113X. A trivial directed walk
  is  considered  to  be  both a circuit and a cycle, as is the empty directed
  walk  [22X()[122X.  A  [13Xsimple circuit[113X is another name for a non-trivial and non-empty
  directed cycle.[133X
  
