Grasplogic Native

Common errors

• ModuleNotFoundError: No module named 'graspologic_native'

  cause The `graspologic-native` package is not installed in the current Python environment.
  fix Run `pip install graspologic-native` to install the package.

• ImportError: DLL load failed while importing _leiden_utils: The specified module could not be found.

  cause This error typically occurs on Windows when a compiled C++ extension cannot load its native dependencies (e.g., a specific runtime library) or if the installed wheel is incompatible with your system.
  fix Verify that your Python version and architecture (32-bit/64-bit) match the installed `graspologic-native` wheel. Reinstalling in a clean virtual environment might resolve the issue, or ensure required C++ runtime libraries (like Visual C++ Redistributable) are present. If compiling from source, ensure all build dependencies are met.

• TypeError: 'numpy.ndarray' object cannot be interpreted as an integer

  cause A function that expects a scalar integer (e.g., `random_seed`, `n_iterations`) was passed a NumPy array or another incorrect type. This often happens when mixing up matrix inputs with scalar parameters.
  fix Review the function signature and ensure that each argument is passed with the correct Python type (e.g., `10` for an integer, `np.array(...)` for a matrix). Cast types explicitly if necessary.

Warnings

• gotcha Most end-users should interact with the higher-level `graspologic` library instead of directly using `graspologic-native`. This library is primarily a C++ backend for performance-critical operations, and its direct API is less stable and less documented for general consumption.
  Fix: Prefer `import graspologic` and use its provided functions unless you have specific performance tuning or low-level integration needs.
• breaking As a compiled C++ extension, `graspologic-native` has specific Python version compatibility. Using it outside the supported Python range (currently >=3.8, <3.14) will lead to installation failures or `ImportError` due to ABI incompatibility.
  Fix: Ensure your Python environment matches the `requires_python` range specified on PyPI (e.g., Python 3.8-3.13 for version 1.2.5). Consider using a virtual environment.
• gotcha Binary wheels might not be available for all operating systems, architectures, or Python versions. If a pre-compiled wheel isn't found, `pip` will attempt to compile from source, requiring a C++ compiler (like MSVC on Windows, GCC/Clang on Linux/macOS) and development headers.
  Fix: Check PyPI for available wheels (`https://pypi.org/project/graspologic-native/#files`). If no wheel is available for your environment, ensure you have a C++ compiler installed and configured, along with Python development headers (e.g., `python3-dev` on Debian/Ubuntu).

Install

• pip install graspologic-native Install stable version

Imports

• leiden
  wrong:

  import graspologic_native.leiden

  correct:

  from graspologic_native.partition import leiden

  Functions are typically imported directly from their respective submodules (e.g., `partition`, `match`).
• GraphMatchSolver

  from graspologic_native.match import GraphMatchSolver

Quickstart

This quickstart demonstrates how to directly use the `leiden` community detection algorithm from `graspologic_native.partition`. It creates a simple adjacency matrix and applies the algorithm to find community assignments for the nodes. Note that `graspologic-native` functions often expect NumPy arrays as input.

import numpy as np
from graspologic_native.partition import leiden

# Create a sample adjacency matrix (e.g., for a small graph)
# Must be a square NumPy array, typically int or float type.
adj_matrix = np.array([
    [0, 1, 1, 0, 0],
    [1, 0, 1, 0, 0],
    [1, 1, 0, 0, 0],
    [0, 0, 0, 0, 1],
    [0, 0, 0, 1, 0]
], dtype=np.int32)

# Call the leiden community detection algorithm
# Parameters: adjacency matrix, resolution, random_seed, n_iterations
# Returns: communities (numpy array of community assignments)
communities = leiden(adj_matrix, 1.0, 42, 10)

print(f"Adjacency Matrix:\n{adj_matrix}")
print(f"Detected Communities: {communities}")

# Expected output might be something like:
# Detected Communities: [0 0 0 1 1]