NAME
  dggath, dgscat, gscat - convert distributed source graphs to or from centralized ones

SYNOPSIS
  dggath [options] [igfile] [ogfile]

  dgscat [options] [igfile] [ogfile]

  gscat [options] [igfile] [ogfile]

DESCRIPTION
  The dggath program gathers distributed graphs into centralized
  graphs. It reads a set of files igfile representing fragments of a
  distributed source graph, and writes them back on the form of a
  single centralized source graph ogfile.

  The dgscat program scatters centralized source graphs into
  distributed graphs. It reads a centralized source graph igfile and
  writes it back on the form of a set of files ogfile representing
  fragments of the corresponding distributed source graph.

  The gscat program does exactly the same as dgscat, but does not
  require to be run in a parallel environment. Since gscat processes
  the input centralized graph file as a text stream, it does not need
  to load the full graph in memory before building the distributed
  graph fragment files. It is therefore much less resource consuming,
  but does not allow for the checking of graph consistency, as it has
  no global vision of the graph structure.

  When file names are not specified, data is read from standard input
  and written to standard output. Standard streams can also be
  explicitly represented by a dash '-'.

  When the proper libraries have been included at compile time, dggath
  and dgscat can directly handle compressed graphs, both as input and
  output. A stream is treated as compressed whenever its name is
  postfixed with a compressed file extension, such as
  in 'brol.grf.bz2' or '-.gz'. The compression formats which can be
  supported are the bzip2 format ('.bz2'), the gzip format ('.gz'),
  and the lzma format ('.lzma').

  dggath and dgscat base on implementations of the MPI interface to
  spread work across the processing elements. It is therefore not
  likely to be run directly, but instead through some launcher command
  such as mpirun.

DISTRIBUTED FILE NAMES
  In order to tell whether programs should read from, or write to, a
  single file located on only one processor, or to multiple instances
  of the same file on all of the processors, or else to distinct files
  on each of the processors, a special grammar has been designed,
  which is based on the '%' escape character. Four such escape
  sequences are defined, which are interpreted independently on every
  processor, prior to file opening. By default, when a filename is
  provided, it is assumed that the file is to be opened on only one of
  the processors, called the root processor, which is usually process
  0 of the communicator within which the program is run. The index
  of the root processor can be changed by means of the -r
  option. Using any of the first three escape sequences below will
  instruct programs to open in parallel a file of name equal to the
  interpreted filename, on every processor on which they are run.

  %p  Replaced by the number of processes in the global communicator in
      which the program is run. Leads to parallel opening.

  %r  Replaced on each process running the program by the rank of this
      process in the global communicator. Leads to parallel opening.

  %-  Discarded, but leads to parallel opening. This sequence is mainly
      used to instruct programs to open on every processor a file of
      identical name. The opened files can be, according whether the
      given path leads to a shared directory or to directories that
      are local to each processor, either to the opening of multiple
      instances of the same file, or to the opening of distinct files
      which may each have a different content, respectively (but in
      this latter case it is much recommended to identify files by
      means of the '%r' sequence).

  %%  Replaced by a single '%' character. File names using this escape
      sequence are not considered for parallel opening, unless one or
      several of the three other escape sequences are also present.

For instance, filename 'brol' will lead to the opening of file 'brol'
on the root processor only, filename '%-brol' (or even 'br%-ol') will
lead to the parallel opening of files called 'brol' on every
processor, and filename 'brol%p-%r' will lead to the opening of files
'brol2-0' and 'brol2-1', respectively, on each of the two processors
on which the program were to run.

OPTIONS
  -c          For dggath and dgscat only. Check the consistency of the
              input source graph after loading it into memory.

  -h          Display some help.

  -inbr     For gscat only. Create an imbalanced distributed graph,
              in which the distributed graph files for all processes
              will receive \textit{nbr} vertices of the graph, save
              for the file for the last process, which will receive
              all the remaining vertices.

  -rpnum    Set root process for centralized files (default is 0).

  -V          Display program version and copyright.

EXAMPLE
  Run dgscat on 5 processing elements to scatter centralized graph
  file brol.grf into 5 gzipped file fragments brol5-0.dgr.gz to
  brol5-4.dgr.gz.

    $ mpirun -np 5 dgscat brol.grf brol%p-%r.dgr.gz

SEE ALSO
  dgmap(1), dgord(1), dgtst(1), gmk_hy(1).

  PT-Scotch user's manual.

AUTHOR
  Francois Pellegrini <francois.pellegrini@labri.fr>
