deltaspin: lift print_Mi / print_Mag_Force out of SpinConstrain class

Phase 2 of god-class slimming: lift the two table-printing member
functions print_Mi and print_Mag_Force out of SpinConstrain<TK> and
into free function templates in the spinconstrain namespace, alongside
the lambda-loop helpers landed in phase 1.

Motivation
----------
print_Mi / print_Mag_Force are pure formatting routines (FmtTable
output) that read Mi_ and lambda_ via the existing getters. They
do not belong on the class interface; lifting them further shrinks
the public API and consolidates all deltaspin printing in
lambda_loop_helper.{h,cpp}.

Changes
-------
- lambda_loop_helper.{h,cpp}: add print_Mi / print_Mag_Force free
  function templates. Both are generic (no per-TK stub needed);
  instantiated for std::complex<double> (real path) and double
  (nspin=2 stub path) so callers holding either TK can link.
- spin_constrain.{h,cpp}: remove print_Mi / print_Mag_Force member
  declarations and definitions; add get_atomLabels() getter so
  helpers can read the per-atom label vector.
- spin_constrain.{h,cpp}: promote check_atomCounts() to const (it
  only reads atomCounts and calls get_nat, both safe). Replaces
  std::map::iterator with const_iterator in two loops.
- ctrl_output_pw.cpp / ctrl_scf_lcao.cpp: update call sites from
  'sc.print_Mag_Force(ofs_running)' / 'sc.print_Mi(ofs_running)' to
  'spinconstrain::print_Mag_Force(sc, ofs_running)' /
  'spinconstrain::print_Mi(sc, ofs_running)'; add lambda_loop_helper.h
  include.

Verification
------------
- 'make -j 30' in build_max_para_test: clean build of abacus +
  abacus_basic_para + all MODULE_LCAO_deltaspin_* test targets.
- 'ctest -R deltaspin --output-on-failure': 5/5 tests passed.

Out of scope
------------
PW-specific methods (cal_mi_pw, update_psi_charge_pw_*,
calculate_delta_hcc), LCAO-specific helpers (cal_mi_lcao, convert,
calculate_MW, collect_MW) and accumulate_Mi_from_becp remain as
member functions for subsequent phases.

Author: abacus_fixer

source/source_io/module_ctrl/ctrl_output_pw.cpp

@@ -10,6 +10,7 @@
 #include "../module_wf/get_wf_pw.h"
 #include "../module_wf/write_wfc_pw.h" // use write_wfc_pw
 #include "source_base/formatter.h"
+#include "source_lcao/module_deltaspin/lambda_loop_helper.h"
 #include "source_lcao/module_deltaspin/spin_constrain.h"
 #include "source_pw/module_pwdft/elecond.h"
 #include "source_pw/module_pwdft/onsite_proj.h" // use projector
