source: src/Fragmentation/Exporters/SphericalPointDistribution.hpp@ f5fa48

/*
 * SphericalPointDistribution.hpp
 *
 *  Created on: May 29, 2014
 *      Author: heber
 */


#ifndef SPHERICALPOINTDISTRIBUTION_HPP_
#define SPHERICALPOINTDISTRIBUTION_HPP_

// include config.h
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif

#include "CodePatterns/Assert.hpp"

#include <cmath>
#include <list>
#include <map>
#include <set>
#include <vector>

#include "LinearAlgebra/Vector.hpp"

class SphericalPointDistributionTest;

/** contains getters for the VSEPR model for specific number of electrons.
 *
 * This struct contains specialized functions returning a list of Vectors
 * (points in space) to match the VSEPR model for the given number of electrons.
 *
 * This is implemented via template specialization of the function get().
 *
 * These specializations are taken from the python script \b CreateVspeShapes.py
 * by Christian Neuen, 07th May 2009.
 */
struct SphericalPointDistribution
{
  /** Cstor for SphericalPointDistribution, allows setting radius of sphere
   *
   * \param _BondLength desired radius of sphere
   */
  SphericalPointDistribution(const double _Bondlength = 1.) :
    Bondlength(_Bondlength),
    SQRT_3(sqrt(3.0))
  {}

  //!> typedef for the list of points
  typedef std::list<Vector> Polygon_t;
  //!> typedef for the list of points with integral weights
  typedef std::list<std::pair<Vector, int> > WeightedPolygon_t;
  //!> typedef for a sorted list of indices
  typedef std::set<unsigned int> IndexSet_t;
  //!> typedef for the adjacency list of a polygon
  typedef std::map<unsigned int, IndexSet_t > adjacency_t;

  /** General getter function for the distribution of points on the surface.
   *
   * \warn this function needs to be specialized!
   *
   * \return Polygon_t with points on the surface centered at (0,0,0)
   */
  template <int N> Polygon_t get()
  {
    ASSERT(0, "SphericalPointDistribution::get() - not specialized for "+toString(N)+".");
  }

  template <int N> adjacency_t getConnections()
  {
    ASSERT(0, "SphericalPointDistribution::getConnections() - not specialized for "+toString(N)+".");
  }

  /** Returns vacant spots to fill to get a complete spherical point distribution from
   * given points \a _polygon, containing then \a _N in total.
   *
   * The idea is to produce a matching from all points in \a _polygon to those
   * in \a _newpolygon in such a way that their distance difference is minimal.
   * As we just look at numbers of points determined by valency, i.e.
   * independent of the number of atoms, we simply go through each of the possible
   * mappings. We stop when the L1 error is below a certain \a threshold,
   * otherwise we pick the matching with the lowest L2 error.
   *
   * This is a helper to determine points where to best insert saturation
   * hydrogens.
   *
   * \param _polygon already filled places to match
   * \param _N desired total number fo points
   */
  Polygon_t getRemainingPoints(const WeightedPolygon_t &_polygon, const int _N);

  //!> default radius of the spherical distribution
  const double Bondlength;
  //!> precalculated value for root of 3
  const double SQRT_3;
  //!> threshold for L1 error below which matching is immediately acceptable
  static const double L1THRESHOLD;
  //!> threshold for L2 error below which matching is acceptable
  static const double L2THRESHOLD;

  //!> typedef for a full rotation specification consisting of axis and angle.
  typedef std::pair<Vector, double> Rotation_t;

  //!> typedef for a list of indices (of points in a polygon)
  typedef std::list<unsigned int> IndexList_t;
  //!> typedef enumerating possibly multiple points accumulated as one point
  typedef std::list< IndexList_t > IndexTupleList_t;
  //!> typedef for a vector of indices
  typedef std::vector<unsigned int> IndexArray_t;
  //!> typedef for a Vector of positions
  typedef std::vector<Vector> VectorArray_t;
  //!> typedef for a Vector of positions with weights
  typedef std::vector< std::pair<Vector, int> > WeightedVectorArray_t;
  //!> typedef for a vector of degrees (or integral weights)
  typedef std::vector<unsigned int> WeightsArray_t;

  //!> amplitude up to which deviations in checks of rotations are tolerated
  static const double warn_amplitude;

  struct PolygonWithIndices
  {
    //!> array with points
    VectorArray_t polygon;
    //!> list with indices for the above points, defining subset
    IndexList_t indices;
  };

  struct PolygonWithIndexTuples
  {
    //!> array with points
    VectorArray_t polygon;
    //!> list with tuples of indices for the above points, defining subset
    IndexTupleList_t indices;
  };

  /** Returns associated \a _N points equally distributed on a sphere's surface
   * with respect to the given set of points \a _polygon.
   *
   * This function is similar to getRemainingPoints() in that both calculate
   * a matching between the given points \a _polygon and the \a _N equally
   * distributed points. The difference is that getRemainingPoints() returns
   * the unmatched points. This function however is supposed to match (almost)
   * all and return for each of the points a respective set of points where to
   * place saturation hydrogens.
   *
   * This set of points is then used as a "global" reference set over all
   * fragments (\sa FragmentationFragmentationAction::performCall()) such that
   * the common saturation hydrogens for the same atom over all containing
   * fragments remain at exactly the same position, the saturation consistency
   * principle. Only by that do we maintain same eigenvalues and hence minimal
   * disturbance (due to approximate invariance of hydrogen to its chemical
   * neighborhood) when using the fragmention method with closed-shell
   * calculations requiring this saturation of dangling bonds.
   *
   * \param _polygon already filled places to match
   * \param _N desired total number fo points
   * \return a set of positions and a list of tuples of indices such that each
   *        point in \a _polygon is related to one of the tuples and designates
   *        those positions where a number of hydrogens should be placed when
   *        the bond associated with this point is removed, i.e. the bond
   *        becomes a dangling one.
   */
  PolygonWithIndexTuples getAssociatedPoints(
      const WeightedPolygon_t &_polygon,
      const int _N);

