Quick Start Guide
=================

Installation
------------

Basic Installation::

    pip install graphem-rapids

With CUDA support::

    pip install graphem-rapids[cuda]

With RAPIDS cuVS::

    pip install graphem-rapids[rapids]

All features::

    pip install graphem-rapids[all]

Basic Usage
-----------

Generate and Embed a Graph
~~~~~~~~~~~~~~~~~~~~~~~~~~~

::

    import graphem_rapids as gr

    # Generate graph (returns sparse adjacency matrix)
    adjacency = gr.generate_er(n=1000, p=0.01, seed=42)

    # Create embedder with automatic backend selection
    embedder = gr.create_graphem(adjacency, n_components=3)

    # Run force-directed layout
    embedder.run_layout(num_iterations=50)

    # Get positions (numpy array)
    positions = embedder.get_positions()  # shape: (n_vertices, n_components)

    # Visualize (2D or 3D)
    embedder.display_layout()

Backend Selection
-----------------

Automatic (Recommended)
~~~~~~~~~~~~~~~~~~~~~~~

::

    embedder = gr.create_graphem(adjacency, n_components=3)

PyTorch Backend
~~~~~~~~~~~~~~~

Best for 1K-100K vertices::

    embedder = gr.GraphEmbedderPyTorch(
        adjacency, n_components=3, device='cuda',
        L_min=1.0, k_attr=0.2, k_inter=0.5,
        n_neighbors=10, batch_size=None
    )

RAPIDS cuVS Backend
~~~~~~~~~~~~~~~~~~~

Best for 100K+ vertices::

    embedder = gr.GraphEmbedderCuVS(
        adjacency, n_components=3,
        index_type='auto',  # 'brute_force', 'ivf_flat', 'ivf_pq'
        sample_size=1024, batch_size=None
    )

**Index Types:**
  * ``brute_force``: <100K vertices (exact KNN)
  * ``ivf_flat``: 100K-1M vertices (good balance)
  * ``ivf_pq``: >1M vertices (memory-efficient)

Configuration
-------------

Environment Variables
~~~~~~~~~~~~~~~~~~~~~

::

    export GRAPHEM_BACKEND=pytorch        # Force specific backend
    export GRAPHEM_PREFER_GPU=true        # Prefer GPU backends
    export GRAPHEM_MEMORY_LIMIT=8         # Memory limit in GB
    export GRAPHEM_VERBOSE=true           # Enable verbose logging

Programmatic Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~

::

    from graphem_rapids.utils.backend_selection import BackendConfig, get_optimal_backend

    config = BackendConfig(
        n_vertices=50000,
        force_backend='cuvs',
        memory_limit=16.0,
        prefer_gpu=True
    )
    backend = get_optimal_backend(config)
    embedder = gr.create_graphem(adjacency, backend=backend)

Check Available Backends
~~~~~~~~~~~~~~~~~~~~~~~~

::

    info = gr.get_backend_info()
    print(f"CUDA: {info['cuda_available']}")
    print(f"Recommended: {info['recommended_backend']}")