qpms/pointgroups.h

   1 /*! \file pointgroups.h
   2  * \brief Quaternion-represented 3D point groups.
   3  */
   4 #ifndef POINTGROUPS_H
   5 #define POINTGROUPS_H
   6
   7 #include "qpms_error.h"
   8 #include "quaternions.h"
   9
  10
  11 /// Returns true if the point group class belongs to one of the seven "axial" group series.
  12 static inline _Bool qpms_pg_is_finite_axial(qpms_pointgroup_class cls) {
  13         switch(cls) {
  14         case QPMS_PGS_CN:
  15         case QPMS_PGS_S2N:
  16         case QPMS_PGS_CNH:
  17         case QPMS_PGS_CNV:
  18         case QPMS_PGS_DN:
  19         case QPMS_PGS_DND:
  20         case QPMS_PGS_DNH:
  21                 return true;
  22         default:
  23                 return false;
  24         }
  25 }
  26
  27 /// Absolute tolerance threshold used internally to consider two different `qpms_irot3_t` instances equal.
  28 /**
  29  * Used by @ref qpms_pg_irot3_approx_cmp_v.
  30  * By default, set to @ref QPMS_QUAT_ATOL.
  31  * It should work fine if the point group orders stay reasonable (thousands or less).
  32  * Do not touch if unsure what you are doing.
  33  */
  34 extern double qpms_pg_quat_cmp_atol;
  35
  36 /// An ordering of qpms_irot3_t that considers close enough elements equal.
  37 int qpms_pg_irot3_approx_cmp(const qpms_irot3_t *, const qpms_irot3_t *,
  38                 double atol ///< Absolute tolerance for the quaternion part difference.
  39                 );
  40 /// A `search.h` compatible ordering of qpms_irot3_t that considers close enough elements equal.
  41 /** The tolerance is determined by global variable @ref qpms_pg_quat_cmp_atol.
  42  */
  43 int qpms_pg_irot3_approx_cmp_v(const void *, const void *);
  44
  45 /// Returns the order of a given 3D point group type.
  46 /** For infinite groups returns 0. */
  47 qpms_gmi_t qpms_pg_order(qpms_pointgroup_class cls, ///< Point group class.
  48                 qpms_gmi_t n ///< Number of rotations around main axis (only for finite axial groups).
  49                          );
  50
  51 /// Generates the canonical elements of a given 3D point group type.
  52 /** Uses the canonical generators and DPS. */
  53 qpms_irot3_t *qpms_pg_canonical_elems(
  54                 qpms_irot3_t *target, ///< Target array (optional; if NULL, a new one is allocated)
  55                 qpms_pointgroup_class cls, ///< Point group class.
  56                 qpms_gmi_t ///< Number of rotations around \a z axis (only for axial group classes).
  57                 );
  58
  59 /// Returns the number of canonical generators of a given 3D point group type.
  60 /** TODO what does it do for infinite (Lie) groups? */
  61 qpms_gmi_t qpms_pg_genset_size(qpms_pointgroup_class cls, ///< Point group class.
  62                 qpms_gmi_t n ///< Number of rotations around main axis (only for axial groups).
  63                 );
  64
  65 /// Fills an array of canonical generators of a given 3D point group type.
  66 /** TODO what does it do for infinite (Lie) groups? */
  67 qpms_gmi_t qpms_pg_genset(qpms_pointgroup_class cls, ///< Point group class.
  68                 qpms_gmi_t n, ///< Number of rotations around main axis (only for axial groups).
  69                 qpms_irot3_t gen[] ///< Target generator array
  70                 );
  71
  72 /// Generates all elements of a given point group.
  73 /** The order of elements corresponds to the one obtained from qpms_pg_canonical_elems().
  74  */
  75 qpms_irot3_t *qpms_pg_elems(qpms_irot3_t *target, ///< Target array (optional; if NULL, a new one is allocated)
  76                 qpms_pointgroup_t g ///< Specification of the point group.
  77                 );
  78
  79 /// Checks whether \a a is subgroup of \a b (in a dirty general way).
  80 _Bool qpms_pg_is_subgroup(qpms_pointgroup_t a, qpms_pointgroup_t b);
  81
  82
  83
  84 #endif //POINTGROUPS_H