OptiCloud: Generate Optimal Point Clouds with Minimal Energy

Version 1.0.10 (10.5 KB) by Moreno, M.
OptiCloud generates a uniform N-point cloud with minimal potential energy within a unit P-dimensional hyperrectangle (L) or hypersphere (D).
11 Downloads
Updated 8 Oct 2024

View License

Description
OptiCloud is a function designed to generate a point cloud with minimal potential energy within a hyperrectangle or a hypersphere. The generated point cloud is normalized to range between 0 and 1 in all dimensions, providing a 'uniform' distribution of points. This function is particularly useful for simulations, numerical methods, and visualization tasks that require uniformly distributed points in multi-dimensional spaces.
Syntax
OptiCloud
OptiCloud(nPts, dimOrd)
OptiCloud(nPts, dimOrd, 'Par_1', Val_1, ...)
OptiCloud(nPts, dimOrd, 'Par_1', Val_1, ..., 'Flag_1', ...)
[X, E, S, ...] = OptiCloud( ...)
Inputs
  • nPts: Number of points (scalar) or an initial sample to optimize (matrix of size [nPts x dimOrd]).
  • dimOrd: Dimensionality (positive integer). Not needed if nPts is a matrix.
Optional Parameter-Value Pairs:
  • 'NumRun': Number of re-runs to seek minimum potential (positive integer). Default is 1. Also: 'Cycles', 'Try'.
  • 'MaxIter': Maximum number of iterations (positive integer). Default depends on nPts. Also: 'Iterations', 'Iter'.
  • 'PotEne': Potential energy or distance constant (positive scalar). Default depends on nPts. Also: 'Potential', 'Pot', 'Energy'.
  • 'MinTol': Convergence tolerance (positive scalar). Default is 1e-16. Also: 'Tolerance', 'Tol'.
  • 'Penalty': Iteration penalty for point overlap (positive integer). Default is 10.
Optional Flags:
  • 'cartesian': Use a cartesian sampling method. Default is false. Opposites are 'radial' or 'spherical'.
  • 'best' or 'elite': Initializes each run with the best sample found so far. Default is false.
  • 'single': Use single-precision computations. Default depends on nPts. Opposite is 'double'.
  • 'verbose': Display progress messages. Default is false.
  • 'maximin' or 'distance': Use distance-based solver for the calculations. Deault is false.
  • '2d': Use flat markers in 3D plots rather than shaded spheres. Default is false.
Outputs
  1. X: Coordinates of the optimized point cloud (array of size [nPts x dimOrd]).
  2. E: Final potential energy.
  3. S: Structure containing all parameters and flags used.
  4. Additional outputs: Empty, but a figure is generated if nargout > 3 or nargout == 0.
Usage Notes
  • Visualization: When no output is specified, the function generates a figure and assigns the result to ans in the workspace.
  • Optimization: Optimal energy configurations are achieved by increasing 'NumRun' and fine-tuning 'PotEne' (decrease) and 'MaxIter' (increase). Using an initialized solution in nPts can also be beneficial. Using 'maximin' can produce higher-quality solutions, although slower.
  • Defaults: The default values of 'MaxIter' and 'PotEne' have been computed to produce within a low iteration count decent-quality results when nPts < 1e3 and dimOrd < 6. Operating outside that range may require manual inputs to produce optimal results.
