Metadata-Version: 2.4
Name: hyperpopy
Version: 0.1.3
Summary: Poisson Hyperplane Model Package
Author-email: Alec Shelley <ams01@stanford.edu>
Maintainer-email: Alec Shelley <ams01@stanford.edu>
License-Expression: MIT
Project-URL: Homepage, https://github.com/AlecShelley/hyperpopy
Project-URL: Repository, https://github.com/AlecShelley/hyperpopy
Project-URL: Issues, https://github.com/AlecShelley/hyperpopy/issues
Keywords: poisson,hyperplane,geometry,probability,monte-carlo
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: matplotlib>=3.3.0
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: numba>=0.50.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0; extra == "dev"
Requires-Dist: black>=21.0; extra == "dev"
Requires-Dist: isort>=5.0; extra == "dev"
Requires-Dist: pylint>=2.8.0; extra == "dev"
Requires-Dist: mypy>=0.800; extra == "dev"
Requires-Dist: jupyter>=1.0; extra == "dev"
Requires-Dist: ipykernel>=6.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=4.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0; extra == "docs"
Requires-Dist: nbsphinx>=0.8; extra == "docs"
Dynamic: license-file

# hyperpopy: Poisson Hyperplane Model Package

[![PyPI version](https://badge.fury.io/py/hyperpopy.svg)](https://badge.fury.io/py/hyperpopy)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A Python package for working with Poisson hyperplane models, providing tools for analytical calculations, generation, visualization, and Monte Carlo simulation of Poisson hyperplane processes.

## Features

- **Analytical Calculations**: Compute conditional probability functions for color in the Poisson model
- **Generation & Visualization**: Generate and plot realizations of the Poisson model
- **Monte Carlo Simulation**: Estimate connectivity distributions and color probabilities
- **Probability Landscapes**: Visualize conditional probability functions

## Installation

```bash
pip install --upgrade hyperpopy
```

## Quick Start

```python
import hyperpopy
import numpy as np

# Calculate the arrival rate of a Poisson hyperplane process
rate_2d = hyperpopy.rate(2, 1.0)  # 2D, radius 1.0
print(f"2D Poisson rate: {rate_2d}")

# Generate a 2D visualization of the Poisson hyperplane process
fig = hyperpopy.plot_hyperplanes_color_2d(
    radius=10,
    grid_resolution=100,
    colorcutoffs=np.array([0.5]),
    cmap_list=hyperpopy.frozen_lake_colors
)

# Calculate color distribution for given points
points = np.array([[0, 0], [1, 0], [0, 1]])
colors = (0, 1, 0)  # Known colors for first two points
color_dist = (0.5, 0.5)  # Equal probability for each color

prob_dist = hyperpopy.color_distribution(points, colors, color_dist)
print(f"Color probabilities: {prob_dist}")
```

## Key Functions

### Analytical Utilities
- `rate(dimension, radius)`: Calculate Poisson hyperplane arrival rate
- `color_distribution(points, colors, color_dist)`: Compute conditional color probabilities
- `hitrate_1d/2d/3d(points)`: Calculate hit rates for convex hulls
- `slash_rates(points)`: Return rates of hyperplane partitions

### Generation & Visualization
- `sample_from_ball(dimension, num_points)`: Sample points from unit ball
- `plot_hyperplanes_color_2d()`: Generate 2D Poisson hyperplane visualizations
- `hyperplane_partition(points, gridpoints)`: Partition space using hyperplanes

### Monte Carlo Simulation
- `monte_carlo_hyperplane_partitions()`: Estimate connectivity distributions
- `plot_mc_colors_with_errorbars()`: Plot convergence with error bars
- `probability_landscape()`: Visualize probability landscapes in 2D/3D

## Examples

See the `examples/` directory for comprehensive examples including:
- Figure generation from research papers
- Monte Carlo convergence analysis
- Probability landscape visualization
- Chord length statistics

## Citation

If you use this package in your research, please cite:

```bibtex
@software{hyperpopy2024,
  title={HyperPopy: Poisson Hyperplane Model Package},
  author={Alec Shelley},
  year={2024},
  url={https://github.com/AlecShelley/hyperpopy}
}
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Links

- [GitHub Repository](https://github.com/AlecShelley/hyperpopy)
- [PyPI Package](https://pypi.org/project/hyperpopy/)
- [Issue Tracker](https://github.com/AlecShelley/hyperpopy/issues)
