PyTorch Hyperbolic

https://pytorch-hyperbolic.readthedocs.io/en/latest/
Admin
A PyTorch package designed to make the implementation of hyperbolic neural networks easier and...
Tokens:9,001
Snippets:56
Trust Score:9.6
Update:4 months ago
Show doc for...
Tokens:
Raw
### Plotting Transformations with Scaled Parameters

Source: https://pytorch-hyperbolic.readthedocs.io/en/latest/intuition_lorentz.html

Demonstrates the effect of scaled linear transformations on point clouds, showing how large values are handled. This is a variation of the previous example with amplified parameters.

```python
plot_transformations(x, parameters*100, point_indices)

```

--------------------------------

### Initialize and Visualize 2D Data

Source: https://pytorch-hyperbolic.readthedocs.io/en/latest/intuition.html

Initializes a 2D array of random values and visualizes them using a colormap based on their distance from the origin. Requires torch and matplotlib.

```python
import torch
import matplotlib.pyplot as plt

def map_colors(values):
    import matplotlib as mpl

    cmap = mpl.colormaps["viridis"]

    values = values.pow(2).sum(dim=1).sqrt()

    values = values - values.min()

    values = values / values.max()

    return cmap(values)

fig, ax = plt.subplots(figsize=(5,5))
x = torch.rand(100,2) * 10
x = x - x.mean()

colors = map_colors(x)
ax.scatter(x[:, 0], x[:, 1], s=1, c=colors)
```

--------------------------------

### HypLinear Layer Initialization

Source: https://pytorch-hyperbolic.readthedocs.io/en/latest/nn.html

Initializes a Hyperbolic Linear layer, performing linear transformations in hyperbolic space.

```python
Hyperbolic linear layer.
```

--------------------------------

### Compare Distances in Euclidean and Hyperbolic Spaces

Source: https://pytorch-hyperbolic.readthedocs.io/en/latest/intuition.html

Calculates and visualizes the distances between two specific points in the input space and in hyperbolic spaces with varying curvatures. Demonstrates how perceived distances change with curvature.

```python
ball = PoincareBall()
curvatures = [None, 1, 3, 5]

point_indices = [1, 14]

fig, axes = plt.subplots(ncols= 4, nrows=1, figsize=(16,4))

for ax, curvature in zip(axes, curvatures):
    if curvature is None:
        ax.scatter(x[:, 0], x[:, 1], s=1, c=colors)
        ax.scatter(x[point_indices, 0], x[point_indices, 1], s=5, c="r")
        distance_x = x[point_indices[0], 0] - x[point_indices[1], 0]
        distance_y = x[point_indices[0], 1] - x[point_indices[1], 1]
        distance = math.sqrt((distance_x ** 2) + (distance_y ** 2))
        ax.set_title("Input Space\nd={:.2}".format(distance))
    else:
        x_balled = ball.proj(ball.expmap0(x, c=curvature), c=curvature)
        ax.scatter(x_balled[:, 0], x_balled[:, 1], s=1, c=colors)
        ax.scatter(x_balled[point_indices, 0], x_balled[point_indices, 1], s=5, c="r")
        distance = math.sqrt(ball.sqdist(x_balled[point_indices[0],:], x_balled[point_indices[1], :], c=curvature))
        radius = 1/math.sqrt(curvature)
        circle2 = plt.Circle((0, 0), radius, color='lightgray', fill=False)
        ax.add_patch(circle2)
        ax.set_title("Curvature {}
d={}".format(curvature, round(distance, 1)))
        ax.set_ylim((-1,1))
        ax.set_xlim((-1,1))
```

--------------------------------

### Visualize Poincaré Disk with Varying Curvature

Source: https://pytorch-hyperbolic.readthedocs.io/en/latest/intuition.html

Visualizes how data points are projected onto the Poincaré Disk manifold with different curvature values. Higher curvature appears to bring points closer together visually, but actual distances differ.

```python
ball = PoincareBall()
curvatures = [1, 3, 5]

fig, axes = plt.subplots(ncols= 3, nrows=1, figsize=(15,5))

for ax, curvature in zip(axes, curvatures):
    x_balled = ball.proj(ball.expmap0(x, c=curvature), c=curvature)
    ax.scatter(x_balled[:, 0], x_balled[:, 1], s=1,c=colors)

    radius = 1/math.sqrt(curvature)
    circle2 = plt.Circle((0, 0), radius, color='lightgray', fill=False)
    ax.add_patch(circle2)
    ax.set_title("Curvature {}".format(curvature))
    ax.set_ylim((-1,1))
    ax.set_xlim((-1,1))
```

