Metadata-Version: 2.4
Name: pyeqsp
Version: 1.0b1
Summary: Python Equal Area Sphere Partitioning Library
Author-email: Paul Leopardi <paul.leopardi@gmail.com>
License-Expression: MIT
Project-URL: Homepage, http://eqsp.sourceforge.net
Project-URL: Repository, https://github.com/penguian/pyeqsp
Project-URL: Beta Feedback, https://github.com/penguian/pyeqsp/discussions/categories/beta-testing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: matplotlib
Provides-Extra: mayavi
Requires-Dist: mayavi; extra == "mayavi"
Requires-Dist: PyQt5; extra == "mayavi"
Provides-Extra: docs
Requires-Dist: sphinx>=5.0; extra == "docs"
Requires-Dist: sphinx_rtd_theme; extra == "docs"
Requires-Dist: myst_parser; extra == "docs"
Requires-Dist: sphinxcontrib-mermaid; extra == "docs"
Requires-Dist: sphinx-version-warning; extra == "docs"
Provides-Extra: dev
Requires-Dist: ruff; extra == "dev"
Requires-Dist: pylint; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: coverage; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Dynamic: license-file

# PyEQSP: Python Equal Area Sphere Partitioning Library

**Release 1.0b1** (2026-04-21): Copyright 2026 Paul Leopardi

PyEQSP is a Python library that implements the **Recursive Zonal Equal Area (EQ) Sphere Partitioning** algorithm, originally developed as a Matlab toolbox by Paul Leopardi.

An **EQ partition** divides Sᵈ (the unit sphere in ℝ<sup>d+1</sup>) into a finite number of regions of equal area. Area measurement uses the Lebesgue measure inherited from the surrounding space.

> **Naming Distinction**: While the project and GitHub repository share the name **PyEQSP** (or **pyeqsp** on PyPI), you import the package as **eqsp**.

Release **1.0b1** achieves **100% project-wide coverage** for both the core library and the entire maintenance ecosystem.

The **diameter** of a region is the maximum distance between any two of its points (formally the supremum of the Euclidean distance). EQ partitions produce regions with small diameter; specifically, there exists a constant C(d) such that the greatest diameter for an N-region partition of Sᵈ is bounded by C(d)·N<sup>-1/d</sup>.

## What is an EQ point set?

An **EQ point set** consists of the centre points of the regions of an EQ partition. The algorithm defines each region as a product of intervals in spherical polar coordinates. The centre point of a region corresponds to the centre of each interval, except for spherical caps and their descendants, where the centre of the cap itself defines the point.

## Applications

EQ partitions and point sets are useful in a range of
applications that require well-distributed points on a sphere,
including:

- Numerical integration (quadrature) on the sphere
- Sensor, satellite, or antenna placement
- Mesh generation for geophysical and climate models
- Monte Carlo sampling on spherical domains
- Computer graphics and rendering

## Documentation

