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_PartGeomKway extends the standard multilevel k-way partitioner by incorporating vertex coordinate information. The coordinates are used to compute an initial geometric partition that seeds the multilevel refinement, which can significantly improve partition quality for graphs derived from spatial discretizations such as finite element or finite difference meshes. When the communicator contains more than 4096 processes, the function automatically falls back to ParMETIS_V3_PartKway. 
int ParMETIS_V3_PartGeomKway(
    idx_t *vtxdist, idx_t *xadj, idx_t *adjncy, idx_t *vwgt,
    idx_t *adjwgt, idx_t *wgtflag, idx_t *numflag, idx_t *ndims, real_t *xyz,
    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. 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. ncon values per vertex in interleaved order. 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. 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.
​
ndims
idx_t*
Number of coordinate dimensions. Must be 2 (2D) or 3 (3D).
​
xyz
real_t*
Vertex coordinates for all local vertices, stored interleaved by vertex: [x0, y0, z0, x1, y1, z1, ...]. Size local_nvtxs * ndims.
​
ncon
idx_t*
Number of balancing constraints per vertex.
​
nparts
idx_t*
Desired number of partitions.
​
tpwgts
real_t*
Target partition weights. Array of nparts * ncon values. Values for each constraint must sum to 1.0. Pass NULL for equal-weight partitions.
​
ubvec
real_t*
Per-constraint imbalance tolerance. Array of ncon values greater than 1.0. For example, 1.05 allows 5% imbalance.
​
options
idx_t*
Algorithm options. If options[0] = 0, all defaults are used. If options[0] = 1, options[1] sets the debug level and options[2] sets the random seed.
​
edgecut
idx_t*
Output. Total weight of edges crossing partition boundaries.
​
part
idx_t*
Output. Partition assignment for each local vertex. Caller must allocate 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.
When the communicator contains more than 4096 processes, this function automatically falls back to ParMETIS_V3_PartKway and ignores the coordinate data.

​
Usage example

#include <parmetis.h>

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);

    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 */];

    /* 2D coordinates for each local vertex */
    idx_t ndims = 2;
    real_t xyz[local_nvtxs * 2]; /* [x0, y0, x1, y1, ...] */

    idx_t wgtflag = 0;
    idx_t numflag = 0;
    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};
    idx_t edgecut;
    idx_t part[local_nvtxs];

    int ret = ParMETIS_V3_PartGeomKway(
        vtxdist, xadj, adjncy,
        NULL, NULL,
        &wgtflag, &numflag, &ndims, xyz,
        &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