Skip to content
VioGraph Docs

Algorithm Discovery

Tutorial

Algorithm Discovery

Find, inspect, and run any algorithm by name

20 min Intermediate
AlgorithmsDiscoveryNetworkXExecution

What You'll Learn

  • List native algorithms - Browse all available algorithms and filter by category
  • List NetworkX algorithms - Discover additional algorithms from the NetworkX library
  • Inspect parameters - Use algorithm_info() to see parameter names, types, and descriptions
  • Run by name - Execute any algorithm via run() when no convenience method exists
  • Control execution - Choose synchronous (wait=True) vs asynchronous (wait=False) mode
  • Handle lock conflicts - Check locks and handle ResourceLockedError during concurrent execution
1

Setup

Connect to the platform and provision a tutorial graph

# Cell 1 — Parameters
USERNAME = "_FILL_ME_IN_"  # Set your email before running
# Cell 2 — Connect
from graph_olap import GraphOLAPClient
client = GraphOLAPClient(username=USERNAME)


# Cell 3 — Provision
from notebook_setup import provision
personas, conn = provision(USERNAME)
analyst = personas["analyst"]
admin = personas["admin"]
ops = personas["ops"]
client = analyst


print(f"Connected to {conn.name} | {conn.query_scalar('MATCH (n) RETURN count(n)')} nodes")
2

Discovering Native Algorithms

List and filter the built-in algorithm catalogue

algos = conn.algo.algorithms()
print(f"Available native algorithms: {len(algos)}\n")
for algo in algos:
    print(f"  {algo['name']:25s} {algo['category']}")
centrality = conn.algo.algorithms(category="centrality")
print(f"Centrality algorithms: {len(centrality)}")
for algo in centrality:
    print(f"  {algo['name']}: {algo.get('description', '')}")
3

Inspecting Algorithm Parameters

Use algorithm_info() to understand inputs before running

info = conn.algo.algorithm_info("pagerank")
print(f"Algorithm: {info['name']}")
print(f"Category:  {info['category']}")
print(f"\nParameters:")
for p in info.get("parameters", []):
    print(f"  {p['name']:20s} {p.get('type', ''):10s} {p.get('description', '')}")
4

Discovering NetworkX Algorithms

Browse the extended algorithm library powered by NetworkX

nx_centrality = conn.networkx.algorithms(category="centrality")
print(f"NetworkX centrality algorithms: {len(nx_centrality)}\n")
for algo in nx_centrality:
    print(f"  {algo['name']:30s} {algo.get('description', '')[:50]}")
info = conn.networkx.algorithm_info("katz_centrality")
print(f"Algorithm: {info['name']}")
print(f"\nParameters:")
for p in info.get("parameters", []):
    print(f"  {p['name']:20s} {p.get('type', ''):10s} {p.get('description', '')}")
5

Running Algorithms with run()

Execute any algorithm by name -- no convenience method needed

# Run Louvain community detection via generic run()
result = conn.algo.run(
    "louvain",
    node_label="Customer",
    edge_type="SHARES_ACCOUNT",
    property_name="discovery_community",
    params={"resolution": 1.5},
)


print(f"Algorithm:    {result.algorithm}")
print(f"Status:       {result.status}")
print(f"Execution ID: {result.execution_id}")
print(f"Duration:     {result.duration_ms}ms")
print(f"Nodes updated: {result.nodes_updated}")
# Run Katz centrality (no convenience method for this one)
result = conn.networkx.run(
    "katz_centrality",
    node_label="Customer",
    property_name="katz_score",
    params={"alpha": 0.1},
)


print(f"Algorithm:    {result.algorithm}")
print(f"Type:         {result.algorithm_type}")
print(f"Status:       {result.status}")


# Query results
top = conn.query(
    "MATCH (c:Customer) WHERE c.katz_score IS NOT NULL "
    "RETURN c.id, c.katz_score ORDER BY c.katz_score DESC LIMIT 5"
)
for row in top:
    print(f"  {row['c.id']:20s} {row['c.katz_score']:.4f}")
6

Synchronous vs Asynchronous Execution

Choose blocking or non-blocking algorithm runs

# Asynchronous: returns immediately
exec_async = conn.algo.run(
    "pagerank",
    node_label="Customer",
    edge_type="SHARES_ACCOUNT",
    property_name="pr_async",
    wait=False,  # Don't block
)
print(f"Submitted:    {exec_async.execution_id}")
print(f"Status:       {exec_async.status}")  # "pending" or "running"


# In practice, you would poll or wait. For this tutorial,
# the algorithm completes quickly on our small graph.
import time
time.sleep(2)


# Re-run with wait=True to verify it completed
exec_sync = conn.algo.run(
    "pagerank",
    node_label="Customer",
    edge_type="SHARES_ACCOUNT",
    property_name="pr_sync",
    wait=True,  # Block until done
)
print(f"\nSynchronous:  {exec_sync.status}")
print(f"Duration:     {exec_sync.duration_ms}ms")
7

Handling Lock Conflicts

Check instance locks before running algorithms

from graph_olap.exceptions import ResourceLockedError


# Check lock before running
lock = conn.get_lock()
if lock.locked:
    print(f"Instance locked by {lock.holder_name}, running {lock.algorithm}")
else:
    print("Instance is unlocked — safe to run algorithms")


# Handle lock conflicts gracefully
try:
    result = conn.algo.run(
        "wcc",
        node_label="Customer",
        edge_type="SHARES_ACCOUNT",
        property_name="wcc_discovery",
    )
    print(f"WCC completed: {result.status}")
except ResourceLockedError as e:
    print(f"Lock conflict: {e}")
    print("Wait for the current algorithm to complete, then retry")

Key Takeaways

  • algorithms() lists all available algorithms; filter by category to narrow results
  • algorithm_info() reveals parameter names, types, and descriptions before you run
  • run() executes any algorithm by name -- use it when no convenience method exists
  • Use wait=True (default) for synchronous execution, wait=False for async
  • Check conn.get_lock() before running to avoid ResourceLockedError
  • AlgorithmExecution provides metadata: execution_id, duration_ms, nodes_updated