### Install Base Development Dependencies

Source: https://github.com/maxvanspengler/hyperbolic_learning_library/blob/main/CONTRIBUTING.md

Install the repository with base development dependencies. Recommended for general development contributions.

```bash
pip install -e .[dev]
```

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

### Build HTML Documentation with Sphinx

Source: https://github.com/maxvanspengler/hyperbolic_learning_library/blob/main/docs/README.md

Use this command to build the HTML documentation. Ensure you have Sphinx installed and the Makefile is present in the docs directory.

```make
html
```

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

### Install HypLL with pip

Source: https://github.com/maxvanspengler/hyperbolic_learning_library/blob/main/docs/source/install.md

Install the HypLL library from PyPI using pip. Ensure your virtual environment is activated before running this command.

```bash
pip install hypll
```

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

### Build HTML Documentation with Sphinx (Custom Python)

Source: https://github.com/maxvanspengler/hyperbolic_learning_library/blob/main/docs/README.md

Alternatively, specify the Python interpreter for Sphinx if you have multiple Python versions installed. This command ensures the correct Python environment is used for building the documentation.

```bash
SPHINXBUILD="python3 -m sphinx.cmd.build" make html
```

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

### Initialize and Use HLinear Layer

Source: https://context7.com/maxvanspengler/hyperbolic_learning_library/llms.txt

Demonstrates initializing a hyperbolic linear layer (HLinear) and passing a ManifoldTensor input. The output is also a ManifoldTensor on the specified manifold.

```python
import torch
from hypll.manifolds.poincare_ball import Curvature, PoincareBall
from hypll.nn import HLinear
from hypll.tensors import ManifoldTensor, TangentTensor

manifold = PoincareBall(c=Curvature(1.0))
layer = HLinear(in_features=16, out_features=32, manifold=manifold, bias=True)

# Input: batch of 8 points in 16-dim hyperbolic space
x_euc = torch.randn(8, 16) * 0.1
x = ManifoldTensor(data=x_euc, manifold=manifold, man_dim=-1)

out = layer(x)
print(out.shape)     # torch.Size([8, 32])
print(type(out))     # <class 'hypll.tensors.manifold_tensor.ManifoldTensor'>
print(out.manifold)  # PoincareBall
```

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

### Activate Virtual Environment (Linux/macOS)

Source: https://github.com/maxvanspengler/hyperbolic_learning_library/blob/main/docs/source/install.md

Activate the created virtual environment on Linux or macOS systems. This ensures that subsequent commands use the environment's Python interpreter and packages.

```bash
source .env/bin/activate
```

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

### Create Python Virtual Environment

Source: https://github.com/maxvanspengler/hyperbolic_learning_library/blob/main/docs/source/install.md

Use this command to create a new virtual environment for your project. This helps manage dependencies.

```bash
python -venv .env
```

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

### Initialize RiemannianAdam Optimizer

Source: https://context7.com/maxvanspengler/hyperbolic_learning_library/llms.txt

Initialize RiemannianAdam, an extension of PyTorch's Adam optimizer for Riemannian manifolds. It projects Euclidean gradients to the tangent space and uses exponential maps for updates.

```python
import torch
from torch import nn
from hypll.manifolds.poincare_ball import Curvature, PoincareBall
from hypll.nn import HLinear, HReLU
from hypll.optim import RiemannianAdam
from hypll.tensors import ManifoldTensor, TangentTensor

manifold = PoincareBall(c=Curvature(requires_grad=True))

model = nn.Sequential(
    HLinear(32, 64, manifold=manifold),
    HReLU(manifold=manifold),
    HLinear(64, 10, manifold=manifold),
)

# Includes learnable curvature 'c' automatically
optimizer = RiemannianAdam(model.parameters(), lr=1e-3, betas=(0.9, 0.999), weight_decay=1e-4)
criterion = nn.CrossEntropyLoss()

# Training step
inputs = torch.randn(16, 32) * 0.1
tangents = TangentTensor(data=inputs, man_dim=-1, manifold=manifold)
x = manifold.expmap(tangents)
labels = torch.randint(0, 10, (16,))

optimizer.zero_grad()
out = model(x)
loss = criterion(out.tensor, labels)
loss.backward()
optimizer.step()
print(f"Loss: {loss.item():.4f}")
```

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

