README.md

metadata

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:

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:

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/:

# 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)

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:

# 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.