Merge pull request #448 from Cytnx-dev/rename_combineBonds2comboneBond

Rename combineBonds to combineBond
Cytnx-dev · Aug 30, 2024 · 81706af · 81706af
2 parents 9643192 + f05f0b6
commit 81706af
Show file tree

Hide file tree

Showing 9 changed files with 180 additions and 9 deletions.
diff --git a/include/Bond.hpp b/include/Bond.hpp
@@ -556,6 +556,74 @@ namespace cytnx {
 
     /**
     @brief combine multiple input bonds with self, and return a new combined Bond instance.
+    @param[in] bds the bonds that to be combined with self.
+          @param[in] is_grp this parameter is only used when the bond is
+      symmetric bond (bondType.BD_BRA or bondType.BD_KET).
+      If is_grp is true, the basis with duplicated quantum number will be
+      grouped together as a single basis. See
+      group_duplicates(std::vector<cytnx_uint64> &mapper) const.
+    @return [Bond] a new combined bond instance.
+          @pre
+            1. The type of all bonds (see cytnx::bondType) need to be same.
+            2. The Symmetry of all bonds should be same.
+          @note Compare to \n
+      combineBond_(const std::vector<Bond> &bds, const bool &is_grp),\n
+            this function will create a new Bond object.
+    @see combineBond_(const std::vector<Bond> &bds, const bool &is_grp)
+
+    ## Example:
+    ### c++ API:
+    \include example/Bond/combineBond.cpp
+    #### output>
+    \verbinclude example/Bond/combineBond.cpp.out
+    ### python API:
+    \include example/Bond/combineBond.py
+    #### output>
+    \verbinclude example/Bond/combineBond.py.out
+    */
+    Bond combineBond(const std::vector<Bond> &bds, const bool &is_grp = true) {
+      Bond out = this->clone();
+      for (cytnx_uint64 i = 0; i < bds.size(); i++) {
+        out.combineBond_(bds[i], is_grp);
+      }
+      return out;
+    }
+
+    /**
+    @brief combine multiple input bonds with self, inplacely
+    @param[in] bds the bonds that to be combined with self.
+          @param[in] is_grp this parameter is only used when the bond is
+      symmetric bond (bondType.BD_BRA or bondType.BD_KET).
+      If is_grp is true, the basis with duplicated quantum number will be
+      grouped together as a single basis. See
+      group_duplicates(std::vector<cytnx_uint64> &mapper) const.
+        @pre
+          1. The type of all bonds (see cytnx::bondType) need to be same.
+          2. The Symmetry of all bonds should be same.
+        @note Compare to \n
+      combineBond(const std::vector<Bond> &bds, const bool &is_grp),\n
+          this function will create a new Bond object.
+    @see combineBond(const std::vector<Bond> &bds, const bool &is_grp)
+
+    ## Example:
+    ### c++ API:
+    \include example/Bond/combineBond_.cpp
+    #### output>
+    \verbinclude example/Bond/combineBond_.cpp.out
+    ### python API:
+    \include example/Bond/combineBond_.py
+    #### output>
+    \verbinclude example/Bond/combineBond_.py.out
+    */
+    void combineBond_(const std::vector<Bond> &bds, const bool &is_grp = true) {
+      for (cytnx_uint64 i = 0; i < bds.size(); i++) {
+        this->combineBond_(bds[i], is_grp);
+      }
+    }
+
+    /**
+    @deprecated
+    @brief combine multiple input bonds with self, and return a new combined Bond instance.
     @param[in] bds the bonds that to be combined with self.
           @param[in] is_grp this parameter is only used when the bond is
       symmetric bond (bondType.BD_BRA or bondType.BD_KET).
@@ -590,6 +658,7 @@ namespace cytnx {
     }
 
     /**
+    @deprecated
     @brief combine multiple input bonds with self, inplacely
     @param[in] bds the bonds that to be combined with self.
           @param[in] is_grp this parameter is only used when the bond is

diff --git a/include/UniTensor.hpp b/include/UniTensor.hpp
@@ -296,6 +296,7 @@ namespace cytnx {
                                                          const cytnx_uint64 &rowrank = 0);
     virtual boost::intrusive_ptr<UniTensor_base> to_dense();
     virtual void to_dense_();
+    virtual void combineBond(const std::vector<std::string> &indicators, const bool &force = false);
     virtual void combineBonds(const std::vector<cytnx_int64> &indicators, const bool &force,
                               const bool &by_label);
     virtual void combineBonds(const std::vector<std::string> &indicators,
@@ -732,6 +733,7 @@ namespace cytnx {
      * @param permute_back
      * @param by_label
      */
+    void combineBond(const std::vector<std::string> &indicators, const bool &force = true);
     void combineBonds(const std::vector<cytnx_int64> &indicators, const bool &force,
                       const bool &by_label);
     void combineBonds(const std::vector<std::string> &indicators, const bool &force = true);
@@ -1717,6 +1719,7 @@ namespace cytnx {
 
     void group_basis_();
 
+    void combineBond(const std::vector<std::string> &indicators, const bool &force = false);
     void combineBonds(const std::vector<cytnx_int64> &indicators, const bool &force = false);
     void combineBonds(const std::vector<cytnx_int64> &indicators, const bool &force,
                       const bool &by_label);
@@ -3359,7 +3362,7 @@ namespace cytnx {
 
     /**
      * @deprecated This function is deprecated. Please use \n
-     *   combineBonds(const std::vector<std::string> &indicators, const bool &force) \n
+     *   combineBond(const std::vector<std::string> &indicators, const bool &force) \n
      *   instead.
      */
     void combineBonds(const std::vector<cytnx_int64> &indicators, const bool &force,
@@ -3368,6 +3371,7 @@ namespace cytnx {
     }
 
     /**
+    @deprecated
     @brief Combine the sevral bonds of the UniTensor.
         @param[in] indicators the labels of the lags you want to combine.
         @param[in] force If force is true, it will combine the bonds anyway even the direction
@@ -3383,13 +3387,27 @@ namespace cytnx {
 
     /**
      * @deprecated This function is deprecated. Please use \n
-     *   combineBonds(const std::vector<std::string> &indicators, const bool &force) \n
+     *   combineBond(const std::vector<std::string> &indicators, const bool &force) \n
      *   instead.
      */
     void combineBonds(const std::vector<cytnx_int64> &indicators, const bool &force = false) {
       this->_impl->combineBonds(indicators, force);
     }
 
+    /**
+    @brief Combine the sevral bonds of the UniTensor.
+        @param[in] indicators the labels of the lags you want to combine.
+        @param[in] force If force is true, it will combine the bonds anyway even the direction
+      of the bonds are same. After combining, the direction of the bonds will be set as
+      same as the first bond.
+        @pre
+            1. The size of \p indicators need to >= 2.
+            2. The UniTensor cannot be diagonal form (that means is_diag cannot be true.)
+        */
+    void combineBond(const std::vector<std::string> &indicators, const bool &force = false) {
+      this->_impl->combineBond(indicators, force);
+    }
+
     /**
     @brief Contract the UniTensor with common labels.
           @details This function contract the UniTensor lags with common labels.

diff --git a/pybind/bond_py.cpp b/pybind/bond_py.cpp
@@ -100,8 +100,16 @@ void bond_binding(py::module &m) {
     .def("clone", &Bond::clone)
     .def("__copy__", &Bond::clone)
     .def("__deepcopy__", &Bond::clone)
-    .def("combineBond", &Bond::combineBond, py::arg("bd"), py::arg("is_grp") = true)
-    .def("combineBond_", &Bond::combineBond_, py::arg("bd"), py::arg("is_grp") = true)
+    .def("combineBond", [](Bond &self, const Bond &bd,
+                           bool is_grp = true) { return self.combineBond(bd, is_grp); })
+    .def("combineBond", [](Bond &self, const std::vector<Bond> &bds,
+                           bool is_grp = true) { return self.combineBonds(bds, is_grp); })
+    .def("combineBond_", [](Bond &self, const Bond &bd,
+                            bool is_grp = true) { return self.combineBond_(bd, is_grp); })
+    .def("combineBond_", [](Bond &self, const std::vector<Bond> &bds,
+                            bool is_grp = true) { return self.combineBonds_(bds, is_grp); })
+    // .def("combineBond", &Bond::combineBond, py::arg("bd"), py::arg("is_grp") = true)
+    // .def("combineBond_", &Bond::combineBond_, py::arg("bd"), py::arg("is_grp") = true)
     .def("combineBonds", &Bond::combineBonds, py::arg("bds"), py::arg("is_grp") = true)
     .def("combineBonds_", &Bond::combineBonds_, py::arg("bds"), py::arg("is_grp") = true)
     .def("getDegeneracies", [](Bond &self) { return self.getDegeneracies(); })

diff --git a/src/BlockUniTensor.cpp b/src/BlockUniTensor.cpp
@@ -1843,6 +1843,7 @@ namespace cytnx {
     this->_fx_group_duplicates(has_dup, idx_mappers);
   }
 
+  // Deprecated, internal use only
   void BlockUniTensor::combineBonds(const std::vector<cytnx_int64> &indicators, const bool &force) {
     cytnx_error_msg(this->is_diag(),
                     "[ERROR][BlockUniTensor] cannot combineBonds when is_diag = true!%s", "\n");
@@ -1974,7 +1975,7 @@ namespace cytnx {
     this->group_basis_();
   }
 
-  void BlockUniTensor::combineBonds(const std::vector<std::string> &indicators, const bool &force) {
+  void BlockUniTensor::combineBond(const std::vector<std::string> &indicators, const bool &force) {
     cytnx_error_msg(indicators.size() < 2, "[ERROR] the number of bonds to combine must be > 1%s",
                     "\n");
     std::vector<std::string>::iterator it;
@@ -1989,6 +1990,11 @@ namespace cytnx {
     this->combineBonds(idx_mapper, force);
   }
 
+  void BlockUniTensor::combineBonds(const std::vector<std::string> &indicators, const bool &force) {
+    this->combineBond(indicators, force);
+  }
+
+  // Deprecated
   void BlockUniTensor::combineBonds(const std::vector<cytnx_int64> &indicators, const bool &force,
                                     const bool &by_label) {
     cytnx_error_msg(indicators.size() < 2, "[ERROR] the number of bonds to combine must be > 1%s",

diff --git a/src/DenseUniTensor.cpp b/src/DenseUniTensor.cpp
@@ -686,7 +686,7 @@ namespace cytnx {
     }
     return out;
   }
-  void DenseUniTensor::combineBonds(const std::vector<std::string> &indicators, const bool &force) {
+  void DenseUniTensor::combineBond(const std::vector<std::string> &indicators, const bool &force) {
     cytnx_error_msg(indicators.size() < 2, "[ERROR] the number of bonds to combine must be > 1%s",
                     "\n");
     std::vector<std::string>::iterator it;
@@ -700,6 +700,11 @@ namespace cytnx {
     }
     this->combineBonds(idx_mapper, force);
   }
+  // Deprecated
+  void DenseUniTensor::combineBonds(const std::vector<std::string> &indicators, const bool &force) {
+    this->combineBond(indicators, force);
+  }
+  // Deprecated
   void DenseUniTensor::combineBonds(const std::vector<cytnx_int64> &indicators, const bool &force) {
     cytnx_error_msg(indicators.size() < 2, "[ERROR] the number of bonds to combine must be > 1%s",
                     "\n");
@@ -894,6 +899,7 @@ namespace cytnx {
   }
   */
 
+  // Deprecated
   void DenseUniTensor::combineBonds(const std::vector<cytnx_int64> &indicators, const bool &force,
                                     const bool &by_label) {
     cytnx_error_msg(indicators.size() < 2, "[ERROR] the number of bonds to combine must be > 1%s",

diff --git a/src/UniTensor_base.cpp b/src/UniTensor_base.cpp
@@ -384,16 +384,23 @@ namespace cytnx {
     cytnx_error_msg(true, "[ERROR] fatal internal, cannot call on a un-initialize UniTensor_base%s",
                     "\n");
   }
+  // Deprecated
   void UniTensor_base::combineBonds(const std::vector<cytnx_int64> &indicators,
                                     const bool &permute_back, const bool &by_labels) {
     cytnx_error_msg(true, "[ERROR] fatal internal, cannot call on a un-initialize UniTensor_base%s",
                     "\n");
   }
+  void UniTensor_base::combineBond(const std::vector<std::string> &indicators,
+                                   const bool &permute_back) {
+    cytnx_error_msg(true, "[ERROR] fatal internal, cannot call on a un-initialize UniTensor_base%s",
+                    "\n");
+  }
   void UniTensor_base::combineBonds(const std::vector<std::string> &indicators,
                                     const bool &permute_back) {
     cytnx_error_msg(true, "[ERROR] fatal internal, cannot call on a un-initialize UniTensor_base%s",
                     "\n");
   }
+  // Deprecated
   void UniTensor_base::combineBonds(const std::vector<cytnx_int64> &indicators,
                                     const bool &permute_back) {
     cytnx_error_msg(true, "[ERROR] fatal internal, cannot call on a un-initialize UniTensor_base%s",

diff --git a/tests/Bond_test.cpp b/tests/Bond_test.cpp
@@ -155,7 +155,7 @@ TEST(Bond, CombindBondSymm_v2) {
 
   Bond bd_sym_b = Bond(BD_BRA, {{0, 0}, {2, 1}}, {1, 1}, {Symmetry::U1(), Symmetry::Zn(2)});
   Bond bd_sym_c = Bond(BD_BRA, {{1, 1}}, {2}, {Symmetry::U1(), Symmetry::Zn(2)});
-  Bond bd_sym_d = bd_sym_a.combineBonds({bd_sym_b, bd_sym_c});
+  Bond bd_sym_d = bd_sym_a.combineBond({bd_sym_b, bd_sym_c});
   EXPECT_EQ(bd_sym_d.type(), BD_BRA);
   EXPECT_EQ(bd_sym_d, Bond(BD_BRA, {{1, 0}, {3, 1}}, {6, 6}, {Symmetry::U1(), Symmetry::Zn(2)}));
 

diff --git a/tests/DenseUniTensor_test.cpp b/tests/DenseUniTensor_test.cpp
@@ -1900,6 +1900,63 @@ TEST_F(DenseUniTensorTest, combineBonds_ut_uninit) {
   EXPECT_ANY_THROW(ut_uninit.combineBonds(labels_combine));
 }
 
+/*=====test info=====
+describe:test combineBond
+====================*/
+TEST_F(DenseUniTensorTest, combineBond) {
+  std::vector<std::string> labels = {"a", "b", "c"};
+  auto ut = UniTensor({Bond(5), Bond(4), Bond(3)}, labels);
+  ut.set_rowrank(1);
+  int seed = 0;
+  random::uniform_(ut, -100.0, 100.0, seed);
+  std::vector<std::string> labels_combine = {"b", "c"};
+  ut.combineBond(labels_combine);
+
+  // construct answer directly
+  labels = {"a", "b"};
+  int rowrank = 1;
+  auto ans_ut = UniTensor({Bond(5), Bond(12)}, labels, rowrank);
+  auto tens = ut.get_block().reshape({5, 12});
+  ans_ut.put_block(tens);
+
+  // compare
+  EXPECT_TRUE(AreEqUniTensor(ut, ans_ut));
+}
+
+/*=====test info=====
+describe:test combineBond with diagonal UniTensor
+====================*/
+TEST_F(DenseUniTensorTest, combineBond_diag) {
+  EXPECT_THROW(ut_complex_diag.combineBond(ut_complex_diag.labels()), std::logic_error);
+}
+
+/*=====test info=====
+describe:test combineBond error
+====================*/
+TEST_F(DenseUniTensorTest, combineBond_error) {
+  std::vector<std::string> labels = {"a", "b", "c"};
+  auto ut = UniTensor({Bond(5), Bond(4), Bond(3)}, labels);
+  ut.set_rowrank(1);
+  int seed = 0;
+  random::uniform_(ut, -100.0, 100.0, seed);
+
+  // not exist labels
+  std::vector<std::string> labels_combine = {"c", "d"};
+  EXPECT_THROW(ut.combineBond(labels_combine), std::logic_error);
+
+  // empty combine's label
+  labels_combine = std::vector<std::string>();
+  EXPECT_THROW(ut.combineBond(labels_combine), std::logic_error);
+}
+
+/*=====test info=====
+describe:test combindbonds with uninitialized UniTensor
+====================*/
+TEST_F(DenseUniTensorTest, combineBond_ut_uninit) {
+  std::vector<std::string> labels_combine = {};
+  EXPECT_ANY_THROW(ut_uninit.combineBond(labels_combine));
+}
+
 TEST_F(DenseUniTensorTest, contract1) {
   ut1.set_labels({"a", "b", "c", "d"});
   ut2.set_labels({"a", "aa", "bb", "cc"});

diff --git a/tests/gpu/Bond_test.cpp b/tests/gpu/Bond_test.cpp
@@ -49,7 +49,7 @@ TEST(Bond, gpu_CombineBondNoSymmBraKet) {
   EXPECT_EQ(bd5.type(), BD_BRA);
   bd3.set_type(BD_BRA);
   bd4.set_type(BD_BRA);
-  Bond bd_all = bd1.combineBonds({bd2, bd3, bd4});
+  Bond bd_all = bd1.combineBond({bd2, bd3, bd4});
   EXPECT_EQ(bd_all.dim(), 210);
   EXPECT_EQ(bd_all.type(), BD_BRA);
   EXPECT_EQ(bd_all.Nsym(), 0);
@@ -155,7 +155,7 @@ TEST(Bond, gpu_CombindBondSymm_v2) {
 
   Bond bd_sym_b = Bond(BD_BRA, {{0, 0}, {2, 1}}, {1, 1}, {Symmetry::U1(), Symmetry::Zn(2)});
   Bond bd_sym_c = Bond(BD_BRA, {{1, 1}}, {2}, {Symmetry::U1(), Symmetry::Zn(2)});
-  Bond bd_sym_d = bd_sym_a.combineBonds({bd_sym_b, bd_sym_c});
+  Bond bd_sym_d = bd_sym_a.combineBond({bd_sym_b, bd_sym_c});
   EXPECT_EQ(bd_sym_d.type(), BD_BRA);
   EXPECT_EQ(bd_sym_d, Bond(BD_BRA, {{1, 0}, {3, 1}}, {6, 6}, {Symmetry::U1(), Symmetry::Zn(2)}));