--------------------------------

### HGATConv Layer Initialization

Source: https://pytorch-hyperbolic.readthedocs.io/en/latest/nn.html

Initializes a Hyperbolic Graph Attention Convolutional layer. Similar to HGCNConv, it assumes input features are on the manifold and outputs features on the manifold.

```python
Hyperbolic graph attention layer.
It assumes that the input is already on the manifold and outputs the feature matrix on the manifold.
```

--------------------------------

### HGCNConv Layer Initialization

Source: https://pytorch-hyperbolic.readthedocs.io/en/latest/nn.html

Initializes a Hyperbolic Graph Convolutional layer. It assumes input features are already on the manifold and outputs features also on the manifold. This implementation is based on HGCN models and adapted for PyTorch Geometric's MessagePassing framework.

```python
It assumes that the input is already on the manifold and outputs the feature matrix on the manifold.
Implementation based on https://github.com/HazyResearch/hgcn/blob/master/layers/hyp_layers.py but implemented for the MessagePassing framework using the GCN template from https://pytorch-geometric.readthedocs.io/en/latest/tutorial/create_gnn.html#implementing-the-gcn-layer
```

--------------------------------

### Project Data onto Poincaré Ball Manifold

Source: https://pytorch-hyperbolic.readthedocs.io/en/latest/intuition.html

Projects 2D Euclidean data onto a Poincaré Ball manifold using the exponential map and then back to Euclidean space. Visualizes the original, projected, and re-projected data, highlighting two tracked points and the Poincaré Disk boundary. Requires torch_hyperbolic and math.

```python
from torch_hyperbolic.manifolds import PoincareBall
import math

curvature = 1
point_indices = [1, 14]

ball = PoincareBall()
x_balled = ball.expmap0(x, c=curvature)
x_back_euclidean = ball.logmap0(x_balled, c=curvature)
fig, axes = plt.subplots(ncols=3, nrows=1, figsize=(15,5))

for ax, values, title in zip(axes, [x, x_balled, x_back_euclidean], ["Euclidean", "Hyperbolic", "Back to Euclidean"]):
    ax.scatter(values[:, 0], values[:, 1], s=1, c=colors)
    ax.scatter(values[point_indices, 0], values[point_indices, 1], s=3, c="r")
    radius = 1/math.sqrt(curvature)
    circle2 = plt.Circle((0, 0), radius, color='lightgray', fill=False)
    ax.add_patch(circle2)
    ax.set_title(title)
```

--------------------------------

### Visualize 2D Point Cloud in Euclidean Space

Source: https://pytorch-hyperbolic.readthedocs.io/en/latest/intuition_lorentz.html

Generates a scatter plot of 1000 random 2D points, colored according to their distance from the origin using the map_colors function. Requires torch and matplotlib.pyplot.

```python
import torch
import matplotlib.pyplot as plt
fig, ax = plt.subplots(figsize=(5,5))
x = torch.rand(1000,2)
x = x - x.mean()
colors = map_colors(x)
ax.scatter(x[:, 0], x[:, 1], s=1, c=colors)
```

--------------------------------

### Visualize Euclidean and Hyperbolic Bias Addition

Source: https://pytorch-hyperbolic.readthedocs.io/en/latest/intuition.html

This function visualizes the results of adding a bias parameter to a point in both Euclidean and hyperbolic spaces. It compares Euclidean addition with Möbius addition in the hyperbolic space and shows the transformed results in the respective other space. Use this to understand the geometric implications of bias addition.

