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.
METIS exposes a minimal set of types and enumeration constants through metis.h. The two core scalar types, idx_t and real_t, have widths that are fixed at library build time. All function pointers, array sizes, and index values use idx_t; floating-point partition weights and imbalance tolerances use real_t.
idx_t and real_t widths are set at library compile time via the IDXTYPEWIDTH and REALTYPEWIDTH preprocessor defines. Your application code must be compiled against the same metis.h used to build the library. Linking an application built with 32-bit idx_t against a library built with 64-bit idx_t (or vice versa) results in undefined behavior and incorrect results without any compile-time diagnostic.
Scalar Types
idx_t
Integer type used for all vertex counts, edge counts, partition IDs, array indices, and option values throughout the API.
/* IDXTYPEWIDTH == 32 */
typedef int32_t idx_t;
/* IDXTYPEWIDTH == 64 */
typedef int64_t idx_t;
| Setting | Underlying type | Maximum value | When to use |
|---|
IDXTYPEWIDTH 32 | int32_t | ~2.1 billion | Graphs with fewer than 2^31−1 vertices and edges (default) |
IDXTYPEWIDTH 64 | int64_t | ~9.2 × 10^18 | Very large graphs exceeding 32-bit limits |
make config i64=1.
real_t
Floating-point type used for partition target weights (tpwgts), imbalance tolerances (ubvec), and internal balance computations.
/* REALTYPEWIDTH == 32 */
typedef float real_t;
/* REALTYPEWIDTH == 64 */
typedef double real_t;
| Setting | Underlying type | When to use |
|---|
REALTYPEWIDTH 32 | float | Default; sufficient for most partitioning weight computations |
REALTYPEWIDTH 64 | double | When very precise target weight ratios are needed |
make config r64=1.
Preprocessor Constants
/* Library version */
#define METIS_VER_MAJOR 5
#define METIS_VER_MINOR 2
#define METIS_VER_SUBMINOR 1
/* Size of the options array */
#define METIS_NOPTIONS 40
METIS_NOPTIONS defines the required size of the options[] array passed to all API functions. Always declare idx_t options[METIS_NOPTIONS] and initialize with METIS_SetDefaultOptions before use.
Enumeration Types
rstatus_et — Return Codes
typedef enum {
METIS_OK = 1, /* Returned normally */
METIS_ERROR_INPUT = -2, /* Erroneous inputs or options */
METIS_ERROR_MEMORY = -3, /* Insufficient memory */
METIS_ERROR = -4 /* Other errors */
} rstatus_et;
int. Test the return value before using any output arrays:
int ret = METIS_PartGraphKway(...);
if (ret != METIS_OK) {
/* handle error */
}
moptions_et — Options Array Index
typedef enum {
METIS_OPTION_PTYPE, /* 0 - partitioning scheme */
METIS_OPTION_OBJTYPE, /* 1 - objective function */
METIS_OPTION_CTYPE, /* 2 - coarsening scheme */
METIS_OPTION_IPTYPE, /* 3 - initial partitioning scheme */
METIS_OPTION_RTYPE, /* 4 - refinement scheme */
METIS_OPTION_DBGLVL, /* 5 - debug output bitmask */
METIS_OPTION_NIPARTS, /* 6 - number of initial partition trials */
METIS_OPTION_NITER, /* 7 - refinement iterations */
METIS_OPTION_NCUTS, /* 8 - number of cuts to attempt */
METIS_OPTION_SEED, /* 9 - random seed */
METIS_OPTION_ONDISK, /* 10 - out-of-core processing */
METIS_OPTION_MINCONN, /* 11 - minimize subdomain connectivity */
METIS_OPTION_CONTIG, /* 12 - require contiguous partitions */
METIS_OPTION_COMPRESS, /* 13 - compress graph before ordering */
METIS_OPTION_CCORDER, /* 14 - order connected components separately */
METIS_OPTION_PFACTOR, /* 15 - high-degree vertex pruning factor */
METIS_OPTION_NSEPS, /* 16 - number of separators per bisection */
METIS_OPTION_UFACTOR, /* 17 - load imbalance tolerance */
METIS_OPTION_NUMBERING, /* 18 - vertex numbering (0 or 1) */
METIS_OPTION_DROPEDGES, /* 19 - drop edges during coarsening */
METIS_OPTION_NO2HOP, /* 20 - disable 2-hop matching */
METIS_OPTION_TWOHOP, /* 21 - 2-hop matching control */
METIS_OPTION_FAST, /* 22 - fast (lower quality) mode */
/* remaining entries are for internal/command-line use */
} moptions_et;
options[] array. See the Options Array Reference for full documentation of each entry.
moptype_et — Operation Type
typedef enum {
METIS_OP_PMETIS, /* Recursive bisection partitioning */
METIS_OP_KMETIS, /* Direct k-way partitioning */
METIS_OP_OMETIS /* Nested dissection ordering */
} moptype_et;
mptype_et — Partitioning Schemes
typedef enum {
METIS_PTYPE_RB, /* Multilevel recursive bisection */
METIS_PTYPE_KWAY /* Multilevel k-way partitioning */
} mptype_et;
METIS_OPTION_PTYPE. Used by mesh partitioning functions to select the underlying graph partitioner.
mgtype_et — Graph Types for Meshes
typedef enum {
METIS_GTYPE_DUAL, /* Dual graph (elements as vertices) */
METIS_GTYPE_NODAL /* Nodal graph (nodes as vertices) */
} mgtype_et;
METIS_PartMeshDual and METIS_PartMeshNodal.
mctype_et — Coarsening Schemes
typedef enum {
METIS_CTYPE_RM, /* Random matching */
METIS_CTYPE_SHEM /* Sorted heavy-edge matching */
} mctype_et;
METIS_OPTION_CTYPE. SHEM (the default) preferentially matches vertices connected by heavier edges, generally producing better coarsened graphs.
miptype_et — Initial Partitioning Schemes
typedef enum {
METIS_IPTYPE_GROW, /* Greedy grow bisection */
METIS_IPTYPE_RANDOM, /* Random bisection */
METIS_IPTYPE_EDGE, /* Edge-based separator */
METIS_IPTYPE_NODE, /* Node-based separator */
METIS_IPTYPE_METISRB /* Recursive bisection for k-way initial partition */
} miptype_et;
METIS_OPTION_IPTYPE. Defaults differ by operation: GROW for recursive bisection (single constraint), RANDOM for recursive bisection (multi-constraint), METISRB for k-way, EDGE for ordering.
mrtype_et — Refinement Schemes
typedef enum {
METIS_RTYPE_FM, /* Fiduccia-Mattheyses 2-way */
METIS_RTYPE_GREEDY, /* Greedy k-way */
METIS_RTYPE_SEP2SIDED, /* Two-sided node FM (separator) */
METIS_RTYPE_SEP1SIDED /* One-sided node FM (separator) */
} mrtype_et;
METIS_OPTION_RTYPE. FM is used by recursive bisection, GREEDY by k-way, and the separator variants by ordering. Not all combinations are valid — METIS returns METIS_ERROR_INPUT for incompatible pairs.
mdbglvl_et — Debug Levels
typedef enum {
METIS_DBG_INFO = 1, /* General diagnostic messages */
METIS_DBG_TIME = 2, /* Timing analysis */
METIS_DBG_COARSEN = 4, /* Coarsening progress */
METIS_DBG_REFINE = 8, /* Refinement progress */
METIS_DBG_IPART = 16, /* Initial partitioning info */
METIS_DBG_MOVEINFO = 32, /* Vertex moves during refinement */
METIS_DBG_SEPINFO = 64, /* Moves during separator refinement */
METIS_DBG_CONNINFO = 128, /* Subdomain connectivity minimization */
METIS_DBG_CONTIGINFO = 256, /* Connected component elimination */
METIS_DBG_MEMORY = 2048 /* Workspace allocation info */
} mdbglvl_et;
METIS_OPTION_DBGLVL. These are bitmask values — combine multiple levels with bitwise OR:
options[METIS_OPTION_DBGLVL] = METIS_DBG_INFO | METIS_DBG_TIME | METIS_DBG_REFINE;
mobjtype_et — Objective Types
typedef enum {
METIS_OBJTYPE_CUT, /* Minimize edge cut */
METIS_OBJTYPE_VOL, /* Minimize communication volume */
METIS_OBJTYPE_NODE /* Minimize node separator size */
} mobjtype_et;
METIS_OPTION_OBJTYPE. CUT is the default for partitioning; NODE is used internally by ordering. VOL minimizes the total number of distinct partition boundaries a vertex participates in, which better models communication cost in some parallel applications.
METIS_Free
int METIS_Free(void *ptr);
METIS_MeshToDual and METIS_MeshToNodal, which allocate the output xadj and adjncy arrays.
idx_t *xadj = NULL, *adjncy = NULL;
idx_t numflag = 0;
METIS_MeshToDual(&ne, &nn, eptr, eind, &ncommon, &numflag, &xadj, &adjncy);
/* ... use xadj and adjncy ... */
METIS_Free(xadj);
METIS_Free(adjncy);
METIS_Free is a thin wrapper around the C standard free(). Passing NULL is safe (no-op). Do not call METIS_Free on memory you allocated yourself, and do not call free() on memory returned by METIS mesh conversion functions (behavior is equivalent in current versions but the separation is a good practice for forward compatibility).
METIS_Free always returns METIS_OK.