Symmetry.hpp

Go to the documentation of this file.

#ifndef CYTNX_SYMMETRY_H_
#define CYTNX_SYMMETRY_H_
 
#include <fstream>
#include <ostream>
#include <string>
#include <variant>
#include <vector>
 
#include "cytnx_error.hpp"
#include "Type.hpp"
#include "utils/dynamic_arg_resolver.hpp"
 
namespace cytnx {
  enum SymmetryType : int { Void = -99, U = -1, Z = 0, fPar = -2, fNum = -3 };
 
  enum fermionParity : bool { EVEN = false, ODD = true };
 
  // helper class, has implicitly conversion to std::vector<int64>!
  class Qs {
   private:
    std::vector<cytnx_int64> tmpQs;
 
   public:
    template <class... Ts>
    Qs(const cytnx_int64 &e1, const Ts... elems) {
      this->tmpQs = dynamic_arg_int64_resolver(e1, elems...);
    }
 
    Qs(const std::vector<cytnx_int64> &qin) { this->tmpQs = qin; }
 
    // interprete as 2d vector directly implicitly convert!
    explicit operator std::vector<cytnx_int64>() const { return this->tmpQs; };
 
    std::pair<std::vector<cytnx_int64>, cytnx_uint64> operator>>(const cytnx_uint64 &dim) {
      return std::make_pair(this->tmpQs, dim);
    }
  };
 
  //=====================================
  // Symmetry kinds (std::variant alternatives).
  //
  // Symmetry is a plain value type: the active kind lives inline in a
  // std::variant and every public method of Symmetry dispatches with
  // std::visit. The visit lambdas are the completeness contract: adding a new
  // alternative to Symmetry::kind_variant that does not implement the full
  // rule set below fails to compile.
  //
  // Each kind keeps the legacy `n` field with the value the previous
  // intrusive-ptr implementation stored (U1: 1, Zn: n, fPar: -2, fNum: -1);
  // it backs Symmetry::n() and the Save/Load binary format.
 
  class U1Symmetry {
   public:
    // mutable: backs the legacy `int &n() const` accessor of Symmetry.
    mutable int n;
    static constexpr int stype_id = SymmetryType::U;
 
    U1Symmetry() : n(1) {}
 
    bool check_qnum(const cytnx_int64 &in_qnum) const;
    bool check_qnums(const std::vector<cytnx_int64> &in_qnums) const;
    void combine_rule_(std::vector<cytnx_int64> &out, const std::vector<cytnx_int64> &inL,
                       const std::vector<cytnx_int64> &inR) const;
    void combine_rule_(cytnx_int64 &out, const cytnx_int64 &inL, const cytnx_int64 &inR,
                       const bool &is_reverse) const;
    void reverse_rule_(cytnx_int64 &out, const cytnx_int64 &in) const;
    fermionParity get_fermion_parity(const cytnx_int64 &in_qnum) const;
    bool is_fermionic() const { return false; }
    void print_info() const;
    std::string stype_str() const { return "U1"; }
  };
 
  class ZnSymmetry {
   public:
    // mutable: backs the legacy `int &n() const` accessor of Symmetry.
    mutable int n;
    static constexpr int stype_id = SymmetryType::Z;
 
    explicit ZnSymmetry(const int &n) : n(n) {
      if (n <= 1) cytnx_error_msg(true, "%s", "[ERROR] ZnSymmetry can only have n > 1");
    }
 
    bool check_qnum(const cytnx_int64 &in_qnum) const;
    bool check_qnums(const std::vector<cytnx_int64> &in_qnums) const;
    void combine_rule_(std::vector<cytnx_int64> &out, const std::vector<cytnx_int64> &inL,
                       const std::vector<cytnx_int64> &inR) const;
    void combine_rule_(cytnx_int64 &out, const cytnx_int64 &inL, const cytnx_int64 &inR,
                       const bool &is_reverse) const;
    void reverse_rule_(cytnx_int64 &out, const cytnx_int64 &in) const;
    fermionParity get_fermion_parity(const cytnx_int64 &in_qnum) const;
    bool is_fermionic() const { return false; }
    void print_info() const;
    std::string stype_str() const { return "Z" + std::to_string(this->n); }
  };
 