### Activate Virtual Environment (Windows)

Source: https://github.com/maxvanspengler/hyperbolic_learning_library/blob/main/docs/source/install.md

Activate the created virtual environment on Windows systems. This ensures that subsequent commands use the environment's Python interpreter and packages.

```bash
.env/Scripts/activate
```

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

### Format Code with Black

Source: https://github.com/maxvanspengler/hyperbolic_learning_library/blob/main/CONTRIBUTING.md

Use Black to automatically format code according to project standards. Run this command in the root directory.

```bash
black .
```

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

### Initialize RiemannianSGD Optimizer with Momentum and Nesterov

Source: https://context7.com/maxvanspengler/hyperbolic_learning_library/llms.txt

Initialize RiemannianSGD, implementing stochastic gradient descent on Riemannian manifolds with optional momentum and Nesterov acceleration. Updates use exponential maps and parallel transport for momentum.

```python
import torch
from hypll.manifolds.poincare_ball import Curvature, PoincareBall
from hypll.nn import HLinear
from hypll.optim import RiemannianSGD
from hypll.tensors import ManifoldTensor, TangentTensor

manifold = PoincareBall(c=Curvature(1.0))
layer = HLinear(16, 8, manifold=manifold)

optimizer = RiemannianSGD(
    layer.parameters(), lr=0.01, momentum=0.9, dampening=0.0, nesterov=True
)

inputs = torch.randn(4, 16) * 0.1
tangents = TangentTensor(data=inputs, man_dim=-1, manifold=manifold)
x = manifold.expmap(tangents)

optimizer.zero_grad()
out = layer(x)
loss = out.tensor.sum()
loss.backward()
optimizer.step()
```

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

### ChangeManifold

Source: https://context7.com/maxvanspengler/hyperbolic_learning_library/llms.txt

Module to transition ManifoldTensors between different hyperbolic manifolds via logmap and expmap.

```APIDOC
## ChangeManifold — Transition between manifolds

`ChangeManifold` is a `torch.nn.Module` that transfers a `ManifoldTensor` from one manifold to another via logmap at the origin followed by expmap on the target manifold.

```python
import torch
from hypll.manifolds.euclidean import Euclidean
from hypll.manifolds.poincare_ball import Curvature, PoincareBall
from hypll.nn import ChangeManifold
from hypll.tensors import ManifoldTensor

source_manifold = Euclidean()
target_manifold = PoincareBall(c=Curvature(1.0))

changer = ChangeManifold(target_manifold=target_manifold)

x = ManifoldTensor(data=torch.randn(4, 8) * 0.1, manifold=source_manifold, man_dim=-1)
y = changer(x)
print(y.manifold)  # PoincareBall
print(y.shape)     # torch.Size([4, 8])
```
```

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

### Create TangentTensor at Origin and Base Point

Source: https://context7.com/maxvanspengler/hyperbolic_learning_library/llms.txt

Shows how to create TangentTensor objects representing tangent vectors at the origin (using None for manifold_points) and at an existing ManifoldTensor base point.

```python
import torch
from hypll.manifolds.poincare_ball import Curvature, PoincareBall
from hypll.tensors import ManifoldTensor, TangentTensor

manifold = PoincareBall(c=Curvature(1.0))

# Tangent vector at the origin
v_at_origin = TangentTensor(
    data=torch.tensor([[0.2, 0.3]]),
    manifold_points=None,   # None means origin
    manifold=manifold,
    man_dim=-1,
)
point = manifold.expmap(v_at_origin)   # ManifoldTensor

# Tangent vector at an existing point
base = ManifoldTensor(data=torch.tensor([[0.1, 0.0]]), manifold=manifold, man_dim=-1)
v_at_base = TangentTensor(
    data=torch.tensor([[0.05, 0.1]]),
    manifold_points=base,
    manifold=manifold,
    man_dim=-1,
)
new_point = manifold.expmap(v_at_base)  # ManifoldTensor

# Convert Euclidean vector to tangent vector at base point
u_euc = ManifoldTensor(
    data=torch.tensor([[0.1, 0.2]]),
    manifold=manifold, man_dim=-1
)
tangent = manifold.euc_to_tangent(x=base, u=u_euc)  # TangentTensor
```

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

