Release 1.0b2 (2026-06-07): 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.0b2 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.
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.
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
The full documentation for PyEQSP is available at Read the Docs and mirrored at SourceForge.
For a comprehensive overview, including mathematical background, detailed tutorials, and advanced use cases, please consult the User Guide and Core Concepts.
PyEQSP is currently in Open Beta. We actively welcome feedback from researchers and developers to help us reach a stable 1.0 release.
- 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.
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.
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)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)PyEQSP provides both Matplotlib-based 2D projections and interactive 3D renderings via Mayavi:
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()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')Standalone Python scripts demonstrating core library features:
- examples/user-guide/src/: Contains
example_quick_start.py,example_visualize_2d.py,example_visualize_3d.py, andexample_symmetric_partitions.py.
These examples are fully integrated into the test suite and documentation.
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.
The package includes benchmarks to measure the efficiency of core partitioning and mathematical operations. See doc/maintainer/benchmarks.md for details.
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
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.
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)).
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).
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.
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
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