  class FermionParitySymmetry {
   public:
    // mutable: backs the legacy `int &n() const` accessor of Symmetry.
    mutable int n = -2;
    static constexpr int stype_id = SymmetryType::fPar;
 
    bool check_qnum(const cytnx_int64 &in_qnum) const;
    bool check_qnums(const std::vector<cytnx_int64> &in_qnums) const;
    void combine_rule_(std::vector<cytnx_int64> &out, const std::vector<cytnx_int64> &inL,
                       const std::vector<cytnx_int64> &inR) const;
    void combine_rule_(cytnx_int64 &out, const cytnx_int64 &inL, const cytnx_int64 &inR,
                       const bool &is_reverse) const;
    void reverse_rule_(cytnx_int64 &out, const cytnx_int64 &in) const;
    fermionParity get_fermion_parity(const cytnx_int64 &in_qnum) const;
    bool is_fermionic() const { return true; }
    void print_info() const;
    std::string stype_str() const { return "fP"; }
  };
 
  class FermionNumberSymmetry {
   public:
    // mutable: backs the legacy `int &n() const` accessor of Symmetry.
    mutable int n = -1;
    static constexpr int stype_id = SymmetryType::fNum;
 
    bool check_qnum(const cytnx_int64 &in_qnum) const;
    bool check_qnums(const std::vector<cytnx_int64> &in_qnums) const;
    void combine_rule_(std::vector<cytnx_int64> &out, const std::vector<cytnx_int64> &inL,
                       const std::vector<cytnx_int64> &inR) const;
    void combine_rule_(cytnx_int64 &out, const cytnx_int64 &inL, const cytnx_int64 &inR,
                       const bool &is_reverse) const;
    void reverse_rule_(cytnx_int64 &out, const cytnx_int64 &in) const;
    fermionParity get_fermion_parity(const cytnx_int64 &in_qnum) const;
    bool is_fermionic() const { return true; }
    void print_info() const;
    std::string stype_str() const { return "f#"; }
  };
 
  //=====================================
  // this is API
  class Symmetry {
   public:
    //[Note] this is hidden from user.
    using kind_variant =
      std::variant<U1Symmetry, ZnSymmetry, FermionParitySymmetry, FermionNumberSymmetry>;
 
    kind_variant _impl;
 
    Symmetry(const int &stype = -1, const int &n = 0) {
      this->Init(stype, n);
    };  // default is U1Symmetry
 
    void Init(const int &stype = -1, const int &n = 0) {
      if (stype == SymmetryType::U) {
        this->_impl = U1Symmetry();
      } else if (stype == SymmetryType::Z) {
        this->_impl = ZnSymmetry(n);
      } else if (stype == SymmetryType::fPar) {
        this->_impl = FermionParitySymmetry();
      } else if (stype == SymmetryType::fNum) {
        this->_impl = FermionNumberSymmetry();
      } else {
        cytnx_error_msg(true, "%s", "[ERROR] invalid symmetry type.");
      }
    }
    Symmetry &operator=(const Symmetry &rhs) = default;
    Symmetry(const Symmetry &rhs) = default;
 
    //[genenrators]
    static Symmetry U1() { return Symmetry(SymmetryType::U, 1); }
 
    static Symmetry Zn(const int &n) { return Symmetry(SymmetryType::Z, n); }
 
    static Symmetry FermionParity() { return Symmetry(SymmetryType::fPar); }
 
    static Symmetry FermionNumber() { return Symmetry(SymmetryType::fNum); }
 
    Symmetry clone() const { return *this; }
 
    int stype() const {
      return std::visit([](const auto &kind) { return kind.stype_id; }, this->_impl);
    }
 
