4. Practical Usage Guide

This guide provides a hands-on introduction to using the core PyEQSP functions for research and data analysis.

4.1. Step 1: Initialize a Partition

The most common task is generating a set of \(N\) points roughly uniformly distributed on a sphere.

4.1.1. Generating Regions

Use eq_regions to find the boundaries of the partition.

import eqsp
regions = eqsp.eq_regions(dim=2, N=1000)

4.1.2. Generating Point Sets

Use eq_point_set to get the centre points of each region.

points = eqsp.eq_point_set(dim=2, N=1000)
# points is a (3, 1000) NumPy array (column-major convention)

4.2. Step 2: Analyze Geometric Properties

Once you have a point set, you can measure its quality using metrics.

4.2.1. Min-Distance

Measuring the separation between points helps check packing efficiency.

# Measure min distance from existing points
min_dist = eqsp.point_set_min_dist(points)
print(f"Min-distance: {min_dist}")

4.2.2. Riesz Energy

Calculate the energy of the point set to test its uniformity from a physical perspective.

# Measure energy from existing points
energy, _ = eqsp.point_set_energy_dist(points, s=2)
print(f"Riesz s-energy: {energy}")

Tip

A complete standalone version of this workflow can be found in examples/user-guide/src/example_quick_start.py.

4.3. Step 3: Advanced Partitioning (\(S^3\) and SO(3))

For applications involving rotations or orientations, you can partition the higher-dimensional \(S^3\).

# Partition into 5000 regions on S^3
points_s3 = eqsp.eq_point_set(dim=3, N=5000)

4.4. Step 4: Fast Vectorized Binning

If you have a large set of data points (e.g., climate observations) and need to bin them into equal-area regions:

  1. Generate the regions using eq_regions.

  2. Map your data points to the regions.

Note: PyEQSP uses high-performance NumPy vectorization to handle large datasets efficiently.