Commit 412bdd0f authored by Florian Pausch's avatar Florian Pausch

Merge branch 'master' of https://git.rwth-aachen.de/ita/toolbox

parents c0d88c1a 4e7f304d
Recursive Zonal Equal Area (EQ) Sphere Partitioning Toolbox.
Release 1.10 2005-06-26
Copyright 2004-2005 Paul Leopardi for the University of New South Wales.
AUTHORS
For licensing, see COPYING.
For revision history, see CHANGELOG.
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.
[Leo05]: P. Leopardi,
"A partition of the unit sphere into regions of equal area and small diameter",
Applied Maths Report AMR05/18, May, 2005, submitted to
Electronic Transactions on Numerical Analysis.
http://www.maths.unsw.edu.au/applied/files/2005/amr05_18.pdf
[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, "Sphere Points,"
http://www.math.vanderbilt.edu/~esaff/sphere_points.html
[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.
http://mathworld.wolfram.com/Hypersphere.html
[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 B. Rasmus Anthin.
Matlab Central File Exchange
http://www.mathworks.com/matlabcentral/fileexchange/
Home page of B. Rasmus Anthin
http://www.etek.chalmers.se/~e8rasmus/
Files modified and relicenced with permission of B. Rasmus Anthin:
./private
install.m uninstall.m
This diff is collapsed.
Recursive Zonal Equal Area (EQ) Sphere Partitioning Toolbox.
Release 1.10 2005-06-26
COPYING
For references, see AUTHORS.
For revision history, see CHANGELOG.
Copyright (c) 2004, 2005, University of New South Wales
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
% Recursive Zonal Equal Area Sphere Partitioning Toolbox.
% Release 1.10 2005-06-26
%
%Functions by category
%=====================
%
%Installation
%------------
%
% install_eq_toolbox Install toolbox
% uninstall_eq_toolbox Uninstall toolbox
%
%Recursive zonal equal area sphere partitions
%--------------------------------------------
%
% Partitions
% eq_caps Partition a sphere into to nested spherical caps
% eq_regions Recursive zonal equal area (EQ) partition of sphere
%
% Point sets
% eq_point_set Center points of regions of EQ partition,
% in Cartesian coordinates
% eq_point_set_polar Center points of regions of an EQ partition,
% in spherical polar coordinates
%
% Partition options
% partition_options Options for EQ partition
%
%Properties of recursive zonal equal area sphere partitions
%----------------------------------------------------------
%
% Diameter
% eq_diam_bound Maximum per-region diameter bound of EQ partition
% eq_vertex_diam Maximum vertex diameter of EQ partition
%
% eq_diam_coeff Coefficients of diameter bound and vertex diameter of
% EQ partition
% eq_vertex_diam_coeff Coefficient of maximum vertex diameter of EQ partition
%
%Hook for user-defined properties
% eq_regions_property Property of regions of an EQ partition
%
%Properties of EQ point sets
%---------------------------
%
% Energy and minimum distance
% eq_energy_dist Energy and minimum distance of an EQ point set
% point_set_energy_dist Energy and minimum distance of a point set
%
% Energy
% eq_energy_coeff Coefficient in expansion of energy of an EQ point set
% point_set_energy_coeff Coefficient in expansion of energy of a point set
% calc_energy_coeff Coefficient of second term in expansion of energy
%
% Minimum distance
% eq_min_dist Minimum distance between center points of an
% EQ partition
% point_set_min_dist Minimum distance between points of a point set
%
% eq_dist_coeff Coefficient of minimum distance of an EQ point set
% point_set_dist_coeff Coefficient of minimum distance of a point set
% calc_dist_coeff Coefficient of minimum distance
%
% Spherical cap packing density
% eq_packing_density Density of packing given by minimum distance of
% EQ point set
% point_set_packing_density Density of packing given by minimum distance of
% a point set
% calc_packing_density Density of packing given by minimum distance
%
% Hook for user-defined properties
% eq_point_set_property Property of an EQ point set
%
%Illustrations
%-------------
%
% Illustration of EQ Partitions of S^2 or S^3
% show_s2_partition 3D illustration of an EQ partition of S^2
% project_s2_partition Use projection to illustrate an EQ partition of S^2
% project_s3_partition Use projection to illustrate an EQ partition of S^3
%
% Illustration of point sets on S^2 or S^3
% show_r3_point_set 3D illustration of a point set
% project_point_set Use projection to illustrate a point set of
% S^2 or S^3
% Illustration of a recursive zonal equal area sphere partition algorithm
% illustrate_eq_algorithm Illustrate the EQ partition algorithm
%
% Illustration options
% illustration_options Options for illustrations of EQ partitions
%
%Tests
%-----
%
% eq_area_error Total area error and max area error per region of an
% EQ partition
%
%Utilities
%---------
%
% area_of_cap Area of spherical cap
% area_of_collar Area of spherical collar
% area_of_ideal_region Area of one region of an EQ partition
% area_of_sphere Area of sphere
% cart2polar2 Convert Cartesian to spherical polar coordinates on S^2
% euc2sph_dist Convert Euclidean to spherical distance
% euclidean_dist Euclidean distance between two points
% fatcurve Create a parameterized cylindrical surface
% haslight Check if axis handle has a light attached
% ideal_collar_angle Ideal angle for spherical collars of an EQ partition
% illustration_options Options for illustrations of EQ partitions
% partition_options Options for EQ partition
% polar2cart Convert spherical polar to Cartesian coordinates
% sph2euc_dist Convert spherical to Euclidean distance
% spherical_dist Spherical distance between two points on the sphere
% sradius_of_cap Spherical radius of spherical cap of given area
% volume_of_ball Volume of the unit ball
%
% If the previous text scrolled off the screen, try
% more on; help eq_sphere_partitions; more off;
% Copyright 2004-2005 Paul Leopardi for the University of New South Wales.
% $Revision 1.10 $ $Date 2005-06-26 $
% Function changed name from e2s to euc2sph_dist
% Function changed name from s2e to sph2euc_dist
% Function changed name from s2x to polar2cart
% Function changed name from x2s2 to cart2polar2
% Add new function fatcurve
% Add new function haslight
% Clean up descriptions
% Documentation files renamed
% $Revision 1.00 $ $Date 2005-02-13 $
%
% For licensing, see COPYING.
% For references, see AUTHORS.
% For revision history, see CHANGELOG.
Recursive Zonal Equal Area (EQ) Sphere Partitioning Toolbox.
Release 1.10 2005-06-26
Copyright 2004-2005 Paul Leopardi for the University of New South Wales.
INSTALL.txt
For licensing, see COPYING.
For references, see AUTHORS.
For revision history, see CHANGELOG.
NOTE:
This file has lines terminated by CR-LF for use with DOS and Windows Notepad.
On Windows, to read AUTHORS, COPYING and CHANGELOG, use another editor, such as
Wordpad or the Matlab editor.
Installation
============
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. You need to unzip the file eqsp-1.10.zip into the directory
where you want the toolbox to reside. This will create the subdirectory
eq_sphere_partitions.
On Linux, Unix and Mac OS X, to perform the unzip, run the GNU unzip command
unzip eqsp-1.00.zip
On Mac OS X, as an alternative, you can use:
Stuffit Expander (free): http://www.stuffit.com/mac/expander/index.html
On Windows, use one of:
7-zip (free): http://www.7-zip.org
Winzip (commercial): http://www.winzip.com
2. Run Matlab, change directory to eq_sphere_partitions and then run
install_eq_toolbox.
The function INSTALL_EQ_TOOLBOX adds the directories of this toolbox to your
Matlab path by changing the contents of the Matlab file pathdef.m. Here is the
result of HELP INSTALL_EQ_TOOLBOX.
-------------------------------------------------------------------------------
INSTALL_EQ_TOOLBOX Install using Toolbox Installer, with sensible defaults
Syntax
install_eq_toolbox(arg);
Description
INSTALL_EQ_TOOLBOX uses Toolbox Installer to install this toolbox. It must
be run from the top level directory of this toolbox, which must contain the
file info.ins.
If INSTALL_EQ_TOOLBOX is called with no argument, it asks the user for
confirmation before taking any action.
INSTALL_EQ_TOOLBOX first checks if the file pathname.m exists on the current
Matlab path and can be appended to.
If so, it asks the user for confirmation and then simply calls the INSTALL
function of Toolbox Installer to update the file pathname.m.
If not, it tries to choose a sensible directory in which to create a new
pathdef.m file, and suggests this to the user before proceeding.
INSTALL_EQ_TOOLBOX DIRNAME, that is INSTALL_EQ_TOOLBOX('DIRNAME'),
calls INSTALL('DIRNAME'), using DIRNAME as the directory for pathdef.m.
INSTALL_EQ_TOOLBOX -, that is INSTALL_EQ_TOOLBOX('-'), calls INSTALL('-'),
which displays a dialog box so the user can select the directory to be used
for pathdef.m.
Notes
If it is necessary to create a new pathdef.m file, the directory which
INSTALL_EQ_TOOLBOX suggests to the user for this file defaults to
the directory which contains startup.m, if this exists.
Otherwise INSTALL_EQ_TOOLBOX suggests the following directory to the user:
For Unix systems including Linux and Mac: $HOME/matlab
For Windows systems: [matlabroot '\toolbox\local'].
If this directory does not exist, INSTALL_EQ_TOOLBOX tries to create it.
For Toolbox Installer 2.2 by B. Rasmus Anthin, see
Matlab Central File Exchange
http://www.mathworks.com/matlabcentral/fileexchange/
Home page of B. Rasmus Anthin
http://www.etek.chalmers.se/~e8rasmus/
Examples
> install_eq_toolbox
Info: Installer will create the file /c/leopardi/matlab/pathdef.m
Proceed (y/n)? y
Info: Installer has created the directory /c/leopardi/matlab
Info: Installed.
> install_eq_toolbox
Info: Installer will update the file /c/leopardi/matlab/pathdef.m
Proceed (y/n)? y
Info: Installed.
> install_eq_toolbox
Info: Installer will update the file /c/leopardi/matlab/pathdef.m
Info: Proceed (y/n)? n
> cd ~
> install_eq_toolbox
??? Error using ==> install_eq_toolbox
Please run install_eq_toolbox from toolbox directory, eg. /c/leopardi/[...]
See also
UNINSTALL_EQ_TOOLBOX, PATHDEF, PATH, Toolbox Installer 2.2
-------------------------------------------------------------------------------
Uninstallation
==============
This toolbox also provides an uninstallation command. The function
UNINSTALL_EQ_TOOLBOX removes the toolbox directories from the path, and saves
the updated path to pathdef.m. Note that UNINSTALL_EQ_TOOLBOX does not undo
everything done by INSTALL_EQ_TOOLBOX. In particular, UNINSTALL_EQ_TOOLBOX does
not delete pathdef.m or its directory, even if these were created by
INSTALL_EQ_TOOLBOX.
For more details, see HELP UNINSTALL_EQ_TOOLBOX (in lower case).
Installing other Matlab toolboxes or upgrading Matlab
=====================================================
Since INSTALL_EQ_TOOLBOX may create the file pathdef.m, you will need to be
careful when installing other Matlab toolboxes or upgrading Matlab.
In particular, you will need to ensure that your Matlab path is set correctly.
If things go badly wrong and you can't fix the problem in any other way,
try the following steps:
1. Use UNINSTALL_EQ_TOOLBOX to uninstall this toolbox.
2. If you know that INSTALL_EQ_TOOLBOX created the file pathdef.m
then delete this file.
3. Install the other Matlab toolboxes or upgrade Matlab.
4. Run INSTALL_EQ_TOOLBOX again.
Recursive Zonal Equal Area (EQ) Sphere Partitioning Toolbox.
Release 1.10 2005-06-26
Copyright 2004-2005 Paul Leopardi for the University of New South Wales.
README.txt
For licensing, see COPYING
For references, see AUTHORS
For revision history, see CHANGELOG.
NOTE:
This file has lines terminated by CR-LF for use with DOS and Windows Notepad.
On Windows, to read AUTHORS, COPYING and CHANGELOG, use another editor, such as
Wordpad or the Matlab editor.
>> 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. Produce illustrations
5. Test the toolbox
6. Perform some utility function
>> 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.
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 Matlab versions 6.5 and 7.0.1 on Linux,
and 6.5.1 on Windows.
>> 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 file eqsp-1.10.zip 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.txt: Installation instructions in DOS CR-LF text format.
README.txt: 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, S2X
-------------------------------------------------------------------------------
>> 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. 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.
%Recursive Zonal Equal Area Sphere Partitioning: Illustrations
%
% Recursive Zonal Equal Area (EQ) Sphere Partitioning Toolbox.
% Release 1.10 2005-06-01
%
%Functions by category
%=====================
%
% Illustration of EQ Partitions of S^2 or S^3
% show_s2_partition 3D illustration of an EQ partition of S^2
% project_s2_partition Use projection to illustrate an EQ partition of S^2
% project_s3_partition Use projection to illustrate an EQ partition of S^3
%
% Illustration of point sets on S^2 or S^3
% show_r3_point_set 3D illustration of a point set
% project_point_set Use projection to illustrate a point set of
% S^2 or S^3
%
% Illustration options
% illustration_options Options for illustrations of EQ partitions
% Copyright 2004-2005 Paul Leopardi for the University of New South Wales.
% $Revision 1.10 $ $Date 2005-06-01 $
% Documentation files renamed
% $Revision 1.00 $ $Date 2005-02-13 $
%
% For licensing, see COPYING.
% For references, see AUTHORS.
% For revision history, see CHANGELOG.
function gopt = illustration_options(gdefault, varargin)
%ILLUSTRATION_OPTIONS Options for illustrations of EQ partitions
%
%Syntax
% gopt = illustration_options(gdefault,options);
%
%Description
% GOPT = ILLUSTRATION_OPTIONS(GDEFAULT,options) collects illustration options,
% specified as name, value pairs, and places these into the structure GOPT.
% The structure GDEFAULT is used to define default option values.
%
% The structures gdefault and gopt may contain the following fields:
% fontsize: numeric
% long_title: boolean
% stereo: boolean
% show_points: boolean
% show_sphere: boolean
% show_surfaces: boolean
%
% The following illustration options are available.
%
% 'fontsize': Font size used in titles.
% number Assigns number to field gopt.fontsize.
%
% 'title': Length of titles.
% 'long': Long titles.
% Sets gopt.show_title to true.
% Sets gopt.long_title to true.
% 'short': Short titles.
% Sets gopt.show_title to true.