Recursive Zonal Equal Area Sphere Partitioning Toolbox

Recursive zonal equal area partition of S^2 into 33 regions

SourceForge.net project page

Download the current version of the Recursive Zonal Equal Area (EQ) Sphere Partitioning Toolbox from the EQ Sphere Partitions project page hosted at SourceForge.


FAQ - from the README

What is the Recursive Zonal Equal Area (EQ) Sphere Partitioning Toolbox?

The Recursive Zonal Equal Area (EQ) Sphere Partitioning Toolbox is a suite of Matlab functions. These functions are intended for use in exploring different aspects of EQ sphere partitioning.

The functions are grouped into the following groups of tasks:

  1. Create EQ partitions
  2. Find properties of EQ partitions
  3. Find properties of EQ point sets
  4. Create histograms based on EQ partitions
  5. Produce illustrations
  6. Perform some utility function
  7. Test the toolbox

What is an EQ partition?

An EQ partition is a partition of S^dim [the unit sphere in the dim+1 Euclidean space R^(dim+1)] into a finite number of regions of equal area. The area of each region is defined using the Lebesgue measure inherited from R^(dim+1).

The diameter of a region is the sup of the Euclidean distance between any two points of the region. The regions of an EQ partition have been proven to have small diameter, in the sense that there exists a constant C(dim) such that the maximum diameter of the regions of an N region EQ partition of S^dim is bounded above by C(dim)*N^(-1/dim).

What is an EQ point set?

An EQ point set is the set of center points of the regions of an EQ partition. Each region is defined as a product of intervals in spherical polar coordinates. The center point of a region is defined via the center points of each interval, with the exception of spherical caps and their descendants, where the center point is defined using the center of the spherical cap.

What's new?

For details of changes from earlier versions of the EQ partitioning code, and changes from 1.00 to the current release, see CHANGELOG.

Which versions of Matlab can I use?

This toolbox has been tested with various Matlab versions between R2020b and R2023b on Linux, MacOS and Windows 10.

How do I install the Recursive Zonal Equal Area Sphere Partitioning Toolbox?

This toolbox is organized into a number of directories. To use it effectively, these directories need to be on your Matlab path every time you start Matlab. You will therefore need to install the toolbox before using it.

To do this,

  1. Unzip the downloaded Zip file into the directory where you want the toolbox to reside. This will create the subdirectory eq_sphere_partitions.
  2. Run Matlab, change directory to eq_sphere_partitions and then run install_eq_toolbox.
For more information, see INSTALL.txt.

What documentation is available?

The user documentation includes the help comments in each Matlab M file, plus the extra files Contents.m, AUTHORS, CHANGELOG, COPYING, INSTALL.txt and README.txt.

The extra files contain the following:

Contents.m:
A brief description of those functions in the toolbox which are visible to end users.
AUTHORS:
Authors, acknowledgements and references.
CHANGELOG:
Revision history.
COPYING:
Software license terms.
INSTALL:
Installation instructions.
README:
Information for first-time users.

How do I get help?

To see a brief description of the functions in the toolbox, enter the command HELP EQ_SPHERE_PARTITIONS (in lower case). The command WHAT lists all the functions in your current directory.

For each function, the command HELP FUNCTION, where FUNCTION is the name of the function, will give the help for the function.

The help format is:

  1. Summary line.
  2. Syntax of the function call.
  3. Description, usually with a description of each argument.
  4. Notes.
  5. Example of use of the function.
  6. See also.

For example, here is the result of HELP EQ_POINT_SET:


 EQ_POINT_SET Center points of regions of EQ partition, in Cartesian coordinates

 Syntax
  points_x = eq_point_set(dim,N,options);

 Description
  POINTS_X = EQ_POINT_SET(dim,N) does the following:
  1) uses the recursive zonal equal area sphere partitioning algorithm to
  partition S^dim (the unit sphere in dim+1 dimensional space) into N regions
  of equal area and small diameter, and
  2) sets POINTS_X to be an array of size (dim+1 by N), containing the center
  points of each region.
  Each column of POINTS_X represents a point of S^dim, in Cartesian coordinates.

  The arguments dim and N must be positive integers.

  POINTS_X = EQ_POINT_SET(dim,N,'offset','extra') uses experimental extra offsets
  for S^2 and S^3 to try to minimize energy.

  POINTS_X = EQ_POINT_SET(dim,N,extra_offset) uses experimental extra offsets if
  extra_offset is true or non-zero.

 Notes
  Each region is defined as a product of intervals in spherical polar
  coordinates. The center point of a region is defined via the center points
  of each interval, with the exception of spherical caps and their descendants,
  where the center point is defined using the center of the spherical cap.

  If dim > 3, extra offsets are not used.
  For more details on options, see help partition_options.

 Examples

  >> points_x = eq_point_set(2,4)

  points_x =
           0    0.0000   -0.0000    0.0000
           0    1.0000   -1.0000         0
      1.0000    0.0000    0.0000   -1.0000

  >> size(points_x)

  ans =

       3     4

 See also
  PARTITION_OPTIONS, EQ_POINT_SET_POLAR, EQ_REGIONS, POLAR2CART