```python
from torch_hyperbolic.manifolds import PoincareBall

ball = PoincareBall()
parameters = torch.rand(2,).double()
point_indices = [1, 14]

def plot_addition(x, parameters, point_indices):

        a = x.double()

        b = a + parameters

        curvature = 1

        c = ball.proj(ball.expmap0(b, c=curvature), c=curvature)

        d = ball.proj(ball.expmap0(a, c=curvature), c=curvature)

        hyperbolic_bias = ball.proj(ball.expmap0(parameters, c=curvature),c=curvature)

        e = ball.proj(ball.mobius_add(d, hyperbolic_bias, c=curvature), c=curvature)

        f = ball.logmap0(e, c = curvature)

        fig, axes = plt.subplots(ncols= 3, nrows=2, figsize=(16,8))

        titles = ["a. Euclidean Input\n$d={}$",
                "b. Euclidean Addition\n$d={}$",
                "c. Euclidean Add. into Hyperbolic\n$d={}$",
                "d. Hyperbolic Input\n$d={}$",
                "e. Möbius Additionn\n$d={}$",
                "f. Möbius Add. into Euclidean\n$d={}$"]


        for i, (ax, values) in enumerate(zip(axes.flatten(), [a, b, c, d, e, f])):
                ax.scatter(values[:, 0], values[:, 1], s=1, c=colors)
                ax.scatter(values[point_indices, 0], values[point_indices, 1], s=5, c="r")
                if i < 2 or i == 5:
                        distance_x = values[point_indices[0], 0] - values[point_indices[1], 0]
                        distance_y = values[point_indices[0], 1] - values[point_indices[1], 1]
                        distance = math.sqrt((distance_x ** 2) + (distance_y ** 2))
                else:
                        distance = math.sqrt(ball.sqdist(values[point_indices[0],:], values[point_indices[1], :], c=curvature))
                radius = 1/math.sqrt(curvature)
                circle2 = plt.Circle((0, 0), radius, color='lightgray', fill=False)
                ax.add_patch(circle2)
                ax.set_title(titles[i].format(round(distance,2)))

        plt.tight_layout()

plot_addition(x, parameters, point_indices)

```

--------------------------------

### Map Euclidean Points to Hyperboloid Manifold

Source: https://pytorch-hyperbolic.readthedocs.io/en/latest/intuition_lorentz.html

Projects 2D Euclidean points into a 3D Hyperboloid manifold, then back to Euclidean space to visualize the transformation. Demonstrates the effect of curvature on the manifold's shape and point distances. Requires torch_hyperbolic, math, and matplotlib.pyplot.

```python
from torch_hyperbolic.manifolds import Hyperboloid
import math

curvature = 1
point_indices = [1, 14]

ball = Hyperboloid()

colors = map_colors(x)

x_0 = torch.zeros((x.shape[0],)).unsqueeze(-1)

x_0 = torch.cat((x_0, x), dim=-1)

x_balled = ball.proj(ball.expmap0(x_0, c=curvature), c=curvature)
x_back_euclidean = ball.proj_tan0(ball.logmap0(x_balled, c=curvature), c=curvature)
fig = plt.figure(figsize=plt.figaspect(0.33))

for i, (values, title) in enumerate(zip([x_0, x_balled, x_back_euclidean], ["Euclidean", "Hyperbolic", "Back to Euclidean"])):
    ax = fig.add_subplot(1,3,i+1, projection='3d')
    ax.scatter(values[:, 1], values[:, 2], values[:, 0], s=1, c=colors)
    ax.set_title(title)

plt.tight_layout()
```

--------------------------------

### HFiLMConv Layer Initialization

Source: https://pytorch-hyperbolic.readthedocs.io/en/latest/nn.html

Initializes a Hyperbolic Feature-wise Linear Modulation Graph Convolutional layer. This layer also assumes input features are on the manifold and outputs features on the manifold.

```python
Hyperbolic feature-wise linear modulation graph convolution layer.
It assumes that the input is already on the manifold and outputs the feature matrix on the manifold.
```

--------------------------------

### Plotting Linear Transformations in Lorentz Model

Source: https://pytorch-hyperbolic.readthedocs.io/en/latest/intuition_lorentz.html

Visualizes the effect of matrix multiplication on point clouds in Euclidean and hyperbolic spaces. Requires PyTorch, Matplotlib, and the hyperbolic library.

