Hex: Main Page

| Hex 2.2 Hydrogen-electron collision solver

Hex Documentation

Author
  Jakub Benda, MFF UK, jakub.bendaseznam.cz

Date
  10. 2. 2017

# Hex-db

Hex-db is the interface program that can be used to access data precomputed by the computational modules. Also, its built-in algorithms can, on demand, compute various derived scattering quantities. The full list of available variables is given in the section Theory.

## Installation

The whole package is written in C++11, which is supported by most of the up-to-date compilers. The following have been tested:

- GCC 6.3.0
- LLVM/clang 3.9.1
- Intel C++ Composer XE 17.0

There are several external libraries that are being used for some partial tasks. Here is the list of the libraries with versions that were used:

- GSL 2.1
  Obtainable from http://www.gnu.org/software/gsl/
  Used for special functions and some others.
- SQLite 3.15.0
  Obtainable from http://www.sqlite.org/download.html
  Used for access to the database files.

Some or all of the libraries may be present in precompiled form in the repositories of the Linux distribution used.

### Build and run

Once the needed libraries are present in the system include and library paths, all that is necessary to build the program is running "make" from this directory.

    make

This should create an executable "hex-db" in the subdirectory "bin/". One can then create an empty database by the command

    bin/hex-db --new

The tables present in the new database can be listed using "sqlite3" program,

    sqlite3 hex.db .tables    # prints "ics ionf tmat"

The SQL statements used to create the tables can be retrieved similarly,

    sqlite3 hex.db .schema

As soon as there are some data to import, one will run

    bin/hex-db --import <SQL_batch_file> --update

If the external libraries are installed in non-standard locations, one needs to edit the Makefile accordingly.

### Building on Windows

The program has been successfully tested on Windows 10 (and most probably will work exactly the same in older versions). The compilation has been done in the Code::Blocks IDE (the project file *.cbp is included with the source code). It is necessary to install a full-featured MinGW-w64 compiler, though; the compiler bundled with Code::Blocks lacks all necessary features.

1. Download MinGW-w64 installer from SourceForge (tested 6.3.0 x86_64 posix seh).
2. Download and install latest Code::Blocks (tested version was 16.01), configure to use MinGW-w64 binaries.

## Theory

The computational modules of the package Hex (e.g. hex-dwba, hex-pwba2 or hex-ecs) produce output in the form of radial part of the T-matrix. The full T-matrix for transition \( (n_i,l_i,m_i) \rightarrow (n_f,l_f,m_f) \) at energy \( E = k_i^2 - n_i^{-2} = k_f^2 - n_f^{-2} \) (energy is in Rydbergs) is

\[ T_{n_i l_i m_i\rightarrow n_f l_f m_f}^{L M S} = \delta_{M}^{m_i} \sum_\ell T_{fi,\ell}^{LMS} Y_{\ell}^{m_i-m_f} , \]

where the radial part depends on theory. It will be much different for exterior complex scaling and for Born approximation. This utility code (and associated standalone interface library) can then be used to produce following information:

- the scattering amplitude

  \[ f_{i \rightarrow f}^{S} = -\frac{1}{2\pi} T_{i \rightarrow f}^{S} = -\frac{1}{2\pi} \sum_{\ell L} T_{fi,\ell}^{Lm_iS} Y_{\ell}^{m_i-m_f} \ , \]

- the differential cross section

  \[ \frac{\mathrm{d}\sigma_{i \rightarrow f}^{S}}{\mathrm{d}\Omega} = \frac{k_f}{k_i} \frac{2S+1}{4} |f_{i \rightarrow f}^{S}|^2 \ , \]

- the partial integral cross section

  \[ \sigma_{i \rightarrow f}^{LS} = \frac{k_f}{k_i} \frac{2S + 1}{4} \int_{4\pi} |f_{i \rightarrow f}^{LS}|^2 \mathrm{d}\Omega = \frac{k_f}{k_i} \frac{2S+1}{16\pi^2} \sum_{\ell L'} T_{i \rightarrow f,\ell}^{Lm_iS}T_{i \rightarrow f,\ell}^{L'm_iS*} \ , \]

- the “complete” integral cross section

  \[ \sigma_{i \rightarrow f} = \sum_{LS} \sigma_{i \rightarrow f}^{LS} \ , \]

- the total cross section

  \[ \sigma_i = \sum_{n_f = 1}^\infty \sum_{l_f = 0}^{n_f - 1} \sum_{m_f = -l_f}^{l_f} \sigma_{i \rightarrow f} \ , \]

