dgscat(1)						      PT-Scotch user's manual							 dgscat(1)

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 distrib-
       uted 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', on input only).

       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.

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

								  August 03, 2010							 dgscat(1)