@@ -214,7 +215,7 @@ void ModuleIO::ctrl_scf_pw(const int istep,
     {
         spinconstrain::SpinConstrain<std::complex<double>>& sc = spinconstrain::SpinConstrain<std::complex<double>>::getScInstance();
         sc.cal_mi_pw();
-        sc.print_Mag_Force(GlobalV::ofs_running);
+        spinconstrain::print_Mag_Force(sc, GlobalV::ofs_running);
     }
 
     //------------------------------------------------------------------

source/source_io/module_ctrl/ctrl_scf_lcao.cpp

@@ -25,6 +25,7 @@
 #include "../module_dm/write_dmr.h"                           // use ModuleIO::write_dmr()
 #include "../module_dos/write_dos_lcao.h"                      // use ModuleIO::write_dos_lcao()
 #include "../module_wf/write_wfc_nao.h"                       // use ModuleIO::write_wfc_nao()
+#include "source_lcao/module_deltaspin/lambda_loop_helper.h"   // print_Mi / print_Mag_Force free functions
 #include "source_lcao/module_deltaspin/spin_constrain.h"   // use spinconstrain::SpinConstrain<TK>
 #include "source_lcao/module_operator_lcao/ekinetic.h" // use hamilt::EKinetic
 #ifdef __MLALGO
@@ -554,8 +555,8 @@ void ModuleIO::ctrl_scf_lcao(UnitCell& ucell,
     {
         spinconstrain::SpinConstrain<TK>& sc = spinconstrain::SpinConstrain<TK>::getScInstance();
         sc.cal_mi_lcao(istep);
-        sc.print_Mi(GlobalV::ofs_running);
-        sc.print_Mag_Force(GlobalV::ofs_running);
+        spinconstrain::print_Mi(sc, GlobalV::ofs_running);
+        spinconstrain::print_Mag_Force(sc, GlobalV::ofs_running);
     }
 
     //------------------------------------------------------------------

source/source_lcao/module_deltaspin/lambda_loop_helper.cpp

@@ -4,9 +4,12 @@
 #include <cmath>
 #include <cstdio>
 #include <iomanip>
+#include <string>
 #include <utility>
+#include <vector>
 
 #include "basic_funcs.h"
+#include "source_base/formatter.h"
 
 /**
  * @file lambda_loop_helper.cpp
@@ -345,6 +348,116 @@ bool check_gradient_decay(const SpinConstrain<TK>& sc,
     return false;
 }
 
+/**
+ * @brief Print atomic magnetic moments Mi in a formatted table.
+ *
+ * @par Output format
+ * - nspin=2: "Total Magnetism (uB)" with single z-component column
+ * - nspin=4: three columns (Mx, My, Mz)
+ *
+ * Lifted from SpinConstrain<TK>::print_Mi; accesses state via getters.
+ */
+template <typename TK>
+void print_Mi(const SpinConstrain<TK>& sc, std::ostream& ofs_running)
+{
+    sc.check_atomCounts();
+    const int nat = sc.get_nat();
+    const int nspin = sc.get_nspin();
+    const auto& Mi = sc.get_Mi();
+    const auto& atomLabel = sc.get_atomLabels();
+    std::vector<double> mag_x(nat, 0.0);
+    std::vector<double> mag_y(nat, 0.0);
+    std::vector<double> mag_z(nat, 0.0);
+    if (nspin == 2)
+    {
+        const std::vector<std::string> title = {"Total Magnetism (uB)", ""};
+        const std::vector<std::string> fmts = {"%-26s", "%20.10f"};
+        FmtTable table(/*titles=*/title,
+                       /*nrows=*/nat,
+                       /*formats=*/fmts,
+                       /*indent=*/0,
+                       /*align=*/{/*value*/FmtTable::Align::RIGHT, /*title*/FmtTable::Align::LEFT});
+        for (int iat = 0; iat < nat; ++iat)
+        {
+            mag_z[iat] = Mi[iat].z;
+        }
+        table << atomLabel << mag_z;
+        ofs_running << table.str() << std::endl;
+    }
+    else if (nspin == 4)
+    {
+        const std::vector<std::string> title = {"Total Magnetism (uB)", "", "", ""};
+        const std::vector<std::string> fmts = {"%-26s", "%20.10f", "%20.10f", "%20.10f"};
+        FmtTable table(/*titles=*/title,
+                       /*nrows=*/nat,
+                       /*formats=*/fmts,
+                       /*indent=*/0,
+                       /*align=*/{/*value*/FmtTable::Align::RIGHT, /*title*/FmtTable::Align::LEFT});
+        for (int iat = 0; iat < nat; ++iat)
+        {
+            mag_x[iat] = Mi[iat].x;
+            mag_y[iat] = Mi[iat].y;
+            mag_z[iat] = Mi[iat].z;
+        }
+        table << atomLabel << mag_x << mag_y << mag_z;
+        ofs_running << table.str() << std::endl;
+    }
+}
+
+/**
+ * @brief Print the magnetic force (-lambda) per atom in eV/uB.
+ *
+ * Lifted from SpinConstrain<TK>::print_Mag_Force; accesses state via getters.
+ * lambda is read via get_sc_lambda() and converted from Ry to eV on output.
+ */
+template <typename TK>
+void print_Mag_Force(const SpinConstrain<TK>& sc, std::ostream& ofs_running)
+{
+    sc.check_atomCounts();
+    const int nat = sc.get_nat();
+    const int nspin = sc.get_nspin();
+    const auto& lambda = sc.get_sc_lambda();
+    const auto& atomLabel = sc.get_atomLabels();
+    std::vector<double> mag_force_x(nat, 0.0);
+    std::vector<double> mag_force_y(nat, 0.0);
+    std::vector<double> mag_force_z(nat, 0.0);
+    if (nspin == 2)
+    {
+        const std::vector<std::string> title = {"Magnetic force (eV/uB)", ""};
+        const std::vector<std::string> fmts = {"%-26s", "%20.10f"};
+        FmtTable table(/*titles=*/title,
+                       /*nrows=*/nat,
+                       /*formats=*/fmts,
+                       /*indent=*/0,
+                       /*align=*/{/*value*/FmtTable::Align::RIGHT, /*title*/FmtTable::Align::LEFT});
+        for (int iat = 0; iat < nat; ++iat)
+        {
+            mag_force_z[iat] = lambda[iat].z * ModuleBase::Ry_to_eV;
+        }
+        table << atomLabel << mag_force_z;
+        ofs_running << table.str() << std::endl;
+    }
+    else if (nspin == 4)
+    {
+        const std::vector<std::string> title = {"Magnetic force (eV/uB)", "", "", ""};
+        const std::vector<std::string> fmts = {"%-26s", "%20.10f", "%20.10f", "%20.10f"};
+        FmtTable table(/*titles=*/title,
+                       /*nrows=*/nat,
+                       /*formats=*/fmts,
+                       /*indent=*/0,
+                       /*align=*/{/*value*/FmtTable::Align::RIGHT, /*title*/FmtTable::Align::LEFT});
+        for (int iat = 0; iat < nat; ++iat)
+        {
+            mag_force_x[iat] = lambda[iat].x * ModuleBase::Ry_to_eV;
+            mag_force_y[iat] = lambda[iat].y * ModuleBase::Ry_to_eV;
+            mag_force_z[iat] = lambda[iat].z * ModuleBase::Ry_to_eV;
+        }
+        table << atomLabel << mag_force_x << mag_force_y << mag_force_z;
+        ofs_running << table.str() << std::endl;
+    }
+}
+
+
 // Explicit instantiation for the only supported TK = std::complex<double>.
 // The double stub is provided by template_helpers.cpp via the existing
 // specialization mechanism (kept as a separate file to avoid duplicate symbols).
@@ -366,4 +479,14 @@ template bool check_gradient_decay<std::complex<double>>(const SpinConstrain<std
                                                           std::vector<ModuleBase::Vector3<double>>,
                                                           bool, std::ostream&);
 
+// print_Mi / print_Mag_Force are generic (no per-TK stub needed): the
+// template body works for both TK = std::complex<double> (real usage) and
+// TK = double (nspin=2 stub path instantiated by template_helpers_test).
+// We instantiate both so callers in PW/LCAO ESolvers that hold either TK
+// can link against a single definition.
+template void print_Mi<std::complex<double>>(const SpinConstrain<std::complex<double>>&, std::ostream&);
+template void print_Mag_Force<std::complex<double>>(const SpinConstrain<std::complex<double>>&, std::ostream&);
+template void print_Mi<double>(const SpinConstrain<double>&, std::ostream&);
+template void print_Mag_Force<double>(const SpinConstrain<double>&, std::ostream&);
+
 } // namespace spinconstrain

source/source_lcao/module_deltaspin/lambda_loop_helper.h

@@ -134,6 +134,32 @@ bool check_gradient_decay(const SpinConstrain<TK>& sc,
                           bool print,
                           std::ostream& ofs_running);
 
+/**
+ * @brief Print atomic magnetic moments Mi in a formatted table.
+ *
+ * @par Output format
+ * - nspin=2: "Total Magnetism (uB)" with single z-component column
+ * - nspin=4: three columns (Mx, My, Mz)
+ *
+ * @param sc          SpinConstrain instance
+ * @param ofs_running Log output stream
+ */
+template <typename TK>
+void print_Mi(const SpinConstrain<TK>& sc, std::ostream& ofs_running);
+
+/**
+ * @brief Print the magnetic force (-lambda) per atom in eV/uB.
+ *
+ * @par Physical meaning
+ * Magnetic force = dL/dMi = -lambda. Large |lambda| means the system
+ * strongly resists the target moment constraint.
+ *
+ * @param sc          SpinConstrain instance
+ * @param ofs_running Log output stream
+ */
+template <typename TK>
+void print_Mag_Force(const SpinConstrain<TK>& sc, std::ostream& ofs_running);
+
 } // namespace spinconstrain
 
 #endif // LAMBDA_LOOP_HELPER_H