```python
parameters = torch.rand((3,3)).double()
point_indices = [1, 14]


def plot_transformations(x, parameters, point_indices):

        curvature = 10

        a = x_0.double()

        b = torch.mm(a, parameters)

        b[:, 0] = 0

        c = ball.proj(ball.expmap0(b, c=curvature), c=curvature)

        d = ball.proj(ball.expmap0(a, c=curvature), c=curvature)

        e = ball.proj(ball.mobius_matvec(parameters, d, c=curvature), c=curvature)

        f = ball.logmap0(e, c = curvature)

        f[:, 0] = 0

        titles = ["a. Euclidean Input\n$d={}$",
                "b. Euclidean Transformation\n$d={}$",
                "c. Euclidean Transf. into Hyperbolic\n$d={}$",
                "d. Hyperbolic Input\n$d={}$",
                "e. Möbius Matvec Transformation\n$d={}$",
                "f.Möbius Transf. into Euclidean\n$d={}$"]

        fig = plt.figure(figsize=plt.figaspect(0.4))

        for i, values in enumerate([a, b, c, d, e, f]):
                ax = fig.add_subplot(2,3,i+1, projection='3d')
                ax.scatter(values[:, 1], values[:, 2], values[:, 0], s=1 , c=colors)
                ax.scatter(values[point_indices, 1], values[point_indices, 2], values[point_indices, 0], s=10, c="r")
                if i < 2 or i == 5:
                        distance_x = values[point_indices[0], 1] - values[point_indices[1], 1]
                        distance_y = values[point_indices[0], 2] - values[point_indices[1], 2]
                        distance = math.sqrt((distance_x ** 2) + (distance_y ** 2))
                else:
                        distance = math.sqrt(ball.sqdist(values[point_indices[0],:], values[point_indices[1], :], c=curvature))
                ax.set_title(titles[i].format(round(distance,2)))

        plt.tight_layout()

plot_transformations(x, parameters, point_indices)

```

--------------------------------

### Compare Distances for Points Near Origin

Source: https://pytorch-hyperbolic.readthedocs.io/en/latest/intuition.html

Repeats the distance comparison for two points selected to be closer to the origin. This helps illustrate how the hyperbolic distance metric behaves differently for points located near the center versus near the boundary of the Poincaré Disk.

```python
ball = PoincareBall()
curvatures = [None, 1, 3, 5]

point_indices = x.pow(2).sum(dim=-1).argsort()[0:2].tolist()

fig, axes = plt.subplots(ncols= 4, nrows=1, figsize=(16,4))

for ax, curvature in zip(axes, curvatures):
    if curvature is None:
        ax.scatter(x[:, 0], x[:, 1], s=1, c=colors)
        ax.scatter(x[point_indices, 0], x[point_indices, 1], s=5, c="r")
        distance_x = x[point_indices[0], 0] - x[point_indices[1], 0]
        distance_y = x[point_indices[0], 1] - x[point_indices[1], 1]
        distance = math.sqrt((distance_x ** 2) + (distance_y ** 2))
        ax.set_title("Input Space\nd={:.2}".format(distance))
    else:

```

--------------------------------

### Map Colors Based on Euclidean Distance

Source: https://pytorch-hyperbolic.readthedocs.io/en/latest/intuition_lorentz.html

Maps a set of 2D points to colors using the 'viridis' colormap based on their Euclidean distance from the origin. Requires matplotlib and torch.

```python
def map_colors(values):
    import matplotlib as mpl

    cmap = mpl.colormaps["viridis"]

    values = values.pow(2).sum(dim=1).sqrt()

    values = values - values.min()

    values = values / values.max()

    return cmap(values)
```

--------------------------------

### Compare Point Distances in Euclidean vs. Hyperbolic Space

Source: https://pytorch-hyperbolic.readthedocs.io/en/latest/intuition_lorentz.html

Compares the distance between two points in Euclidean space and on the Hyperboloid manifold for various curvature values. Demonstrates that curvature has less impact on distances for points closer to the origin. Requires matplotlib.pyplot and math.

```python
curvatures = [None, 1, 5, 10]

point_indices = x.pow(2).sum(dim=-1).argsort()[0:2].tolist()

fig = plt.figure(figsize=plt.figaspect(0.25))

for i, curvature in enumerate(curvatures):
    ax = fig.add_subplot(1,4,i+1, projection='3d')
    if curvature is None:
        ax.scatter(x_0[:, 1], x_0[:, 2], x_0[:, 0], s=1, c=colors)
        ax.scatter(x_0[point_indices, 1], x_0[point_indices, 2], x_0[point_indices, 0], s=10, c="r")
        distance_x = x[point_indices[0], 0] - x[point_indices[1], 0]
        distance_y = x[point_indices[0], 1] - x[point_indices[1], 1]
        distance = math.sqrt((distance_x ** 2) + (distance_y ** 2))
        ax.set_title("Input Space\nd={:.5}".format(distance))
    else:
        x_balled = ball.proj(ball.expmap0(x_0, c=curvature), c=curvature)
        ax.scatter(x_balled[:, 1], x_balled[:, 2], x_balled[:, 0], s=1, c=colors)
        ax.scatter(x_balled[point_indices, 1], x_balled[point_indices, 2], x_balled[point_indices, 0], s=10, c="r")
```

