add doxygen-style comments in LCAO_Descriptor class

.readthedocs.yaml

@@ -7,7 +7,8 @@ version: 2
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
-   configuration: ABACUS.develop/source/module_orbital/1_Documents/sphinx/source/conf.py
+   configuration: source/module_deepks/doc/sphinx/source/conf.py
+#   configuration: source/module_orbital/1_Documents/sphinx/source/conf.py
 
 # Optionally build your docs in additional formats such as PDF
 formats:
@@ -17,4 +18,4 @@ formats:
 python:
    version: 3.7
    install:
-   - requirements: ABACUS.develop/source/module_orbital/1_Documents/sphinx/requirements.txt
+   - requirements: source/module_orbital/1_Documents/sphinx/requirements.txt

doc/developers.md

@@ -38,6 +38,8 @@ For comments that need to be shown in documents, these formats should be used --
 
 A helpful VS Code extension -- Doxygen Documentation Generator, can help you formating comments.
 
+An practical example is class [LCAO_Descriptor](https://github.com/deepmodeling/abacus-develop/source/src_lcao/LCAO_descriptor.h), the effects can be seen on [readthedocs page](remaining, need to deploy)
+
 - Detailed Comment Block
     ```
     /**

source/module_deepks/doxygen/conf_dpks

@@ -0,0 +1,9 @@
+PROJECT_NAME = module_deepks
+INPUT = ../../src_lcao
+PROJECT_BRIEF = "DeePKS: Generate descriptors, load a model and calculate energy and force."
+OUTPUT_DIRECTORY = .
+FILE_PATTERNS = LCAO_descriptor*
+EXTRACT_ALL = YES
+USE_MATHJAX = YES
+GENERATE_XML = YES
+ENABLE_PREPROCESSING = NO

source/module_deepks/sphinx/requirements.txt

@@ -0,0 +1,5 @@
+sphinx
+breathe
+exhale
+sphinx_rtd_theme
+myst_parser

source/module_deepks/sphinx/source/conf.py

@@ -0,0 +1,83 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
+sys.path.append( "/usr/local/lib/python3.9/site-packages/breathe" )
+
+# -- Project information -----------------------------------------------------
+
+project = 'ABACUS-DeePKS'
+copyright = '2021, x'
+
+# The full version, including alpha/beta/rc tags
+release = '0.1'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [ 'sphinx.ext.todo', 'breathe', 'exhale', 'sphinx.ext.mathjax', "sphinx_rtd_theme", 'myst_parser'
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_rtd_theme"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# -- Options for breathe -------------------------------------------------
+
+breathe_projects = { "ABACUS-DeePKS": "../../doxygen/xml/" }
+breathe_default_project = "ABACUS-DeePKS"
+
+#-- Options for exhale-------------------------------------
+# Setup the exhale extension
+exhale_args = {
+    # These arguments are required
+    "containmentFolder":     "./DeePKS_API",
+    "rootFileName":          "library_root.rst",
+    "rootFileTitle":         "DeePKS",
+    "doxygenStripFromPath":  "..",
+    # Suggested optional arguments
+    "createTreeView":        True,
+    # TIP: if using the sphinx-bootstrap-theme, you need
+    # "treeViewIsBootstrap": True,
+    #"exhaleExecutesDoxygen": True,
+    #"exhaleDoxygenStdin":    "INPUT = ../../src_lcao"
+}
+
+# Tell sphinx what the primary language being documented is.
+primary_domain = 'cpp'
+
+# Tell sphinx what the pygments highlight language should be.
+highlight_language = 'cpp'

source/module_deepks/sphinx/source/index.rst

@@ -0,0 +1,25 @@
+.. test_orb documentation master file, created by
+   sphinx-quickstart on Fri Jun 11 16:54:33 2021.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to ABACUS-DeePKS's documentation!
+====================================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+
+   DeePKS_API/library_root
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
+

source/src_lcao/LCAO_descriptor.h

@@ -8,11 +8,13 @@
 #include <torch/script.h>
 #include "../src_pw/global.h"
 
-//------------------------------------------------------------------------------
-// This class computes the descriptors for each atom from LCAO basis set,
-// interfaces with pytorch to obtain the correction potential in LCAO basis,
-// and computes the forces according to the correction potential
-//------------------------------------------------------------------------------
+///
+/// This class computes the descriptors for each atom from LCAO basis set,
+/// interfaces with pytorch to obtain the correction potential in LCAO basis,
+/// and computes the forces according to the correction potential.
+/// 
+/// For details of DeePKS method, you can refer to [DeePKS paper](https://pubs.acs.org/doi/10.1021/acs.jctc.0c00872).
+///
 //
 // caoyu add 2021-03-29
 //
@@ -27,78 +29,96 @@ class LCAO_Descriptor
     explicit LCAO_Descriptor();
     ~LCAO_Descriptor();
 
-     //only for descriptor part, not including scf
-    void init(const int lm, const int nm, const int tot_inl);
+    ///only for descriptor part, not including scf
+    void init(const int lm/**< [in] max angular momentum quantum number: 'L'*/,
+        const int nm/**< [in] max orbital number with the same 'L', for each 'L'*/,
+        const int tot_inl/**< [in] total number of radial orbitals (sum of atoms 'I', angular number 'L' and orbital number 'N') */);
 
-	// cal S_alpha_mu: overlap between lcao basis Phi and descriptor basis Al
-    void build_S_descriptor(const bool &calc_deri);
+	/// calculate\f$S_{\alpha, \mu} = \langle\alpha|\phi_\mu\rangle \f$ overlap between lcao basis Phi and descriptor basis Alpha
+    void build_S_descriptor(const bool &calc_deri/**< [in] 0 for \f$\langle\phi|\alpha\rangle\f$, 1 for \f$\langle\frac{d\phi}{dR}|\alpha\rangle\f$*/);
 
 
-	// 1. Load DeePKS model
-    // 2. Initialize the deltaV Hamiltonian matrix 
-    // 3. If FORCE, initialize the matrces for force
-    void deepks_pre_scf(const std::string& model_file);
+	/// 1. Load DeePKS model
+    /// 2. Initialize the deltaV Hamiltonian matrix 
+    /// 3. If FORCE, initialize the matrces for force
+    void deepks_pre_scf(const std::string& model_file/**< [in] path of a traced model file, provided by deepks-kit*/);
 
 
-	//------------------------------------------------------------------------------
-	// cal_projected_DM: pdm = S_alpha_mu * inv(Sloc) * DM * inv(Sloc) * S_nu_beta
-	// cal_descriptor: EIGENVALUE of pdm in block of I_n_l
-	// cal_dm_as_descriptor: compute the descriptor for each atom
-	// cal_v_delta: compute <psi|deltaV|psi>
-	// add_v_delta: add <psi|deltaV|psi> to the Hamiltonian matrix
-	// cal_f_delta: compute the force related to deltaV, input dm is density matrix
-	//------------------------------------------------------------------------------
-    void cal_projected_DM(const ModuleBase::matrix &dm);
+    //S_alpha_mu * DM  * S_nu_beta
+    ///calculate projected density matrix:
+    ///\f[D^ I_{ nlmm'} = \sum_{i}\sum_{\mu, \nu}\langle\alpha^I_{nlm}|\phi_\mu\rangle c_{i,\mu}c_{i,\nu} \langle\phi_\nu|\alpha^I_{nlm' }\rangle\f]
+    void cal_projected_DM(const ModuleBase::matrix& dm/**< [in] density matrix*/);
+
+    ///EIGENVALUE of pdm in block of I_n_l
     void cal_descriptor(void);
-    void cal_dm_as_descriptor(const ModuleBase::matrix& dm); // mohan add 2021-08-04
+
+    ///compute the descriptor for each atom
+    void cal_dm_as_descriptor(const ModuleBase::matrix& dm/**< [in] density matrix*/); // mohan add 2021-08-04
 
-    void cal_gedm(const ModuleBase::matrix& dm);	//need to load model in this step
-    void build_v_delta_alpha(const bool& cal_deri);
-    void build_v_delta_mu(const bool& cal_deri);
-    void cal_v_delta(const ModuleBase::matrix& dm);
+    ///calculate \f$\frac{dE_\delta}{dD^I_{nlmm'}}\f$
+    void cal_gedm(const ModuleBase::matrix& dm/**< [in] density matrix*/);	//need to load model in this step
+
+    ///calculate \f$\sum_{I}\sum_{nlmm'}\langle\phi_\mu|\alpha^I_{nlm}\rangle{\frac{dE}{dD^I_{nlmm'}}}\langle\alpha^I_{nlm'}|\phi_\nu\rangle\f$ (for gamma_only)
+    void build_v_delta_alpha(const bool& cal_deri/**< [in] 0 for 3-center intergration, 1 for its derivation*/);
+
+    ///calculate \f$\sum_{I}\sum_{nlmm'}\langle\phi_\mu|\alpha^I_{nlm}\rangle{\frac{dE}{dD^I_{nlmm'}}}\langle\alpha^I_{nlm'}|\phi_\nu\rangle\f$ (for multi-k)
+    void build_v_delta_mu(const bool &cal_deri/**< [in] 0 for 3-center intergration, 1 for its derivation*/);
+
+    ///compute \f$H_{\delta, \mu\nu} = \langle\phi_\mu|V_\delta|\phi_\nu\rangle\f$ 
+    void cal_v_delta(const ModuleBase::matrix& dm/**< [in] density matrix*/);
+
+    ///add \f$H_{\delta, \mu\nu}\f$ to the Hamiltonian matrix
     void add_v_delta(void);
 
-    void cal_f_delta_hf(const ModuleBase::matrix& dm);
-    void cal_f_delta_pulay(const ModuleBase::matrix& dm);
-    void cal_f_delta(const ModuleBase::matrix& dm);
-
-
-	//----------------------------------------------------------------------
-	// print_descriptors: print descriptors based on LCAO basis
-	// print_H_V_delta: print the deltaV matrix in LCAO basis
-	// print_F_delta: print the force related to deltaV for each atom
-	//----------------------------------------------------------------------
-	void print_descriptor(void);
-	void print_H_V_delta(void);
-	void print_F_delta(const std::string& fname);
-
-	//----------------------------------------------------------------------
-	/*These 3 functions save the [dm_eig], [e_base], [f_base]
-	of current configuration as .npy file, when deepks_scf = 1.
-	After a full group of consfigurations are calculated,
-    we need a python script to 'load' and 'torch.cat' these .npy files,
-    and get l_e_delta and l_f_delta corresponding to the exact e,f data.*/
-	//----------------------------------------------------------------------
+    ///compute Hellmann-Feynman term of the force contribution of \f$E_\delta\f$
+    void cal_f_delta_hf(const ModuleBase::matrix& dm/**< [in] density matrix*/);
+
+    ///compute Pulay  term of the force contribution of \f$E_\delta\f$
+    void cal_f_delta_pulay(const ModuleBase::matrix& dm/**< [in] density matrix*/);
+
+    ///compute the force contribution of \f$E_\delta\f$
+    void cal_f_delta(const ModuleBase::matrix& dm/**< [in] density matrix*/);
+
+
+    ///print descriptors based on LCAO basis
+    void print_descriptor(void);
+
+    ///print the \f$H_\delta\f$ matrix in LCAO basis
+    void print_H_V_delta(void);
+
+    ///print the force related to\f$V_\delta\f$ for each atom
+    void print_F_delta(const std::string &fname/**< [in] the name of output file*/);
+
+	///----------------------------------------------------------------------
+	///The following 3 functions save the `[dm_eig], [e_base], [f_base]`
+	///of current configuration as `.npy` file, when `deepks_scf = 1`.
+	///After a full group of consfigurations are calculated,
+    ///we need a python script to `load` and `torch.cat` these `.npy` files,
+    ///and get `l_e_delta,npy` and `l_f_delta.npy` corresponding to the exact E, F data.
+    /// 
+    /// Unit of energy: Ry
+    ///
+    /// Unit of force: Ry/Bohr
+    ///----------------------------------------------------------------------
 	void save_npy_d(void);
-	void save_npy_e(const double &ebase);	//Ry
-	void save_npy_f(const ModuleBase::matrix &fbase);//Ry
+	void save_npy_e(const double &ebase/**<[in] \f$E_{base}\f$, 'en.etot', in Ry*/);
+	void save_npy_f(const ModuleBase::matrix &fbase/**<[in] \f$F_{base}\f$, in Ry/Bohr*/);
 
-    void cal_e_delta_band(const std::vector<ModuleBase::matrix>& dm);	//tr[rho*H_V_delta]
+    ///calculate \f$tr(\rho H_\delta), \rho = \sum_i{c_{i, \mu}c_{i,\nu}} \f$ (for gamma_only)
+    void cal_e_delta_band(const std::vector<ModuleBase::matrix>& dm/**<[in] density matrix*/);
 //-------------------
 // public variables 
 //-------------------
 public:
-
-	//------------------------------------------------------
-    //E_delta: in Ry, correction energy provided by NN
-    //e_delta_band: tr(dm*H_V_delta)
-    //H_V_delta: correction term to the Hamiltonian matrix 
-	//F_delta: in Ry/Bohr, force due to the correction term
-	//------------------------------------------------------
+
+    ///(Unit: Ry) Correction energy provided by NN
     double E_delta = 0.0;
-    double e_delta_band=0.0;
+    ///(Unit: Ry)  \f$tr(\rho H_\delta), \rho = \sum_i{c_{i, \mu}c_{i,\nu}} \f$ (for gamma_only)
+    double e_delta_band = 0.0;
+    ///Correction term to the Hamiltonian matrix: \f$\langle\psi|V_\delta|\psi\rangle\f$
     double* H_V_delta;
-	ModuleBase::matrix	F_delta;
+    ///(Unit: Ry/Bohr) Total Force due to the DeePKS correction term \f$E_{\delta}\f$
+    ModuleBase::matrix	F_delta;
 
 //-------------------
 // private variables
@@ -138,15 +158,16 @@ class LCAO_Descriptor
 	//gedm:dE/dD, [tot_Inl][2l+1][2l+1]	(E: Hartree)
 	std::vector<torch::Tensor> gedm_tensor;
 
-	//gdmx: dD/dX		\sum_{mu,nu} 4*c_mu*c_nu * <dpsi_mu/dx|alpha_m><alpha_m'|psi_nu>
+	//gdmx: dD/dX		\sum_{mu,nu} 2*c_mu*c_nu * <dpsi_mu/dx|alpha_m><alpha_m'|psi_nu>
 	double*** gdmx;	//[natom][tot_Inl][2l+1][2l+1]
 	double*** gdmy;
 	double*** gdmz;
 
-	//dE/dD, autograd from loaded model(E: Ry)
+	///dE/dD, autograd from loaded model(E: Ry)
 	double** gedm;	//[tot_Inl][2l+1][2l+1]
 
-	int n_descriptor;
+    ///size of descriptor(projector) basis set
+    int n_descriptor;
 
 	// \sum_L{Nchi(L)*(2L+1)}
 	int des_per_atom;