### Sort Imports with isort

Source: https://github.com/maxvanspengler/hyperbolic_learning_library/blob/main/CONTRIBUTING.md

Use isort to automatically sort and separate imports for improved readability. Run this command in the root directory.

```bash
isort .
```

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

### Run Tests with Pytest

Source: https://github.com/maxvanspengler/hyperbolic_learning_library/blob/main/CONTRIBUTING.md

Execute all tests in the project using Pytest. This command should be run from the root directory.

```bash
pytest
```

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

### Initialize and Use HConvolution2d Layer

Source: https://context7.com/maxvanspengler/hyperbolic_learning_library/llms.txt

Shows how to initialize a hyperbolic 2D convolution layer (HConvolution2d) and apply it to a ManifoldTensor representing images. The input ManifoldTensor must have man_dim=1.

```python
import torch
from hypll.manifolds.poincare_ball import Curvature, PoincareBall
from hypll.nn import HConvolution2d
from hypll.tensors import ManifoldTensor

manifold = PoincareBall(c=Curvature(1.0))
conv = HConvolution2d(
    in_channels=3, out_channels=16, kernel_size=3,
    manifold=manifold, stride=1, padding=1
)

# Input: batch of 2 RGB images of size 32x32 on the manifold
imgs = torch.randn(2, 3, 32, 32) * 0.1
x = ManifoldTensor(data=imgs, manifold=manifold, man_dim=1)

out = conv(x)
print(out.shape)   # torch.Size([2, 16, 32, 32])
print(out.man_dim) # 1
```

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

### Transition Between Manifolds with ChangeManifold

Source: https://context7.com/maxvanspengler/hyperbolic_learning_library/llms.txt

Use ChangeManifold to transfer ManifoldTensors between different hyperbolic or Euclidean manifolds. It employs logmap and expmap to perform the transformation.

```python
import torch
from hypll.manifolds.euclidean import Euclidean
from hypll.manifolds.poincare_ball import Curvature, PoincareBall
from hypll.nn import ChangeManifold
from hypll.tensors import ManifoldTensor

source_manifold = Euclidean()
target_manifold = PoincareBall(c=Curvature(1.0))

changer = ChangeManifold(target_manifold=target_manifold)

x = ManifoldTensor(data=torch.randn(4, 8) * 0.1, manifold=source_manifold, man_dim=-1)
y = changer(x)
print(y.manifold)  # PoincareBall
print(y.shape)     # torch.Size([4, 8])
```

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

### Define ManifoldParameter for Euclidean and Poincaré Ball

Source: https://context7.com/maxvanspengler/hyperbolic_learning_library/llms.txt

Illustrates creating ManifoldParameter instances for learnable weights on Euclidean and Poincaré Ball manifolds. Access the underlying tensor using .tensor.

```python
import torch
from hypll.manifolds.euclidean import Euclidean
from hypll.manifolds.poincare_ball import Curvature, PoincareBall
from hypll.tensors import ManifoldParameter

manifold = PoincareBall(c=Curvature(1.0))

# Weight matrix living on the Euclidean manifold (for linear layer weights)
weight = ManifoldParameter(
    data=torch.empty(16, 32),
    manifold=Euclidean(),
    man_dim=0,
    requires_grad=True,
)

# Embedding table living on the Poincaré ball
embedding_weight = ManifoldParameter(
    data=torch.randn(100, 8) * 0.01,
    manifold=manifold,
    man_dim=-1,
    requires_grad=True,
)

# Access underlying parameter tensor for standard torch ops
print(embedding_weight.tensor.shape)  # torch.Size([100, 8])
```

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

### ManifoldTensor Usage and Operations

Source: https://context7.com/maxvanspengler/hyperbolic_learning_library/llms.txt

