Libleidenalg.Wrapper 1.2.0

Libleidenalg.Wrapper

Managed .NET wrapper for the native libleidenalg library.

Supported platforms

The published Windows x64 package includes native runtime assets:

• runtimes/win-x64/native/libleidenalg.dll
• runtimes/win-x64/native/igraph.dll

Other operating systems and CPU architectures are not bundled yet. To use this package on another platform, provide matching native libleidenalg and igraph shared libraries at runtime.

Linux x64 assets are a planned packaging improvement for container and App Service deployments, but they are not included in this package yet.

Install

dotnet add package Libleidenalg.Wrapper

The package targets .NET 8.0.

Current API

The managed wrapper exposes these native Leiden partition models:

All models support unweighted and weighted graphs. Modularity also supports a separate weights argument for callers that store edge weights separately from the edge list.

Modularity partitioning:

int[] LeidenModularity.Partition(
    int vertexCount,
    IReadOnlyList<(int From, int To)> edges,
    bool directed,
    ulong seed,
    out double quality);

int[] LeidenModularity.Partition(
    int vertexCount,
    IReadOnlyList<(int From, int To, double Weight)> edges,
    bool directed,
    ulong seed,
    out double quality);

int[] LeidenModularity.Partition(
    int vertexCount,
    IReadOnlyList<(int From, int To)> edges,
    IReadOnlyList<double> weights,
    bool directed,
    ulong seed,
    out double quality);

Resolution-based partitioning:

int[] LeidenCpm.Partition(
    int vertexCount,
    IReadOnlyList<(int From, int To)> edges,
    bool directed,
    double resolution,
    ulong seed,
    out double quality);

int[] LeidenCpm.Partition(
    int vertexCount,
    IReadOnlyList<(int From, int To, double Weight)> edges,
    bool directed,
    double resolution,
    ulong seed,
    out double quality);

int[] LeidenRbConfiguration.Partition(
    int vertexCount,
    IReadOnlyList<(int From, int To, double Weight)> edges,
    bool directed,
    double resolution,
    ulong seed,
    out double quality);

int[] LeidenRber.Partition(
    int vertexCount,
    IReadOnlyList<(int From, int To, double Weight)> edges,
    bool directed,
    double resolution,
    ulong seed,
    out double quality);

Non-resolution partitioning:

int[] LeidenSignificance.Partition(
    int vertexCount,
    IReadOnlyList<(int From, int To, double Weight)> edges,
    bool directed,
    ulong seed,
    out double quality);

int[] LeidenSurprise.Partition(
    int vertexCount,
    IReadOnlyList<(int From, int To, double Weight)> edges,
    bool directed,
    ulong seed,
    out double quality);

For callers that prefer a single return object, PartitionWithDetails(...) overloads are available on every managed partition model. They return LeidenPartitionResult, which contains Membership, Quality, CommunityCount, Elapsed, NativeVersion, PartitionType, and Resolution.

For deployment diagnostics, call LeidenNativeInfo.GetVersion() to read the native libleidenalg runtime version loaded by the process.

Parameters:

• vertexCount: number of vertices in the graph. Vertices are indexed from 0 to vertexCount - 1.
• edges: edge list as (From, To) pairs, or weighted (From, To, Weight) tuples.
• weights: optional separate edge weights list. The count must match edges.
• directed: whether to treat the graph as directed.
• resolution: CPM, RBConfiguration, and RBER resolution parameter. Larger values generally favor smaller communities.
• seed: random seed forwarded to the native optimiser for reproducible runs.
• quality: receives the native quality value for the returned partition.

Return value:

• int[]: community membership per vertex. The array length is vertexCount, and membership[i] is the community id assigned to vertex i.

Exceptions:

• ArgumentOutOfRangeException: vertexCount is negative.
• ArgumentOutOfRangeException: an edge endpoint is outside 0..vertexCount-1.
• ArgumentOutOfRangeException: a weight or resolution value is not finite and greater than zero.
• ArgumentNullException: edges is null.
• ArgumentNullException: weights is null for the separate weights overload.
• ArgumentException: weights.Count does not match edges.Count.
• LeidenException: native libleidenalg returns an error.

