<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 the &Digraphs; package version &VERSION;.  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>Luke Elliott,</Item>
    <Item>Christopher Jefferson,</Item>
    <Item>Markus Pfeiffer,</Item>
    <Item>Chris Russell, and</Item>
    <Item>Finn Smith.</Item>
  </List>

  The &Digraphs; package contains a variety of methods for efficiently creating
  and storing 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="JunttilaKaski"/> 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="McKay201494"/> for computing automorphism groups and canonical forms
  in &Digraphs;. See Section 
  <Ref Sect="Isomorphisms and canonical labellings"/> for more details.  
  <P/>

  <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>
