TREX Configuration file
+Table of Contents
+-
+
- 1. Metadata (metadata group) +
- 2. Electron (electron group) +
- 3. Nucleus (nucleus group) +
- 4. TODO Effective core potentials (ecp group) +
- 5. Basis set (basis group) +
- 6. Atomic orbitals (ao group) + + +
- 7. Molecular orbitals (mo group) + + +
- 8. TODO Slater determinants +
- 9. TODO Reduced density matrices (rdm group) +
- 10. Appendix + + +
+This page contains information about the general structure of the
+TREXIO library. The source code of the library can be automatically
+generated based on the contents of the trex.json configuration file,
+which itself is compiled from different sections (groups) presented below.
+
+For more information about the automatic generation on the source code +or regarding possible modifications, please contact the TREXIO developers. +
+ +
+All quantities are saved in TREXIO file 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 produced trex.json configuration file as the library is
+written in C.
+
+In Fortran, the arrays are 1-based and in most other languages the
+arrays are 0-based. Hence, we introduce the index type which is an
+1-based int in the Fortran interface and 0-based otherwise.
+
1 Metadata (metadata group)
++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. +
+ +| Variable | +Type | +Dimensions (for arrays) | +Description | +
|---|---|---|---|
code_num |
+int |
++ | Number of codes used to produce the file | +
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 | +
2 Electron (electron group)
++We consider wave functions expressed in the spin-free formalism, where +the number of ↑ and ↓ electrons is fixed. +
+ +| Variable | +Type | +Dimensions | +Description | +
|---|---|---|---|
up_num |
+int |
++ | Number of ↑-spin electrons | +
dn_num |
+int |
++ | Number of ↓-spin electrons | +
3 Nucleus (nucleus group)
++The nuclei are considered as fixed point charges. Coordinates are +given in Cartesian \((x,y,z)\) format. +
+ +| Variable | +Type | +Dimensions | +Description | +
|---|---|---|---|
num |
+int |
++ | Number of nuclei | +
charge |
+float |
+(nucleus.num) |
+Charges of the nuclei | +
coord |
+float |
+(3,nucleus.num) |
+Coordinates of the atoms | +
label |
+str |
+(nucleus.num) |
+Atom labels | +
point_group |
+str |
++ | Symmetry point group | +
4 TODO Effective core potentials (ecp group)
++An effective core potential (ECP) \(V_A^{\text{pp}}\) replacing the +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 +
| Variable | +Type | +Dimensions | +Description | +
|---|---|---|---|
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 |
+(ecp.local_num_n_max, nucleus.num) |
++ |
local_coef |
+float |
+(ecp.local_num_n_max, nucleus.num) |
++ |
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 |
+(ecp.non_local_num_n_max, nucleus.num) |
++ |
non_local_coef |
+float |
+(ecp.non_local_num_n_max, nucleus.num) |
++ |
non_local_power |
+int |
+(ecp.non_local_num_n_max, nucleus.num) |
++ |
5 Basis set (basis group)
++We consider here basis functions centered on nuclei. Hence, we enable +the possibility to define 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}\, f_{ks}(\gamma_{ks},p)\, + \exp \left( - \gamma_{ks} + \vert \mathbf{r}-\mathbf{R}_A \vert ^p \right). + \] +
+ ++In the case of Gaussian functions, \(n_s\) is always zero. +
+ ++Different codes normalize functions at different levels. Computing +normalization factors requires the ability to compute overlap +integrals, so the normalization factors should be written in the +file to ensure that the file is self-contained and does not need the +client program to have the ability to compute such integrals. +
+ ++Some codes assume that the contraction coefficients are for a linear +combination of normalized primitives. This implies that a normalization +constant for the primitive \(ks\) needs to be computed and stored. If +this normalization factor is not required, \(f_{ks}=1\). +
+ ++Some codes assume that the basis function are normalized. This +implies the computation of an extra normalization factor, \(\mathcal{N}_s\). +If the the basis function is not considered normalized, \(\mathcal{N}_s=1\). +
+ + ++All the basis set parameters are stored in one-dimensional arrays: +
+ +| Variable | +Type | +Dimensions | +Description | +
|---|---|---|---|
type |
+str |
++ | Type of basis set: "Gaussian" or "Slater" | +
num |
+int |
++ | Total Number of shells | +
prim_num |
+int |
++ | Total number of primitives | +
nucleus_index |
+index |
+(nucleus.num) |
+Index of the first shell of each nucleus (\(A\)) | +
nucleus_shell_num |
+int |
+(nucleus.num) |
+Number of shells for each nucleus | +
shell_ang_mom |
+int |
+(basis.num) |
+Angular momentum 0:S, 1:P, 2:D, ... |
+
shell_prim_num |
+int |
+(basis.num) |
+Number of primitives in the shell (\(N_{\text{prim}}\)) | +
shell_factor |
+float |
+(basis.num) |
+Normalization factor of the shell (\(\mathcal{N}_s\)) | +
shell_prim_index |
+index |
+(basis.num) |
+Index of the first primitive in the complete list | +
exponent |
+float |
+(basis.prim_num) |
+Exponents of the primitives (\(\gamma_{ks}\)) | +
coefficient |
+float |
+(basis.prim_num) |
+Coefficients of the primitives (\(a_{ks}\)) | +
prim_factor |
+float |
+(basis.prim_num) |
+Normalization coefficients for the primitives (\(f_{ks}\)) | +
+For example, consider H2 with the following basis set (in GAMESS +format), where both the AOs and primitives are considered normalized: +
+ ++HYDROGEN +S 5 +1 3.387000E+01 6.068000E-03 +2 5.095000E+00 4.530800E-02 +3 1.159000E+00 2.028220E-01 +4 3.258000E-01 5.039030E-01 +5 1.027000E-01 3.834210E-01 +S 1 +1 3.258000E-01 1.000000E+00 +S 1 +1 1.027000E-01 1.000000E+00 +P 1 +1 1.407000E+00 1.000000E+00 +P 1 +1 3.880000E-01 1.000000E+00 +D 1 +1 1.057000E+00 1.0000000 ++ +
+we have: +
+ ++type = "Gaussian" +num = 12 +prim_num = 20 + +nucleus_index = [0 , 6] +shell_ang_mom = [0 , 0 , 0 , 1 , 1 , 2 , 0 , 0 , 0 , 1 , 1 , 2 ] +shell_prim_num = [5 , 1 , 1 , 1 , 1 , 1 , 5 , 1 , 1 , 1 , 1 , 1 ] +shell_prim_index = [0 , 5 , 6 , 7 , 8 , 9 , 10, 15, 16, 17, 18, 19] +shell_factor = [1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1.] + +exponent = +[ 33.87, 5.095, 1.159, 0.3258, 0.1027, 0.3258, 0.1027, 1.407, + 0.388, 1.057, 33.87, 5.095, 1.159, 0.3258, 0.1027, 0.3258, 0.1027, 1.407, + 0.388, 1.057] + +coefficient = +[ 0.006068, 0.045308, 0.202822, 0.503903, 0.383421, 1.0, 1.0, + 1.0, 1.0, 1.0, 0.006068, 0.045308, 0.202822, 0.503903, 0.383421, 1.0, 1.0, + 1.0, 1.0, 1.0] + +prim_factor = +[ 1.0006253235944540e+01, 2.4169531573445120e+00, 7.9610924849766440e-01 + 3.0734305383061117e-01, 1.2929684417481876e-01, 3.0734305383061117e-01, + 1.2929684417481876e-01, 2.1842769845268308e+00, 4.3649547399719840e-01, + 1.8135965626177861e+00, 1.0006253235944540e+01, 2.4169531573445120e+00, + 7.9610924849766440e-01, 3.0734305383061117e-01, 1.2929684417481876e-01, + 3.0734305383061117e-01, 1.2929684417481876e-01, 2.1842769845268308e+00, + 4.3649547399719840e-01, 1.8135965626177861e+00 ] ++
6 Atomic orbitals (ao group)
++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 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}}\). +
+ +| Variable | +Type | +Dimensions | +Description | +
|---|---|---|---|
cartesian |
+int |
++ | 1: true, 0: false |
+
num |
+int |
++ | Total number of atomic orbitals | +
shell |
+index |
+(ao.num) |
+basis set shell for each AO | +
normalization |
+float |
+(ao.num) |
+Normalization factors | +
6.1 One-electron integrals (ao_1e_int group)
+-
+
- \[ \hat{V}_{\text{ne}} = \sum_{A=1}^{N_\text{nucl}} + \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 +
- \(\hat{h} = \hat{T}_\text{e} + \hat{V}_\text{ne} + + \hat{V}_\text{ecp,l} + \hat{V}_\text{ecp,nl}\) : core electronic Hamiltonian +
+The one-electron integrals for a one-electron operator \(\hat{O}\) are +\[ \langle p \vert \hat{O} \vert q \rangle \], returned as a matrix +over atomic orbitals. +
+ +| Variable | +Type | +Dimensions | +Description | +
|---|---|---|---|
overlap |
+float |
+(ao.num, ao.num) |
+\(\langle p \vert q \rangle\) | +
kinetic |
+float |
+(ao.num, ao.num) |
+\(\langle p \vert \hat{T}_e \vert q \rangle\) | +
potential_n_e |
+float |
+(ao.num, ao.num) |
+\(\langle p \vert \hat{V}_{\text{ne}} \vert q \rangle\) | +
ecp_local |
+float |
+(ao.num, ao.num) |
+\(\langle p \vert \hat{V}_{\text{ecp,l}} \vert q \rangle\) | +
ecp_non_local |
+float |
+(ao.num, ao.num) |
+\(\langle p \vert \hat{V}_{\text{ecp,nl}} \vert q \rangle\) | +
core_hamiltonian |
+float |
+(ao.num, ao.num) |
+\(\langle p \vert \hat{h} \vert q \rangle\) | +
6.2 Two-electron integrals (ao_2e_int group)
++The two-electron integrals for a two-electron operator \(\hat{O}\) are +\[ \langle p q \vert \hat{O} \vert r s \rangle \] in physicists +notation or \[ ( pr \vert \hat{O} \vert qs ) \] in chemists +notation, where \(p,q,r,s\) are indices over atomic orbitals. +
+ ++Functions are provided to get the indices in physicists or chemists +notation. +
+ +-
+
- \[ \hat{W}_{\text{ee}} = \sum_{i=2}^{N_\text{elec}} \sum_{j=1}^{i-1} \frac{1}{\vert \mathbf{r}_i - \mathbf{r}_j \vert} \] : electron-electron repulsive potential operator. +
- \[ \hat{W}^{lr}_{\text{ee}} = \sum_{i=2}^{N_\text{elec}} + \sum_{j=1}^{i-1} \frac{\text{erf}(\vert \mathbf{r}_i - + \mathbf{r}_j \vert)}{\vert \mathbf{r}_i - \mathbf{r}_j \vert} \] : electron-electron long range potential +
| Variable | +Type | +Dimensions | +Description | +
|---|---|---|---|
eri |
+float sparse |
+(ao.num, ao.num, ao.num, ao.num) |
+Electron repulsion integrals | +
eri_lr |
+float sparse |
+(ao.num, ao.num, ao.num, ao.num) |
+Long-range Electron repulsion integrals | +
7 Molecular orbitals (mo group)
+| Variable | +Type | +Dimensions | +Description | +
|---|---|---|---|
type |
+str |
++ | String identify the set of MOs | +
num |
+int |
++ | Number of MOs | +
coefficient |
+float |
+(ao.num, mo.num) |
+MO coefficients | +
class |
+str |
+(mo.num) |
+Core, Inactive, Active, Virtual, Deleted | +
symmetry |
+str |
+(mo.num) |
+Symmetry in the point group | +
occupation |
+float |
+(mo.num) |
+Occupation number | +
7.1 One-electron integrals (mo_1e_int group)
++The operators as the same as those defined in the +AO one-electron integrals section. Here, the integrals are given in +the basis of molecular orbitals. +
+ +| Variable | +Type | +Dimensions | +Description | +
|---|---|---|---|
overlap |
+float |
+(mo.num, mo.num) |
+\(\langle i \vert j \rangle\) | +
kinetic |
+float |
+(mo.num, mo.num) |
+\(\langle i \vert \hat{T}_e \vert j \rangle\) | +
potential_n_e |
+float |
+(mo.num, mo.num) |
+\(\langle i \vert \hat{V}_{\text{ne}} \vert j \rangle\) | +
ecp_local |
+float |
+(mo.num, mo.num) |
+\(\langle i \vert \hat{V}_{\text{ecp,l}} \vert j \rangle\) | +
ecp_non_local |
+float |
+(mo.num, mo.num) |
+\(\langle i \vert \hat{V}_{\text{ecp,nl}} \vert j \rangle\) | +
core_hamiltonian |
+float |
+(mo.num, mo.num) |
+\(\langle i \vert \hat{h} \vert j \rangle\) | +
7.2 Two-electron integrals (mo_2e_int group)
++The operators as the same as those defined in the +AO two-electron integrals section. Here, the integrals are given in +the basis of molecular orbitals. +
+ +| Variable | +Type | +Dimensions | +Description | +
|---|---|---|---|
eri |
+float sparse |
+(mo.num, mo.num, mo.num, mo.num) |
+Electron repulsion integrals | +
eri_lr |
+float sparse |
+(mo.num, mo.num, mo.num, mo.num) |
+Long-range Electron repulsion integrals | +
8 TODO Slater determinants
+9 TODO Reduced density matrices (rdm group)
+| Variable | +Type | +Dimensions | +Description | +
|---|---|---|---|
one_e |
+float |
+(mo.num, mo.num) |
++ |
one_e_up |
+float |
+(mo.num, mo.num) |
++ |
one_e_dn |
+float |
+(mo.num, mo.num) |
++ |
two_e |
+float sparse |
+(mo.num, mo.num, mo.num, mo.num) |
++ |
10 Appendix
+10.1 Python script from table to json
+print("""#+begin_src python :tangle trex.json""") +print(""" "%s": {"""%(title)) +indent = " " +f1 = 0 ; f2 = 0 ; f3 = 0 +for line in data: + line = [ x.replace("~","") for x in line ] + name = '"'+line[0]+'"' + typ = '"'+line[1]+'"' + dims = line[2] + if '(' in dims: + dims = dims.strip()[1:-1] + dims = [ '"'+x.strip()+'"' for x in dims.split(',') ] + dims = "[ " + ", ".join(dims) + " ]" + else: + dims = "[ ]" + f1 = max(f1, len(name)) + f2 = max(f2, len(typ)) + f3 = max(f3, len(dims)) + +fmt = "%%s%%%ds : [ %%%ds, %%%ds ]" % (f1, f2, f3) +for line in data: + line = [ x.replace("~","") for x in line ] + name = '"'+line[0]+'"' + typ = '"'+line[1]+'"' + dims = line[2] + if '(' in dims: + dims = dims.strip()[1:-1] + dims = [ '"'+x.strip()+'"' for x in dims.split(',') ] + dims.reverse() + dims = "[ " + ", ".join(dims) + " ]" + else: + if dims.strip() != "": + dims = "ERROR" + else: + dims = "[]" + buffer = fmt % (indent, name, typ.ljust(f2), dims.ljust(f3)) + indent = " , " + print(buffer) + +if last == 0: + print(" } ,") +else: + print(" }") +print("""#+end_src""") + ++