Example

using Libleidenalg;

var edges = new List<(int From, int To)>
{
    (0, 1),
    (1, 2),
    (2, 0),
    (3, 4)
};

double quality;
int[] membership = LeidenModularity.Partition(
    vertexCount: 5,
    edges: edges,
    directed: false,
    seed: 42,
    quality: out quality);

Console.WriteLine(string.Join(",", membership));
Console.WriteLine(quality);

Weighted modularity example

Use weighted edges when edge strength represents co-mention counts, confidence, relationship strength, or repeated evidence. In weighted mode, each edge weight is passed directly to native libleidenalg/igraph.

using Libleidenalg;

var edges = new List<(int From, int To, double Weight)>
{
    (0, 1, 10.0),
    (1, 2, 10.0),
    (2, 0, 10.0),
    (2, 3, 0.25),
    (3, 4, 10.0),
    (4, 5, 10.0),
    (5, 3, 10.0)
};

int[] membership = LeidenModularity.Partition(
    vertexCount: 6,
    edges: edges,
    directed: false,
    seed: 42,
    quality: out double quality);

CPM example

CPM is useful when you want an explicit resolution parameter and want to avoid modularity's known resolution limit.

using Libleidenalg;

var edges = new List<(int From, int To, double Weight)>
{
    (0, 1, 1.0),
    (1, 2, 1.0),
    (3, 4, 1.0)
};

int[] membership = LeidenCpm.Partition(
    vertexCount: 5,
    edges: edges,
    directed: false,
    resolution: 0.1,
    seed: 42,
    quality: out double quality);

Duplicate edges

Duplicate edges are preserved as parallel edges. The native graph wrapper uses igraph adjacency lists configured with multiple-edge support, and the weight of parallel edges contributes to node/community strength. For production GraphRAG graphs, prefer aggregating repeated evidence into a single weighted edge because it makes intent explicit and usually reduces graph size.

For example, repeated (A, B) observations can be represented as one (A, B, count) weighted edge.

Resolution guidance

The modularity, significance, and surprise overloads do not expose a resolution parameter because their native partition models do not support one. Use LeidenCpm.Partition(...), LeidenRbConfiguration.Partition(...), or LeidenRber.Partition(...) when you need explicit resolution tuning.

For CPM, RBConfiguration, and RBER, lower resolution values generally produce larger communities and higher values generally produce smaller communities. Practical starting points depend on graph density and weight scale, but useful first sweeps are often 0.01, 0.05, 0.1, 0.5, and 1.0. Weighted GraphRAG graphs with large edge weights may need larger resolution values than sparse unweighted graphs.

Synchronous execution and cancellation

Partitioning calls are synchronous native calls. Cancellation is not currently supported once optimisation has entered native libleidenalg. If you need to keep an application responsive, run partitioning on a background worker and use your own timeout or cancellation policy before starting the native call.

Rough graph-size guidance

Performance depends on graph topology, edge count, density, directedness, and resolution settings. As a practical starting point:

• Keep graph construction outside hot loops.
• Aggregate repeated evidence into weighted edges to reduce edge count.
• Start with smaller subgraphs when tuning resolution.
• Capture LeidenPartitionResult.Elapsed in production traces for your own workload-specific benchmarks.
• Very dense graphs or graphs with millions of edges should be benchmarked in the target hosting environment before using them on request paths.

Example output:

0,0,0,1,1
0.375

Notes

• The current wrapper covers modularity and CPM partitioning. The native C++ library supports additional partition models; those are not yet exposed by this .NET package.
• Edge endpoints should refer to valid vertex ids. Invalid native inputs are reported as LeidenException when detected by the C API.
• For large graphs, prefer constructing the edge list once and reusing it rather than rebuilding tuples repeatedly in hot loops.
• The package and bundled native runtime are GPL-3.0-or-later. Applications that redistribute this package or derived binaries should review GPL obligations with their legal counsel.