What is the input? What is the output?

The help for each function briefly describes the input and the output, as per the example for eq_point_set above.

Which file to begin with?

You need to find a function which does what you want to do. Examples:

  1. Create EQ partitions
  2. Find properties of EQ partitions
  3. Find properties of EQ point sets
  4. Create a histogram
  5. Produce an illustration

Is the toolbox for use with S^2 and S^3 only? What is the maximum dimension?

In principle, any function which has dim as a parameter will work for any integer dim >= 1. In practice, for large d, the function may be slow, or may consume large amounts of memory.

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 very large N, the function may be slow, or may consume large amounts of memory.

What are the options for visualizing points or equal area regions?

A number of different illustrations are available:

See the help for these functions for details.


Presentations
Publications
PhD Thesis
Distributing points on the sphere: Partitions, separation, quadrature and energy , UNSW, 2007.
Accompanying Thesis/Dissertation Sheet.

Authors

Origin

Maple and Matlab code is based on Ed Saff [SafSP], [Saf03] and Ian Sloan [Slo03].

References

[Dahl78]:
B. E. J. Dahlberg, "On the distribution of Fekete points", Duke Math. J. 45 (1978), no. 3, pp. 537--542.
[KuiS98]:
A. B. J. Kuijlaars, E. B. Saff, "Asymptotics for minimal discrete energy on the sphere", Transactions of the American Mathematical Society, v. 350 no. 2 (Feb 1998) pp. 523--538.
[KuiSS04]:
A. B. J. Kuijlaars, E. B. Saff, X. Sun, "Minimum separation f the minimal energy points on spheres in Euclidean spaces", (preprint) 2004-11-30.
[LeGS01]:
T. Le Gia, I. H. Sloan, "The uniform norm of hyperinterpolation on the unit sphere in an arbitrary number of dimensions", Constructive Approximation (2001) 17: p249-265.
[Mue98]:
C. Mueller, "Analysis of spherical symmetries in Euclidean spaces", Springer, 1998.
[RakSZ94]:
E. A. Rakhmanov, E. B. Saff, Y. M. Zhou, "Minimal discrete energy on the sphere", Mathematics Research Letters, 1 (1994), pp. 647--662.
[RakSZ95]:
E. A. Rakhmanov, E. B. Saff, Y. M. Zhou, "Electrons on the sphere", Computational methods and function theory 1994 (Penang), pp. 293--309, Ser. Approx. Decompos., 5, World Sci. Publishing, River Edge, NJ, 1995.
[SafK97]:
E. B. Saff, A. B. J. Kuijlaars, "Distributing many points on a sphere", Mathematical Intelligencer, v19 no1 (1997), pp. 5--11.
[SafSP]:
E. B. Saff, Points on Spheres and Manifolds - Equal Area Points.
[Saf03]:
Ed Saff, "Equal-area partitions of sphere", Presentation at UNSW, 2003-07-28.
[Slo03]:
Ian Sloan, "Equal area partition of S^3", Notes, 2003-07-29.
[WeiMW]:
E. W. Weisstein, Hypersphere. From MathWorld--A Wolfram Web Resource.
[Zho95]:
Y. M. Zhou, "Arrangement of points on the sphere", Thesis, University of South Florida, 1995.
[Zho98]:
Y. M. Zhou, "Equidistribution and extremal energy of N points on the sphere", Modelling and computation for applications in mathematics, science, and engineering (Evanston, IL, 1996), pp. 39--57, Numer. Math. Sci. Comput., Oxford Univ. Press, New York, 1998.

Installation and Utilities

Toolbox Installer 2.2, 2003-07-22 by Rasmus Anthin.

Files modified and relicenced with permission of Rasmus Anthin:

./private:
install.m       uninstall.m

Web site



Page Generated: Wednesday 6 November 2024