Molassembler  3.0.0
Molecule graph and conformer library
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
Scine::Molassembler::Shapes::Continuous Namespace Reference

Symmetry element, point group, and polyhedral shape continuous metrics. More...

Namespaces

 Fixed
 Continuous symmetry measures for fixed symmetry elements.
 

Data Structures

struct  ShapeResult
 Result of a continuous shape measure calculation. More...
 

Typedefs

using PositionCollection = Eigen::Matrix< double, 3, Eigen::Dynamic >
 

Functions

PositionCollection normalize (const PositionCollection &positions)
 Normalize positions for continuous symmetry measure analysis. More...
 
std::pair< double,
Elements::Rotation
element (const PositionCollection &normalizedPositions, Elements::Rotation rotation)
 Optimizes the axis of a rotational symmetry element and calculates the continuous symmetry measure.
 
std::pair< double,
Elements::Reflection
element (const PositionCollection &normalizedPositions, Elements::Reflection reflection)
 Optimizes the norm of a reflection symmetry element and calculates the continuous symmetry measure.
 
double element (const PositionCollection &normalizedPositions, const Elements::Inversion &)
 Calculates the CSM for centroid inversion. More...
 
double Cinf (const PositionCollection &normalizedPositions)
 Calculates the continuous symmetry measure for an infinite order rotation axis.
 
double pointGroup (const PositionCollection &normalizedPositions, PointGroup pointGroup)
 Calculates the continuous symmetry measure for a set of particles and a particular point group. More...
 
ShapeResult shapeFaithfulPaperImplementation (const PositionCollection &normalizedPositions, Shape shape)
 Faithful implementation of the continuous shape measure calculation algorithm from the paper. More...
 
ShapeResult shapeAlternateImplementation (const PositionCollection &normalizedPositions, Shape shape)
 Slightly optimized implmentation of the continuous shape measure calculation algorithm. More...
 
ShapeResult shapeAlternateImplementationCentroidLast (const PositionCollection &normalizedPositions, Shape shape)
 Like shapeAlternateImplementation, but the centroid is the last position.
 
ShapeResult shapeHeuristics (const PositionCollection &normalizedPositions, Shape shape)
 Calculates the continuous shape measure of a set of coordinates with respect to a particular shape using heuristics. More...
 
ShapeResult shapeHeuristicsCentroidLast (const PositionCollection &normalizedPositions, Shape shape)
 Same as shapeHeuristics(), except with set centroid mapping, so faster.
 
ShapeResult shape (const PositionCollection &normalizedPositions, Shape shape)
 Forwarding function to calculate the continuous shape measure. More...
 
ShapeResult shapeCentroidLast (const PositionCollection &normalizedPositions, Shape shape)
 Same as shape(), except with set centroid mapping.
 
double minimumDistortionAngle (Shape a, Shape b)
 Calculates minimum distortion angle in radians for shapes A and B. More...
 
double minimalDistortionPathDeviation (const PositionCollection &positions, Shape a, Shape b, double minimumDistortionAngle)
 Calculates deviation of positions from minimal distortion path between two shapes. More...
 
double minimalDistortionPathDeviation (const PositionCollection &positions, Shape a, Shape b)
 
std::array< double, 4 > randomCloudDistributionParameters (Shape shape, unsigned N, unsigned seed)
 Beta distribution parameters of shape measures of random point clouds. More...
 
boost::optional< double > probabilityRandomCloud (double measure, Shape shape)
 Probability that shape measure in set of measures for random point clouds. More...
 

Detailed Description

Symmetry element, point group, and polyhedral shape continuous metrics.

Function Documentation

double Scine::Molassembler::Shapes::Continuous::element ( const PositionCollection &  normalizedPositions,
const Elements::Inversion &   
)

Calculates the CSM for centroid inversion.

Note
An inversion element cannot be optimized.
double Scine::Molassembler::Shapes::Continuous::minimalDistortionPathDeviation ( const PositionCollection &  positions,
Shape  a,
Shape  b,
double  minimumDistortionAngle 
)

Calculates deviation of positions from minimal distortion path between two shapes.

Calculates \(\Delta_AB = \frac{1}{\theta_AB}\left[ \arcsin\frac{\sqrt{\textrm{CShM}A_(X)}}{10} + \arcsin\frac{\sqrt{\textrm{CShM}B_(X)}}{10} \right] - 1\) where \(\theta_AB\) is the minimum distortion angle for the shape pair and \(\textrm{CShM}i_(x)\) is the continuous shape measure of the positions \(x\) with regards to the shape \(i\).

This function form avoids two shape calculations if the minimum distortion angle between a and b is known.

Warning
This function calls shape(), where heuristics are used for particular shape sizes.

Complexity Two continuous shape calculations.

double Scine::Molassembler::Shapes::Continuous::minimalDistortionPathDeviation ( const PositionCollection &  positions,
Shape  a,
Shape  b 
)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Complexity Three continuous shape calculations.

double Scine::Molassembler::Shapes::Continuous::minimumDistortionAngle ( Shape  a,
Shape  b 
)

Calculates minimum distortion angle in radians for shapes A and B.

Calculates \(\theta_AB\) in:

\(k_XY = \sqrt{\textrm{CShM}A_(B)} = \sqrt{\textrm{CShM}B_(A)} = 10 \sin(\theta_AB)\)

Warning
This function calls shape(), where heuristics are used for particular shape sizes.

Complexity One continuous shape calculation.

PositionCollection Scine::Molassembler::Shapes::Continuous::normalize ( const PositionCollection &  positions)

Normalize positions for continuous symmetry measure analysis.

Reframes to center of mass frame (although no masses exist) and rescales vectors so that the maximum distance is 1)

double Scine::Molassembler::Shapes::Continuous::pointGroup ( const PositionCollection &  normalizedPositions,
PointGroup  pointGroup 
)

Calculates the continuous symmetry measure for a set of particles and a particular point group.

Parameters
normalizedPositions
pointGroup
Note
This function isn't super stable. The Nelder-Mead over SO(3) works okay, but the initial simplex is a problem and can lead the algorithm into a local minimum. Not very performant either, it would be better with quaternions instead of rotation matrices.
Returns
The continuous symmetry measure
boost::optional<double> Scine::Molassembler::Shapes::Continuous::probabilityRandomCloud ( double  measure,
Shape  shape 
)

Probability that shape measure in set of measures for random point clouds.

The random point clouds are generated by a zero vector representing the centroid, and points of uniformly distributed direction and normally distributed (mu = 1, stddev = 0.2) length.

A beta distribution is fitted against two hundred such continuous shape measures with respect to the chosen shape.

The probability is then the cumulative distribution function value of the passed measure in the fitted beta distribution.

The distribution parameters for N = 200 random point clouds are precomputed for shapes of sizes <= 8 and hardcoded into the binary. If no beta distribution parameters are available for a shape, returns None.

Complexity Constant

std::array<double, 4> Scine::Molassembler::Shapes::Continuous::randomCloudDistributionParameters ( Shape  shape,
unsigned  N,
unsigned  seed 
)

Beta distribution parameters of shape measures of random point clouds.

The random point clouds are generated by a zero vector representing the centroid, and points of uniformly distributed direction and normally distributed (mu = 1, stddev = 0.2) length.

Parameters
shapeShape for which to determine distribution parameters
NNumber of point clouds to generate
seedSeeding of the PRNG used for randomness

Complexity N continuous shape calculations, which are basically factorial in the size of the shape

Returns
an array of parameters, signifying alpha, beta, loc = 0 and scale parameters
ShapeResult Scine::Molassembler::Shapes::Continuous::shape ( const PositionCollection &  normalizedPositions,
Shape  shape 
)

Forwarding function to calculate the continuous shape measure.

Forwards its call to shapeAlternateImplementation() by default. In debug builds, forwards its call to shapeHeuristics() from shape size 6 onwards. In release builds, forwards its call to shapeHeuristics() from shape size 9 onwards.

ShapeResult Scine::Molassembler::Shapes::Continuous::shapeAlternateImplementation ( const PositionCollection &  normalizedPositions,
Shape  shape 
)

Slightly optimized implmentation of the continuous shape measure calculation algorithm.

Paper says:

  • For each index mapping
    • Minimize over rotation
    • Minimize over isotropic scaling factor.

This does:

  • For each index mapping
    • Minimize over rotation
  • For the best index mapping, minimize over isotropic scaling factor

and is hence faster. Gives the same results.

Parameters
normalizedPositions
shape
Returns
ShapeResult Scine::Molassembler::Shapes::Continuous::shapeFaithfulPaperImplementation ( const PositionCollection &  normalizedPositions,
Shape  shape 
)

Faithful implementation of the continuous shape measure calculation algorithm from the paper.

Parameters
normalizedPositions
shapeComplexity \(\Theta(N!)\). Note that \(N\) is the size of the shape plus one since a centroid is involved as well.
Returns
ShapeResult Scine::Molassembler::Shapes::Continuous::shapeHeuristics ( const PositionCollection &  normalizedPositions,
Shape  shape 
)

Calculates the continuous shape measure of a set of coordinates with respect to a particular shape using heuristics.

Since shapeFaithfulPaperImplementation() scales as \(\Theta(N!)\) and we have shapes with 12 vertices plus the centroid, we need heuristics to speed up the shape calculation while not sacrificing too much accuracy.

Heuristic used here: For all tuples of five positions, align the positions, then greedily choose the best next sequence alignments until all positions are matched.

Judgement of accuracy / speed tradeoff is that this is worth using from size 6 onwards in debug builds and from size 9 onwards in release builds.

Parameters
normalizedPositionsset of coordinates to compare with the shape
shapeReference shape to compare against

Complexity Approximately \(\Omega(\frac{N!}{(N-5)!})\) quaternion fits, where \(N\) is the number of positions being matched. Note that \(N\) is typically the size of the shape plus one since a centroid is involved as well. For N > 12, other terms may dominate complexity, but this is yet untested.

Note
Works well for positions deviating little from the ideal shape. For large deviations, exhibits small relative errors. To explore the characteristics of this function, you can try out the shape analysis binary.
Returns
The continuous shape measure determined by heuristics