spatula.optimize

Overview

Mesh(points)	Optimize by testing provided rotations.
NoOptimization([orientation])	Evaluate at one fixed orientation with no optimization loop.
Optimizer()	Base class for optimizers.
RandomSearch([max_iter, seed])	Optimize by testing $N$ random rotations.
StepGradientDescent([initial_point, ...])	Optimize by rounds of 3 1D gradient descents.
Union()	Combine an optimization scheme with a specific secondary optimizer.

Details

Classes to optimize over SO(3) for spatula.PGOP.

class spatula.optimize.Mesh(points)

Optimize by testing provided rotations.

__init__(points)

Create a Mesh optimizer.

Parameters:

points ($(N, 4)$ numpy.ndarray of float) – The rotaional quaternions to test.

classmethod from_grid(n_axes=75, n_angles=10)

Create a Mesh optimizer that tests rotations on a uniform grid.

The axes are chosen by the numerical solutions to the Tammes problem and angles by equadistant rotations according to the Haar measure.

Parameters:

• n_axes (int, optional) – The number of axes to rotate about. Defaults to 75.

• n_angles (int, optional) – The number of angles to rotate per axes. Defaults to 10.

Returns:

mesh – The optimizer which will test $N_{axes} \cdot N_{angles}$ points.

Return type:

Mesh

classmethod from_lattice(n_rotations=150)

Create a Mesh optimizer that tests rotations on a Fibonacci lattice.

The lattice provides a mostly-uniform covering of the 3-sphere. Refer to this paper for a derivation. Although the quaternions generated by this method are slightly less uniform than those from ~.from_grid, an arbitrary number of rotations can be generated by this approach.

Parameters:

n_rotations (int, optional) – The number of rotation in the lattice. Defaults to 75.

Returns:

mesh – The optimizer which will test $N_{rotations}$ samples.

Return type:

Mesh

class spatula.optimize.NoOptimization(orientation=(1.0, 0.0, 0.0, 0.0))

Evaluate at one fixed orientation with no optimization loop.

Instead of searching over rotations, this optimizer evaluates the objective exactly once at the provided orientation. For PGOP and BOOSOP this is equivalent to rotating each neighborhood by the same fixed quaternion and then computing the order parameter.

__init__(orientation=(1.0, 0.0, 0.0, 0.0))

Create a NoOptimization object.

Parameters:

orientation (tuple[float, float, float, float], optional) –

The fixed orientation quaternion in [w, x, y, z] convention (note SciPy uses [x, y, z, w]). The quaternion is normalized internally before use.

This sets the single rotation used for evaluation. Example: NoOptimization(orientation=q) on an unrotated neighborhood gives the same result as NoOptimization() on a neighborhood rotated by q.

Defaults to the identity quaternion (1, 0, 0, 0), which means no additional rotation is applied.

property orientation

Normalized fixed quaternion.

Returned in [w, x, y, z] convention.

Type:

tuple[float, float, float, float]

class spatula.optimize.Optimizer

Base class for optimizers.

__weakref__

list of weak references to the object

class spatula.optimize.RandomSearch(max_iter=150, seed=42)

Optimize by testing $N$ random rotations.

__init__(max_iter=150, seed=42)

Create a RandomSearch optimizer.

Parameters:

• max_iter (int, optional) – The number of rotations to try. Defaults to 150.

• seed (int, optional) – The random number seed to use for generating random rotations. Defaults to 42.

class spatula.optimize.StepGradientDescent(initial_point=(1.0, 0.0, 0.0, 0.0), max_iter=150, initial_jump=0.001, learning_rate=0.05, tol=1e-06)

Optimize by rounds of 3 1D gradient descents.

The optimization uses a 3-vector, $\nu$ to represent rotations in $SO(3)$. The conversion to the axis-angle representation for $\nu$ is

$$\alpha = \frac{\nu}{||\nu||} \\ \theta = ||\nu||.$$

The representation is continuous in $SO(3)$. StepGradientDescent performs potentially multiple rounds of 3 1-dimensional gradient descents, one for each dimension to find the local minimum. Each smaller optimization is terminated when the improvement in objective is less than the provided tolerance. The entire optimization ends when between rounds of optimization the decrease in objective is less than the provided tolerance.

__init__(initial_point=(1.0, 0.0, 0.0, 0.0), max_iter=150, initial_jump=0.001, learning_rate=0.05, tol=1e-06)

Create a StepGradientDescent object.

Parameters:

• optimizer (Optimizer) – The initial optimizer. The best/final point of this optimizer will be sent to the StepGradientDescent as the initial point.

• initial_point ($(4,)$ numpy.ndarray of float, optional) – The initial point to start the optimization. Defaults to the identity quaternion.

• max_iter (int, optional) – The maximum number of iterations before stopping optimization. Defaults to 150.

• initial_jump (float, optional) – The size of the initial jump in each dimension to get an initial gradient. Defaults to 0.001.

• learning_rate (float, optional) – The degree to move along the gradient. Higher values lead to larger moves and can result in quicker convergence or failure to converge. Defaults to 0.05.

• tol (float, optional) – The value that when the reduction in the object is less than the current optimization stops. The entire optimization stops when the objective from the last round of 1 dimensional optimizations is below tol. Defaults to 1e-6.

class spatula.optimize.Union

Combine an optimization scheme with a specific secondary optimizer.

The union optimizer uses the best point from the first optimization to start the second optimizer.

classmethod with_step_gradient_descent(optimizer, max_iter=150, initial_jump=0.001, learning_rate=0.055, tol=1e-06)

Create a Union optimizer with a StepGradientDescent second step.

Arguments are passed through to the constructor of StepGradientDescent.

Parameters:

• optimizer (Optimizer) – The initial optimizer. The best/final point of this optimizer will be sent to the StepGradientDescent as the initial point.

• max_iter (int, optional) – The maximum number of iterations before stopping optimization. Defaults to 150.

• initial_jump (float, optional) – The size of the initial jump in each dimension to get an initial gradient. Defaults to 0.001.

• learning_rate (float, optional) – The degree to move along the gradient. Higher values lead to larger moves and can result in quicker convergence or failure to converge. Defaults to 0.05.

• tol (float, optional) – The value that when the reduction in the object is less than the current optimization stops. The entire optimization stops when the objective from the last round of 1 dimensional optimizations is below tol. Defaults to 1e-6.