Hex-db

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.

Theory

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 scattering amplitude
\[ f_{i \rightarrow f}^{S}(E) = -\frac{1}{2\pi} T_{i \rightarrow f}^{S}(E) = -\frac{1}{2\pi} \sum_{L} f_{i \rightarrow f}^{LS}(E) = -\frac{1}{2\pi} \sum_{\ell L} Y_{\ell m_i-m_f}(\hat{\vec{k}}_f) T_{fi,\ell}^{LS}(E) \ , \]
the differential cross section
\[ \frac{\mathrm{d}\sigma_{i \rightarrow f}^{S}}{\mathrm{d}\Omega}(E) = \frac{k_f}{k_i} \frac{2S+1}{4} |f_{i \rightarrow j}^{S}|^2 \ , \]
the partial integral cross section
\[ \sigma_{i \rightarrow f}^{LS}(E) = \frac{k_f}{k_i} \frac{2S + 1}{4} \int_{4\pi} |f_{i \rightarrow f}^{LS}(E)|^2 \mathrm{d}\Omega(\hat{\vec{k}}_f) = \frac{k_f}{k_i} \frac{2S+1}{16\pi^2} \sum_\ell |T_{fi,\ell}^{LS}(E)|^2 \ , \]
the “complete” integral cross section
\[ \sigma_{i \rightarrow f}(E) = \sum_{LS} \sigma_{i \rightarrow f}^{LS}(E) \ , \]
the total cross section
\[ \sigma_i(E) = \sum_{n_f = 1}^\infty \sum_{l_f = 0}^{n_f - 1} \sum_{m_f = -l_f}^{l_f} \sigma_{i \rightarrow f}(E) \ , \]
and also the dimensionless, \( i \leftrightarrow j \) symmetrical, collision strength
\[ \Omega_{i \rightarrow f}^{LS} (E) = k_i^2 \sigma_{i \rightarrow f}^{LS}(E) \]
or the momentum transfer
\[ \eta_{i \rightarrow f}^{LS} = \int \frac{\mathrm{d}\sigma_{i \rightarrow f}^{LS}}{\mathrm{d}\Omega}(E) (1 - \cos\vartheta) \mathrm{d}\Omega(\hat{\vec{k}}_f) \ . \]

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".

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

Quantity	Compulsory 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