{"id":9794,"library":"graspologic-native","title":"Grasplogic Native","description":"Graspologic-native is a Python native companion module providing high-performance C++ implementations for core algorithms used by the `graspologic` library, such as graph matching, partitioning, and clustering. It offers accelerated computation for graph-theoretic operations. The current version is 1.2.5, and its release cadence generally aligns with major updates to the `graspologic` library.","status":"active","version":"1.2.5","language":"en","source_language":"en","source_url":"https://github.com/microsoft/graspologic-native","tags":["graph-theory","network-analysis","algorithms","performance","native-extension","community-detection"],"install":[{"cmd":"pip install graspologic-native","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"This library is primarily a low-level backend for graspologic; direct usage is less common.","package":"graspologic","optional":true},{"reason":"Functions within graspologic-native typically expect and return NumPy arrays for graph data structures.","package":"numpy","optional":false},{"reason":"Often used alongside NumPy for sparse matrix operations and other scientific computing tasks related to graphs.","package":"scipy","optional":true}],"imports":[{"note":"Functions are typically imported directly from their respective submodules (e.g., `partition`, `match`).","wrong":"import graspologic_native.leiden","symbol":"leiden","correct":"from graspologic_native.partition import leiden"},{"symbol":"GraphMatchSolver","correct":"from graspologic_native.match import GraphMatchSolver"}],"quickstart":{"code":"import numpy as np\nfrom graspologic_native.partition import leiden\n\n# Create a sample adjacency matrix (e.g., for a small graph)\n# Must be a square NumPy array, typically int or float type.\nadj_matrix = np.array([\n    [0, 1, 1, 0, 0],\n    [1, 0, 1, 0, 0],\n    [1, 1, 0, 0, 0],\n    [0, 0, 0, 0, 1],\n    [0, 0, 0, 1, 0]\n], dtype=np.int32)\n\n# Call the leiden community detection algorithm\n# Parameters: adjacency matrix, resolution, random_seed, n_iterations\n# Returns: communities (numpy array of community assignments)\ncommunities = leiden(adj_matrix, 1.0, 42, 10)\n\nprint(f\"Adjacency Matrix:\\n{adj_matrix}\")\nprint(f\"Detected Communities: {communities}\")\n\n# Expected output might be something like:\n# Detected Communities: [0 0 0 1 1]","lang":"python","description":"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."},"warnings":[{"fix":"Prefer `import graspologic` and use its provided functions unless you have specific performance tuning or low-level integration needs.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"All versions"},{"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).","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Run `pip install graspologic-native` to install the package.","cause":"The `graspologic-native` package is not installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'graspologic_native'"},{"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.","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.","error":"ImportError: DLL load failed while importing _leiden_utils: The specified module could not be found."},{"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.","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.","error":"TypeError: 'numpy.ndarray' object cannot be interpreted as an integer"}]}