README.md

---
title: Ideal Polyhedron Volume Toolkit
emoji: 🔺
colorFrom: blue
colorTo: purple
sdk: docker
pinned: false
license: mit
---

# Ideal Polyhedra Volume Toolkit

A Python toolkit for computing and optimizing volumes of ideal hyperbolic polyhedra using Delaunay triangulation, hull projection, and fast/exact Lobachevsky functions.

## Installation

Install the package in development mode:

```bash
pip install -e .
```

Dependencies: `numpy`, `scipy`, `mpmath`, `torch`

## Project Structure

```
ideal_poly_volume_toolkit/
├── ideal_poly_volume_toolkit/   # Core package
│   ├── geometry.py              # Core geometry and volume computation functions
│   ├── visualization.py         # 3D visualization utilities
│   ├── rivin_holonomy.py        # Penner-Rivin holonomy computation
│   ├── pointset_to_fuchsian.py  # Full Fuchsian group pipeline
│   └── __init__.py
│
├── bin/                         # Command-line tools and GUI
│   ├── gui.py                   # 🎨 Interactive Gradio web interface
│   ├── optimize_polyhedron.py  # General optimization wrapper
│   ├── analyze_distribution.py # Distribution analysis wrapper
│   └── README.md
│
├── examples/                    # Organized example scripts
│   ├── distributions/          # Distribution analysis examples
│   │   ├── tetrahedron/       # Tetrahedron volume distributions
│   │   ├── five_vertex/       # 5-vertex polyhedra distributions
│   │   ├── six_vertex/        # 6-vertex polyhedra distributions
│   │   └── euclidean/         # Euclidean tetrahedra analysis
│   ├── optimization/           # Optimization examples by vertex count
│   │   ├── 7vertex/           # 7-vertex optimization (octahedron variants)
│   │   ├── 12vertex/          # 12-vertex optimization
│   │   ├── 20vertex/          # 20-vertex optimization (icosahedron)
│   │   └── platonic/          # Platonic solid analysis
│   ├── visualization/          # Visualization scripts
│   └── analysis/               # Statistical and theoretical analysis
│
├── scripts/                     # Active research/development scripts
├── results/                     # Output files
│   ├── data/                   # JSON configuration files
│   ├── plots/                  # PNG visualization outputs
│   └── logs/                   # Optimization logs
└── docs/                        # Documentation
    ├── RESULTS_SUMMARY.md
    └── PLATONIC_MAXIMALITY_RESULTS.md
```

## Core Functionality

### `ideal_poly_volume_toolkit.geometry` - Volume Computation

- **Stereographic projection**: `lift_to_sphere_with_inf()`, `inverse_stereographic_from_sphere_pts()`
- **Triangulation**: `delaunay_triangulation_indices()`, `hull_tris_projected_back()`
- **Lobachevsky function**: `lob_fast()` (PyTorch autodiff), `lob_exact()` (mpmath high-precision)
- **Volume computation**:
  - `triangle_volume_from_points()` - Single triangle volume
  - `ideal_poly_volume_via_delaunay()` - Full polyhedron via Delaunay
  - `ideal_poly_volume_via_hull_project_back()` - Full polyhedron via convex hull

### `ideal_poly_volume_toolkit.rivin_holonomy` - Penner-Rivin Algorithm

- **Holonomy computation**: `generators_from_triangulation()` - Compute Fuchsian group generators
- **Arithmeticity testing**: Check if polyhedra have arithmetic holonomy (traces in number fields)
- **Triangulation structures**: `Triangulation` class for managing ideal triangulations

### `ideal_poly_volume_toolkit.pointset_to_fuchsian` - Full Pipeline

- **Group computation**: `group_from_pointset()` - Convert point sets to Fuchsian groups
- **Trace field analysis**: `invariant_trace_field_signature()` - Analyze arithmetic properties
- **Visualization**: `render_snapshot()` - High-quality rendering with iridescence and transparency
- **Mesh export**: `hull_to_mesh()`, `export_mesh_obj()` - Export to OBJ format

## Quick Start

### 🎨 Interactive GUI (Easiest)

The fastest way to get started is with the Gradio web interface:

```bash
python bin/gui.py
```

Then open your browser to `http://127.0.0.1:7860`

**Features:**
- Interactive optimization with real-time progress
- Distribution analysis with automatic plotting
- 3D visualization in sphere and Poincaré ball models
- No need to remember command-line arguments!

### Command-Line Tools

For scripting and batch processing, use the wrapper scripts in `bin/`:

```bash
# Optimize a 7-vertex polyhedron (10 trials)
python bin/optimize_polyhedron.py --vertices 7 --trials 10

# Analyze volume distribution for tetrahedra
python bin/analyze_distribution.py --vertices 4 --samples 10000

# Get help on any tool
python bin/optimize_polyhedron.py --help
```

See `bin/README.md` for detailed usage and examples.

### Computing a volume (Python API)

```python
import numpy as np
from ideal_poly_volume_toolkit.geometry import ideal_poly_volume_via_delaunay

# Define vertices in the complex plane (stereographic projection)
vertices = np.array([0.0+0.0j, 1.0+0.0j, 0.5+0.866j])
volume = ideal_poly_volume_via_delaunay(vertices)
print(f"Volume: {volume}")
```

### Running examples

Examples are organized by topic. For instance:

```bash
# 7-vertex optimization
cd examples/optimization/7vertex
python optimize_7vertex.py

# Tetrahedron distribution analysis
cd examples/distributions/tetrahedron
python tetrahedron_volume_distribution.py

# Visualization
cd examples/visualization
python visualize_golden_config.py
```

## Key Examples

- **7-vertex optimization**: Testing the hypothesis that the maximum volume is an octahedron with one stellated face
- **20-vertex optimization**: Finding maximal volume configurations for icosahedron-like polyhedra
- **Distribution analysis**: Statistical analysis of volume distributions for various polyhedra
- **Platonic solids**: Analysis of regular polyhedra and their perturbations

## Research Results

See `docs/RESULTS_SUMMARY.md` and `docs/PLATONIC_MAXIMALITY_RESULTS.md` for detailed findings.

## License

See LICENSE file.