the sample of n nodes that reproduces a density best up to the bandwidth, on the sphere or the rotation group; MATLAB’s optimal discrete sampling points

Syntax

v = optimalSample(sF, 1000)

Equally weighted directions.

v = optimalSample(sF, v0)

Moved from the starting nodes v0.

v = optimalSample(sF, 1000, bandwidth=128)

Exact up to degree 128.

v = optimalSample(sF, n, method='steepestDescent')

Gradient descent instead of L-BFGS.

v = optimalSample(sF, n, maxIter=1000, tol=0.005*degree)

More iterations, a finer stop.

v, c = optimalSample(sF, n, optimizeWeights=True)

The weights optimised too.

v, c = optimalSample(sF, n, optimizeWeights=True, minWeight=1e-4)

Nodes of smaller weight dropped.

ori = optimalSample(odf, 500)

Orientations of an ODF.

res = optimalSample(odf, 500, diagnostics=True)

With the discrepancy and the stop reason.

Description

The nodes are moved until the weighted point measure they form has the same harmonic coefficients as the density, up to the bandwidth, as nearly as possible. The density need not be normalised. The result fits the density far better than discreteSample, at the price of time.

The minimisation is a limited memory BFGS iteration along the geodesics of the sphere or of the rotation group. memory=0 or method=’steepestDescent’ is plain gradient descent.

With optimizeWeights=True the weights are unknowns too; they stay nonnegative and sum to one, so they are volume fractions that calcDensity(v, weights=c) takes. The first warmUp iterations move the nodes only. MATLAB optimises the weights when a second output is asked for; here the keyword says it.

Input

`f`	S2Fun or SO3Fun, a nonnegative real density
`n`	the number of nodes, or the starting nodes, vector3d or orientation

Keywords

keyword	default	description
`optimizeWeights`	`False`	optimise the weights as well and return the nodes and the weights
`bandwidth`	`None`	the largest harmonic degree reproduced; by default the preference defaultS2Bandwidth on the sphere, 32 on SO(3)
`maxIter`	`None`	the largest number of iterations; by default 1000 on the sphere, 100 on SO(3)
`tol`	`None`	stop when no node moves further, in radians; by default 0.01 degree on the sphere, 0.1 degree on SO(3)
`weights`	`None`	the starting weights, fixed unless optimised; by default equal
`memory`	`5`	the number of steps L-BFGS keeps; 0 is steepest descent
`method`	`'lbfgs'`	‘lbfgs’ or ‘steepestDescent’, the latter an empty memory
`warmUp`	`None`	the iterations that move the nodes only, when the weights are optimised; by default a fifth of maxIter
`tolWeights`	`None`	stop when no weight changes more; by default 1e-3 / n
`tolJ`	`0.0001`	stop below this relative decrease of the discrepancy, when the weights are optimised
`innerIter`	`5`	the multiplicative weight steps per iteration on SO(3)
`minWeight`	`0.0`	drop the nodes of a smaller weight at the end, when the weights are optimised
`diagnostics`	`False`	return an OptimalSampleResult instead of the nodes

Output

`v`	vector3d, or orientation for a function on SO(3), the nodes
`c`	ndarray, the weights, nonnegative and summing to one (with optimizeWeights)
`res`	OptimalSampleResult (with diagnostics): nodes, weights, discrepancy, history, iterations, converged, reason, bandwidth

References

M. Graef, D. Potts, G. Steidl, Quadrature errors, discrepancies, and their relations to halftoning on the torus and the sphere, SIAM J. Sci. Comput. 34 (2012) A2760-A2791
M. Knezevic, N. W. Landry, Procedures for reducing large datasets of crystal orientations using generalized spherical harmonics, Mech. Mater. 88 (2015) 73-86

Used on

RandomSampling, S2FunSampling

MATLAB’s S2Fun.optimalSample

source

Citing this page. This page is part of the documentation of MTEX, a free and open source MATLAB toolbox for analyzing and modeling crystallographic textures. It was written by The MTEX Developers and is published at https://mtex-toolbox.github.io/S2Fun.optimalSample_py.html. If you use MTEX, or reuse text or figures from this page, in your research, please cite

F. Bachmann, R. Hielscher, H. Schaeben: Texture Analysis with MTEX - Free and Open Source Software Toolbox, Solid State Phenomena 160 (2010), 63-68. 10.4028/www.scientific.net/SSP.160.63

BibTeX

@article{bachmann2010mtex,
  author  = {F. Bachmann and R. Hielscher and H. Schaeben},
  title   = {Texture Analysis with MTEX - Free and Open Source Software Toolbox},
  journal = {Solid State Phenomena},
  volume  = {160},
  pages   = {63-68},
  year    = {2010},
  doi     = {10.4028/www.scientific.net/SSP.160.63},
  url     = {https://doi.org/10.4028/www.scientific.net/SSP.160.63}
}

Other papers describing specific MTEX methods are listed under Publications — please cite the one that best fits your application. The MTEX source code is licensed under the GNU General Public License v2.0; the text and figures of this documentation are licensed under CC BY 4.0, which permits reuse — including by automated systems — provided The MTEX Developers and this page are credited.

S2Fun.optimalSample