Demonstrates the creation and basic operations of ManifoldTensor, including shape, dimension, slicing, and device transfers. ManifoldTensor wraps PyTorch tensors with geometric context.

```python
import torch
from hypll.manifolds.poincare_ball import Curvature, PoincareBall
from hypll.tensors import ManifoldTensor

manifold = PoincareBall(c=Curvature(1.0))

# Batch of 4 points in 8-dimensional hyperbolic space
data = torch.randn(4, 8) * 0.1
mt = ManifoldTensor(data=data, manifold=manifold, man_dim=-1)
print(mt.shape)    # torch.Size([4, 8])
print(mt.dim())    # 2
print(mt.man_dim)  # 7

# Slicing (manifold dimension is preserved)
subset = mt[0:2]           # ManifoldTensor, shape [2, 8]

# Device transfer
mt_gpu = mt.cuda()         # ManifoldTensor on GPU (if available)
mt_cpu = mt_gpu.cpu()
```

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

### Train Model for 2 Epochs with Hyperbolic Layers

Source: https://context7.com/maxvanspengler/hyperbolic_learning_library/llms.txt

This code trains a model for two epochs using hyperbolic layers. It demonstrates the typical training loop, including forward and backward passes, optimizer steps, and loss calculation within a hyperbolic manifold context. Ensure `TangentTensor`, `manifold`, `optimizer`, `net`, and `criterion` are properly initialized.

```python
for epoch in range(2):
    running_loss = 0.0
    for i, (inputs, labels) in enumerate(trainloader):
        tangents = TangentTensor(data=inputs, man_dim=1, manifold=manifold)
        manifold_inputs = manifold.expmap(tangents)

        optimizer.zero_grad()
        outputs = net(manifold_inputs)
        loss = criterion(outputs.tensor, labels)
        loss.backward()
        optimizer.step()

        running_loss += loss.item()
        if i % 2000 == 1999:
            print(f"[{epoch+1}, {i+1:5d}] loss: {running_loss / 2000:.3f}")
            running_loss = 0.0

print("Training complete")
torch.save(net.state_dict(), "cifar_hyp_net.pth")
```

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

### End-to-End Hyperbolic CNN Training on CIFAR-10

Source: https://context7.com/maxvanspengler/hyperbolic_learning_library/llms.txt

A complete workflow for training a hyperbolic convolutional neural network using HypLL modules and the RiemannianAdam optimizer on the CIFAR-10 dataset.

```python
import torch
import torchvision
import torchvision.transforms as transforms
from torch import nn
from hypll import nn as hnn
from hypll.manifolds.poincare_ball import Curvature, PoincareBall
from hypll.optim import RiemannianAdam
from hypll.tensors import TangentTensor

# 1. Define manifold
manifold = PoincareBall(c=Curvature(requires_grad=True))

# 2. Load CIFAR-10
transform = transforms.Compose([
    transforms.ToTensor(),
    transforms.Normalize((0.5, 0.5, 0.5), (0.5, 0.5, 0.5)),
])
trainset = torchvision.datasets.CIFAR10(root="./data", train=True, download=True, transform=transform)
trainloader = torch.utils.data.DataLoader(trainset, batch_size=4, shuffle=True, num_workers=2)

# 3. Define hyperbolic CNN
class HypCNN(nn.Module):
    def __init__(self, manifold):
        super().__init__()
        self.conv1 = hnn.HConvolution2d(3, 6, kernel_size=5, manifold=manifold)
        self.pool  = hnn.HMaxPool2d(kernel_size=2, manifold=manifold, stride=2)
        self.conv2 = hnn.HConvolution2d(6, 16, kernel_size=5, manifold=manifold)
        self.fc1   = hnn.HLinear(16 * 5 * 5, 120, manifold=manifold)
        self.fc2   = hnn.HLinear(120, 84, manifold=manifold)
        self.fc3   = hnn.HLinear(84, 10, manifold=manifold)
        self.relu  = hnn.HReLU(manifold=manifold)

    def forward(self, x):
        x = self.pool(self.relu(self.conv1(x)))
        x = self.pool(self.relu(self.conv2(x)))
        x = x.flatten(start_dim=1)
        x = self.relu(self.fc1(x))
        x = self.relu(self.fc2(x))
        return self.fc3(x)

net = HypCNN(manifold)
criterion = nn.CrossEntropyLoss()
optimizer = RiemannianAdam(net.parameters(), lr=0.001)
```

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

