Commit 65e0b6c7 authored by Marco Berzborn's avatar Marco Berzborn

Added some new spherical sampling methods

parent a8e2e67e
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
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.
CHANGELOG
For licensing, see COPYING
For references, see AUTHORS
Changes between Revision 1.02 and Release 1.10 as at 2005-06-26
===============================================================
1) Renamed directories
New name Old name
----------------------------------
eq_illustrations illustrations
eq_partitions partitions
eq_point_set_props point_set_props
eq_region_props region_props
eq_test test
eq_utilities utilities
2) Renamed functions
New name Old name
----------------------------------
eq_utilities:
euc2sph_dist e2s
sph2euc_dist s2e
polar2cart s2x
cart2polar2 x2s2
Other files affected by this change are:
./Contents.m
eq_illustrations:
project_s2_partition.m project_s3_partition.m show_s2_partition.m
eq_partitions:
eq_point_set.m eq_point_set_polar.m
eq_point_set_props:
calc_packing_density.m
eq_region_props/private:
max_diam_bound_of_regions.m max_vertex_diam_of_regions.m
eq_utilities:
Contents.m
3) Moved functions
eq_illustrations/private to to eq_utilities
fatcurve.m haslight.m
Related changes:
eq_utilities/fatcurve.m:
o Flesh out description and examples
Other files affected by this change are:
./Contents.m
eq_utilities:
Contents.m
4) Renamed documentation files
New name Old name
----------------------------------
./
AUTHORS AUTHORS.txt
CHANGELOG CHANGELOG.txt
COPYING COPYING.txt
INSTALL INSTALL.txt
These files amd all M files have been updated to reflect this change.
5) Changed documentation file format
./README.txt
./INSTALL.txt
These files now have lines terminated by CR-LF to suit DOS and Windows Notepad.
6) Distinguish between info and error messages during
installation and uninstallation
./:
install_eq_toolbox.m uninstall_eq_toolbox.m
private
install.m uninstall.m
7) Drop old x2s2 code by Jakob Bjerkemo.
eq_utilities/cart2polar2.m:
Use cart2sph
./AUTHORS:
Drop reference to x2s2,
2001-03-27 by Jakob Bjerkemo for School of Mathematics, UNSW.
since this code is no longer used.
8) Optimizations
eq_partitions/eq_point_set_polar.m
Optimize running time:
o use slice assignments
o trade space for time by using a cache
9) Fixes for installation bugs
./install_eq_toolbox.m:
o Restructure tests for existing pathdef.m file and guesses for pathdef_dir
o Simplify tests after mkdir
o On Windows, do not use [getenv('USERPROFILE') '\matlab'] directory
private/savepathonly.m
o Initialize cell array removed{} as size 0 rather than size 1
o On Windows, do not remove [getenv('USERPROFILE') '\matlab'] directory
./INSTALL
Updated to reflect these fixes.
10) Other bug fixes
eq_partitions/eq_regions.m:
Fix bug in assignment of dim_1_rot
eq_point_set_props/point_set_energy_dist.m
Fix nasty but obvious bug by using separate variables dist and min_dist
11) Packaging uses *.zip rather than *.tar.gz
./INSTALL updated to reflect this.
12) New references
./AUTHORS:
Add reference to [Leo05].
13) Files in private modified and relicenced with permission
./AUTHORS updated to reflect this.
14) New Release number 1.10
Update release number in all Contents.m files, as well as
AUTHORS CHANGELOG COPYING INSTALL.txt README.txt
Changes between Revision 1.01 and Revision 1.02 as at 2005-04-24
================================================================
1) Optimizations
eq_partitions/eq_regions.m:
Optimize running time:
o move 'if nargout' blocks, refactor slice assignments
o trade space for time by using a cache
eq_utilities/area_of_cap.m:
o Use incomplete Beta function BETAINC for dim == 3,
(when s_cap < pi/6 or s_cap > pi*5/6) and for all dim > 3.
o Use sin(s_cap).^2 in preference to (1-cos(s_cap))/2.
eq_utilities/sradius_of_cap.m:
o Use asin rather than acos to avoid subtraction.
o Use symmetry to avoid loss of accuracy in the Southern hemisphere.
o Remove check for when area is close to area of sphere.
Changes between Release 1.00 and Revision 1.01 as at 2005-03-16
===============================================================
1) Optimizations
eq_utilities/area_of_cap.m:
Use incomplete Beta function BETAINC for dim > 8.
Changes between first release of 2004-11-20 and Release 1.00 as at 2005-02-13
=============================================================================
The main semantic change is listed at 10.5) below, and elaborated here.
Circle offset is now the default for EQ_POINT_SET_POLAR and EQ_REGIONS,
because the original default placement of regions was arbitrary and haphazard.
The main effect of this change is that the default result of partitions for
dim > 1 has changed. This includes the default result for EQ_POINT_SET and all
functions which call it. As a consequence, the energy of the default RZ point
set for dim > 1 is likely to be different from the energy obtained from
earlier versions of the software, including the version of 2004-11-20.
List of changes.
---------------
1) Extensive help comments and updated copyright notices throughout.
This includes Contents.m in each user-visible directory.
2) Complete restructure from a single directory to the following structure:
.:
AUTHORS.txt CHANGELOG.txt Contents.m COPYING.txt
illustrations/ info.ins install_eq_toolbox.m INSTALL.txt
partitions/ point_set_props/ private/ README.txt
region_props/ test/ uninstall_eq_toolbox.m utilities/
illustrations:
Contents.m illustration_options.m private/
project_point_set.m project_s2_partition.m project_s3_partition.m
show_s2_partition.m show_r3_point_set.m
illustrations/private:
fatcurve.m haslight.m show_s2_sphere.m surf_jet.m x2eqarea.m x2stereo.m
partitions:
Contents.m illustrate_eq_algorithm.m partition_options.m private/
eq_caps.m eq_point_set.m eq_point_set_polar.m eq_regions.m
partitions/private:
bot_cap_region.m cap_colats.m centres_of_regions.m circle_offset.m
ideal_region_list.m num_collars.m polar_colat.m rot3.m
round_to_naturals.m s2_offset.m sphere_region.m top_cap_region.m
point_set_props:
calc_dist_coeff.m calc_energy_coeff.m calc_packing_density.m
Contents.m point_set_dist_coeff.m point_set_energy_coeff.m
point_set_energy_dist.m point_set_min_dist.m point_set_packing_density.m
eq_dist_coeff.m eq_energy_coeff.m eq_energy_dist.m
eq_min_dist.m eq_packing_density.m eq_point_set_property.m
private:
install.m savepathonly.m uninstall.m
region_props:
Contents.m private/ eq_diam_bound.m
eq_diam_coeff.m eq_regions_property.m eq_vertex_diam_coeff.m
eq_vertex_diam.m
region_props/private:
expand_region_for_diam.m max_diam_bound_of_regions.m
max_vertex_diam_of_regions.m pseudo_region_for_diam.m
test:
Contents.m eq_area_error.m
utilities:
area_of_cap.m area_of_collar.m area_of_ideal_region.m
area_of_sphere.m Contents.m e2s.m
euclidean_dist.m ideal_collar_angle.m s2e.m
s2x.m spherical_dist.m sradius_of_cap.m
volume_of_ball.m x2s2.m
3) Wholesale renaming of functions
Functions were renamed to make the names more consistent, more inutitive,
more distinctive, and sometimes shorter.
The change log before 2004-11-20 refers to functions by their old names.
New name Old name
----------------------------------
illustrations:
project_s2_partition.m illustrate_s2_partition.m
project_s3_partition.m illustrate_s3_partition.m
show_s2_partition.m plot3_s2_partition.m
partitions:
eq_caps.m part_to_caps.m
eq_point_set.m partsphere.m
eq_point_set_polar.m part_to_points.m
eq_regions.m part_to_regions.m
partitions/private:
rot3.m rot.m
point_set_props:
point_set_energy_dist.m sphere_energy_dist.m
point_set_min_dist.m sphere_min_dist.m
region_props:
eq_diam_bound.m max_diam_bound.m
eq_diam_coeff.m vertex_diam_bound_coeff.m
eq_vertex_diam_coeff.m vertex_diam_coeff.m
eq_vertex_diam.m max_vertex_diam.m
test:
eq_area_error.m area_error.m
4) New functions, replaced functions, deleted functions
The following functions are new. Many of these are mentioned in the changes
listed below.
install_eq_toolbox.m
o Install using Toolbox Installer, with sensible defaults
uninstall_eq_toolbox.m
o Uninstall using Toolbox Installer.
illustrations/illustration_options.m
o Options for illustrations of RZ partitions
illustrations/project_point_set.m
o Use projection to illustrate a point set of S^2 or S^3
illustrations/show_r3_point_set.m
o 3D illustration of a point set
illustrations/private/haslight.m
o Check if axis handle has a light attached
illustrations/private/show_s2_sphere.m
o Illustrate the unit sphere S^2
illustrations/private/surf_jet.m
o Set up extreme color values using COLORMAP JET
partitions/partition_options.m
o Options for RZ partition
partitions/private/s2_offset.m
o Experimental offset rotation of S^2
point_set_props/calc_dist_coeff.m
o Coefficient of minimum distance
point_set_props/calc_packing_density.m
o Density of packing given by minimum distance
point_set_props/point_set_dist_coeff.m
o Coefficient of minimum distance of a point set
point_set_props/point_set_energy_coeff.m
o Coefficient in expansion of energy of a point set
point_set_props/point_set_energy_dist.m
o r^(-s) energy and minimum distance of a point set
point_set_props/point_set_min_dist.m
o Minimum distance between points of a point set
point_set_props/point_set_packing_density.m
o Density of packing given by min dist of a point set
point_set_props/eq_dist_coeff.m
o Coefficient of minimum distance of an RZ point set
point_set_props/eq_energy_coeff.m
o Coefficient in expansion of energy of an RZ point set
point_set_props/eq_min_dist.m
o Minimum distance between points of an RZ point set
point_set_props/eq_packing_density.m
o Density of packing given by minimum distance of RZ point set
point_set_props/eq_point_set_property.m
o Property of an RZ point set
private/install.m
o Install toolbox directories
private/savepathonly.m
o Save the current MATLAB path to the file pathdef.m
private/uninstall.m
o Uninstall toolbox directories
region_props/eq_regions_property.m
o Property of regions of an RZ partition
region_props/eq_vertex_diam_coeff.m
o Coefficient of maximum vertex diameter of RZ partition
The following functions have been replaced:
list_energy_dist.m and list_energy_dist_squares.m,
o Replaced by point_set_props/eq_energy_dist.m
list_min_dist_powers.m and list_min_dist_squares.m,
o Replaced by point_set_props/eq_min_dist.m
doc.m, help.m, readme.m
o Replaced by AUTHORS.txt, CHANGELOG.txt, README.txt and Contents.m
stereoplot3.m
o Replaced by illustrations/project_point_set.m
The following functions have been deleted:
calc_dist_ratio.m
o Out of scope.
dist_matrix.m, sphere_dist_matrix.m
o Out of scope.
minus_dist.m, minus_dist_sq.m
o No longer needed.
Were used in constrained nonlinear optimization to estimate diameter.
r2s.m, s2r.m
o Duplicates of e2s.m and s2e.m.
region_is_cap.m, region_is_sphere.m
o No longer needed.
Were used to estimate diameter.
run_diam_bound_coeff_from.m, run_vertex_diam_bound_coeff_from.m
run_vertex_diam_bound_coeff.m, run_vertex_diam_coeff.m
o Out of scope.
Were used for batch jobs run from Linux shell scripts.
5) Use of subfunctions.
The following M files now contain the subfunctions as listed.
As a consequence, the subfunctions no longer exist as separate M files.
illustrations/illustration_options.m:
DUPLICATE_ERROR, OPTION_ERROR, VALUE_ERROR
illustrations/project_s2_partition.m:
PROJECT_S2_REGION, PROJECT_S2_EQ_POINT_SET
illustrations/project_s3_partition.m:
PROJECT_S3_REGION, PROJECT_S3_EQ_POINT_SET
illustrations/show_s2_partition.m:
SHOW_S2_REGION
partitions/illustrate_eq_algorithm.m:
OPTION_ARGUMENTS, ILLUSTRATE_STEPS_1_2,
ILLUSTRATE_STEPS_3_5, ILLUSTRATE_STEPS_6_7
partitions/partition_options.m:
DUPLICATE_ERROR, OPTION_ERROR, VALUE_ERROR
point_set_props/calc_energy_coeff.m:
SPHERE_INT_ENERGY
point_set_props/point_set_energy_dist.m:
POTENTIAL
region_props/private/expand_region_for_diam.m:
APPEND
region_props/private/max_diam_bound_of_regions.m:
DIAM_BOUND_REGION
region_props/private/max_vertex_diam_of_regions.m:
VERTEX_DIAM_REGION
test/eq_area_error.m:
AREA_OF_REGION
utilities/area_of_cap.m:
AREA_INTEGRAND_OF_CAP
6) Installation functions install_eq_toolbox.m, uninstall_eq_toolbox.m,
which use the modified Toolbox Installer functions private/install.m and
private/uninstall.m.
Changes to private/install.m:
o Do not warn on IS_INSTALLED; do not save info.ins
o Use savepath rather than path2rc with Matlab 7 or greater
Changes to private/uninstall.m
o Use rmpath only when directory name is in path.
o Do not warn on IS_INSTALLED; do not save info.ins
o Use savepath rather than path2rc with Matlab 7 or greater
o Use pathsep rather than ':', use lower case if not case sensitive
7) Partition options and illustration options functions.
These make the user interface more consistent and easier to use.
Partition options are implemented by partitions/partition_options.m and used by
illustrations/project_s2_partition.m
illustrations/project_s3_partition.m
illustrations/show_s2_partition.m
partitions/illustrate_eq_algorithm.m
partitions/eq_point_set.m
partitions/eq_point_set_polar.m
partitions/eq_regions.m
point_set_props/eq_energy_dist.m
point_set_props/eq_point_set_property.m
Illustration options are implemented by illustrations/illustration_options.m and
used by
illustrations/project_point_set.m
illustrations/project_s2_partition.m
illustrations/project_s3_partition.m
illustrations/show_s2_partition.m
illustrations/show_r3_point_set.m
partitions/illustrate_eq_algorithm.m
8) Consistent acceptance of argument N as an arbitrary array.
This also makes the user interface more consistent and easier to use.
The following functions contain loops where N is flattened into a row matrix and
the result is reshaped to the original array size of N.
point_set_props/calc_energy_coeff.m
point_set_props/eq_energy_dist.m
point_set_props/eq_point_set_property.m
region_props/eq_diam_coeff.m
region_props/eq_regions_property.m
test/eq_area_error.m
The following function uses the function EQ_POINT_SET_PROPERTY:
point_set_props/eq_min_dist.m
The following functions use the function EQ_REGIONS_PROPERTY:
region_props/eq_diam_bound.m
region_props/eq_vertex_diam.m
As a consequence of these changes, the following functions have been replaced:
list_energy_dist.m and list_energy_dist_squares.m,
replaced by point_set_props/eq_energy_dist.m
list_min_dist_powers.m and list_min_dist_squares.m,
replaced by point_set_props/eq_min_dist.m
Also, region_props/eq_vertex_diam_coeff.m has been simplified.
The following functions also use flatten and reshape, but for an argument other
than N:
utilities/area_of_cap.m for argument S_CAP
utilities/sradius_of_cap.m for argument AREA
9) Checks for number of arguments.
The following functions now use NARGCHK:
partitions/eq_caps.m
partitions/eq_point_set.m
partitions/eq_point_set_polar.m
partitions/eq_regions.m
point_set_props/calc_dist_coeff.m
point_set_props/calc_packing_density.m
point_set_props/point_set_dist_coeff.m
point_set_props/point_set_energy_coeff.m
point_set_props/point_set_packing_density.m
point_set_props/eq_dist_coeff.m
point_set_props/eq_energy_coeff.m
point_set_props/eq_energy_dist.m
point_set_props/eq_min_dist.m
point_set_props/eq_packing_density.m
point_set_props/eq_point_set_property.m
region_props/eq_diam_coeff.m
test/eq_area_error.m
The following functions now use NARGOUTCHK:
partitions/eq_caps.m
partitions/eq_regions.m
region_props/eq_diam_coeff.m
test/eq_area_error.m
10) Changes which affect one or a few functions.
10.1) illustrations/project_s2_partition.m
Now uses normalized font sizes.
10.2) illustrations/project_s2_partition.m, illustrations/project_s3_partition.m
o Now use illustrations/illustrate_point_set.m
o Removed unnecessary calls to PACK
10.3) illustrations/show_s2_partition.m, illustrations/show_r3_point_set.m,
o Now use new function SURF_JET to set up extreme values for COLARMAP JET.
Also, SURF_JET uses HASLIGHT to determine if a light already exists,