source/source_lcao/module_deltaspin/spin_constrain.cpp

@@ -287,7 +287,7 @@ int SpinConstrain<TK>::get_ntype() const
  * - "number of atoms <= 0": some element type has no atoms
  */
 template <typename TK>
-void SpinConstrain<TK>::check_atomCounts()
+void SpinConstrain<TK>::check_atomCounts() const
 {
     if (!this->atomCounts.size())
     {
@@ -297,7 +297,7 @@ void SpinConstrain<TK>::check_atomCounts()
     {
         ModuleBase::WARNING_QUIT("SpinConstrain::check_atomCounts", "nat <= 0");
     }
-    for (std::map<int, int>::iterator it = this->atomCounts.begin(); it != this->atomCounts.end(); ++it)
+    for (std::map<int, int>::const_iterator it = this->atomCounts.begin(); it != this->atomCounts.end(); ++it)
     {
         int itype = it->first;
         if (itype < 0 || itype >= this->get_ntype())
@@ -342,7 +342,7 @@ int SpinConstrain<TK>::get_iat(int itype, int atom_index)
         ModuleBase::WARNING_QUIT("SpinConstrain::get_iat", "atom index out of range [0, nat)");
     }
     int iat = 0;
-    for (std::map<int, int>::iterator it = this->atomCounts.begin(); it != this->atomCounts.end(); ++it)
+    for (std::map<int, int>::const_iterator it = this->atomCounts.begin(); it != this->atomCounts.end(); ++it)
     {
         if (it->first == itype)
         {
@@ -699,6 +699,13 @@ const std::vector<ModuleBase::Vector3<double>>& SpinConstrain<TK>::get_Mi() cons
     return this->Mi_;
 }
 
+/// get human-readable atom labels for table printing
+template <typename TK>
+const std::vector<std::string>& SpinConstrain<TK>::get_atomLabels() const
+{
+    return this->atomLabels_;
+}
+
 /// get nsc
 template <typename TK>
 int SpinConstrain<TK>::get_nsc() const
@@ -765,127 +772,6 @@ void SpinConstrain<TK>::set_ParaV(Parallel_Orbitals* ParaV_in)
     }
 }
 
-/**
- * @brief Print magnetic moments per atom in formatted table.
- *
- * @par Output format
- * - nspin=2: "ATOM   1    2.0000000000" (z-component only)
- * - nspin=4: "ATOM   1    0.0010000000    0.0020000000    1.9990000000" (x, y, z)
- *
- * @par Interpretation
- * - Positive Mi.z: spin aligned with z-axis (spin-up character)
- * - Negative Mi.z: spin anti-aligned with z-axis (spin-down character)
- * - Non-zero Mi.x/Mi.y: non-collinear spin components
- * - Mi close to target_mag: constraint is well-satisfied
- * - Mi far from target_mag: constraint is not yet converged
- */
-template <typename TK>
-void SpinConstrain<TK>::print_Mi(std::ofstream& ofs_running)
-{
-    this->check_atomCounts();
-    int nat = this->get_nat();
-    std::vector<double> mag_x(nat, 0.0);
-    std::vector<double> mag_y(nat, 0.0);
-    std::vector<double> mag_z(nat, 0.0);
-    if (this->nspin_ == 2)
-    {
-        const std::vector<std::string> title = {"Total Magnetism (uB)", ""};
-        const std::vector<std::string> fmts = {"%-26s", "%20.10f"};
-        FmtTable table(/*titles=*/title, 
-                       /*nrows=*/nat, 
-                       /*formats=*/fmts, 
-                       /*indent=*/0,
-                       /*align=*/{/*value*/FmtTable::Align::RIGHT, /*title*/FmtTable::Align::LEFT});
-        for (int iat = 0; iat < nat; ++iat)
-        {
-            mag_z[iat] = Mi_[iat].z;
-        }
-        table << this->atomLabels_ << mag_z;
-        ofs_running << table.str() << std::endl;
-    }
-    else if (this->nspin_ == 4)
-    {
-        const std::vector<std::string> title = {"Total Magnetism (uB)", "", "", ""};
-        const std::vector<std::string> fmts = {"%-26s", "%20.10f", "%20.10f", "%20.10f"};
-        FmtTable table(/*titles=*/title, 
-                       /*nrows=*/nat, 
-                       /*formats=*/fmts, 
-                       /*indent=*/0,
-                       /*align=*/{/*value*/FmtTable::Align::RIGHT, /*title*/FmtTable::Align::LEFT});
-        for (int iat = 0; iat < nat; ++iat)
-        {
-            mag_x[iat] = Mi_[iat].x;
-            mag_y[iat] = Mi_[iat].y;
-            mag_z[iat] = Mi_[iat].z;
-        }
-        table << this->atomLabels_ << mag_x << mag_y << mag_z;
-        ofs_running << table.str() << std::endl;
-    }
-}
-
-/**
- * @brief Print the magnetic force (-lambda) per atom in eV/uB.
- *
- * @par Physical meaning
- * The "magnetic force" is the derivative of the constrained Lagrangian
- * with respect to the magnetic moment: dL/dMi = -lambda_i.
- * It represents how much energy would change if the constraint were relaxed.
- *
- * @par Interpretation
- * - Large |lambda|: The system strongly resists the target moment constraint
- * - lambda ≈ 0: The system naturally has the target moment (no constraint needed)
- * - Positive lambda.z: The constraint pushes the moment in the +z direction
- * - Negative lambda.z: The constraint pushes the moment in the -z direction
- *
- * @par Typical values
- * - Well-converged SCF: lambda ~ 0.01-1 eV/uB
- * - Strongly constrained: lambda ~ 1-10 eV/uB
- * - Diverging SCF: lambda growing without bound (check target_mag合理性)
- */
-template <typename TK>
-void SpinConstrain<TK>::print_Mag_Force(std::ofstream& ofs_running)
-{
-    this->check_atomCounts();
-    int nat = this->get_nat();
-    std::vector<double> mag_force_x(nat, 0.0);
-    std::vector<double> mag_force_y(nat, 0.0);
-    std::vector<double> mag_force_z(nat, 0.0);
-    if (this->nspin_ == 2)
-    {
-        const std::vector<std::string> title = {"Magnetic force (eV/uB)", ""};
-        const std::vector<std::string> fmts = {"%-26s", "%20.10f"};
-        FmtTable table(/*titles=*/title, 
-                       /*nrows=*/nat, 
-                       /*formats=*/fmts, 
-                       /*indent=*/0,
-                       /*align=*/{/*value*/FmtTable::Align::RIGHT, /*title*/FmtTable::Align::LEFT});
-        for (int iat = 0; iat < nat; ++iat)
-        {
-            mag_force_z[iat] = lambda_[iat].z * ModuleBase::Ry_to_eV;
-        }
-        table << this->atomLabels_ << mag_force_z;
-        ofs_running << table.str() << std::endl;
-    }
-    else if (this->nspin_ == 4)
-    {
-        const std::vector<std::string> title = {"Magnetic force (eV/uB)", "", "", ""};
-        const std::vector<std::string> fmts = {"%-26s", "%20.10f", "%20.10f", "%20.10f"};
-        FmtTable table(/*titles=*/title, 
-                       /*nrows=*/nat, 
-                       /*formats=*/fmts, 
-                       /*indent=*/0,
-                       /*align=*/{/*value*/FmtTable::Align::RIGHT, /*title*/FmtTable::Align::LEFT});
-        for (int iat = 0; iat < nat; ++iat)
-        {
-            mag_force_x[iat] = lambda_[iat].x * ModuleBase::Ry_to_eV;
-            mag_force_y[iat] = lambda_[iat].y * ModuleBase::Ry_to_eV;
-            mag_force_z[iat] = lambda_[iat].z * ModuleBase::Ry_to_eV;
-        }
-        table << this->atomLabels_ << mag_force_x << mag_force_y << mag_force_z;
-        ofs_running << table.str() << std::endl;
-    }
-}
-
 /**
  * @brief Reset DeltaSpin operator initialization state.
  *