Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/KarypisLab/ParMETIS/llms.txt

Use this file to discover all available pages before exploring further.

ParMETIS_V3_PartKway is the primary partitioning routine in ParMETIS. It takes a distributed graph stored in CSR format across MPI processes and computes a balanced k-way partition using the multilevel k-way algorithm. The function supports multiple balancing constraints, non-uniform target partition weights, and per-constraint imbalance tolerances, making it suitable for a wide range of scientific computing workloads. 
int ParMETIS_V3_PartKway(
    idx_t *vtxdist, idx_t *xadj, idx_t *adjncy, idx_t *vwgt,
    idx_t *adjwgt, idx_t *wgtflag, idx_t *numflag, idx_t *ncon, idx_t *nparts,
    real_t *tpwgts, real_t *ubvec, idx_t *options, idx_t *edgecut, idx_t *part,
    MPI_Comm *comm);

​
Parameters

​
vtxdist
idx_t*
Distribution of vertices across processes. vtxdist[i] is the global index of the first vertex on process i, and vtxdist[i+1] - vtxdist[i] is the number of local vertices. Size npes + 1; must be identical on all processes.
​
xadj
idx_t*
Local adjacency row pointers in CSR format. xadj[i] is the index into adjncy where the adjacency list of local vertex i begins. Size local_nvtxs + 1.
​
adjncy
idx_t*
Local adjacency column indices in CSR format. Contains the global indices of all neighbors of each local vertex. Size xadj[local_nvtxs].
​
vwgt
idx_t*
Vertex weights. There are ncon weight values per vertex stored in interleaved order: [w0_c0, w0_c1, ..., w1_c0, w1_c1, ...]. May be NULL when bit 1 of wgtflag is 0.
​
adjwgt
idx_t*
Edge weights, one value per entry in adjncy. May be NULL when bit 0 of wgtflag is 0.
​
wgtflag
idx_t*
Bitmask controlling which weights are used. Bit 0 (value 1): use adjwgt. Bit 1 (value 2): use vwgt. Combined values: 0 = no weights, 1 = edge weights only, 2 = vertex weights only, 3 = both.
​
numflag
idx_t*
Indexing convention. 0 for C-style 0-based indexing; 1 for Fortran-style 1-based indexing.
​
ncon
idx_t*
Number of balancing constraints per vertex. Each vertex carries ncon weight values, and the partition is balanced with respect to all ncon constraints simultaneously.
​
nparts
idx_t*
Desired number of partitions. Does not need to equal the number of MPI processes.
​
tpwgts
real_t*
Target partition weights. Array of nparts * ncon values. tpwgts[i * ncon + j] is the desired fraction of constraint j’s total weight assigned to partition i. All values for a given constraint must sum to 1.0. Pass NULL to request equal-sized partitions.
​
ubvec
real_t*
Per-constraint imbalance tolerance. Array of ncon values. ubvec[i] = 1.05 allows up to 5% imbalance for constraint i. Must be greater than 1.0 for all entries.
​
options
idx_t*
Algorithm options. If options[0] = 0, all defaults are used. If options[0] = 1, additional entries are read: options[PMV3_OPTION_DBGLVL] (index 1) sets the debug level, and options[PMV3_OPTION_SEED] (index 2) sets the random number seed.
​
edgecut
idx_t*
Output. Total weight of edges whose endpoints are assigned to different partitions. Written on all processes.
​
part
idx_t*
Output. Partition assignment for each local vertex. part[i] is the partition ID (0 to nparts - 1) of local vertex i. The caller must allocate this array with at least local_nvtxs elements.
​
comm
MPI_Comm*
Pointer to the MPI communicator covering all participating processes.

​
Return value

Returns METIS_OK (1) on success. Any other value indicates an error.

​
Usage example

#include <parmetis.h>

/* Assumes vtxdist, xadj, adjncy are already populated across MPI processes. */
int main(int argc, char *argv[]) {
    MPI_Init(&argc, &argv);
    MPI_Comm comm = MPI_COMM_WORLD;

    int npes, rank;
    MPI_Comm_size(comm, &npes);
    MPI_Comm_rank(comm, &rank);

    /* Graph distribution: 10 vertices per process */
    idx_t local_nvtxs = 10;
    idx_t vtxdist[npes + 1];
    for (int i = 0; i <= npes; i++) vtxdist[i] = i * local_nvtxs;

    /* CSR adjacency (populated by caller) */
    idx_t xadj[local_nvtxs + 1];
    idx_t adjncy[/* nnz */];

    idx_t wgtflag = 0;   /* no weights */
    idx_t numflag = 0;   /* 0-based indexing */
    idx_t ncon    = 1;
    idx_t nparts  = npes;
    real_t tpwgts[nparts];
    for (int i = 0; i < nparts; i++) tpwgts[i] = 1.0f / nparts;
    real_t ubvec  = 1.05f;
    idx_t options[3] = {0, 0, 0};  /* use defaults */
    idx_t edgecut;
    idx_t part[local_nvtxs];

    int ret = ParMETIS_V3_PartKway(
        vtxdist, xadj, adjncy,
        NULL, NULL,              /* no weights */
        &wgtflag, &numflag, &ncon, &nparts,
        tpwgts, &ubvec, options,
        &edgecut, part, &comm);

    if (ret != METIS_OK) { /* handle error */ }

    MPI_Finalize();
    return 0;
}

Build docs developers (and LLMs) love

Get started for freeTalk to us