- and also the dimensionless, \( i \leftrightarrow j \) symmetrical, collision strength

  \[ \Omega_{i \rightarrow f}^{LS} = k_i^2 (2\ell_i + 1) \sigma_{i \rightarrow f}^{LS} \]

- or the momentum transfer

  \[ \eta_{i \rightarrow f}^{LS} = \int \frac{\mathrm{d}\sigma_{i \rightarrow f}^{LS}}{\mathrm{d}\Omega} (1 - \cos\vartheta) \, \mathrm{d}\Omega = \frac{k_f}{k_i} \frac{2S+1}{16\pi^2} \sum_{\ell \ell'} \left(\delta_{\ell\ell'} - \sqrt{\frac{2\ell+1}{2\ell'+1}} C_{\ell,m_i-m_f,1,0}^{\ell',m_i-m_f} C_{\ell,0,1,0}^{\ell',0} \right) \sum_{LL'} T_{i \rightarrow f,\ell}^{LS} T_{i \rightarrow f,\ell'}^{L'S\ast} \]

- and spin-flip cross section

  \[ \frac{\mathrm{d}\varsigma_{i \rightarrow f}}{\mathrm{d}\Omega} = \frac{1}{4} \frac{k_f}{k_i} |f_{i \rightarrow f}^1 - f_{i \rightarrow f}^0|^2 \,. \]

Ultimately, all these variables are computed from the partial wave expansion of the T-matrix. This series can converge very slow, particularly in the case of large energies. One can use the Born subtraction method to overcome this difficulty. Assuming that for some large total angular momentum the Born approximation can provide accurate partial T-matrices, it is

\[ T \approx \sum_{L = 0}^{L_0} T_{\ell} Y_\ell^{m_i-m_f} + \sum_{L = L_0 + 1}^\infty T_{\mathrm{Born},\ell} Y_\ell^{m_i-m_f} = T_{\mathrm{Born}} + \sum_{L = 0}^{L_0} \left(T_\ell - T_{\mathrm{Born},\ell}\right) Y_\ell^{m_i-m_f} \ , \]

i.e. the resulting T-matrix is the Born T-matrix corrected by the first \( L_0 + 1 \) partial waves. The angle-dependent full Born T-matrix \( T_{\mathrm{Born}} \) is stored in the form of Chebyshev expansion. The Born partial T-matrices \( T_{\mathrm{Born},\ell} \) are stored along the exact partial T-matrices \( T_\ell \).

## The database

The file "hex.db" contains SQL database in the form of several tables. The most low-level data (the T-matrices) are stored in the table "tmat" that has the following columns:

Field name | Data type | Comment
--- | --- | ---
ni | INTEGER | Initial principal quantum number.
li | INTEGER | Initial orbital quantum number.
mi | INTEGER | Initial magnetic quantum number.
nf | INTEGER | Final principal quantum number.
lf | INTEGER | Final orbital quantum number.
mf | INTEGER | Final magnetic quantum number.
L | INTEGER | Conserved total angular momentum of a partial wave.
S | INTEGER | Conserved total spin of the system.
Ei | DOUBLE PRECISION | Projectile impact energy.
ell | INTEGER | Out-going partial wave.
Re_T_ell | DOUBLE PRECISION | Real part of \( T_\ell \).
Im_T_ell | DOUBLE PRECISION | Imaginary part of \( T_\ell \).

However, there are more tables (currently also "bornf" for angle-dependent Born T-matrices, "ics" for integral cross section, "ccs" for complete cross section, and "ionf" for radial part of the ionization amplitude).

The initial database file can be created by the shell command

    hex-db --new

which is equivalent to (if "sqlite3" program is available in PATH)

    sqlite3 hex.db 'CREATE TABLE "tmat" (
       ni INTEGER, li INTEGER, mi INTEGER,
       nf INTEGER, lf INTEGER, mf INTEGER,
       L INTEGER, S INTEGER, Ei DOUBLE PRECISION, ell INTEGER,
       Re_T_ell DOUBLE PRECISION, Im_T_ell DOUBLE PRECISION
       PRIMARY KEY (ni,li,mi,nf,lf,mf,L,S,Ei,ell)
    )'

and several similar statements more, for each variable that has to be precomputed. Whether a variable has a dedicated table within the database can be inquired by looking at its member function SQL_CreateTable. If there are similar commands, one has to update the database after data insertion to be able to use the new data:

    hex-db --update

The insertion of scattering T-matrices, as produced by computational units, is very easy:

    hex-db --import T-matrices.sql

which is equivalent to

    sqlite3 hex.db < T-matrices.sql

