More documentation in TREX JSON

trex.org

@@ -1,6 +1,11 @@
 #+TITLE: TREX Configuration file
 
 All the quantities are saved in atomic units.
+The dimensions of the arrays in the tables below are given in
+column-major order (as in Fortran), and the ordering of the dimensions
+is reversed in the produces JSON configuration file as the library is
+written in C.
+
   #+begin_src python :tangle trex.json 
 {
   #+end_src
@@ -8,9 +13,15 @@ All the quantities are saved in atomic units.
 
 * Metadata
   
+  As we expect our files to be archived in open-data repositories, we
+  need to give the possibility to the users to store some metadata
+  inside the files. We propose to store the list of names of the codes
+  which have participated to the creation of the file, a list of
+  authors of the file, and a textual description.
+
   #+NAME: metadata
   | ~code_num~    | ~int~ |                         | Number of codes used to produce the file |
-  | ~code ~       | ~str~ | ~(metadata.code_num)~   | Names of the codes used                  |
+  | ~code~        | ~str~ | ~(metadata.code_num)~   | Names of the codes used                  |
   | ~author_num~  | ~int~ |                         | Number of authors of the file            |
   | ~author~      | ~str~ | ~(metadata.author_num)~ | Names of the authors of the file         |
   | ~description~ | ~str~ |                         | Text describing the content of file      |
@@ -19,21 +30,24 @@ All the quantities are saved in atomic units.
   #+RESULTS:
   :results:
   #+begin_src python :tangle trex.json
-      "metadata": {
+"metadata": {
     "code_num" : [ "int", []                        ]
     ,       "code " : [ "str", [ "metadata.code_num" ]   ]
     ,  "author_num" : [ "int", []                        ]
     ,      "author" : [ "str", [ "metadata.author_num" ] ]
     , "description" : [ "str", []                        ]
-      } ,
+} ,
   #+end_src
   :end:
 
 * Electron
 
+   We consider wave functions expressed in the spin-free formalism, where
+   the number of \uparrow and \downarrow electrons is fixed.
+
   #+NAME:electron
-  | ~up_num~ | ~int~ | Number of $\uparrow$-spin electrons   |
+  | ~up_num~ | ~int~ | Number of \uparrow-spin electrons   |
-  | ~dn_num~ | ~int~ | Number of $\downarrow$-spin electrons |
+  | ~dn_num~ | ~int~ | Number of \downarrow-spin electrons |
 
   #+CALL: json(data=electron, title="electron")
   #+RESULTS:
@@ -48,10 +62,13 @@ All the quantities are saved in atomic units.
 
 * Nucleus
 
+  The nuclei are considered as fixed point charges. Coordinates are
+  given in Cartesian $(x,y,z)$ format.
+
   #+NAME: nucleus
   | ~num~         | ~int~   |                   | Number of nuclei         |
   | ~charge~      | ~float~ | ~(nucleus.num)~   | Charges of the nuclei    |
-  | ~coord~       | ~float~ | ~(nucleus.num, 3)~ | Coordinates of the atoms |
+  | ~coord~       | ~float~ | ~(3,nucleus.num)~ | Coordinates of the atoms |
   | ~label~       | ~str~   | ~(nucleus.num)~   | Atom labels              |
   | ~point_group~ | ~str~   |                   | Symmetry point group     |
 
@@ -71,29 +88,57 @@ All the quantities are saved in atomic units.
 
 * TODO Effective core potentials
 
-  - $\hat{V}_\text{ecp,l} =$ : local component
+  An effective core potential (ECP) $V_A^{\text{pp}}$ replacing the
-  - $\hat{V}_\text{ecp,nl} =$ : non-local component
+  core electrons of atom $A$ is the sum of a local component
+  $V_A^{\text{l}}$ and a non-local component $V_A^{\text{nl}}$.
+  The local component is given by
+
+  \[
+  \hat{V}_A^{\text{l}}(r) = -\frac{Z_A^{\text{eff}}}{r} +
+  \frac{Z_A^{\text{eff}}}{r}\, \exp\left( -\alpha_A\, r^2\right) +
+  Z_{\text{eff}}\, \alpha_A\, r\, \exp\left( -\beta_A\, r^2\right) +
+  \gamma_A \exp\left( -\delta_A\, r^2\right),
+  \]
+
+  and the component obtained after localizing the non-local operator is
+
+  \[
+  \hat{V}_A^{\text{nl}}(r) =
+  \zeta_A\, \exp\left( -\eta_A\, r^2\right) |0\rangle \langle 0| +
+  \mu_A \,  \exp\left( -\nu_A \, r^2\right) |1\rangle \langle 1|
+  \]
+
+  where $r=|\mathbf{r-R}_A|$ is the distance to the nucleus on which the
+  potential is centered, $Z_A^{\text{eff}}$ is the effective charge
+  due to the removed electrons, $|0\rangle \langle 0|$
+  and $|1\rangle \langle 1|$ are projections over zero and one principal angular
+  momenta, respectively (generalization to higher angular momenta is
+  straightforward),  and all the parameters labeled by Greek
+  letters are parameters.
+
+  - $\hat{V}_\text{ecp,l} = \sum_A \hat{V}_A^{\text{l}}$ : local component
+  - $\hat{V}_\text{ecp,nl} = \sum_A \hat{V}_A^{\text{nl}}$ : non-local component
 
   #+NAME: ecp
   | ~lmax_plus_1~         | ~int~   | ~(nucleus.num)~                          | $l_{\max} + 1$             |
   | ~z_core~              | ~float~ | ~(nucleus.num)~                          | Charges to remove          |
   | ~local_n~             | ~int~   | ~(nucleus.num)~                          | Number of local function   |
   | ~local_num_n_max~     | ~int~   |                                          | Maximum value of ~local_n~ |
-  | ~local_exponent~      | ~float~ | ~(nucleus.num, ecp.local_num_n_max)~     |                            |
+  | ~local_exponent~      | ~float~ | ~(ecp.local_num_n_max, nucleus.num)~     |                            |
-  | ~local_coef~          | ~float~ | ~(nucleus.num, ecp.local_num_n_max)~     |                            |
+  | ~local_coef~          | ~float~ | ~(ecp.local_num_n_max, nucleus.num)~     |                            |
-  | ~local_power~         | ~int~   | ~(nucleus.num, ecp.local_num_n_max)~     |                            |
+  | ~local_power~         | ~int~   | ~(ecp.local_num_n_max, nucleus.num)~     |                            |
   | ~non_local_n~         | ~int~   | ~(nucleus.num)~                          |                            |
   | ~non_local_num_n_max~ | ~int~   |                                          |                            |
-  | ~non_local_exponent~  | ~float~ | ~(nucleus.num, ecp.non_local_num_n_max)~ |                            |
+  | ~non_local_exponent~  | ~float~ | ~(ecp.non_local_num_n_max, nucleus.num)~ |                            |
-  | ~non_local_coef~      | ~float~ | ~(nucleus.num, ecp.non_local_num_n_max)~ |                            |
+  | ~non_local_coef~      | ~float~ | ~(ecp.non_local_num_n_max, nucleus.num)~ |                            |
-  | ~non_local_power~     | ~int~   | ~(nucleus.num, ecp.non_local_num_n_max)~ |                            |
+  | ~non_local_power~     | ~int~   | ~(ecp.non_local_num_n_max, nucleus.num)~ |                            |
 
   #+CALL: json(data=ecp, title="ecp")
 
   #+RESULTS:
   :results:
   #+begin_src python :tangle trex.json
-      "ecp": {
+"ecp": {
     "lmax_plus_1" : [ "int"  , [ "nucleus.num" ]                            ]
     ,              "z_core" : [ "float", [ "nucleus.num" ]                            ]
     ,             "local_n" : [ "int"  , [ "nucleus.num" ]                            ]
@@ -106,12 +151,38 @@ All the quantities are saved in atomic units.
     ,  "non_local_exponent" : [ "float", [ "nucleus.num", "ecp.non_local_num_n_max" ] ]
     ,      "non_local_coef" : [ "float", [ "nucleus.num", "ecp.non_local_num_n_max" ] ]
     ,     "non_local_power" : [ "int"  , [ "nucleus.num", "ecp.non_local_num_n_max" ] ]
-      } ,
+} ,
   #+end_src
   :end:
 
 * Basis set
 
+  We consider here basis functions centered on nuclei. Hence, we enable
+  the possibility to define \emph{dummy atoms} to place basis functions
+  in random positions.
+
+  The atomic basis set is defined as a list of shells. Each shell $s$ is
+  centered on a center $A$, possesses a given angular momentum $l$ and a
+  radial function $R_s$. The radial function is a linear combination of
+  $N_{\text{prim}}$ /primitive/ functions that can be of type
+  Slater ($p=1$) or Gaussian ($p=2$),
+  parameterized by exponents $\gamma_{ks}$ and coefficients $a_{ks}$:
+  \[
+  R_s(\mathbf{r}) = \mathcal{N}_s \vert\mathbf{r}-\mathbf{R}_A\vert^{n_s}
+  \sum_{k=1}^{N_{\text{prim}}} a_{ks}
+  \exp \left( - \gamma_{ks}
+  \vert \mathbf{r}-\mathbf{R}_A \vert ^p \right). 
+  \]
+
+  In the case of Gaussian functions, $n_s$ is always zero.  The
+  normalization factor $\mathcal{N}_s$ ensures that all the functions
+  of the shell are normalized to unity. As this normalization requires
+  the ability to compute overlap integrals, the normalization factors
+  should be written in the file to ensure that the file is
+  self-contained and does not require the client program to have the
+  ability to compute such integrals.
+
+
   #+NAME: basis
   | ~type~           | ~str~   |                     | Type of basis set: "Gaussian" or "Slater"         |
   | ~shell_num~      | ~int~   |                     | Total Number of shells                            |
@@ -146,30 +217,72 @@ All the quantities are saved in atomic units.
 
 * Atomic orbitals
 
+  Going from the atomic basis set to AOs implies a systematic
+  construction of all the angular functions of each shell.  We
+  consider two cases for the angular functions: the real-valued
+  spherical harmonics, and the polynomials in Cartesian coordinates.
+  In the case of spherical harmonics, the AOs are ordered in
+  increasing magnetic quantum number ($-l \le m \le l$), and in the case
+  of polynomials we impose the canonical ordering of the
+  Libint2 library, i.e
+
+  \begin{eqnarray}
+  p & : & p_x, p_y, p_z \nonumber \\
+  d & : & d_{xx}, d_{xy}, d_{xz}, d_{yy}, d_{yz}, d_{zz} \nonumber \\
+  f & : & f_{xxx}, f_{xxy}, f_{xxz}, f_{xyy}, f_{xyz}, f_{xzz}, f_{yyy}, f_{yyz}, f_{yzz},      …f_{zzz} \nonumber \\
+  {\rm etc.} \nonumber
+  \end{eqnarray}
+
+  AOs are defined as
+
+  \[
+  \chi_i (\mathbf{r}) = \mathcal{N}_i\, P_{\eta(i)}(\mathbf{r})\, R_{\theta(i)} (\mathbf{r})
+  \]
+
+  where $i$ is the atomic orbital index,
+  $P$ encodes for either the
+  polynomials or the spherical harmonics, $\theta(i)$ returns the
+  shell on which the AO is expanded, and $\eta(i)$ denotes which
+  angular function is chosen.
+  $\mathcal{N}_i$ is a normalization factor that enables the
+  possibility to have different normalization coefficients within a
+  shell, as in the GAMESS convention where
+  $\mathcal{N}_{x^2} \ne \mathcal{N}_{xy}$ because
+  \[ \left[ \iiint \left(x-X_A \right)^2 R_{\theta(i)}
+  (\mathbf{r}) dx\, dy\, dz \right]^{-1/2} \ne 
+   \left[ \iiint \left( x-X_A \right) \left( y-Y_A \right) R_{\theta(i)}
+  (\mathbf{r}) dx\, dy\, dz \right]^{-1/2}.  \] 
+
+  In such a case, one should set the normalization of the shell (in
+  the [[Basis set][Basis set]] section) to $\mathcal{N}_{z^2}$, which is the
+  normalization factor of the atomic orbitals in spherical coordinates.
+  The normalization factor of the $xy$ function which should be
+  introduced here should be $\frac{\mathcal{N}_{xy}}{\mathcal{N}_{z^2}}$.
+
   #+NAME: ao
-  | ~num~           | ~int~   |          | Number of atomic orbitals       |
   | ~cartesian~     | ~int~   |          | ~1~: true, ~0~: false           |
-  | ~shell~         | ~int~   | ~ao.num~ | ID of the basis set shell       |
+  | ~num~           | ~int~   |          | Total number of atomic orbitals |
-  | ~normalization~ | ~float~ | ~ao.num~ | Normalization factor of the AOs |
+  | ~shell~         | ~int~   | ~ao.num~ | basis set shell for each AO     |
+  | ~normalization~ | ~float~ | ~ao.num~ | Normalization factors           |
 
   #+CALL: json(data=ao, title="ao")
 
   #+RESULTS:
   :results:
   #+begin_src python :tangle trex.json
-      "ao": {
+"ao": {
     "num" : [ "int"  , []  ]
     ,     "cartesian" : [ "int"  , []  ]
     ,         "shell" : [ "int"  , []  ]
     , "normalization" : [ "float", []  ]
-      } ,
+} ,
   #+end_src
   :end:
     
 ** One-electron integrals
    
    - \[ \hat{V}_{\text{ne}} = \sum_{A=1}^{N_\text{nucl}}
-    \sum_{i=1}^{N_\text{elec}} \frac{-Q_A }{\vert \mathbf{R}_A -
+     \sum_{i=1}^{N_\text{elec}} \frac{-Z_A }{\vert \mathbf{R}_A -
      \mathbf{r}_i \vert} \] : electron-nucleus attractive potential,
    - \[ \hat{T}_{\text{e}} = 
      \sum_{i=1}^{N_\text{elec}} -\frac{1}{2}\hat{\Delta}_i \] : electronic kinetic energy
@@ -193,14 +306,14 @@ All the quantities are saved in atomic units.
    #+RESULTS:
    :results:
    #+begin_src python :tangle trex.json
-      "ao_1e_int": {
+"ao_1e_int": {
     "overlap" : [ "float", [ "ao.num", "ao.num" ] ]
     ,          "kinetic" : [ "float", [ "ao.num", "ao.num" ] ]
     ,    "potential_n_e" : [ "float", [ "ao.num", "ao.num" ] ]
     ,        "ecp_local" : [ "float", [ "ao.num", "ao.num" ] ]
     ,    "ecp_non_local" : [ "float", [ "ao.num", "ao.num" ] ]
     , "core_hamiltonian" : [ "float", [ "ao.num", "ao.num" ] ]
-      } ,
+} ,
    #+end_src
    :end:
 
@@ -230,10 +343,10 @@ All the quantities are saved in atomic units.
    #+RESULTS:
    :results:
    #+begin_src python :tangle trex.json
-      "ao_2e_int": {
+"ao_2e_int": {
     "eri" : [ "float sparse", [ "ao.num", "ao.num", "ao.num", "ao.num" ] ]
     , "eri_lr" : [ "float sparse", [ "ao.num", "ao.num", "ao.num", "ao.num" ] ]
-      } ,
+} ,
    #+end_src
    :end:
 
@@ -371,6 +484,7 @@ for line in data:
     if '(' in dims:
         dims = dims.strip()[1:-1]
         dims = [ '"'+x.strip()+'"' for x in dims.split(',') ]
+        dims.reverse()
         dims = "[ " + ", ".join(dims) + " ]"
     else:
         dims = "[]"