Documentation Index
Fetch the complete documentation index at: https://mintlify.com/KarypisLab/METIS/llms.txt
Use this file to discover all available pages before exploring further.
gpmetis is the primary command-line tool for partitioning undirected graphs into a specified number of parts. It supports two partitioning algorithms — recursive bisection (rb) and direct k-way partitioning (kway) — and can minimize either the edge-cut or total communication volume. The result is written to a .part.k file alongside the input graph.
Usage
| Argument | Description |
|---|---|
graphfile | Path to the graph file to be partitioned (METIS graph format). |
nparts | Number of partitions to produce. Must be ≥ 2. |
Output File
When partitioning completes successfully,gpmetis writes a partition assignment file named <graphfile>.part.<nparts>. The file contains one integer per line — the partition ID (0-indexed) assigned to the corresponding vertex.
-nooutput to suppress writing this file (useful for benchmarking).
Examples
Options Reference
Partitioning Algorithm
Selects the partitioning scheme.
| Value | Description |
|---|---|
kway | Direct k-way partitioning (default) |
rb | Recursive bisection |
-contig, -minconn, and -objtype=vol are only valid with ptype=kway. Combining them with ptype=rb will cause an error.The objective function to optimize. Applies only when
-ptype=kway.| Value | Description |
|---|---|
cut | Minimize the total edge-cut (default) |
vol | Minimize the total communication volume |
Coarsening
Vertex matching scheme used during graph coarsening.
| Value | Description |
|---|---|
shem | Sorted heavy-edge matching (default) |
rm | Random matching |
When set, disables 2-hop matchings during coarsening. By default, if standard matching does not sufficiently contract the graph, METIS falls back to 2-hop matchings. Use this flag to prevent that fallback.
Initial Partitioning
Scheme used to compute the initial partitioning of the coarsened graph.When
When
-ptype=rb:| Value | Description |
|---|---|
grow | Greedy growth bisection (default for single-constraint graphs) |
random | Random bisection (default for multi-constraint graphs) |
-ptype=kway:| Value | Description |
|---|---|
rb | Recursive bisection for k-way initial partition (default for kway) |
For k-way partitioning,
iptype defaults to rb (METIS_IPTYPE_METISRB) and cannot be set to grow or random. For recursive bisection, only grow and random are valid.Number of initial partitionings to compute during the initial partitioning phase. The default is determined automatically by the algorithm based on graph size.
Refinement
Number of refinement iterations performed at each level of the uncoarsening process. Increasing this value can improve partition quality at the cost of longer runtime.
Number of independent partitionings to compute. The best result (lowest edge-cut or communication volume) is kept. Higher values improve solution quality but increase runtime linearly.
Load Balance
Maximum allowed load imbalance expressed as an integer
x, meaning the actual imbalance tolerance is 1 + x/1000.- For
ptype=rb: imbalance is2*max(left,right)/(left+right). Defaultx=1→ tolerance 1.001. - For
ptype=kway: imbalance ismax_i(pwgts[i])/avgpwgt. Defaultx=30→ tolerance 1.030.
Per-constraint load imbalance tolerances for multi-constraint partitioning. Provide a space-separated list of floating-point values, one per constraint. For example,
"1.02 1.20 1.35" allows 2%, 20%, and 35% imbalance per constraint respectively.When
-ubvec is supplied it takes priority over -ufactor.Path to a file specifying target partition weights. By default all partitions are given equal weight. The file should contain one floating-point weight per partition (or per partition per constraint for multi-constraint graphs), with all weights summing to 1.0 per constraint.
Partition Quality Constraints
Enforces contiguous (connected) partitions. Only applies when
-ptype=kway. If the input graph itself is disconnected, this flag is silently ignored.Minimizes the maximum degree of the subdomain connectivity graph — the graph where each partition is a node and edges connect partitions sharing a boundary. This reduces the number of neighbors each subdomain communicates with. Only applies when
-ptype=kway.Memory and I/O
Stores intermediate coarsened graphs to disk during the coarsening phase, significantly reducing peak memory usage at the cost of additional I/O. Useful for very large graphs that would otherwise exhaust available RAM.
Randomly drops edges during coarsening to further reduce memory usage. May slightly degrade partition quality.
Suppresses writing the
.part.k output file. All statistics and timing information are still printed to stdout. Useful for benchmarking or when only the objective value is needed.Reproducibility and Diagnostics
Seed for the random number generator. A value of
-1 (the default) uses a time-based seed, producing different results each run. Set an explicit seed for reproducible results.Debug verbosity level. Higher values produce more diagnostic output during partitioning. Set to
0 for no debug output (default).