    int &n() const {
      // [legacy API] `int &n() const` (a mutable reference from a const
      // Symmetry) is preserved for compatibility with the intrusive-ptr era;
      // accessor cleanup is tracked together with the #840-era API follow-ups.
      // The kind structs declare `n` mutable, so returning it is well-defined
      // even for genuinely const objects.
      //
      // Value-semantics note (the second observable change of the value-type
      // refactor, alongside `is()` becoming address identity): the returned
      // reference now points into *this* Symmetry's own variant, so writing
      // through it no longer propagates to copies. Under the shared
      // intrusive-ptr impl, `Symmetry b = a; a.n() = k;` also changed b;
      // copies are now independent.
      return std::visit([](const auto &kind) -> int & { return kind.n; }, this->_impl);
    }
 
    std::string stype_str() const {
      return std::visit([](const auto &kind) { return kind.stype_str(); }, this->_impl);
    }
 
    bool check_qnum(const cytnx_int64 &qnum) const {
      return std::visit([&](const auto &kind) { return kind.check_qnum(qnum); }, this->_impl);
    }
 
    bool check_qnums(const std::vector<cytnx_int64> &qnums) const {
      return std::visit([&](const auto &kind) { return kind.check_qnums(qnums); }, this->_impl);
    }
 
    std::vector<cytnx_int64> combine_rule(const std::vector<cytnx_int64> &inL,
                                          const std::vector<cytnx_int64> &inR) const {
      std::vector<cytnx_int64> out;
      this->combine_rule_(out, inL, inR);
      return out;
    }
 
    void combine_rule_(std::vector<cytnx_int64> &out, const std::vector<cytnx_int64> &inL,
                       const std::vector<cytnx_int64> &inR) const {
      std::visit([&](const auto &kind) { kind.combine_rule_(out, inL, inR); }, this->_impl);
    }
 
    cytnx_int64 combine_rule(const cytnx_int64 &inL, const cytnx_int64 &inR,
                             const bool &is_reverse = false) const {
      cytnx_int64 out;
      std::visit([&](const auto &kind) { kind.combine_rule_(out, inL, inR, is_reverse); },
                 this->_impl);
      return out;
    }
 
    void combine_rule_(cytnx_int64 &out, const cytnx_int64 &inL, const cytnx_int64 &inR,
                       const bool &is_reverse = false) const {
      std::visit([&](const auto &kind) { kind.combine_rule_(out, inL, inR, is_reverse); },
                 this->_impl);
    }
 
    void reverse_rule_(cytnx_int64 &out, const cytnx_int64 &in) const {
      std::visit([&](const auto &kind) { kind.reverse_rule_(out, in); }, this->_impl);
    }
 
    cytnx_int64 reverse_rule(const cytnx_int64 &in) const {
      cytnx_int64 out;
      std::visit([&](const auto &kind) { kind.reverse_rule_(out, in); }, this->_impl);
      return out;
    }
 
    fermionParity get_fermion_parity(const cytnx_int64 &in_qnum) const {
      return std::visit([&](const auto &kind) { return kind.get_fermion_parity(in_qnum); },
                        this->_impl);
    }
 
    bool is_fermionic() const {
      return std::visit([](const auto &kind) { return kind.is_fermionic(); }, this->_impl);
    }
 
    void Save(const std::string &fname) const;
 
    void Save(const char *fname) const;
 
    static Symmetry Load(const std::string &fname);
 
    static Symmetry Load(const char *fname);
 
    void _Save(std::fstream &f) const;
    void _Load(std::fstream &f);
 
    void print_info() const {
      std::visit([](const auto &kind) { kind.print_info(); }, this->_impl);
    }
 
    bool operator==(const Symmetry &rhs) const;
 
    bool operator!=(const Symmetry &rhs) const;
  };  // Symmetry
 
  std::ostream &operator<<(std::ostream &os, const Symmetry &in);
 
};  // namespace cytnx
#endif  // CYTNX_SYMMETRY_H_