dgscat(1)

💅 dgscat(1) — like, the PT-Scotch user's manual, but make it make sense

okay so bestie, buckle up 🎀 this page is actually three whole programs in a trench coat — dggath, dgscat, and gscat — and they're all about converting distributed source graphs to or from centralized ones. yes, that's the whole vibe. let's get into it ✨

---

✨ NAME ✨

dggath, dgscat, gscat — convert distributed source graphs to or from centralized ones. that's it, that's the name section 💅

---

🦋 SYNOPSIS 🦋

dggath [options] [igfile] [ogfile]

dgscat [options] [igfile] [ogfile]

gscat [options] [igfile] [ogfile]

three icons, three little command lines, all living their best life with the same shape 🔥

---

🌸 DESCRIPTION 🌸

okay so picture this: the dggath program gathers distributed graphs into centralized graphs. it reads a whole set of files, igfile, that represent fragments of a distributed source graph, and writes them back on the form of a single centralized source graph, ogfile. gathering. it's giving collect-and-conquer 🫶

then there's dgscat, which does the literal opposite energy — it scatters centralized source graphs into distributed graphs. it reads one centralized source graph igfile and writes it back on the form of a set of files ogfile that represent fragments of the corresponding distributed source graph. scatter era 💫

and gscat does exactly the same as dgscat, but — and this is the iconic part — it 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. so it's therefore much less resource consuming 🍓 but plot twist: it does not allow for the checking of graph consistency, because it has no global vision of the graph structure. no thoughts, head empty, but efficient 😭

lowkey an important tradeoff: gscat = cheap and chill, but it can't vibe-check your graph for you.

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 -. inclusivity, we love to see it ✨

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). fancy 💅

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. so like, don't just type it into your terminal and expect main character energy — it needs its squad 🌈

---

🧚 DISTRIBUTED FILE NAMES 🧚

okay so this is the part where names get weird, and honestly? obsessed 🎀

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

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. population count vibes 👑
• %r — replaced on each process running the program by the rank of this process in the global communicator. leads to parallel opening. everybody gets their own little number 🎀
• %- — 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). the way that dash just dips out but still causes parallel opening?? iconic 🫶
• %% — 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. escaping the escape, very meta of you 🦋

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. no cap, that's genuinely how it works ✨

---

💜 OPTIONS 💜

• -c — for dggath and dgscat only. check the consistency of the input source graph after loading it into memory. a little self-care checkup for your graph 💅
• -h — display some help. say less, bestie 🫶
• -rpnum — set root process for centralized files (default is 0). so like, -r plus the process number, all smooshed together ✨
• -V — display program version and copyright. the receipts, if you will 👑

---

⭐ 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. look at it go 🔥

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

five little fragments, all from one command. it's giving delegation 💫

---

💀 SEE ALSO 💀

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

PT-Scotch user's manual. that's the whole family, go say hi 🌸

---

🙈 AUTHOR 🙈

Francois Pellegrini <francois.pellegrini@labri.fr> — the icon behind all of this 🎀

---

okay that's the whole page, bestie, you ate that 💅 and for the record, this masterpiece of a manual comes to you courtesy of the PT-Scotch user's manual, dated 23 November 2019 — go off, 2019 🫶✨