---
name: "mcxmap"
section: "1"
platform: "linux"
package: "mcl"
version: "1:22-282+ds-4"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/mcxmap"
---

# mcxmap(1)

mcxmap - permute or remap the indices of graphs and matrices.

**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*)**\]**

This utility relabels graphs or matrices. Its main use is in applying a *map file* to a given matrix or graph. A map file contains a so called *map matrix* in mcl format that has some special properties (given further below). The functionality of mcxmap can also be provided by **mcx**, as 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. However, **mcx** will construct a new matrix and leave the original matrix to be mapped alone. When dealing with huge matrices, considerable gains in efficiency memory-wise and time-wise can be achieved by doing the mapping in-place. This is what mcxmap does. In the future, its functionality may be embedded in **mcx** with new mcx operators.

The special properties of a map matrix are

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

**-o** fname (*output file*)\
 Output file.

**-imx** fname (*input file*)\
 Input file.

**-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 fil (use inverse)*)\
 **-cmapi** fname (*column map fil (use inverse)*)\
 Different ways to specify map files.

**-make-map** (*output map file name*)\
 **-make-mapc** (*output map file name*)\
 **-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*)\
 **-cshift** b (*translate*)\
 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`.

**-rmul** c (*coefficient*)\
 **-rshift** d (*translate*)\
 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`.

**-mul** e (*coefficient*)\
 **-shift** f (*translate*)\
 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`.

**-tab** fname (*read (and map) tab file*)\
 This option requires the **-map** option. **mcxmap** will output the mapped tab definition.

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.

```
(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  $
)
```

Stijn van Dongen.

**[mcxio(5)](/mcxio/5.md)**, **[mcx(1)](/mcx/1.md)**, **[mcxsubs(1)](/mcxsubs/1.md)**, and **[mclfamily(7)](/mclfamily/7.md)** for an overview of all the documentation and the utilities in the mcl family.