The raw database file allows standard queriyng, which can be employed to retrieve some low level data, like

    sqlite3 -column hex.db 'SELECT Ei,Re_T_ell,Im_T_ell FROM "tmat" WHERE
       ni = 1 AND li = 0 AND mi = 0 AND
       nf = 1 AND lf = 0 AND mf = 0 AND
       Ei > 0.75 AND Ei <= 0.88' > output.txt

which will print real and imaginary parts of H(1s) \( \rightarrow \) H(1s) T-matrices for energies between \( E = 0.75 \) Ry and \( E = 0.88 \) Ry into the file "output.txt".

## Usage

Apart from direct program access (when the sources were linked to a custom code), one can use a CLI (command line interface) which has the following switches:

Short option | Long option | Usage
--- | --- | ---
`-h` | `--help` | Print basic usage info and exit.
`-D` | `--database` | Use given database file. This is optional; "hex.db" is used if omitted.
`-n` | `--new` | Create database file, either "hex.db" or the given name if specified by –database.
`-i` | `--import` | Import SQL data produced by some of the modules.
`-u` | `--update` | Update cache tables (variables dependent on lower-level data) after insertion.
`-o` | `--optimize` | Use VACUUM command to shrink the database file.
`-d` | `--dump` | Export all data in the form of SQL statements.
`-v` | `--vars` | Print available variables with short info.
`-p` | `--params` | Show what quantum numbers need to be given for a specific variable.
| `--Eunits` | Change energy units (Ry/a.u./eV).
| `--Tunits` | Length units – units of output (a.u./cgs).
| `--Aunits` | Angular units (deg/rad).
| `--<variable>` | Scattering variable to compute (scatamp, dcs, ics, ccs, tcs, asy, ...).
| `--<Q-number>` | Quantum number specification (ni,li,mi,nf,lf,mf,L,S,Ei,...).

Quantity | Compulsory quantum numbers | STDIN contains*
--- | --- | ---
Scattering amplitude | \( n_i, l_i, m_i, n_f, l_f, m_f, S, E_i \) | angles [deg]
Differential cross section | \( n_i, l_i, m_i, n_f, l_f, m_f, S, E_i \) | angles [deg]
Spin asymmetry | \( n_i, l_i, m_i, n_f, l_f, m_f, E_i \) | angles [deg]
Momentum transfer | \( n_i, l_i, m_i, n_f, l_f, m_f, S \) | energies [Ry]
Integral cross section | \( n_i, l_i, m_i, n_f, l_f, m_f, ell \) | energies [Ry]
Complete cross section | \( n_i, l_i, m_i, n_f, l_f, m_f \) | energies [Ry]
Collision strength | \( n_i, l_i, m_i, n_f, l_f, m_f, ell \) | energies [Ry]
Total cross section | \( n_i, l_i, m_i \) | energies [Ry]

*) Standard input should contain values of angles or energies separated by white characters (spaces, newlines etc.). The list ends with EOF (Ctrl+D if manually entering data; inserted automatically when using standard "seq" invocation).

For every STDIN entry the program will respond with one number computed (and interpolated if necessary) from the database. If there are no relevant data in database, the result will be zero. If the available energy interval doesn't contain some of the required energies, appropriate error message will be printed. Here are some examples of usage:

    # scattering amplitude
    seq 0.01 0.01 3.14    | hex-db --database="hex.db" --scatamp    --ni=1 --li=0 --mi=0 --nf=3 --lf=0 --mf=0 --S=0

    # differential cross section
    seq 0.01 0.01 3.14    | hex-db --database="hex.db" --dcs        --ni=1 --li=0 --mi=0 --nf=3 --lf=0 --mf=0 --S=0

    # total cross section
    seq 0.650 0.001 0.850 | hex-db --database="hex.db" --tcs        --ni=1 --li=0 --mi=0

You may need to set the LC_NUMERIC environment variable to en_US.utf8 (or en_GB.utf8 or any other localitation that uses decimal point instead of decimal comma). An alternative is the workaround with sed.

    # [Czech locale] avoid commas by changing locale
    export LC_ALL=C
    seq 0.01 0.01 3.14    | hex-db –database="hex.db" –scatamp    –ni=1 –li=0 –mi=0 –nf=3 –lf=0 –mf=0 –S=0

    # [Czech locale] avoid commas by substitution
    seq 0.01 0.01 3.14 | sed -e "s/,/\./g" | hex-db –database="hex.db" –scatamp    –ni=1 –li=0 –mi=0 –nf=3 –lf=0 –mf=0 –S=0