OptiCloud: Generate Optimal Point Clouds with Minimal Energy

OptiCloud generates a uniform N-point cloud with minimal potential energy within a unit P-dimensional hyperrectangle (L) or hypersphere (D).

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. It can also reproduce several design spaces, such as central-composite, box-behnken, and optimal-space filling (both maximum distance and minimum entropy).

MiniCloud is the reduced version of OptiCloud, best-suited for smaller samples with previous knowledge of the input parameters. It is faster but lacks robustness: it is recommended for more experienced users.

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(...)

[X, E] = MiniCloud(nPts, dimOrd, potEne, [numRun, maxIter])

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 in 'cartesian' cases, although slower. The maximum minimum-distance solution is returned in the third output argument S.
• 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');

% Example 8: 'Smaller' MiniCloud function
[X, E] = MiniCloud(100, 2, 7e-3, [2, 20]);

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.
• MiniCloud: Faster and more compact version of OptiCloud for more experienced users. It is limited to spherical sampling and an energy-based solver, in single precision.

Dependencies:

• MATLAB Version: Developed and tested on MATLAB R2016b and later.
• Toolboxes: No additional toolboxes strictly required.

See also:

rand | lhsdesign

Author:

Miguel Moreno

September 2024