  static PolygonWithIndexTuples getIdentityAssociation(
      const WeightedPolygon_t &_polygon);

  static Vector calculateCenterOfMinimumDistance(
      const SphericalPointDistribution::VectorArray_t &_positions,
      const SphericalPointDistribution::IndexList_t &_indices);

private:
  //!> points for the ideal distribution
  Polygon_t points;
  //!> connection information between these ideal points
  adjacency_t adjacency;

  /** Initialize inner status (points and adjacency) to desired number of
   * points.
   *
   * \param _N number of points
   */
  void initSelf(const int _N);

private:
  //!> grant unit tests access to private parts
  friend class SphericalPointDistributionTest;

  static std::pair<double, double> calculateErrorOfMatching(
      const VectorArray_t &_old,
      const VectorArray_t &_new,
      const IndexTupleList_t &_Matching);

  static Polygon_t removeMatchingPoints(
      const PolygonWithIndices &_points);

  struct MatchingControlStructure {
    MatchingControlStructure(
        const adjacency_t &_adjacency,
        const VectorArray_t &_oldpoints,
        const VectorArray_t &_newpoints,
        const WeightsArray_t &_weights
        );
    bool foundflag;
    double bestL2;
    const adjacency_t &adjacency;
    const VectorArray_t oldpoints;
    const VectorArray_t newpoints;
    const WeightsArray_t weights;
    IndexTupleList_t bestmatching;
  };

  static void recurseMatchings(
      MatchingControlStructure &_MCS,
      IndexTupleList_t &_matching,
      IndexList_t _indices,
      WeightsArray_t &_remainingweights,
      WeightsArray_t::iterator _remainiter,
      const unsigned int _matchingsize
      );

  MatchingControlStructure findBestMatching(const WeightedPolygon_t &_polygon);

  static IndexList_t joinPoints(
      Polygon_t &_newpolygon,
      const VectorArray_t &_newpoints,
      const IndexTupleList_t &_bestmatching
      );

  static Rotation_t findPlaneAligningRotation(
      const PolygonWithIndices &_referencepositions,
      const PolygonWithIndices &_currentpositions
      );

  static Rotation_t findPointAligningRotation(
      const PolygonWithIndices &remainingold,
      const PolygonWithIndices &remainingnew);
};

// declare specializations

template <> SphericalPointDistribution::Polygon_t SphericalPointDistribution::get<0>();
template <> SphericalPointDistribution::Polygon_t SphericalPointDistribution::get<1>();
template <> SphericalPointDistribution::Polygon_t SphericalPointDistribution::get<2>();
template <> SphericalPointDistribution::Polygon_t SphericalPointDistribution::get<3>();
template <> SphericalPointDistribution::Polygon_t SphericalPointDistribution::get<4>();
template <> SphericalPointDistribution::Polygon_t SphericalPointDistribution::get<5>();
template <> SphericalPointDistribution::Polygon_t SphericalPointDistribution::get<6>();
template <> SphericalPointDistribution::Polygon_t SphericalPointDistribution::get<7>();
template <> SphericalPointDistribution::Polygon_t SphericalPointDistribution::get<8>();
template <> SphericalPointDistribution::Polygon_t SphericalPointDistribution::get<9>();
template <> SphericalPointDistribution::Polygon_t SphericalPointDistribution::get<10>();
template <> SphericalPointDistribution::Polygon_t SphericalPointDistribution::get<11>();
template <> SphericalPointDistribution::Polygon_t SphericalPointDistribution::get<12>();
template <> SphericalPointDistribution::Polygon_t SphericalPointDistribution::get<14>();

template <> SphericalPointDistribution::adjacency_t SphericalPointDistribution::getConnections<0>();
template <> SphericalPointDistribution::adjacency_t SphericalPointDistribution::getConnections<1>();
template <> SphericalPointDistribution::adjacency_t SphericalPointDistribution::getConnections<2>();
template <> SphericalPointDistribution::adjacency_t SphericalPointDistribution::getConnections<3>();
template <> SphericalPointDistribution::adjacency_t SphericalPointDistribution::getConnections<4>();
template <> SphericalPointDistribution::adjacency_t SphericalPointDistribution::getConnections<5>();
template <> SphericalPointDistribution::adjacency_t SphericalPointDistribution::getConnections<6>();
template <> SphericalPointDistribution::adjacency_t SphericalPointDistribution::getConnections<7>();
template <> SphericalPointDistribution::adjacency_t SphericalPointDistribution::getConnections<8>();
template <> SphericalPointDistribution::adjacency_t SphericalPointDistribution::getConnections<9>();
template <> SphericalPointDistribution::adjacency_t SphericalPointDistribution::getConnections<10>();
template <> SphericalPointDistribution::adjacency_t SphericalPointDistribution::getConnections<11>();
template <> SphericalPointDistribution::adjacency_t SphericalPointDistribution::getConnections<12>();
template <> SphericalPointDistribution::adjacency_t SphericalPointDistribution::getConnections<14>();

#endif /* SPHERICALPOINTDISTRIBUTION_HPP_ */