<Chapter Label="The Digraphs package">
  <Heading>
    The &Digraphs; package
  </Heading>
  <Index Key="Digraphs">&Digraphs; package overview</Index>

<Section><Heading>Introduction</Heading>

  This is the manual for version &VERSION; of the &Digraphs; package.
  This package was developed at the University of St Andrews by:
  <List>
    <Item>Jan De Beule,</Item>
    <Item>Julius Jonu&#353;as,</Item>
    <Item>James D. Mitchell,</Item>
    <Item>Michael C. Torpey, and</Item>
    <Item>Wilf A. Wilson.</Item>
  </List>
  Additional contributions were made by:
  <List>
    <Item>Stuart Burrell,</Item>
    <Item>Reinis Cirpons,</Item>
    <Item>Luke Elliott,</Item>
    <Item>Max Horn,</Item>
    <Item>Christopher Jefferson,</Item>
    <Item>Markus Pfeiffer,</Item>
    <Item>Chris Russell,</Item>
    <Item>Finn Smith, and</Item>
    <Item>Maria Tsalakou,</Item>
    <Item>Murray Whyte.</Item>
  </List>

  The &Digraphs; 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. <P/>

  If the &Grape; package is available, it will be loaded automatically.
  Digraphs created with the &Digraphs; package can be converted to &Grape;
  graphs with <Ref Oper="Graph"/>, and conversely &Grape; graphs can be
  converted to &Digraphs; objects with <Ref Oper="Digraph"/>.  &Grape; is not
  required for &Digraphs; to run. <P/>

  The &bliss; tool <Cite Key="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 &Digraphs; package rely on &bliss;. If the &NautyTracesInterface;
  package for GAP is available then it is also possible to use &nauty; <Cite
    Key="MP14"/> for computing automorphism groups and canonical forms
  in &Digraphs;. See Section 
  <Ref Sect="Isomorphisms and canonical labellings"/> for more details.  
  <P/>

  From 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 <Ref Func="MakeImmutable"
  BookName = "ref"/>.  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).

  <Subsection Label="Definitions"><Heading>Definitions</Heading>

    For the purposes of this package and its documentation, the following
    definitions apply: <P/>

    A <E>digraph</E> <M>E=(E^0,E^1,r,s)</M>, also known as a <E>directed
      graph</E>, consists of a set of vertices <M>E^0</M> and a set of edges
    <M>E^1</M> together with functions <M>s, r: E^1 \to E^0</M>, called the
    <E>source</E> and <E>range</E>, respectively.

    The source and range of an edge is respectively the values of <M>s, r</M> at
    that edge.

    An edge is called a <E>loop</E> if its source and range are the same.

    A digraph is called a <E>multidigraph</E> if there exist two or more edges
    with the same source and the same range. <P/>

    A <E>directed walk</E> on a digraph is a sequence of alternating vertices
    and edges <M>(v_1, e_1, v_2, e_2, ..., e_{n-1}, v_n)</M> such that each edge
    <M>e_i</M> has source <M>v_i</M> and range <M>v_{i+1}</M>. A <E>directed
      path</E> is a directed walk where no vertex (and hence no edge) is
    repeated.  A <E>directed circuit</E> is a directed walk where <M>v_1 =
      v_n</M>, and a <E>directed cycle</E> is a directed circuit where where no
    vertex is repeated, except for <M>v_1 = v_n</M>.  <P/>

    The <E>length</E> of a directed walk <M>(v_1, e_1, v_2, e_2, ..., e_{n-1},
      v_n)</M> is equal to <M>n-1</M>, the number of edges it contains.  A
    directed walk (or path) <M>(v_1, e_1, v_2, e_2, ..., e_{n-1}, v_n)</M> is
    sometimes called a directed walk (or path) <E>from vertex <M>v_1</M> to
      vertex <M>v_n</M></E>.  A directed walk of zero length, i.e. a sequence
    <M>(v)</M> for some vertex <M>v</M>, is called <E>trivial</E>. A trivial
    directed walk is considered to be both a circuit and a cycle, as is the
    empty directed walk <M>()</M>. A <E>simple circuit</E> is another name for a
    non-trivial and non-empty directed cycle.<P/>

  </Subsection>
  </Section>
</Chapter>
