dgmap(1)

dgmap(1) / dgpart(1) 💖

okay bestie, welcome to the PT-Scotch user's manual ✨ this one is literally called dgmap, and its lil sibling is dgpart. they're the parallel cousins of the mapping crew. sit down, grab a snack 🍓, we're doing this.

---

🌸 NAME 🌸

dgmap, dgpart — compute static mappings and partitions in parallel 💅

---

🦋 SYNOPSIS 🦋

dgmap [options] [gfile] [tfile] [mfile] [lfile]

dgpart [options] [nparts/pwght] [gfile] [mfile] [lfile]

---

✨ DESCRIPTION ✨

So. dgmap computes, in a parallel way, a static mapping of a source graph onto a target graph. that's the whole vibe. 🫶

dgpart is the simplified interface to dgmap, and instead of static mapping it does graph partitioning. so yeah, you have to hand it the number of parts you want, in lieu of the target architecture. and when you're using the program for graph clustering, that number of parts turns into maximum cluster weight. cute, right? 💀

the -b and -c options let you set your preferences on how the default mapping strategy behaves. and if you want to go full custom, -m lets you define your own mapping strategy. main character energy fr fr 👑

and the -q option? that one turns these programs into graph clustering programs. heads up though: in that case, dgmap only accepts variable-sized target architectures. no exceptions, bestie.

now, the source graph file gfile is either a centralized graph file, or a whole set of files representing fragments of a distributed graph. for dgmap, the target architecture file tfile describes either algorithmically-coded topologies like meshes and hypercubes, or decomposition-defined architectures created by means of the amk_grf(1) program. (want the full tea on target architectures? see gmap(1), they explain it there.) the resulting mapping gets stored in file mfile. and any eventual logging info — like the stuff -v produces — gets sent to file lfile. 📝

when you don't specify file names, data is read from standard input and written to standard output. and standard streams can also be explicitely represented by a dash '-'. yes, the typo "explicitely" is theirs, we're keeping it, it's iconic 🎀

when the proper libraries have been included at compile time, dgmap and dgpart 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, like in 'brol.grf.bz2' or '-.gz'. the compression formats which can be supported are:

• the bzip2 format ('.bz2')
• the gzip format ('.gz')
• the lzma format ('.lzma')

also dgmap and dgpart base on implementations of the MPI interface to spread work across the processing elements. so like, they are not likely to be run directly — instead you run them through some launcher command such as mpirun. no cap 🫡

---

💅 OPTIONS 💅

• -bval — Set maximum load imbalance ratio for graph partitioning or static mapping. and when these programs are used as clustering tools, this parameter sets the maximum load imbalance ratio for recursive bipartitions. exclusive with the -m option. ⚠️
• -copt — Choose default mapping strategy according to one or several options among:
  • b — enforce load balance as much as possible. ⚖️
  • q — privilege quality over speed (default). 👑
  • s — privilege speed over quality. 💨
  • t — enforce safety. 🛟
  • x — enforce scalability. 📈

and this one is exclusive with the -m option too. ✨

• -h — Display some help. 🙋
• -mstrat — Use parallel mapping strategy strat (see PT-Scotch user's manual for more information). 🧠
• -q — (for dgpart)
• -qpwght — (for dgmap) Use the programs as graph clustering tools instead of static mapping or graph partitioning tools. for dgpart, the number of parts will become the maximum cluster weight. for dgmap, this number pwght has to be passed after the option. 🌸
• -rpnum — Set root process for centralized files (default is 0). 🎯
• -V — Display program version and copyright. 📜
• -vverb — Set verbose mode to verb. it's a set of one of more characters which can be:
  • m — mapping information. 🗺️
  • s — strategy information. 🧩
  • t — timing information. ⏱️

---

⚠️ NOTE ⚠️

okay so at the time being (version 5.1), dgmap cannot compute full static mappings as gmap(1) does — only partitions (that is, mappings onto unweighted or weighted complete graphs). and target architectures other than the 'cmplt' and 'wcmplt' ones will lead to an error message. so don't come for her, she's doing her best 😭

---

🌈 EXAMPLES 🌈

Run dgpart on 5 processing elements to compute a partition into 7 parts of graph brol.grf and save the resulting ordering to file brol.map. 🎀

$ mpirun -np 5 dgpart 7 brol.grf brol.map

Run dgpart on 5 processing elements to partition into 7 parts the distributed graph stored on graph fragment files brol5-0.dgr to brol5-4.dgr, and save the resulting mapping to file brol.map. (see dgscat(1) for an explanation of the '%p' and '%r' sequences in names of distributed graph fragments.) 🦋

$ mpirun -np 5 dgpart 7 brol%p-%r.dgr brol.map

---

👀 SEE ALSO 👀

dgtst(1), dgscat(1), amk_grf(1), acpl(1), gmap(1), gmtst(1).

PT-Scotch user's manual. 📖

---

💜 AUTHOR 💜

Francois Pellegrini <francois.pellegrini@labri.fr>

---

and that's the whole page bestie, you ate that 💅✨ this was the PT-Scotch user's manual dgmap(1) page, dated 23 November 2019. go forth and map some graphs, you got this 🫶🌸💖