For a comprehensive overview, including mathematical background, detailed tutorials, and advanced use cases, please consult the [User Guide](https://github.com/penguian/pyeqsp/blob/main/doc/user_guide.md) and [Core Concepts](https://github.com/penguian/pyeqsp/blob/main/doc/user/core_concepts.md).

## Beta Testing & Community Feedback

PyEQSP is currently in **Open Beta**. We actively welcome feedback from researchers and developers to help us reach a stable 1.0 release.

### How to Participate
- **GitHub Discussions**: Visit our [Discussions tab](https://github.com/penguian/pyeqsp/discussions) to ask questions, share results, or suggest ideas.
- **Beta Feedback Hub**: Share your quick verification reports (successes!), environment screenshots, or performance observations in our [pinned feedback issue #26](https://github.com/penguian/pyeqsp/issues/26).
- **Report Detailed Bugs**: If you encounter a specific reproducible error, crash, or mathematical discrepancy, please [open a new issue](https://github.com/penguian/pyeqsp/issues/new/choose) using the **Bug Report** template.

### Portability Notice

While the core library is designed for cross-platform compatibility, it has been developed and tested exclusively on **Linux** to date. For other platforms, we recommend environments such as **macOS** (using Homebrew, `coreutils`, and `bash --posix`) or **Windows 11** (via WSL - Windows Subsystem for Linux) as they are most likely to work "out of the box." However, we provide no guarantees for these platforms until they are properly tested. Specific documentation and fixes for macOS and Windows currently depend on **volunteer contributors**.

For installation instructions and environment setup, see [INSTALL.md](https://github.com/penguian/pyeqsp/blob/main/INSTALL.md).

## Quick Start

### Step 1: Create EQ Partitions
Generate the centre points of an EQ partition of Sᵈ into N regions. These are returned as an array in Cartesian coordinates:

```python
import eqsp

dim = 2
N = 100
points_x = eqsp.eq_point_set(dim, N)
# points_x.shape is (dim+1, N)

# Or force a symmetric partition (even number of collars)
points_sym = eqsp.eq_point_set(dim, N, even_collars=True)
```

Create an array in spherical polar coordinates representing
the centre points:

```python
points_s = eqsp.eq_point_set_polar(dim, N)
```

Create an array in polar coordinates representing the regions
of an EQ partition:

```python
regions = eqsp.eq_regions(dim, N)
# regions.shape is (dim, 2, N)
```

### Step 2: Calculate Properties
Find the (per-partition) boundary on the diameter of the EQ partition and calculate the r<sup>-s</sup> (Riesz) energy or min-distance:

```python
from eqsp.region_props import eq_diam_bound
from eqsp.point_set_props import eq_energy_dist

# Find diameter boundary
diam_bound = eq_diam_bound(dim, N)

# Find energy and distance
s = dim - 1  # Standard Riesz energy kernel power
energy, min_dist = eq_energy_dist(dim, [N], s)
```

### Step 3: Produce Illustrations
PyEQSP provides both Matplotlib-based 2D projections and interactive 3D renderings via Mayavi:

#### 2D Illustrations (Matplotlib)

Project the EQ partition of S² into N regions onto a
2D plane:

```python
from eqsp.illustrations import project_s2_partition
import matplotlib.pyplot as plt

project_s2_partition(10, proj='stereo')
plt.show()
```

Illustrate the EQ algorithm steps for the partition of Sᵈ
into N regions:

```python
from eqsp.illustrations import illustrate_eq_algorithm

illustrate_eq_algorithm(3, 10)
plt.show()
```

#### 3D Visualizations (Mayavi)

Display a 3D rendering of the EQ partition of S² into N
regions:

```python
from eqsp.visualizations import show_s2_partition

show_s2_partition(10)
# Opens a native Mayavi GUI window.
```

Display a 3D stereographic projection of the EQ partition of
S³ into N regions:

```python
from eqsp.visualizations import project_s3_partition

project_s3_partition(10, proj='stereo')
```

## User Guide Examples

Standalone Python scripts demonstrating core library features:
- **[examples/user-guide/src/](https://github.com/penguian/pyeqsp/tree/main/examples/user-guide/src/)**: Contains `example_quick_start.py`, `example_visualize_2d.py`, `example_visualize_3d.py`, and `example_symmetric_partitions.py`.

These examples are fully integrated into the test suite and documentation.

## Thesis Examples

For users interested in reproducing the results from the
original PhD thesis, reproduction scripts are available in the
`examples/phd-thesis/` directory. See
[doc/user/phd-thesis-examples.md](https://github.com/penguian/pyeqsp/blob/main/doc/user/phd-thesis-examples.md)
for details.

## Performance & Benchmarking

The package includes benchmarks to measure the efficiency of core partitioning and mathematical operations. See [doc/maintainer/benchmarks.md](https://github.com/penguian/pyeqsp/blob/main/doc/maintainer/benchmarks.md) for details.

## Frequently Asked Questions

### Is PyEQSP for S² and S³ only? What is the max dimension?

In principle, any function which has `dim` as a parameter will
work for any integer dim ≥ 1 (where S¹ is the circle). In
practice, for large $d$, the functions may be slow or consume
large amounts of memory due to the recursive nature or array
sizes.

### What is the range of the number of points, N?

In principle, any function which takes `N` as an argument will
work with any positive integer value of `N`. In practice, for
large `N`, the functions may be slow or memory-intensive.

### Visualization options

- `illustrations.project_s2_partition(N, proj=...)`:
  2D projection of S² partition (Matplotlib).
- `illustrations.illustrate_eq_algorithm(dim, N)`:
  Step-by-step visualization (Matplotlib).
- `visualizations.show_s2_partition(N)`:
  3D plot of S² partition (Mayavi).
- `visualizations.project_s3_partition(N, proj=...)`:
  3D projection of S³ partition (Mayavi).

See the docstrings for more details (e.g.
`help(eqsp.visualizations.show_s2_partition)`).

## Package Structure

- `eqsp.partitions`: Core partitioning functions
  (`eq_regions`, `eq_point_set`, `eq_caps`).
- `eqsp.utilities`: Geometric utilities
  (`area_of_cap`, `volume_of_ball`, `polar2cart`, etc.).
- `eqsp.point_set_props`: Properties of point sets
  (energy, min distance).
- `eqsp.region_props`: Properties of regions
  (diameter, vertex max dist).
- `eqsp.illustrations`: 2D visualizations (Matplotlib).
- `eqsp.visualizations`: 3D visualizations (Mayavi).

## Reporting Bugs & Contributing

Found a bug? Please [open an issue](https://github.com/penguian/pyeqsp/issues/new/choose). If you would like to contribute code or documentation improvements, please see [CONTRIBUTING.md](https://github.com/penguian/pyeqsp/blob/main/CONTRIBUTING.md) for our technical standards and workflow.

## Citation

If you use this software in research, please cite the original
work:

> Paul Leopardi, "A partition of the unit sphere into regions
> of equal area and small diameter", Electronic Transactions on
> Numerical Analysis, Volume 25, 2006, pp. 309-327.
> http://etna.mcs.kent.edu/vol.25.2006/pp309-327.dir/pp309-327.html

For a recent case study and discussion on the applicability of these
constructions, see:

> Paul Leopardi, "The applicability of equal area partitions of
> the unit sphere", Journal of Approximation Software, Volume 1,
> Issue 2, 2024.
> https://doi.org/10.13135/jas.10248

## License

This software is released under the **MIT License**. See the
`LICENSE` file for details.

The MATLAB implementation can be found at:
https://github.com/penguian/eq_sphere_partitions with a mirror at
https://sourceforge.net/projects/eqsp
