Kramers and quaternion decomposition of spinor expressions

CMakeLists.txt

@@ -423,6 +423,8 @@ set(SeQuant_mbpt_src
         SeQuant/domain/mbpt/space_qns.hpp
         SeQuant/domain/mbpt/spin.cpp
         SeQuant/domain/mbpt/spin.hpp
+        SeQuant/domain/mbpt/spinor.cpp
+        SeQuant/domain/mbpt/spinor.hpp
         SeQuant/domain/mbpt/vac_av.hpp
         SeQuant/domain/mbpt/vac_av.cpp
         SeQuant/domain/mbpt/utils.hpp

SeQuant/domain/mbpt/space_qns.hpp

@@ -89,6 +89,29 @@ struct mask<BatchingQNS> {
   static constexpr type value = static_cast<type>(BatchingQNS::batch);
 };
 
+/// quantum numbers tags related to Kramers symmetry (relativistic 2-component)
+/// \note Kramers QN takes the 8th and 9th rightmost bits since there are 3
+///       possible states (any, kramers-up, kramers-down).
+/// \note Spin and Kramers are mutually exclusive on a single index: an index
+///       is either spin-orbital (alpha/beta) or relativistic-spinor
+///       (kramers-up/kramers-down), never both. Spin restriction is the
+///       non-relativistic limit of Kramers restriction.
+enum class Kramers : bitset_t {
+  up = 0b010000000,    //!< unbarred Kramers spinor (⇑)
+  down = 0b100000000,  //!< barred   Kramers spinor (⇓)
+  /// arbitrary Kramers state represented by 2 bits so overlap and union
+  /// work as expected (`any & up = up`, `up | down = any`, etc.)
+  any = up | down,
+  // syntactic sugar
+  null = 0b000000000
+};
+
+template <>
+struct mask<Kramers> {
+  using type = std::underlying_type_t<Kramers>;
+  static constexpr type value = static_cast<type>(Kramers::any);
+};
+
 }  // namespace sequant::mbpt
 
 #endif  // SEQUANT_DOMAIN_MBPT_SPACE_QNS_HPP

SeQuant/domain/mbpt/spin.hpp

@@ -110,6 +110,19 @@ std::wstring spinannotation_replacе(WS&& label, Spin s) {
 // make null-spin idx
 [[nodiscard]] Index make_spinfree(const Index& idx);
 
+namespace detail {
+
+/// @brief Resets index tags on every Tensor in @p expr.
+///
+/// `canonicalize` tags Index instances and does not always reset them on
+/// exit; calling it twice without an intervening reset (or on a Sum that
+/// aggregates per-term canonicalized Products) trips
+/// `SEQUANT_ASSERT(!tag_.has_value())` in `Taggable::assign`. The standard
+/// SeQuant idiom is `detail::reset_idx_tags(e); simplify(e);`.
+void reset_idx_tags(const ExprPtr& expr);
+
+}  // namespace detail
+
 /// @brief Preserving particle symmetry, swaps bra and ket labels on all tensors
 /// in an expression
 /// @param expr ExprPtr to transform