--------------------------------

### Visualize Transformations with Scaled Parameters

Source: https://pytorch-hyperbolic.readthedocs.io/en/latest/intuition.html

This snippet calls the `plot_transformations` function with parameters multiplied by 5 to demonstrate the effect of larger transformations, particularly near the manifold's boundaries. It highlights how points can be pushed together and how projection handles extreme values.

```python
plot_transformations(x, parameters*5, point_indices)
```

--------------------------------

### HGATConv

Source: https://pytorch-hyperbolic.readthedocs.io/en/latest/nn.html

Implements a Hyperbolic Graph Attention Network (HGAT) layer. Similar to HGCNConv, it operates on features already present on the hyperbolic manifold.

```APIDOC
## HGATConv

### Description
Hyperbolic graph attention layer. It assumes that the input is already on the manifold and outputs the feature matrix on the manifold.

### Class Signature
`HGATConv(in_channels, out_channels, c, manifold='PoincareBall', dropout=0, heads=1, use_bias=True, edge_dim=None, aggr='add', local_agg=False, concat=True, negative_slope=0.2, fill_value='mean', **kwargs)`

### Parameters
This layer includes parameters for attention mechanisms and standard GNN layer configurations.

```

--------------------------------

### Visualize Bias Addition with Large Parameters

Source: https://pytorch-hyperbolic.readthedocs.io/en/latest/intuition.html

This snippet demonstrates the effect of using significantly larger bias parameters in the `plot_addition` function. It shows how large parameters can push points off the manifold, leading to re-projection and potential information loss, acting as a form of inherent regularization.

```python
plot_addition(x, parameters * 10, point_indices)

```

--------------------------------

### Plotting Euclidean vs. Hyperbolic Bias Addition

Source: https://pytorch-hyperbolic.readthedocs.io/en/latest/intuition_lorentz.html

This snippet visualizes the results of bias addition performed in Euclidean space and projected into hyperbolic space, versus direct Möbius addition in hyperbolic space. It requires the Hyperboloid manifold from torch_hyperbolic and matplotlib for plotting.

```python
from torch_hyperbolic.manifolds import Hyperboloid

ball = Hyperboloid()
parameters = torch.rand(3,).double()
point_indices = [1, 14]

def plot_addition(x, parameters, point_indices):

        curvature = 10

        a = x.double()

        parameters = ball.proj_tan0(parameters.squeeze().view(1, -1), c=curvature)

        b = a + parameters

        c = ball.proj(ball.expmap0(b, c=curvature), c=curvature)

        d = ball.proj(ball.expmap0(a, c=curvature), c=curvature)

        hyperbolic_bias = ball.proj(ball.expmap0(parameters, c=curvature),c=curvature)

        e = ball.proj(ball.mobius_add(d, hyperbolic_bias, c=curvature), c=curvature)

        f = ball.logmap0(e, c = curvature)

        f = ball.proj_tan0(f, c = curvature)

        fig = plt.figure(figsize=plt.figaspect(0.47))

        titles = ["a. Euclidean Input\n$d={}$",
                "b. Euclidean Addition\n$d={}$",
                "c. Euclidean Add. into Hyperbolic\n$d={}$",
                "d. Hyperbolic Input\n$d={}$",
                "e. Möbius Addition\n$d={}$",
                "f. Möbius Add. into Euclidean\n$d={}$"]

        for i, values in enumerate([a, b, c, d, e, f]):
                ax = fig.add_subplot(2,3,i+1, projection='3d')
                ax.scatter(values[:, 1], values[:, 2], values[:, 0], s=1, c=colors)
                ax.scatter(values[point_indices, 1], values[point_indices, 2],  values[point_indices, 0],  s=3, c="r")
                if i < 2 or i == 5:
                        distance_x = values[point_indices[0], 0] - values[point_indices[1], 0]
                        distance_y = values[point_indices[0], 1] - values[point_indices[1], 1]
                        distance = math.sqrt((distance_x ** 2) + (distance_y ** 2))
                else:
                        distance = math.sqrt(ball.sqdist(values[point_indices[0],:], values[point_indices[1], :], c=curvature))
                ax.set_title(titles[i].format(round(distance,2)))

        plt.tight_layout()

plot_addition(x_0, parameters, point_indices)

```

