mcxmap(1)

mcxmap(1) 💅

okay bestie, welcome to mcxmap — a USER COMMANDS situation, and it's giving ✨index remapping✨. stay with me, it's actually so good.

---

✨ NAME ✨

mcxmap — permute or remap the indices of graphs and matrices. literally its whole personality. 🦋

---

🌸 SYNOPSIS 🌸

mcxmap -imx fname (input) [-o fname (output)] [-make-map (output map file
name)] [-make-mapc (output map file name)] [-make-mapr (output map file
name)] [-cmul a (coefficient)] [-cshift b (translate)] [-rmul c
(coefficient)] [-rshift d (translate)] [-mul e (coefficient)] [-shift f
(translate)] [-map fname (row/col map file)] [-rmap fname (row map file)]
[-cmap fname (column map file)] [-mapi fname (row/col map file (use
inverse))] [-rmapi fname (row map file (use inverse))] [-cmapi fname
(column map file (use inverse))] [-tab fname (read (and map) tab file)]

---

👑 DESCRIPTION 👑

so this lil utility relabels graphs or matrices. that's the whole gig. its main character use is applying a map file to a given matrix or graph, and it does it in place which is the slay part.

a map file contains a so called map matrix in mcl format that has some special properties (we're getting to those, hold on 🫶).

ngl the functionality of mcxmap can also be provided by mcx, because a mapped matrix (i.e. the result of applying a map matrix to another matrix) is simply the usual matrix product of a matrix and a map matrix. but here's the tea: mcx will construct a new matrix and leave the original matrix to be mapped alone. and when you're dealing with huge matrices, doing the mapping in-place is a considerable gain in efficiency — memory-wise and time-wise. that's what mcxmap does. 🔥

future note bestie: its functionality may be embedded in mcx with new mcx operators. so watch this space. 💀

the special properties of a map matrix 💖

• The column domain and row domain are of the same cardinality.
• Each column has exactly one entry.
• Each row domain index occurs in exactly one column.

these properties imply that the matrix can be used as a map from the column domain onto the row domain. an example map matrix is found in the EXAMPLES Section (yes, we go there, it's cute). ✨

---

💅 OPTIONS 💅

• -o fname (output file) — the output file. where the glow-up lands. 🎀
• -imx fname (input file) — the input file. the before picture. 🌸
• -map fname (row/col map file)) — different ways to specify map files.
• -rmap fname (row map file) — different ways to specify map files.
• -cmap fname (column map file) — different ways to specify map files.
• -mapi fname (row/col map file (use inverse)) — different ways to specify map files.
• -rmapi fname (row map fil (use inverse)) — different ways to specify map files.
• -cmapi fname (column map fil (use inverse)) — different ways to specify map files.
• -make-map (output map file name) — generate a map that maps the specified domain onto the appropriate canonical domain, and write the map matrix to file. 📝
• -make-mapc (output map file name) — generate a map that maps the specified domain onto the appropriate canonical domain, and write the map matrix to file. 📝
• -make-mapr (output map file name) — generate a map that maps the specified domain onto the appropriate canonical domain, and write the map matrix to file. 📝
• -cmul a (coefficient) — these options have affect if neither a column map file nor column canonification is specified. if any of the first two options is used, column indices i are mapped to a*i+b. 🧮
• -cshift b (translate) — same vibe as above: if any of the first two options is used, column indices i are mapped to a*i+b. 🧮
• -rmul c (coefficient) — these options have affect if neither a row map file nor row canonification is specified. if any of the first two options is used, indices i are mapped to c*i+d. 🧮
• -rshift d (translate) — if any of the first two options is used, indices i are mapped to c*i+d. 🧮
• -mul e (coefficient) — if a map file is specified for a given domain, neither a map file nor canonification is specified. if any of the first two options is used, the indices i will be mapped to e*i+f. 🧮
• -shift f (translate) — if any of the first two options is used, the indices i will be mapped to e*i+f. 🧮
• -tab fname (read (and map) tab file) — this option requires the -map option. mcxmap will output the mapped tab definition. 📋

---

🦋 EXAMPLES 🦋

the matrix below has two canonical domains which are identical. it denotes a map of the canonical domain onto itself, in which node 0 is relabeled to 8, node 1 is relabeled to 5, et cetera. iconic honestly.

(mclheader
mcltype matrix
dimensions 12x12
)
(mclmatrix
begin
0  8  $
1  5  $
2  3  $
3  2  $
4  4  $
5  6  $
6  7  $
7  9  $
8  1  $
9  10 $
10 11 $
11 0  $
)

---

🌈 AUTHOR 🌈

Stijn van Dongen. (the author. we stan 👑)

---

⭐ SEE ALSO ⭐

mcxio(5), mcx(1), mcxsubs(1), and mclfamily(7) for an overview of all the documentation and the utilities in the mcl family. go read them bestie, iykyk 🫶

---

that's the whole page!! mwah 💖 this was mcxmap version 22-282, dated 9 Oct 2022, and yes she's still mcxmap(1) at heart. periodt. ✨💅🎀