### Flatten ManifoldTensor with Beta-Concatenation

Source: https://context7.com/maxvanspengler/hyperbolic_learning_library/llms.txt

Demonstrates flattening a ManifoldTensor while preserving geometric correctness through beta-concatenation along the manifold dimension.

```python
img = ManifoldTensor(data=torch.randn(2, 16, 4, 4) * 0.1, manifold=manifold, man_dim=1)
flat = img.flatten(start_dim=1)   # shape [2, 256], beta-concatenated along man_dim
print(flat.shape)  # torch.Size([2, 256])

# Project back onto the manifold
safe = mt.project()
```

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

### Hyperbolic Batch Normalization with HBatchNorm

Source: https://context7.com/maxvanspengler/hyperbolic_learning_library/llms.txt

Implement hyperbolic batch normalization using HBatchNorm for feature vectors or HBatchNorm2d for image tensors. Normalization is performed via Fréchet mean and variance in hyperbolic space.

```python
import torch
from hypll.manifolds.poincare_ball import Curvature, PoincareBall
from hypll.nn import HBatchNorm, HBatchNorm2d
from hypll.tensors import ManifoldTensor

manifold = PoincareBall(c=Curvature(1.0))

# 1D batch norm (for feature vectors)
bn = HBatchNorm(features=32, manifold=manifold, use_midpoint=False)
x = ManifoldTensor(data=torch.randn(8, 32) * 0.1, manifold=manifold, man_dim=-1)
out = bn(x)
print(out.shape)   # torch.Size([8, 32])

# 2D batch norm (for feature maps)
bn2d = HBatchNorm2d(features=16, manifold=manifold)
imgs = ManifoldTensor(data=torch.randn(4, 16, 8, 8) * 0.1, manifold=manifold, man_dim=1)
out2d = bn2d(imgs)
print(out2d.shape)  # torch.Size([4, 16, 8, 8])
```

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

### HAvgPool2d / HMaxPool2d

Source: https://context7.com/maxvanspengler/hyperbolic_learning_library/llms.txt

Hyperbolic pooling layers. HAvgPool2d aggregates patches using Fréchet mean, while HMaxPool2d applies max-pooling in the tangent space.

```APIDOC
## HAvgPool2d / HMaxPool2d — Hyperbolic pooling

`HAvgPool2d` aggregates patches using Fréchet mean (or midpoint) in hyperbolic space. `HMaxPool2d` applies max-pooling in the tangent space at the origin.

```python
import torch
from hypll.manifolds.poincare_ball import Curvature, PoincareBall
from hypll.nn import HAvgPool2d, HMaxPool2d
from hypll.tensors import ManifoldTensor

manifold = PoincareBall(c=Curvature(1.0))

x = ManifoldTensor(
    data=torch.randn(2, 16, 8, 8) * 0.1,
    manifold=manifold, man_dim=1
)

avg_pool = HAvgPool2d(kernel_size=2, manifold=manifold, stride=2)
out_avg = avg_pool(x)
print(out_avg.shape)  # torch.Size([2, 16, 4, 4])

max_pool = HMaxPool2d(kernel_size=2, manifold=manifold, stride=2)
out_max = max_pool(x)
print(out_max.shape)  # torch.Size([2, 16, 4, 4])
```
```

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

### Apply ReLU in Tangent Space with HReLU

Source: https://context7.com/maxvanspengler/hyperbolic_learning_library/llms.txt

Use HReLU to apply the ReLU activation function in the tangent space at the origin of a manifold. This ensures the output remains on the manifold by using logmap and expmap transformations.

```python
import torch
from hypll.manifolds.poincare_ball import Curvature, PoincareBall
from hypll.nn import HReLU
from hypll.tensors import ManifoldTensor

manifold = PoincareBall(c=Curvature(1.0))
relu = HReLU(manifold=manifold)

x = ManifoldTensor(
    data=torch.randn(4, 8) * 0.3,
    manifold=manifold, man_dim=-1
)
out = relu(x)
print(out.shape)   # torch.Size([4, 8])
print(type(out))   # ManifoldTensor
```

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

