SymGroup.hh

Go to the documentation of this file.

#ifndef SYMGROUP_HH
#define SYMGROUP_HH

#include <iostream>
#include <string>
#include <iomanip>

#include "casm/symmetry/SymOp.hh"

namespace CASM {

  class Lattice;

  class SymGroup;
  class MasterSymGroup;
  class SymGroupRep;
  struct SymInfo;

  //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  class SymGroup : public Array<SymOp> {
  public:
    typedef SymOp::vector_type vector_type;
    typedef SymOp::matrix_type matrix_type;
    SymGroup(PERIODICITY_TYPE init_type = PERIODIC) :
      m_lat_ptr(nullptr),
      m_group_periodicity(init_type),
      m_max_error(-1) {
      name.clear();
      latex_name.clear();
    }

    SymGroup(const Array<SymOp> &from_array, PERIODICITY_TYPE init_type = PERIODIC);

    virtual void push_back(const SymOp &new_op);
    virtual void clear();
    virtual void clear_tables();

    void set_lattice(const Lattice &new_lat);

    const Lattice &lattice() const;

    const MasterSymGroup &master_group() const {
      assert(size() && at(0).has_valid_master());
      return at(0).master_group();
    }

    ReturnArray<Index> op_indices() const;

    //maybe contains and find should account for group_periodicity
    //bool contains(const SymOp &test_op) const; //Donghee

    bool contains_periodic(const SymOp &test_op, double tol = TOL) const;


    //Index find(const SymOp &test_op) const;   //Donghee

    Index find_no_trans(const SymOp &test_op) const;

    Index find_periodic(const SymOp &test_op, double tol = TOL) const;
    ReturnArray<Index> find_all_periodic(const Array<SymOp> &subgroup, double tol = TOL) const;

    virtual void sort();

    // Should we change the name to something else?
    SymGroup get_union(const SymGroup &other_group) const;  //Ivy do this

    SymGroup &apply_sym(const SymOp &op);

    Index ind_prod(Index i, Index j) const;

    Index ind_inverse(Index i) const;

    Index class_of_op(Index i) const;

    void set_irrep_ID(Index i, SymGroupRepID ID) const;

    SymGroupRepID get_irrep_ID(Index i) const;

    SymGroupRepID coord_rep_ID() const;

    SymGroupRep const &get_irrep(Index i) const;

    SymGroupRepID add_empty_representation() const;


    void calc_space_group_in_cell(SymGroup &space_group, const Lattice &_cell) const;

    void calc_space_group_in_range(SymGroup &space_group, const Lattice &_cell, Eigen::Vector3i min_trans,  Eigen::Vector3i max_trans) const;

    bool is_group(double tol = TOL) const;
    void enforce_group(double tol = TOL, Index max_size = 200);  //AAB

    void print_locations(std::ostream &stream) const;

    void write(std::string filename, COORD_TYPE mode) const;

    void print(std::ostream &out, COORD_TYPE mode) const;

    SymGroup &operator+=(const Eigen::Ref<const SymOp::vector_type> &shift);
    SymGroup &operator-=(const Eigen::Ref<const SymOp::vector_type> &shift);

    double max_error();

    ReturnArray<Array<Index> > left_cosets(const Array<SymOp> &subgroup, double tol = TOL) const;
    ReturnArray<Array<Index> > left_cosets(const Array<Index> &subgroup_inds) const;

    const Array<Index>::X2 &get_multi_table() const;
    const Array<Index>::X2 &get_alt_multi_table() const;
    void invalidate_multi_tables() const;
    const Array<Index>::X2 &get_conjugacy_classes() const;
    const Array<std::complex<double> >::X2 &character_table() const;
    const Array<bool> &get_complex_irrep_list() const;
    const std::string &get_name() const;
    const std::string &get_latex_name() const;

    PERIODICITY_TYPE periodicity() const {
      return m_group_periodicity;
    }

    std::string possible_space_groups() const {
      return comment;
    }


    const Array<Index>::X3 &subgroups() const;

    void print_character_table(std::ostream &stream);
    ReturnArray<Index> get_irrep_decomposition() const;
    bool is_irreducible() const;

    std::vector<SymGroup> unique_subgroups() const;

    void get_rotation_groups()const;
    void get_point_group_type()const;
    void print_space_group_info(std::ostream &out) const;

    void copy_no_trans(SymGroup &shiftless, bool keep_repeated = false) const;

    jsonParser &to_json(jsonParser &json) const;

    void from_json(const jsonParser &json);

    SymInfo info(Index i) const;

  protected:
    void _generate_conjugacy_classes() const;
    void _generate_character_table() const;
    void _generate_centralizers() const;
    void _generate_elem_order_table() const;
    void _generate_class_names() const;
    void _generate_irrep_names() const;
    bool _generate_multi_table() const;
    void _generate_alt_multi_table() const;
    void _generate_subgroups() const;

    // small_groups are cyclic subgroups.  Found by taking a group
    // element and multiplying it by itself until a group is generated
    // small_groups[i][j][k] is index of symop 'k' in subgroup (i,j) -- the equivalent subroup 'j' of an orbit 'i' of equivalent subgroups
    Array<Index>::X3 _small_subgroups() const;


