Optimization

class symmys.optimization.PointRotations(num_rotations, quaternion_dim=8, include_inversions=True, loss=<function mean_exp_rsq>)

Finds rotations that leave a point cloud unchanged up to a permutation.

This method optimizes a set of unit quaternions to match the distribution of transformed points to the set of unrotated points. Quaternions are then clustered by their axis of rotation and merged into N-fold rotation symmetries.

Parameters:

• num_rotations – Number of plain rotations (and rotoinversions, if enabled) to consider
• quaternion_dim – Optimizer dimension for quaternions (higher may make optimization easier at the cost of more expensive optimization steps)
• include_inversions – If True, include rotoinversions as well as rotations
• loss – Loss function to use; see symmys.losses

build_model()

Create the tensorflow model.

This method can be replaced by child classes to experiment with different network architectures. The returned result should be a dictionary containing at least:

• model: a tensorflow.keras.models.Model instance that replicates a given set of input points
• rotation_layer: a layer with a quaternions attribute to be read
• rotoinversion_layer (if inversions are enabled): a layer with a quaternions attribute to be read

fit(points, epochs=1024, early_stopping_steps=16, validation_split=0.3, hash_sample_N=128, reference_fraction=0.1, optimizer='adam', batch_size=256, valid_symmetries=12, extra_callbacks=[])

Fit rotation quaternions and analyze the collective symmetries of a set of input points.

This method builds a rotation model, fits it to the given data, and groups the found quaternions by their axis and rotation angle.

After fitting, a map of symmetries will be returned: a dictionary of {N-fold: [axes]} containing all the axes about which each observed symmetry were found.

Parameters:

• points – Input points to analyze:: (N, 3) numpy array-like sequence
• epochs – Maximum number of epochs to train
• early_stopping_steps – Patience (in epochs) for early stopping criterion; training halts when the validation set loss does not improve for this many epochs
• validation_split – Fraction of training data to use for calculating validation loss
• hash_sample_N – Minimum number of points to use as reference data for the loss function (see hash_sample())
• reference_fraction – Fraction of given input data to be hashed to form the reference data
• optimizer – Tensorflow/keras optimizer name or instance
• batch_size – Batch size for optimization
• valid_symmetries – Maximum degree of symmetry (N) that will be considered when identifying N-fold rotations
• extra_callbacks – Additional tensorflow callbacks to use during optimization

model

Return the tensorflow model that will perform rotations.

rotation_layer

Return the tensorflow.keras layer for rotations.

rotoinversion_layer

Return the tensorflow.keras layer for rotoinversions.