eq_sphere_partition​s

The Recursive Zonal Equal Area (EQ) Sphere Partitioning Toolbox is a suite of Matlab functions for partitioning and point distribution on mu

Recursive Zonal Equal Area (EQ) Sphere Partitioning Toolbox.

Release 1.12 2024-10-27

Copyright 2024 Paul Leopardi

Copyright 2004-2005 Paul Leopardi for the University of New South Wales.

README

For licensing, see COPYING

For references, see AUTHORS

For revision history, see CHANGELOG.

>> 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?

Release 1.00 2005-02-13 was the first version of the EQ sphere partitioning code to be packaged in toolbox form.

Release 1.10 2005-06-26 is the first public release of the code.

Release 1.12 2024-10-27 brings the Matlab code up to date, and includes histogram utilities.

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.

>> 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, and README.

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: This file.

>> 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 partsphere, above.

>> Which file to begin with?

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

1. Create EQ partitions

o Create an array in Cartesian coordinates representing the `center' points of an EQ partition of S^dim into N regions:

> points_x = eq_point_set(dim,N);

o Create an array in spherical polar coordinates representing the `center' points of an EQ partition of S^dim into N regions:

> points_s = (eq_point_set_polar(dim,N);

o Create an array in polar coordinates representing the regions of an EQ partition of S^dim into N regions:

> regions = eq_regions(dim,N);

2. Find properties of EQ partitions

o Find the (per-partition) maximum diameter bound of the EQ partition of S^dim into N regions:

> diam_bound = eq_diam_bound(dim,N);

3. Find properties of EQ point sets

o Find the r^(-s) energy and min distance of the EQ `center' point sets of S^dim for N points:

> [energy,dist] = eq_energy_dist(dim,N,s);

4. Create a histogram

o Given a set of points, count points in each of N regions of an EQ partition of S^2:

> count_v = eq_count_points_by_s2_region(points_s, 8);

5. Produce an illustration

o Use projection to illustrate the EQ partition of S^2 into N regions:

> project_s2_partition(N);

>> 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:

o Use a 3D plot to illustrate the EQ partition of S^2 into N regions:

> show_s2_partition(N);

o Use projection to illustrate the EQ partition of S^2 into N regions:

> project_s2_partition(N);

o Use projection to illustrate the EQ partition of S^3 into N regions.

> project_s3_partition(N);

o Illustrate the EQ algorithm for the partition of S^dim into N regions.

> illustrate_eq_algorithm(dim,N);

See the help for these functions for details.