### TangentSequential

Source: https://context7.com/maxvanspengler/hyperbolic_learning_library/llms.txt

Applies a sequence of Euclidean modules in the tangent space at the origin, allowing reuse of standard PyTorch modules in hyperbolic networks.

```APIDOC
## TangentSequential — Apply Euclidean modules in tangent space

`TangentSequential` wraps a `torch.nn.Sequential` of standard Euclidean modules and applies them in the tangent space at the origin (logmap → sequential → expmap), allowing reuse of existing PyTorch modules in hyperbolic networks.

```python
import torch
from torch import nn
from hypll.manifolds.poincare_ball import Curvature, PoincareBall
from hypll.nn import TangentSequential
from hypll.tensors import ManifoldTensor

manifold = PoincareBall(c=Curvature(1.0))

# Wrap standard PyTorch layers to operate in tangent space
seq = TangentSequential(
    seq=nn.Sequential(nn.Linear(32, 32), nn.BatchNorm1d(32)),
    manifold=manifold,
)

x = ManifoldTensor(data=torch.randn(8, 32) * 0.1, manifold=manifold, man_dim=-1)
out = seq(x)
print(out.shape)   # torch.Size([8, 32])
print(type(out))   # ManifoldTensor
```
```

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

### Hyperbolic Pooling with HAvgPool2d and HMaxPool2d

Source: https://context7.com/maxvanspengler/hyperbolic_learning_library/llms.txt

Utilize HAvgPool2d for aggregation using Fréchet mean or midpoint, and HMaxPool2d for max-pooling in the tangent space. Both operate on hyperbolic tensors.

```python
import torch
from hypll.manifolds.poincare_ball import Curvature, PoincareBall
from hypll.nn import HAvgPool2d, HMaxPool2d
from hypll.tensors import ManifoldTensor

manifold = PoincareBall(c=Curvature(1.0))

x = ManifoldTensor(
    data=torch.randn(2, 16, 8, 8) * 0.1,
    manifold=manifold, man_dim=1
)

avg_pool = HAvgPool2d(kernel_size=2, manifold=manifold, stride=2)
out_avg = avg_pool(x)
print(out_avg.shape)  # torch.Size([2, 16, 4, 4])

max_pool = HMaxPool2d(kernel_size=2, manifold=manifold, stride=2)
out_max = max_pool(x)
print(out_max.shape)  # torch.Size([2, 16, 4, 4])
```

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

### Hyperbolic Embedding Layer with HEmbedding

Source: https://context7.com/maxvanspengler/hyperbolic_learning_library/llms.txt

Create hyperbolic embeddings using HEmbedding, the hyperbolic equivalent of torch.nn.Embedding. Embeddings are stored on the manifold and initialized from a normal distribution.

```python
import torch
from hypll.manifolds.poincare_ball import Curvature, PoincareBall
from hypll.nn import HEmbedding

manifold = PoincareBall(c=Curvature(1.0))
emb = HEmbedding(num_embeddings=1000, embedding_dim=64, manifold=manifold)

# Lookup token IDs
indices = torch.tensor([0, 5, 42, 99])
out = emb(indices)
print(out.shape)    # torch.Size([4, 64])
print(out.manifold) # PoincareBall
```

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

### Apply Euclidean Modules in Tangent Space with TangentSequential

Source: https://context7.com/maxvanspengler/hyperbolic_learning_library/llms.txt

Wrap standard Euclidean nn.Modules within TangentSequential to apply them in the tangent space of a manifold. This allows for the reuse of existing PyTorch modules in hyperbolic networks.

