qpms/groups.h

   1 /*! \file groups.h
   2  * \brief Point groups.
   3  *
   4  * Right now, the instances of qpms_finite_group_t are created at compilation time
   5  * from source code generated by Python script TODO (output groups.c)
   6  * and they are not to be constructed dynamically.
   7  *
   8  * In the end, I might want to have a special type for 3D point groups
   9  * or more specifically, for the closed subgroups of O(3), see
  10  * https://en.wikipedia.org/wiki/Point_groups_in_three_dimensions.
  11  * They consist of the seven infinite series of axial groups
  12  * (characterized by the series index, the axis direction,
  13  * and the index \a n of the \a n-fold rotational symmetry)
  14  * and the seven remaining point groups + the finite groups.
  15  * All off them have a quite limited number of generators
  16  * (max. 4?; CHECKME).
  17  * The goal is to have some representation that would enable to
  18  *   1. fully describe the symmetries of abstract T-matrices/nanoparticles,
  19  *   2. quickly determine e.g. whether one is a subgroup of another,
  20  *   3. have all the irreps,
  21  *   4. have all in C and without excessive external dependencies,
  22  * etc.
  23  */
  24 #ifndef QPMS_GROUPS_H
  25 #define QPMS_GROUPS_H
  26
  27 #include "qpms_types.h"
  28 #include <assert.h>
  29
  30 /// To be used only in qpms_finite_group_t
  31 struct qpms_finite_group_irrep_t {
  32         int dim; ///< Irrep dimension.
  33         char *name; ///< Irrep label.
  34         /// Irrep matrix data.
  35         /** The r-th row, c-th column of the representation of the i'th element is retrieved as
  36          *  m[i * dim * dim + r * dim + c]
  37          */
  38         complex double *m;
  39 };
  40
  41 /// A point group with its irreducible representations and some metadata.
  42 /**
  43  *  The structure of the group is given by the multiplication table \a mt.
  44  *
  45  *  Each element of the group has its index from 0 to order.
  46  *  The metadata about some element are then accessed using that index.
  47  *
  48  *  All members are in principle optional except \a order and \a mt.
  49  *
  50  *  Note: after changing this struct, don't forget to update the Python method
  51  *  SVWFPointGroupInfo.generate_c_source().
  52  */
  53 typedef struct qpms_finite_group_t {
  54         char *name;
  55         qpms_gmi_t order; ///< Group order (number of elements)
  56         qpms_gmi_t idi; ///< Identity element index
  57         qpms_gmi_t *mt; ///< Group multiplication table. If c = a*b, then ic = mt[order * ia + ib].
  58         qpms_gmi_t *invi; ///< Group elem inverse indices.
  59         qpms_gmi_t *gens; ///< A canonical set of group generators.
  60         int ngens; ///< Number of the generators in gens;
  61         qpms_permutation_t *permrep; ///< Permutation representations of the elements.
  62         char **elemlabels; ///< Optional human readable labels for the group elements.
  63         int permrep_nelem; ///< Number of the elements over which the permutation representation acts.
  64         struct qpms_irot3_t *rep3d; ///< The quaternion representation of a 3D point group (if applicable).
  65         qpms_iri_t nirreps; ///< How many irreps does the group have
  66         struct qpms_finite_group_irrep_t *irreps; ///< Irreducible representations of the group.
  67 } qpms_finite_group_t;
  68
  69 /// Group multiplication.
  70 static inline qpms_gmi_t qpms_finite_group_mul(const qpms_finite_group_t *G,
  71                 qpms_gmi_t a, qpms_gmi_t b) {
  72         assert(a < G->order);
  73         assert(b < G->order);
  74         return G->mt[G->order * a + b];
  75 }
  76
  77 /// Group element inversion.
  78 static inline qpms_gmi_t qpms_finite_group_inv(const qpms_finite_group_t *G,
  79                 qpms_gmi_t a) {
  80         assert(a < G->order);
  81         return G->invi[a];
  82 }
  83
  84 static inline _Bool qpms_iri_is_valid(const qpms_finite_group_t *G, qpms_iri_t iri) {
  85         return (iri > G->nirreps || iri < 0) ? 0 : 1;
  86 }
  87
  88
  89
  90 /// NOT IMPLEMENTED Get irrep index by name.
  91 qpms_iri_t qpms_finite_group_find_irrep_by_name(qpms_finite_group_t *G, char *name);
  92
  93 extern const qpms_finite_group_t QPMS_FINITE_GROUP_TRIVIAL;
  94 extern const qpms_finite_group_t QPMS_FINITE_GROUP_TRIVIAL_G;
  95
  96 #endif // QPMS_GROUPS_H