better documentation of th ECP block

trex.org

@@ -118,7 +118,7 @@ arrays are 0-based. Hence, we introduce the ~index~ type which is an
 * Effective core potentials (ecp group)
 
   An effective core potential (ECP) $V_A^{\text{ECP}}$ replacing the
-  core electrons of atom $A$ is expressed as
+  core electrons of atom $A$ can be expressed as
   \[
   V_A^{\text{ECP}} =
   V_{A \ell_{\max}+1} +
@@ -127,6 +127,9 @@ arrays are 0-based. Hence, we introduce the ~index~ type which is an
   V_{A \ell} - V_{A \ell_{\max}+1} \right] \langle Y_{\ell m} | 
   \]
 
+  The first term in the equation above is sometimes attributed to the local channel,
+  while the remaining terms correspond to the non-local channel projections.
+
   The functions $V_{A\ell}$ are parameterized as:
   \[
   V_{A \ell}(\mathbf{r}) =
@@ -135,13 +138,13 @@ arrays are 0-based. Hence, we introduce the ~index~ type which is an
   e^{-\alpha_{A q \ell} |\mathbf{r}-\mathbf{R}_{A}|^2 }
   \]
   
-  See http://dx.doi.org/10.1063/1.4984046 for more info.
+  See http://dx.doi.org/10.1063/1.4984046 or https://doi.org/10.1063/1.5121006for more info.
   
   #+NAME: ecp
   | Variable             | Type    | Dimensions      | Description                                                                            |
   |----------------------+---------+-----------------+----------------------------------------------------------------------------------------|
   | ~max_ang_mom_plus_1~ | ~int~   | ~(nucleus.num)~ | $\ell_{\max}+1$, one higher than the max angular momentum in the removed core orbitals |
-  | ~z_core~             | ~float~ | ~(nucleus.num)~ | Charges to remove                                                                      |
+  | ~z_core~             | ~float~ | ~(nucleus.num)~ | Number of core electrons to remove per atom                                            |
   | ~num~                | ~dim~   |                 | Total number of ECP functions for all atoms and all values of $\ell$                   |
   | ~ang_mom~            | ~int~   | ~(ecp.num)~     | One-to-one correspondence between ECP items and the angular momentum $\ell$            |
   | ~nucleus_index~      | ~index~ | ~(ecp.num)~     | One-to-one correspondence between ECP items and the atom index                         |
@@ -150,10 +153,17 @@ arrays are 0-based. Hence, we introduce the ~index~ type which is an
   | ~power~              | ~int~   | ~(ecp.num)~     | $n_{A q \ell}$ all ECP powers                                                          |
 
 
+There might be some confusion in the meaning of the $\ell_{\max}$. 
+It can be attributed to the maximum angular momentum occupied 
+in the core orbitals, which are removed by the ECP.
+On the other hand, it can be attributed to the maximum angular momentum of the 
+ECP that replaces the core electrons. 
+*Note*, that the latter $\ell_{\max}$ is always higher by 1 than the former.
+
+
 *Note for developers*: avoid having variables with similar prefix in their name. 
-HDF5 back end might cause issues due to the way `find_dataset` function works 
-in the H5LT module. For example, in the ECP group we use ~max_ang_mom~ and 
-~ang_mom_max~ due to this. 
+HDF5 back end might cause issues due to the way `find_dataset` function works.
+For example, in the ECP group we use ~max_ang_mom~ and not ~ang_mom_max~. 
 The latter causes issues when written before ~ang_mom~ in the TREXIO file.
 
 
@@ -202,19 +212,19 @@ max_ang_mom_plus_1 = [ 1, 1 ]
 # number of core electrons to remove per atom
 zcore = [ 0, 0 ]
 
-# first 4 ECP elements correspond to the first H atom, same for the second H atom
+# first 4 ECP elements correspond to the first H atom; the remaining 4 elements are for the second H atom
 nucleus_index = [
   0, 0, 0, 0,
   1, 1, 1, 1
   ]
 
-# 3 first ECP elements correspond to l=1 of the first H atom, then 1 ECP for l=0; same for the second H atom 
+# 3 first ECP elements correspond to the P orbital (l=1), then 1 element for the S orbital (l=0) ; similar for the second H atom 
 ang_mom = [
   1, 1, 1, 0,
   1, 1, 1, 0
   ]
 
-# flat arrays with ECP quantities that can be parsed based on the aforementioned ecp_ang_mom and ecp_nucleus
+# ECP quantities that can be attributed to atoms and/or angular momenta based on the aforementioned ecp_nucleus and ecp_ang_mom arrays
 coefficient = [
   1.00000000000000, 21.24359508259891, -10.85192405303825, 0.00000000000000,
   1.00000000000000, 21.24359508259891, -10.85192405303825, 0.00000000000000