```python
import torch
from torch import nn
from hypll.manifolds.poincare_ball import Curvature, PoincareBall
from hypll.nn import TangentSequential
from hypll.tensors import ManifoldTensor

manifold = PoincareBall(c=Curvature(1.0))

# Wrap standard PyTorch layers to operate in tangent space
seq = TangentSequential(
    seq=nn.Sequential(nn.Linear(32, 32), nn.BatchNorm1d(32)),
    manifold=manifold,
)

x = ManifoldTensor(data=torch.randn(8, 32) * 0.1, manifold=manifold, man_dim=-1)
out = seq(x)
print(out.shape)   # torch.Size([8, 32])
print(type(out))   # ManifoldTensor
```

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

### PoincareBall Manifold Operations

Source: https://context7.com/maxvanspengler/hyperbolic_learning_library/llms.txt

Demonstrates geometric operations within the Poincaré ball model, including distance, exponential map, logarithmic map, Möbius addition, Fréchet mean, and projection.

```python
import torch
from hypll.manifolds.poincare_ball import Curvature, PoincareBall
from hypll.tensors import ManifoldTensor, TangentTensor

manifold = PoincareBall(c=Curvature(value=1.0))

# Create two points on the manifold
x = ManifoldTensor(data=torch.tensor([[0.1, 0.2]]), manifold=manifold, man_dim=-1)
y = ManifoldTensor(data=torch.tensor([[0.3, 0.1]]), manifold=manifold, man_dim=-1)

# Hyperbolic distance between x and y
d = manifold.dist(x, y)
print(d)  # tensor([0.4142])

# Exponential map: move from origin along a tangent vector
v = TangentTensor(data=torch.tensor([[0.1, 0.0]]), manifold_points=None, manifold=manifold, man_dim=-1)
p = manifold.expmap(v)           # ManifoldTensor on the ball
print(p.tensor)                  # tensor([[0.0997, 0.0000]])

# Logarithmic map: tangent vector at x pointing toward y
tv = manifold.logmap(x=x, y=y)  # TangentTensor
print(tv.tensor)

# Möbius addition
z = manifold.mobius_add(x, y)   # ManifoldTensor

# Fréchet mean of a batch of points
batch = ManifoldTensor(
    data=torch.randn(8, 16).clamp(-0.9, 0.9),
    manifold=manifold, man_dim=-1
)
mean = manifold.frechet_mean(batch, batch_dim=0)  # ManifoldTensor, shape [16]

# Project a tensor onto the manifold (clip to be inside the ball)
raw = ManifoldTensor(data=torch.tensor([[1.5, 0.0]]), manifold=manifold, man_dim=-1)
projected = manifold.project(raw)
```

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

### HReLU

Source: https://context7.com/maxvanspengler/hyperbolic_learning_library/llms.txt

Hyperbolic ReLU activation function. Applies ReLU in the tangent space at the origin, ensuring outputs remain on the manifold.

```APIDOC
## HReLU — Hyperbolic ReLU activation

`HReLU` applies ReLU in the tangent space at the origin (via logmap → ReLU → expmap), ensuring the output remains on the manifold.

```python
import torch
from hypll.manifolds.poincare_ball import Curvature, PoincareBall
from hypll.nn import HReLU
from hypll.tensors import ManifoldTensor

manifold = PoincareBall(c=Curvature(1.0))
relu = HReLU(manifold=manifold)

x = ManifoldTensor(
    data=torch.randn(4, 8) * 0.3,
    manifold=manifold, man_dim=-1
)
out = relu(x)
print(out.shape)   # torch.Size([4, 8])
print(type(out))   # ManifoldTensor
```
```

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

### HypLL Project Citation

Source: https://github.com/maxvanspengler/hyperbolic_learning_library/blob/main/README.md

BibTeX entry for citing the HypLL project in academic work. Includes authors, title, journal, and year.

```bibtex
@article{spengler2023hypll,
  title={HypLL: The Hyperbolic Learning Library},
  author={van Spengler, Max and Wirth, Philipp and Mettes, Pascal},
  journal={arXiv preprint arXiv:2306.06154},
  year={2023}
}
```

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

### HBatchNorm / HBatchNorm2d

Source: https://context7.com/maxvanspengler/hyperbolic_learning_library/llms.txt

Hyperbolic batch normalization layers. Normalizes via Fréchet mean and variance in hyperbolic space. HBatchNorm2d is for 4-D image tensors.

