Hex  1.0
Hydrogen-electron collision solver
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
Hex Documentation
Jakub Benda, MFF UK
1. 2. 2014


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


The computational modules of the package Hex 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} (E) = \delta_{Mm_f} \sum_\ell T_\ell^{LMS}(E) Y_{l_f m_f}(\hat{\vec k}_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 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.
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 "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 "hex" 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".


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 databse 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,...).

QuantityCompulsory quantum numbers STDIN contains*
Scattering amplitude ni, li, mi, nf, lf, mf, S, E angles [deg]
Differential cross section ni, li, mi, nf, lf, mf, S, E angles [deg]
Spin asymmetry ni, li, mi, nf, lf, mf, E angles [deg]
Momentum transfer ni, li, mi, nf, lf, mf, L, S energies [Ry]
Integral cross section ni, li, mi, nf, lf, mf, L, S energies [Ry]
Complete cross section ni, li, mi, nf, lf, mf energies [Ry]
Extrapolated cross section ni, li, mi, nf, lf, mf energies [Ry]
Collision strength ni, li, mi, nf, lf, mf, L, S energies [Ry]
Total cross section ni, li, mi 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

# momentum transfer
seq 0.650 0.001 0.850 | hex-db --database="hex.db" --momtransf  --ni=1 --li=0 --mi=0 --nf=3 --lf=0 --mf=0 --L=0 --S=0

# integral cross section
seq 0.650 0.001 0.850 | hex-db --database="hex.db" --integcs    --ni=1 --li=0 --mi=0 --nf=3 --lf=0 --mf=0 --L=0 --S=0

# sum integral cross section
seq 0.650 0.001 0.850 | hex-db --database="hex.db" --sumintegcs --ni=1 --li=0 --mi=0 --nf=3 --lf=0 --mf=0

# collision strength
seq 0.650 0.001 0.850 | hex-db --database="hex.db" --collstr    --ni=1 --li=0 --mi=0 --nf=3 --lf=0 --mf=0 --L=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.

# scattering amplitude in Czech environment (1)
export LC_NUMERIC=en_GB.utf8
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

# scattering amplitude in Czech environment (2)
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