--------------------------------

### Visualize Transformations in Hyperbolic Space

Source: https://pytorch-hyperbolic.readthedocs.io/en/latest/intuition.html

This function visualizes the effect of Euclidean matrix multiplication and hyperbolic Möbius matrix-vector multiplication on points. It requires `torch_hyperbolic`, `torch`, `matplotlib.pyplot`, and `math`. The `PoincareBall` manifold is used with a specified curvature.

```python
from torch_hyperbolic.manifolds import PoincareBall
ball = PoincareBall()
parameters = torch.rand((2,2)).double()
point_indices = [1, 14]

def plot_transformations(x, parameters, point_indices):

        a = x.double()

        b = torch.mm(a, parameters)

        curvature = 1

        c = ball.proj(ball.expmap0(b, c=curvature), c=curvature)

        d = ball.proj(ball.expmap0(a, c=curvature), c=curvature)

        e = ball.proj(ball.mobius_matvec(parameters, d, c=curvature), c=curvature)

        f = ball.logmap0(e, c = curvature)

        fig, axes = plt.subplots(ncols= 3, nrows=2, figsize=(16,8))

        titles = ["a. Euclidean Input\n$d={}$",
                "b. Euclidean Transformation\n$d={}$",
                "c. Euclidean Transf. into Hyperbolic\n$d={}$",
                "d. Hyperbolic Input\n$d={}$",
                "e. Möbius Matvec Transformation\n$d={}$",
                "f.Möbius Transf. into Euclidean\n$d={}$"]


        for i, (ax, values) in enumerate(zip(axes.flatten(), [a, b, c, d, e, f])):
                ax.scatter(values[:, 0], values[:, 1], s=1, c=colors)
                ax.scatter(values[point_indices, 0], values[point_indices, 1], s=5, c="r")
                if i < 2 or i == 5:
                        distance_x = values[point_indices[0], 0] - values[point_indices[1], 0]
                        distance_y = values[point_indices[0], 1] - values[point_indices[1], 1]
                        distance = math.sqrt((distance_x ** 2) + (distance_y ** 2))
                else:
                        distance = math.sqrt(ball.sqdist(values[point_indices[0],:], values[point_indices[1], :], c=curvature))
                radius = 1/math.sqrt(curvature)
                circle2 = plt.Circle((0, 0), radius, color='lightgray', fill=False)
                ax.add_patch(circle2)
                ax.set_title(titles[i].format(round(distance,2)))

        plt.tight_layout()

plot_transformations(x, parameters, point_indices)
```

--------------------------------

### Analyze Distance Between Points on Hyperboloid with Varying Curvature

Source: https://pytorch-hyperbolic.readthedocs.io/en/latest/intuition_lorentz.html

Visualizes the Hyperboloid manifold and the distance between two selected points for different curvature values (including None for Euclidean space). Highlights how curvature affects distances, especially further from the origin. Requires matplotlib.pyplot and math.

```python
curvatures = [None, 1, 5, 10]

#point_indices = x.pow(2).sum(dim=-1).argsort()[0:2].tolist()
fig = plt.figure(figsize=plt.figaspect(0.25))
for i, curvature in enumerate(curvatures):
    ax = fig.add_subplot(1,4,i+1, projection='3d')
    if curvature is None:
        ax.scatter(x_0[:, 1], x_0[:, 2], x_0[:, 0], s=1, c=colors)
        ax.scatter(x_0[point_indices, 1], x_0[point_indices, 2], x_0[point_indices, 0], s=10, c="r")
        distance_x = x_0[point_indices[0], 0] - x_0[point_indices[1], 0]
        distance_y = x_0[point_indices[0], 1] - x_0[point_indices[1], 1]
        distance = math.sqrt((distance_x ** 2) + (distance_y ** 2))
        ax.set_title("Input Space\nd={:.2}".format(distance))
    else:
        values = ball.proj(ball.expmap0(x_0, c=curvature), c=curvature)
        ax.scatter(values[:, 1], values[:, 2], values[:, 0], s=1, c=colors)
        ax.scatter(values[point_indices, 1], values[point_indices, 2], values[point_indices, 0], s=10, c="r")
        distance = math.sqrt(ball.sqdist(values[point_indices[0],:], values[point_indices[1], :], c=curvature))
        ax.set_title("Curvature {}
d={}".format(curvature, round(distance, 3)))
    ax.set_xlim((-1,1))
    ax.set_ylim((-1,1))
```