```APIDOC
## HBatchNorm / HBatchNorm2d — Hyperbolic batch normalization

`HBatchNorm` implements hyperbolic batch normalization (based on [arXiv:2003.00335](https://arxiv.org/abs/2003.00335)), normalizing via Fréchet mean and variance in hyperbolic space. `HBatchNorm2d` wraps it for 4-D image tensors `(B, C, H, W)`.

```python
import torch
from hypll.manifolds.poincare_ball import Curvature, PoincareBall
from hypll.nn import HBatchNorm, HBatchNorm2d
from hypll.tensors import ManifoldTensor

manifold = PoincareBall(c=Curvature(1.0))

# 1D batch norm (for feature vectors)
bn = HBatchNorm(features=32, manifold=manifold, use_midpoint=False)
x = ManifoldTensor(data=torch.randn(8, 32) * 0.1, manifold=manifold, man_dim=-1)
out = bn(x)
print(out.shape)   # torch.Size([8, 32])

# 2D batch norm (for feature maps)
bn2d = HBatchNorm2d(features=16, manifold=manifold)
imgs = ManifoldTensor(data=torch.randn(4, 16, 8, 8) * 0.1, manifold=manifold, man_dim=1)
out2d = bn2d(imgs)
print(out2d.shape)  # torch.Size([4, 16, 8, 8])
```
```

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

### Curvature Module for Manifold Curvature

Source: https://context7.com/maxvanspengler/hyperbolic_learning_library/llms.txt

The Curvature module wraps the curvature scalar of a hyperbolic manifold. It can be fixed or learnable, with a default softplus constraining strategy to ensure positive curvature.

```python
from hypll.manifolds.poincare_ball import Curvature

# Fixed curvature of 1.0
c_fixed = Curvature(value=1.0, requires_grad=False)
print(c_fixed())  # tensor(0.6931)  (softplus(1.0))

# Learnable curvature — updated during training alongside model parameters
c_learnable = Curvature(value=1.0, requires_grad=True)

# Custom constraining strategy (e.g., absolute value)
import torch
c_custom = Curvature(value=0.5, constraining_strategy=torch.abs, requires_grad=False)
print(c_custom())  # tensor(0.5)
```

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

### Flatten Hyperbolic Tensor with HFlatten

Source: https://context7.com/maxvanspengler/hyperbolic_learning_library/llms.txt

Use HFlatten to flatten a range of dimensions of a ManifoldTensor. It correctly handles the manifold dimension by applying beta-concatenation.

```python
import torch
from hypll.manifolds.poincare_ball import Curvature, PoincareBall
from hypll.nn import HFlatten
from hypll.tensors import ManifoldTensor

manifold = PoincareBall(c=Curvature(1.0))
flatten = HFlatten(start_dim=1, end_dim=-1)

# Feature map from conv layer: (batch, channels, H, W) with man_dim=1
x = ManifoldTensor(data=torch.randn(4, 16, 5, 5) * 0.1, manifold=manifold, man_dim=1)
out = flatten(x)
print(out.shape)   # torch.Size([4, 400])
```

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

### HEmbedding

Source: https://context7.com/maxvanspengler/hyperbolic_learning_library/llms.txt

Hyperbolic embedding layer, analogous to torch.nn.Embedding. Stores embeddings on the manifold and returns ManifoldTensor rows.

```APIDOC
## HEmbedding — Hyperbolic embedding layer

`HEmbedding` is the hyperbolic analog of `torch.nn.Embedding`. It stores an embedding table on the manifold (initialized via expmap from a normal distribution) and returns `ManifoldTensor` rows.

```python
import torch
from hypll.manifolds.poincare_ball import Curvature, PoincareBall
from hypll.nn import HEmbedding

manifold = PoincareBall(c=Curvature(1.0))
emb = HEmbedding(num_embeddings=1000, embedding_dim=64, manifold=manifold)

# Lookup token IDs
indices = torch.tensor([0, 5, 42, 99])
out = emb(indices)
print(out.shape)    # torch.Size([4, 64])
print(out.manifold) # PoincareBall
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.