    Lattice const *m_lat_ptr;

    PERIODICITY_TYPE m_group_periodicity;

    mutable Array<Array<Index> > multi_table;

    mutable Array<Array<Index> > alt_multi_table;

    // information about conjugacy classes
    // conjugacy_classes[i][j] gives index of SymOp 'j' in class 'i'
    mutable Array<Array<Index> > conjugacy_classes;
    mutable Array<std::string> class_names;
    mutable Array<Index> index2conjugacy_class;

    // Information about irreducible representations
    // m_character_table[i][j] is character of conjugacy class 'j' in irrep 'i'
    mutable Array<Array<std::complex<double> > > m_character_table;
    mutable Array<SymGroupRepID> irrep_IDs;
    mutable Array<bool> complex_irrep;
    mutable Array<std::string> irrep_names;

    // subgroups are found by finding the closure for each possible union of small_subgroups
    // organized the same way as small_subgroups
    mutable Array<Array<Array<Index> > > m_subgroups;


    mutable Array<Array<Index> > centralizer_table;
    mutable Array<Array<Index> > elem_order_table;

    mutable std::string name;
    mutable std::string latex_name;
    mutable std::string comment;

    mutable double m_max_error;

    mutable Array<Array<SymOp> > rotation_groups;
    mutable std::string crystal_system;
    mutable bool centric; // if it is centric, special point is same in reciprocal space
    mutable Array<int> group_number; // space group number (min and max)
    mutable Array<std::string> group_name; // 0: International 1: Schonflies


  };

  jsonParser &to_json(const SymGroup &group, jsonParser &json);

  // Note: as a hack this expects group[0] to be present and have the right lattice!!!
  //   it's just used to set the lattice for all the Molecules
  void from_json(SymGroup &group, const jsonParser &json);

  // return SymGroup with all molecular point group sym ops
  // I will centerize your coord_map, fyi.
  SymGroup molecular_point_group(std::map<int, std::vector<Eigen::Vector3d> > coord_map);

  //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  class MasterSymGroup : public SymGroup {
    //NOTE: It may be useful to store a user-specified set of "favored directions" in MasterSymGroup
    //      e.g., {(0,0,1), (1,0,0), (0,1,0)}, which would be used to arbitrate decisions in symmetry-related algorithms
    //            Relevant applications include
    //                - constucting orbit equivalence map
    //                - optimizing the coordinate system of irreps
    //                - deciding prototype cluster

  public:
    MasterSymGroup(PERIODICITY_TYPE init_type = PERIODIC) :
      SymGroup(init_type),
      m_group_index(GROUP_COUNT++) {
    }

    MasterSymGroup(const MasterSymGroup &RHS);
    ~MasterSymGroup();

    Index group_index() const {
      return m_group_index;
    }

    MasterSymGroup &operator=(const MasterSymGroup &RHS);

    void push_back(const SymOp &op);

    void clear();

    void sort();
    //void sort_by_class();

    const SymGroup &point_group() const;

    SymGroupRep const &representation(SymGroupRepID i) const;

    SymGroupRep const &reg_rep() const;

    SymGroupRep const &coord_rep() const;

    SymGroupRepID add_representation(const SymGroupRep &new_rep) const;

    SymGroupRepID add_empty_representation() const;

    SymGroupRepID reg_rep_ID() const;
    SymGroupRepID coord_rep_ID() const;
    SymGroupRepID identity_rep_ID(Index dim) const;
    SymGroupRepID add_kronecker_rep(SymGroupRepID ID1, SymGroupRepID ID2) const;
    SymGroupRepID add_direct_sum_rep(const Array<SymGroupRepID> &rep_IDs) const;
    SymGroupRepID add_transformed_rep(SymGroupRepID orig_ID, const Eigen::MatrixXd &trans_mat) const;
    SymGroupRepID add_rotation_rep() const;

    jsonParser &to_json(jsonParser &json) const;

    void from_json(const jsonParser &json);

  private:

    SymGroupRep *_representation_ptr(SymGroupRepID _id) const;

    SymGroupRepID _add_reg_rep() const;
    SymGroupRepID _add_coord_rep() const;

    SymGroupRepID _add_representation(SymGroupRep *_rep_ptr) const;

    static Index GROUP_COUNT;

    Index m_group_index;

    mutable Array<SymGroupRep *> m_rep_array;

    mutable SymGroupRepID m_coord_rep_ID;

    mutable SymGroupRepID m_reg_rep_ID;

    mutable Array<SymGroupRepID> m_identity_rep_IDs;

    mutable SymGroup m_point_group;
  };

  jsonParser &to_json(const SymGroup &group, jsonParser &json);

  // Note: as a hack this expects group[0] to be present and have the right lattice!!!
  //   it's just used to set the lattice for all the Molecules
  void from_json(SymGroup &group, const jsonParser &json);

  bool compare_periodic(const SymOp &a,
                        const SymOp &b,
                        const Lattice &lat,
                        PERIODICITY_TYPE periodicity,
                        double _tol);

  SymOp within_cell(const SymOp &a, const Lattice &lat, PERIODICITY_TYPE periodicity);

}

#endif