--------------------------------

### Visualize Hyperbolic Points and Calculate Distance

Source: https://pytorch-hyperbolic.readthedocs.io/en/latest/intuition.html

This snippet visualizes points in hyperbolic space using ball projection and calculates the hyperbolic distance between two points. It also adds a circle representing the boundary of the hyperbolic space and sets the plot title with curvature and distance.

```python
x_balled = ball.proj(ball.expmap0(x, c=curvature), c=curvature)
ax.scatter(x_balled[:, 0], x_balled[:, 1], c=colors, s=1)
ax.scatter(x_balled[point_indices, 0], x_balled[point_indices, 1], s=5, c="r")
distance = math.sqrt(ball.sqdist(x_balled[point_indices[0],:], x_balled[point_indices[1], :], c=curvature))
radius = 1/math.sqrt(curvature)
circle2 = plt.Circle((0, 0), radius, color='lightgray', fill=False)
ax.add_patch(circle2)
ax.set_title("Curvature {}
d={}".format(curvature, round(distance, 3)))
ax.set_ylim((-1,1))
ax.set_xlim((-1,1))
```

--------------------------------

### HGCNConv

Source: https://pytorch-hyperbolic.readthedocs.io/en/latest/nn.html

Implements a Hyperbolic Graph Convolutional Network (HGCN) layer. It assumes input features are already on the manifold and outputs features also on the manifold.

```APIDOC
## HGCNConv

### Description
Hyperbolic graph convolution layer. It assumes that the input is already on the manifold and outputs the feature matrix on the manifold. Implementation based on https://github.com/HazyResearch/hgcn/blob/master/layers/hyp_layers.py but implemented for the MessagePassing framework.

### Class Signature
`HGCNConv(in_channels, out_channels, c, manifold='PoincareBall', dropout=0, use_bias=True, aggr='add', normalize=False, use_att=False, local_agg=False)`

### Methods
#### forward(x, edge_index)
Assumes that x is already on the manifold, i.e. that features are hyperbolic.

Parameters:
    x (torch.Tensor): Input node features on the manifold.
    edge_index (torch.Tensor): Graph connectivity.

Returns:
    torch.Tensor: Output node features on the manifold.

#### message(x_i, x_j, norm)
Handles message passing logic. If `local_agg` is true, `x_i` and `x_j` remain on the manifold; otherwise, they are in the tangent space of the origin.

Parameters:
    x_i (torch.Tensor): Features of the destination node.
    x_j (torch.Tensor): Features of the source node.
    norm (torch.Tensor): Normalization factor.

Returns:
    torch.Tensor: Processed message.

```

--------------------------------

### HypLinear

Source: https://pytorch-hyperbolic.readthedocs.io/en/latest/nn.html

A hyperbolic linear layer that performs linear transformations within hyperbolic space.

```APIDOC
## HypLinear

### Description
Hyperbolic linear layer.

### Class Signature
`HypLinear(in_channels, out_channels, c, dropout=0, manifold='PoincareBall', use_bias=True)`

### Parameters
Standard parameters for a linear layer adapted for hyperbolic geometry.

```

--------------------------------

### HyperbolicEncoder Forward Pass

Source: https://pytorch-hyperbolic.readthedocs.io/en/latest/nn.html

Projects input features from Euclidean space onto a hyperbolic manifold. The projection method depends on the chosen manifold (PoincareBall or Hyperboloid).

```python
Projects x into hyperbolic space:
X′=expoc(X)
where exp() exp() is given as
expoc(v)=0⊕c(tanh(|c|λoc||v||22v|c|v||2)) 
for PoincareBall Manifold and
expoc(v)=cosh(|c|||v||L)0+vsinh(|c|||v||L)|c|||v||L
for Hyperboloid Manifold (Lorentz Model)
In case the manifold is a hyperoloid (Lorentz model), the output will have n+1 dimensions
```

--------------------------------

### HGCNConv Forward Pass

Source: https://pytorch-hyperbolic.readthedocs.io/en/latest/nn.html

The forward pass for HGCNConv assumes that the input features 'x' are already in hyperbolic space.

```python
Assumes that x is already on the manifold, i.e. that features are hyperbolic
```

--------------------------------

### HyperbolicEncoder

Source: https://pytorch-hyperbolic.readthedocs.io/en/latest/nn.html

