Home

TNUM and TANA are two components of a Fortran library or code that deal with Kinetic Energy Operators (KEO), $\hat{\mathbf{T}}$, in curvilinear coordinates, $\mathbf{Q}$, for molecular systems. Furthermore, the library can compute the Cartesian coordinates, $\mathbf{x}$, from the curvilinear ones (or the reverse).

• TANA computes $\hat{\mathbf{T}}$ analytically or the metric tensor. It is restricted to polyspherical coordinate types.
• TNUM computes $\hat{\mathbf{T}}$, or more precisely, the metric tensor numerically but exactly using automatic differentiation techniques. In terms of curvilinear coordinates, TNUM can handle complicated curvilinear coordinates by adding coordinate transformations to the polyspherical or z-matrix coordinates.

Both codes share many functionalities, in particular for the input data file, and TNUM is used to check the exactness of TANA KEO.

For instance, the system, $N_2-He$, is described in Jacobi coordinates (see the figure)

Then, the deformation part of the KEO, $\hat{\mathbf{T}}_{def}$, and volume element, $\tau_{def}$, is given by:

$$\hat{\mathbf{T}}_{def}= -\frac{\hbar^2}{2} \left[ \frac{1}{M} \frac{\partial^2 }{\partial R^2} + \frac{1}{m} \frac{\partial^2 }{\partial r^2} + \left( \frac{1}{MR^2} + \frac{1}{mr^2}\right)\left( \sin^{-1}(\theta)\frac{\partial }{\partial \theta} \sin(\theta)\frac{\partial }{\partial \theta}\right)\right]$$ $$\tau_{def}=dR \cdot dr \cdot \sin(\theta)d\theta$$

With TANA, the KEO can be exported in several formats. However, with TNUM, the numerical values of the metric tensor components or of the functions in front of the differential operators are computed at a given geometrical configuration (i.e., numerical values of the internal coordinates, $\mathbf{Q}=[R, r, \theta]$).

Kinetic Energy Operator with curvilinear coordinates

For a molecular system with $N_{at}$ atoms, $\mathbf{Q}_{dyn}=[Q_{dyn}^1,Q_{dyn}^2,...,Q_{dyn}^{n+m}]$ are the curvilinear coordinates associated with the internal deformation.

• $n$ are the number of active coordinates. It can be smaller than $3N_{at}-6$ when reduced dimensionality is used, i.e. the quantum dynamics is performed only with $n$ coordinates.
• $m$ are the number of inactive coordinates ($n+m=3N_{at}-6$). In full dimensionality $m=0$. These $n$ active coordinates, $\mathbf{Q}_{act}=[Q_{act}^1,Q_{act}^2,...,Q_{act}^{n}]$, will be call just $\mathbf{Q}$ in the following.

There are several equivalent expressions for the deformation part of KEO:

$$\hat{\mathbf{T}}_{def} = \frac{-\hbar^2}{2} \sum{_{i,j}^{n,n}} \frac{1}{\rho(\mathbf{Q})} \frac{\partial}{\partial Q_i} \rho(\mathbf{Q})G^{i,j}(\mathbf{Q}) \frac{\partial}{\partial Q_j} + V_{ep}(\mathbf{Q})$$ $$\hat{\mathbf{T}}_{def} = \sum{_{i \geq j}^{n,n}} f_2^{i,j}(\mathbf{Q}) \frac{\partial^2}{\partial Q_i \partial Q_j} + \sum{^n_i} f_1^{i}(\mathbf{Q}) \frac{\partial}{\partial Q_i} +V_{ep}(\mathbf{Q})$$

The presence of the extra-potential term, $V_{ep}(\mathbf{Q})$, is due to the use of a non-Euclidean volume element. For both expressions, the volume element (non-Euclidean) is:

$$\tau_{def} = \rho(\mathbf{Q}) dQ_1 \cdot dQ_2 \cdots dQ_n$$

With this volume element, the scalar product is defined as follows:

$$\int \psi^{*}(\mathbf{Q}) \phi(\mathbf{Q}) \tau_{def}$$

and a wave function, $\psi(\mathbf{Q})$, is normalized as follows:

$$\int \psi^{*}(\mathbf{Q}) \psi(\mathbf{Q}) \tau_{def}=1$$

Important remarks

For a given numerical value of the set of coordinates, $\mathbf{Q}$, TNUM only computes:

• The values of the metric tensor components, contravariant $G^{i,j}(\mathbf{Q})$ or covariant $g_{i,j}(\mathbf{Q})$
• The values of the functions, $f_2^{i,j}(\mathbf{Q})$, $f_1^{i}(\mathbf{Q})$ and $V_{ep}(\mathbf{Q})$
• The values of the Body-Fixed (or Laboratory-Fixed or Space-Fixed) Cartesian coordinates, $\mathbf{x}(\mathbf{Q})$ as function of the curvilinear ones $\mathbf{Q}$ (or the reverse).

