1. Volume 1: The User Guide

This guide enables researchers and scientists to set up PyEQSP and reproduce published research results.

1.1. Introduction & Setup

PyEQSP requires Python 3.11 or later. We recommend using a virtual environment to manage dependencies like NumPy, SciPy, and Matplotlib.

  • Environment Management: See the Installation Guide for strategy details (e.g., venv vs venv_sys).

1.2. Use Cases & Applicability

PyEQSP is the Python successor to the original MATLAB Equal Area Sphere Partitioning toolbox. Researchers use it in many fields:

  • Climate Science: Spatio-temporal reconstructions.

  • Bio-Medicine: RNA folding simulations and MRI sampling.

  • Physics: Correlation energy in Fermi gases.

For a comprehensive review of applications, see the Use Cases Guide and the Journal of Approximation Software (JAS) 2024 paper: “The applicability of equal area partitions of the unit sphere”.

1.3. Core Concepts & Geometries

The library implements recursive zonal partitioning (the EQ algorithm) for these manifolds:

  • Manifolds: Operations on \(S^2\) (sphere), \(S^3\), and higher-dimensional spheres \(S^d\).

  • Coordinate Systems: Support for both Spherical and Euclidean conventions.

For more details on the underlying mathematics, see the Core Concepts & Geometries guide.

1.4. Practical Usage

Generate partitions and analyze their properties using the core API:

  • Partitioning: Creating regions and point sets via eq_regions and eq_point_set.

  • Property Analysis: Measuring min-distance, packing density, and Riesz energy.

For step-by-step examples, see the Practical Usage Guide.

1.5. Visualization

PyEQSP supports both 2D and 3D visualizations:

  • 2D Projections: Matplotlib-based schematics.

  • 3D Interactive Graphics: High-fidelity rendering using Mayavi and VTK.

For detailed plotting options, see the Visualization & Illustration Guide.

1.6. Reproducing Research

A primary goal of PyEQSP is the faithful reproduction of research results from the original PhD thesis [Leo07].

  • Thesis Examples: A dedicated guide to the Thesis Reproduction Scripts is available, which now includes technical setup and troubleshooting details.

1.7. Executable Examples

Standalone Python scripts demonstrating these concepts are available in the examples/user-guide/src/ directory:

  • example_quick_start.py: Basic partitioning and property analysis.

  • example_visualize_2d.py & example_visualize_3d.py: Plotting and interactive rendering.

  • example_symmetric_partitions.py: Using the even_collars parameter.

1.8. Appendices

Technical reference material, setup details, and the migration bridge are available in the appendices:

For the full list of scientific works cited in this volume, see the References chapter.