pycvxset.common.spread_points_on_a_unit_sphere

pycvxset.common.spread_points_on_a_unit_sphere(dim: int, n_points: int | None = None, cvxpy_socp_args: dict[str, Any] | None = None, verbose: bool = False, enable_warning: bool = True, save_points_on_a_unit_sphere: bool = True) → tuple[ndarray, float, ndarray][source]

Spread points on a unit sphere in n-dimensional space.

Parameters:

  • dim (int) – The dimension of the sphere.

  • n_points (int) – The number of points to be spread on the unit sphere. Defaults to None, in which case, we choose

  • = (n_points)

  • cvxpy_socp_args (dict) – Additional arguments to be passed to the CVXPY solver. Defaults to None, in which case the function uses DEFAULT_CVXPY_ARGS_SOCP from pycvxset.common.constants.

  • verbose (bool, optional) – Whether to print verbose output. Defaults to False.

  • enable_warning (bool, optional) – Enables the UserWarning. May be turned off if expected. Defaults to True.

  • save_points_on_a_unit_sphere (bool, optional) – Whether to save the computed points and minimum separation to a file. Defaults to SPOAUS_SAVE_POINTS_ON_A_UNIT_SPHERE.

Returns:

A tuple containing three items:

# opt_locations (ndarray): The spread points on the unit sphere. # minimum_separation (float): The minimum separation between the points. # opt_locations_first_quad (ndarray): The spread points in the first quadrant.

Return type:

tuple

Raises:

  • ValueError – If n_points is less than 2 * dim.

  • UserWarning – If n_points - 2 * dim is not a multiple of 2^dim.

  • NotImplementedError – Unable to solve the convexified problem using CVXPY

  • NotImplementedError – Convex-concave procedure did not converge!

Notes

This function uses the CVXPY library to solve a convex optimization problem to spread the points on the unit sphere. The spread points are returned as opt_locations, the separation between the points is returned as separation, and the spread points in the first quadrant are returned as opt_locations_first_quad.

For dim in [1, 2], the points are available in closed-form. For dim >= 3, we solve the following non-convex optimization problem using convex-concave procedure:

\[\begin{split}\begin{array}{rlrl} \text{maximize} &\quad R \\ \text{subject to} &\quad R \geq 0\\ &\quad x \geq R/2\\ &\quad \|x_i - x_j\| \geq R, && 1 \leq i < j \leq n_\text{points}\\ &\quad \|x_i - e_j\| \geq R, && 1 \leq i \leq n_\text{points}, 1 \leq j \leq n_\text{dim}\\ &\quad \|x_i \| \leq 1, && 1 \leq i \leq n_\text{points}\\ &\quad \|x_i \| \geq 0.8, && 1 \leq i \leq n_\text{points}\\ \end{array}\end{split}\]

The optimization problem seeks to spread points (apart from the standard axes) in the first quadrant so that their pairwise separation is maximized, while they have a norm close to 1. The second constraint is motivated to ensure that the reflections of the points about the quadrant plane is also separated by R.

When save_points_on_a_unit_sphere is True, the function saves the computed points (all), the computed points in the first quadrant, and the minimum separation to a file named tmp/spoaus_dim_{dim}_n_points_{n_points_int}.npz. If the file already exists, the function loads the points and minimum separation from the file instead of recomputing them. This can save time when calling spread_points_on_a_unit_sphere with default values.