Projects features from Euclidean space onto a hyperbolic manifold. It supports different manifolds like PoincareBall and Hyperboloid (Lorentz Model).

```APIDOC
## HyperbolicEncoder

### Description
Projects features from Euclidean space onto a hyperbolic manifold. It supports different manifolds like PoincareBall and Hyperboloid (Lorentz Model).

### Class Signature
`HyperbolicEncoder(manifold: str = 'PoincareBall', curvature=None)`

### Methods
#### forward(x)
Projects x into hyperbolic space using the formula:
`X′=expoc(X)`

Parameters:
    x (torch.Tensor): The node features in Euclidean space.

Returns:
    torch.Tensor: The node features in hyperbolic space.

```

--------------------------------

### HyperbolicDecoder Forward Pass

Source: https://pytorch-hyperbolic.readthedocs.io/en/latest/nn.html

Projects input features from a hyperbolic manifold back into Euclidean space. For the hyperboloid manifold (Lorentz Model), the output dimensions are reduced by one compared to the input.

```python
Projects x from hyperbolic back into euclidean space. In case the manifold is a hyperboloid (Lorentz Model), the output will have n-1 dimensions than the input
```

--------------------------------

### HyperbolicDecoder

Source: https://pytorch-hyperbolic.readthedocs.io/en/latest/nn.html

Translates features from a hyperbolic manifold back into Euclidean space. It handles different manifold types, including the Hyperboloid (Lorentz Model).

```APIDOC
## HyperbolicDecoder

### Description
Translates features from a hyperbolic manifold back into Euclidean space. It handles different manifold types, including the Hyperboloid (Lorentz Model).

### Class Signature
`HyperbolicDecoder(manifold: str = 'PoincareBall', curvature=None)`

### Methods
#### forward(x)
Projects x from hyperbolic space back into Euclidean space.

Parameters:
    x (torch.Tensor): The node features in hyperbolic space.

Returns:
    torch.Tensor: The node features in Euclidean space.

```

--------------------------------

### HFiLMConv Forward Pass

Source: https://pytorch-hyperbolic.readthedocs.io/en/latest/nn.html

The forward pass for HFiLMConv assumes that the input features 'x' are already in hyperbolic space.

```python
Assumes that x is already on the manifold, i.e. that features are hyperbolic with curvature c
```

--------------------------------

### Calculate and Display Distance in Lorentz Model

Source: https://pytorch-hyperbolic.readthedocs.io/en/latest/intuition_lorentz.html

Calculates the hyperbolic distance between two points in the Lorentz model and sets plot limits. This snippet is typically used within a visualization loop.

```python
distance = math.sqrt(ball.sqdist(x_balled[point_indices[0],:], x_balled[point_indices[1], :], c=curvature))
        ax.set_title("Curvature {}
d={}".format(curvature, round(distance, 5)))
        ax.set_ylim((-1,1))
        ax.set_xlim((-1,1))
```

--------------------------------

### HGCNConv Message Function

Source: https://pytorch-hyperbolic.readthedocs.io/en/latest/nn.html

Defines the message passing logic for HGCNConv. If local aggregation is used, features remain on the manifold; otherwise, they are projected to the tangent space of the origin.

```python
If we use local aggregation, x_i and x_j are still on the manifold, else they are in tangent space of origin
```

--------------------------------

### HFiLMConv

Source: https://pytorch-hyperbolic.readthedocs.io/en/latest/nn.html

Hyperbolic Feature-wise Linear Modulation Graph Convolution layer. This layer operates on features residing on the hyperbolic manifold.

```APIDOC
## HFiLMConv

### Description
Hyperbolic feature-wise linear modulation graph convolution layer. It assumes that the input is already on the manifold and outputs the feature matrix on the manifold.

### Class Signature
`HFiLMConv(in_channels, out_channels, c, num_relations=1, nn=None, act=ReLU(), manifold='PoincareBall', dropout=0, aggr='mean', local_agg=False, c_per_relation=False, c_per_relation_init_value=1, c_per_relation_trainable=True)`

### Methods
#### forward(x, edge_index, edge_type=None)
Assumes that x is already on the manifold, i.e. that features are hyperbolic with curvature c.

Parameters:
    x (Tensor | Tuple[Tensor, Tensor]): Input node features.
    edge_index (Tensor | SparseTensor): Graph connectivity.
    edge_type (Tensor | None): Type of edges.

Returns:
    Tensor: Output node features on the manifold.

```
Tokens:
Raw