pyeqsp 1.0b1

Python Equal Area Sphere Partitioning Library

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 ℝ^d+1) 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^-1/d.

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 and Core Concepts.

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 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.
• Report Detailed Bugs: If you encounter a specific reproducible error, crash, or mathematical discrepancy, please open a new issue 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.

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:

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:

points_s = eqsp.eq_point_set_polar(dim, N)

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

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^-s (Riesz) energy or min-distance:

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:

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:

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:

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:

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/: 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 for details.

Performance & Benchmarking

The package includes benchmarks to measure the efficiency of core partitioning and mathematical operations. See 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. If you would like to contribute code or documentation improvements, please see 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