Examples
% Example 1: Default usage ('shuffled' inputs)
OptiCloud
% Example 2: Radial normalization with 500 points in 2D
[X, E, S, ~] = OptiCloud(500, 2);
% Example 3: Cartesian normalization with 100 points in 2D
OptiCloud(100, 2, 'cart');
% Example 4: Initialized case with custom parameters
OptiCloud(rand(100, 3), 'c', 'MaxIter', 1e3, 'NumRun', 2, ...
'PotEne', 1e-3, 'MinTol', 1e-10, 'Penalty', 10, 'verbose');
% Example 5: Handle bad inputs (generates warnings)
OptiCloud(10, 1, 'criterion', 'MaxIter', -1, 'NumRun', -2, ...
'PotEne', -1, 'MinTol', 3, 'Penalty', -1, [], 'Par_1', ...
'Val_1', 'Extra');
% Example 6: Highly optimized case with ENERGIES and short flags
[X, E, S, ~] = OptiCloud(OptiCloud(100, 3, 'try', 1e3, 'v'), ...
'try', 10, 'iter', 1e3, 'pot', 1e-4, 'v', '2d', 'best');
% Example 7: Sample case with DISTANCES and short flags
[X, E, S, ~] = OptiCloud(100, 5, 'c', 'dist', 'best', 'try', ...
10, 'v');
Visualization:
The function automatically plots the final point cloud:
  • 1D and 2D: Uses scatter plots.
  • 3D: Uses shaded spheres or scatter plots based on the '2d' flag.
  • Higher Dimensions: Displays a histogram of point values.
Notes:
  • Performance Tips: For large nPts, consider using the 'single' flag to reduce memory usage and computation time. The algorithm 'maximin' can handle larger sample sizes, but it is notably slower. It sometimes produces higher quality results for 'cartesian' cases.
  • Customization: Adjusting parameters like 'PotEne' and 'MaxIter' can significantly affect the optimization results. Experiment with different values for optimal performance, as the function has been set up for rapid and generic inputs.
  • Error Handling: The function includes warnings and error messages to guide users in providing valid inputs. The use of the 'verbose' flag is encouraged for debugging.
Dependencies:
  • MATLAB Version: Developed and tested on MATLAB R2016b and later.
  • Toolboxes: No additional toolboxes required.
See also:
rand | lhsdesign
Author:
Miguel Moreno
September 2024

Cite As

Moreno, M. (2024). OptiCloud: Generate Optimal Point Clouds with Minimal Energy (https://www.mathworks.com/matlabcentral/fileexchange/173255-opticloud-generate-optimal-point-clouds-with-minimal-energy), MATLAB Central File Exchange. Retrieved .

MATLAB Release Compatibility
Created with R2024a
Compatible with any release
Platform Compatibility
Windows macOS Linux

Community Treasure Hunt

Find the treasures in MATLAB Central and discover how the community can help you!

Start Hunting!
Version Published Release Notes
1.0.10

- Moved method inside VARARGIN

1.0.9

- Removed all dependencies to 'statistics toolbox'
- Moved parts of the code to 'helper functions'
- 'S' is correctly updated before returning outputs
- N-Ball volume and PotEne corrected for MAXIMIN cases

1.0.8

- Removed dependency from Statistics Toolbox.
- Accelerated MAXIMIN calculation for nPts<500 cases.
- Streamlined trivial cases with nPts = 0 or 1.

1.0.7

Small corrections for clarity, robustness, and speed.
Increased accuracy of MAXIMIN algorithm (slower).
Default OptiCloud( ) call activates 'verbose' mode.

1.0.6

- PotEne is always a positive scalar
- MaxIter has a default ('radial') value of 10
- PotEne's default is a function of nPts and dimOrd
- Small correction in new sample generation in MAXIMIN
- Alternative input strings ('iter', 'tol', etc).

1.0.5

- Better handling of failed cases
- Handling of floating point exceptions
- Changed some errors into warnings

1.0.4

- Improved overall function robustness and clarity
- Removed all manual flags and included them in VARARGIN
- Allowed vector and negative PotEne for customly-charged particles
- Added solver settings as output

1.0.3

Small correction:
- When nPts contains an initial sample, bestEnergy is initialized correctly.
- When nPts contains an initial sample and dimOrd is empty, the sample is only used to initialize the first run. Otherwise, it is recycled during all runs.

1.0.2

Minor adjustments:
- Clearer function description
- Better handling of 'nPts = 1' and 'nargout = 0'
- 'potEne' subtly reduced
- Faster 'cart' cases (dimensional factor)
- Enhanced 3D figure limits
- Demo script

1.0.1

Minor changes for better user experinece:
- Added a 'verbose' flag (isVerb) to display progress messages
- Enabled the solution to be initialized from an existing sample
- Divided all energies by two to remove duplicate contributions

1.0.0