Metadata-Version: 2.4
Name: pyeqsp
Version: 0.99.6
Summary: Python Equal Area Sphere Partitioning Library
Author-email: Paul Leopardi <paul.leopardi@gmail.com>
License: PyEQSP: Python Equal Area Sphere Partitioning Library
        
        Copyright 2026 Paul Leopardi
        
        COPYING
        
        For references, see AUTHORS.md.
        For revision history, see CHANGELOG.md.
        
        Permission is hereby granted, free of charge, to any person obtaining
        a copy of this software and associated documentation files (the
        "Software"), to deal in the Software without restriction, including
        without limitation the rights to use, copy, modify, merge, publish,
        distribute, sublicense, and/or sell copies of the Software, and to
        permit persons to whom the Software is furnished to do so, subject to
        the following conditions:
        
        The above copyright notice and this permission notice shall be included
        in all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
        EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
        MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
        IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
        CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
        TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
        SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
        
Project-URL: Homepage, http://eqsp.sourceforge.net
Project-URL: Repository, https://github.com/penguian/pyeqsp
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: COPYING
License-File: AUTHORS.md
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"
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"
Dynamic: license-file

# PyEQSP: Python Equal Area Sphere Partitioning Library

**Release 0.99.6** (2026-03-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 ℝᵈ⁺¹) 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**.

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⁻¹/ᵈ.

## 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/core_concepts.md).

## Installation & Beta Status

PyEQSP is currently in **Beta testing**. We welcome your feedback!

Requires **Python 3.11+**. We recommend installing **PyEQSP** within a virtual environment. See [INSTALL.md](https://github.com/penguian/pyeqsp/blob/main/INSTALL.md) for full instructions, including environment setup and optional dependencies.

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

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⁻ˢ (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/phd-thesis-examples.md](https://github.com/penguian/pyeqsp/blob/main/doc/phd-thesis-examples.md)
for details.

## Performance & Benchmarking

The package includes benchmarks to measure the efficiency of
core partitioning and mathematical operations. See
[doc/benchmarks.md](https://github.com/penguian/pyeqsp/blob/main/doc/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
`COPYING` file for details.

The original Matlab implementation can be found at:
http://eqsp.sourceforge.net