However, TNUM does not compute the KEO action on a quantum state.

TANA will compute the analytical expressions of $G^{i,j}(\mathbf{Q})$ or the $f_2^{i,j}(\mathbf{Q})$, $f_1^{i}(\mathbf{Q})$ and $V_{ep}(\mathbf{Q})$ for polyspherical coordinates only and for specific isotopic masses. Then these analytical expressions can be exported in several format:

• MCTDH operator file (Heidelberg or Quantics version). TANA has been primary designed for that.
• MidasCpp operator file
• Fortan subroutines
• Latex equation

References

For TNUM, see:

• Lauvergnat, D., & Nauts, A. (2002). Exact numerical computation of a kinetic energy operator in curvilinear coordinates. Journal of Chemical Physics, 116(19), 8560.
• Marsili, E., Agostini, F., Nauts, A., & Lauvergnat, D. (2022). Quantum dynamics with curvilinear coordinates: models and kinetic energy operator. Philosophical Transactions of the Royal Society A: Mathematical, Physical and Engineering Sciences, 380(2223).

For TANA, see:

• Ndong, M., Joubert-Doriol, L., Meyer, H.-D., Nauts, A., Gatti, F., & Lauvergnat, D. (2012). Automatic computer procedure for generating exact and analytical kinetic energy operators based on the polyspherical approach. The Journal of Chemical Physics, 136(3), 034107.
• Ndong, M., Nauts, A., Joubert-Doriol, L., Meyer, H., Gatti, F., & Lauvergnat, D. (2013). Automatic computer procedure for generating exact and analytical kinetic energy operators based on the polyspherical approach: General formulation and removal of singularities. The Journal of Chemical Physics, 139(20), 204107.

Installation

You can get the code from GitHub:

• By cloning the repository

git clone https://github.com/lauvergn/Tnum-Tana.git  local-directory

• Download a release with a browser (https://github.com/lauvergn/Tnum-Tana/releases) or with "curl"

curl -LJ https://github.com/lauvergn/Tnum-Tana/archive/refs/tags/v0.9.zip --output Tnum-Tana-0.9.zip

You should get a zip Tnum-Tana-0.9.zip

unzip Tnum-Tana-0.9.zip

Compilation with a makefile

The installation is simple with a makefile. However, we do not have an fully automatic procedure (like configure ...). The program uses some Fortran 2003 features. Therefore, the compilers gfortran need to be recent. The code has been tested with the following compilers:

• gfortran (version 11 and above)
• ifx(2024)
• nagfor (nAG compiler version 7.1)

For instance, the main executables can be built:

# Main Tnum/Tana executable:
make Tnum
# Example of Fortran drivers:
make Tnum_FDriver
# Example of c drivers:
make Tnum_cDriver
# Special Tnum/Tana executable for MCTDH:
make Tnum_MCTDH
# Special Tnum/Tana executable for MidasCpp:
make Tnum_MidasCpp

To build the TnumTana library:

make lib

Furthermore, one can add options:

make FC=ifort OMP=0 OPT=0 LAPACK=0 INT=4
  # FC=ifort to change the compiller to ifort
  # OMP=0/1 to turn off/on the OpenMP fortran flag.
  # OPT=0/1 to turn off/on the fortran optimization.
  # LAPACK=0/1 to turn off/on the lapack use
  # INT=4/8 to change the default integer

The library, libTnum-Tana_XXX_oppY_ompZ_lapackW_intV.a is created in the main directory. Remarks :

• XXX is the compiller (gfortran, ifort ...)
• Y is 0 or 1 (opt0 / opt1: compiler optimization)
• Z is 0 or 1 (omp0 / omp1: whitout/with OpenMP)
• W is 0 or 1 (lapack0 / lapack1: whitout/with lapack)
• V is 4 or 8 (int4 / int8)

If needed, the .mod files are in the obj/obj_XXX_oppY_ompZ_lapackW_intV directory.

With the following example:

make FC=ifort OMP=1 OPT=1 LAPACK=1 INT=4

Two libraries are generated:

• The first one, libTnum-Tana_ifort_opt1_omp1_lapack1_int4.a, contains only Tnum-Tana subroutines. Therefore, other libraries are needed.
• The second one, libTnumTanaFull_ifort_opt1_omp1_lapack1_int4.a or libTnumTanaFull.a, contains everything.

Compilation with fpm

For the installation, on can use fpm (Fortran Package Manager). To build the library:

fpm build

To run some tests with fpm:

fpm run Tnum90 --< TESTS/exa_TnumDriver/dat_driver0 > res