Multidip  1.0
Multi-photon matrix elements
multidip_special Module Reference

Special functions and objects used by MULTIDIP. More...

Data Types

interface  cphaz
 
interface  coulfg
 
interface  couln
 
interface  decay
 
interface  dgemm
 
interface  dgemv
 
interface  dsyev
 
interface  dgetrf
 
interface  dgetrs
 
interface  zgemm
 
interface  zgemv
 
interface  zgetrf
 
interface  zgetrs
 
interface  zgetri
 

Functions/Subroutines

subroutine calculate_r_matrix (nchan, nstat, wmat, eig, Etot, Rmat)
 Calculate scattering R-matrix. More...
 
subroutine calculate_t_matrix (K, T, nopen)
 Calculate T-matrix from K-matrix. More...
 
subroutine calculate_s_matrix (T, S, nopen)
 Calculate S-matrix from T-matrix. More...
 
subroutine scatak (rmatr, eig, etot, w, Ek, l, Km, Ak)
 Photoionization coefficient. More...
 
real(wp) function cphase (Z, l, k)
 Coulomb phase. More...
 
recursive complex(wp) function complex_gamma (l, x)
 Complex Gamma function. More...
 
subroutine coul (Z, l, Ek, r, F, Fp, G, Gp)
 Coulomb functions. More...
 
complex(wp) function coulh (Z, s, l, Ek, r)
 Coulomb-Hankel function. More...
 
complex(wp) function coulh_asy (Z, s, l, Ek, r)
 Coulomb-Hankel function (asymptotic form) More...
 
subroutine coul_gsl (Z, l, Ek, r, F, Fp, G, Gp)
 Coulomb functions (GSL) More...
 
subroutine coul_ukrmol (Z, l, Ek, r, F, Fp, G, Gp)
 Coulomb functions (UKRmol) More...
 
subroutine diagonalize_symm_matrix (M, eigs, eigv, check)
 Diagonalize a real symmetric matrix. More...
 
subroutine invert_matrix (T)
 Invert a complex matrix. More...
 
subroutine solve_complex_system (n, A, X, Y)
 Solve system of equations with complex matrix. More...
 
logical function next_permutation (p)
 Construct or advance permutation. More...
 
subroutine swap (a, b)
 Exchange value of two integers. More...
 
subroutine reverse (a)
 Reverse order of elements in array. More...
 
subroutine kahan_add (X, dX, err)
 Compensated summation. More...
 
real(wp) function beta_contraction_tensor (J, n, p, li, mi, qi, lj, mj, qj)
 Angular part of the beta parameters. More...
 
recursive real(wp) function wigner_d_multiint (n, l, a, b, lp, ap, bp)
 Orientation averaging. More...
 
real(wp) function beta_2p_arb_pol_sph_harm (Lbig, Mbig, n, pB, lp, mp, qB, pA, l, m, qA)
 Two-photon asymmetry parameter for the arbitrary polarized case. More...
 
real(wp) function beta_2p_demekhin (L, p1, p2, li, mi, q1i, q2i, lj, mj, q1j, q2j)
 Two-photon asymmetry parameter. More...
 
real(wp) recursive function cartesian_vector_component_product_average (q)
 Return Cartesian invariant. More...
 

Detailed Description

Special functions and objects used by MULTIDIP.

Author
J Benda
Date
2020

Function/Subroutine Documentation

◆ beta_2p_arb_pol_sph_harm()

real(wp) function multidip_special::beta_2p_arb_pol_sph_harm ( integer, intent(in)  Lbig,
integer, intent(in)  Mbig,
integer, intent(in)  n,
integer, dimension(n), intent(in)  pB,
integer, intent(in)  lp,
integer, intent(in)  mp,
integer, dimension(n), intent(in)  qB,
integer, dimension(n), intent(in)  pA,
integer, intent(in)  l,
integer, intent(in)  m,
integer, dimension(n), intent(in)  qA 
)

Two-photon asymmetry parameter for the arbitrary polarized case.

Author
Z Masin
Date
2023

Explicit form of the two-photon asymmetry parameter from Ertel et al, Journal of Chemical Physics, submitted, (2023). This routine implements the most general case when the polarizations of all four photons involved are chosen arbitrarily. The resulting asymmetry parameter can have a non-zero M value corresponding to a spherical harmonic Y_{L,M}^{*}.

The routine uses two different conventions for the asymmetry parameters. In case of M = 0 (no net difference between the polarizations in the two 2-photon arms) the routine uses the Legendre polynomials P_{L} as the basis:

\[ I = \frac{1}{4\pi}\sum_{L=0}^{4}b_{L}P_{L}(\cos\theta). \]

In the general case with M /= 0 the asymmetry parameters are coefficients in spherical harmonic expansion:

\[ I = \sum_{L,M}\hat{b}_{L,M}Y_{L,M}^{*}(\mathbf{k}). \]

Note the conjugation of the spherical harmonic of momentum.

The input for this routine differs from that for beta_2p_demekhin and beta_contraction_tensor in the choice of the polarizations of the photons for the first (A) and second (B) 2-photon amplitudes by means of the arrays pA and pB. Each of them specifies the polarizations of the first and second photons.

Definition at line 1122 of file multidip_special.F90.

Here is the caller graph for this function:

◆ beta_2p_demekhin()

real(wp) function multidip_special::beta_2p_demekhin ( integer, intent(in)  L,
integer, intent(in)  p1,
integer, intent(in)  p2,
integer, intent(in)  li,
integer, intent(in)  mi,
integer, intent(in)  q1i,
integer, intent(in)  q2i,
integer, intent(in)  lj,
integer, intent(in)  mj,
integer, intent(in)  q1j,
integer, intent(in)  q2j 
)

Two-photon asymmetry parameter.

Author
J Benda
Date
2020

Explicit form of the two-photon asymmetry parameter from Demekhin, Lagutin, Petrov, Phys. Rev. A 85 (2012) 023416.

Note
The explicit formula contains an apparent extra factor of (-1)^(L + lj), which is however fully absorbed into the phase of the wave function in the present approach.

Definition at line 1190 of file multidip_special.F90.

Here is the caller graph for this function:

◆ beta_contraction_tensor()

real(wp) function multidip_special::beta_contraction_tensor ( integer, intent(in)  J,
integer, intent(in)  n,
integer, dimension(n), intent(in)  p,
integer, intent(in)  li,
integer, intent(in)  mi,
integer, dimension(n), intent(in)  qi,
integer, intent(in)  lj,
integer, intent(in)  mj,
integer, dimension(n), intent(in)  qj 
)

Angular part of the beta parameters.

Author
J Benda
Date
2020

Evaluates the contraction coefficient \( T_{m p_1 q_1 q_1'\dots p_n q_n q_n'}^{Jll'} \) in

\[ \frac{\mathrm{d}\sigma^{(p_1\dots p_n)}}{\mathrm{d}\Omega} = \frac{1}{4\pi} \sum_{J} b_J^{(p_1\dots p_n)} P_J(\cos\theta) = \frac{1}{4\pi} \sum_{Jlml'm'\atop q_1 q_1' \dots q_n q_n'} M_{mq_1\dots q_n}^{(l)} M_{m'q_1'\dots q_n'}^{(l')*} T_{m m', p_1 q_1 q_1'\dots p_n q_n q_n'}^{Jll'} P_J(\cos\theta), \]

which has the following explicit form:

\[ T_{m m', p_1 q_1 q_1'\dots p_n q_n q_n'}^{Jll'} = \sum_{\mu} (-1)^{\mu} (2J + 1) \sqrt{(2l + 1)(2l' + 1)} \left(\begin{matrix} l & l' & J \\ 0 & 0 & 0 \end{matrix}\right) \left(\begin{matrix} l & l' & J \\ \mu & -\mu & 0 \end{matrix}\right) \frac{1}{8\pi^2} \int D_{\mu m}^{(l)} D_{\mu m'}^{(l')*} D_{p_1 q_1}^{(1)*} D_{p_1 q_1'}^{(1)} \dots D_{p_n q_n}^{(1)*} D_{p_n q_n}^{(1)} \mathrm{d}\hat{R} . \]

The real averaging integral over orientations of the molecule is re-expressed as

\[ (-1)^{m + m'} \frac{1}{8\pi^2} \int D_{-\mu, -m}^{(l)*} D_{-\mu, -m'}^{(l')} D_{p_1 q_1}^{(1)*} D_{p_1 q_1'}^{(1)} \dots D_{p_n q_n}^{(1)*} D_{p_n q_n}^{(1)} \mathrm{d}\hat{R} \]

and then calculated in wigner_D_multiint.

Note
In the present implementation, all laboratory-frame polarisations \( p_i \) are considered equal to zero, i.e. the field is linearly polarized.

Definition at line 990 of file multidip_special.F90.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ calculate_r_matrix()

subroutine multidip_special::calculate_r_matrix ( integer, intent(in)  nchan,
integer, intent(in)  nstat,
real(wp), dimension(:, :), intent(in)  wmat,
real(wp), dimension(:), intent(in)  eig,
real(wp), intent(in)  Etot,
real(wp), dimension(:, :), intent(inout)  Rmat 
)

Calculate scattering R-matrix.

Authors
J Benda
Date
2023

R-matrix is calculated from boundary amplitudes and R-matrix poles provided using the formula

\[ R_{uv}(E) = \sum_{j} w_{uj}(a) \frac{1}{E_j - E} w_{vj}(a) \,. \]

Parameters
[in]nchanNumber of partial wave channels in this symmetry.
[in]nstatNumber of inner region states in this symmetry.
[in]wmatBoundary amplitudes for this symmetry.
[in]eigR-matrix poles for this symmetry.
[in]EtotTotal energy of the target + electron system.
[in,out]RmatR-matrix to calculate.

Definition at line 237 of file multidip_special.F90.

Here is the caller graph for this function:

◆ calculate_s_matrix()

subroutine multidip_special::calculate_s_matrix ( complex(wp), dimension(:, :), intent(in)  T,
complex(wp), dimension(:, :), intent(inout)  S,
integer, intent(in)  nopen 
)

Calculate S-matrix from T-matrix.

Author
J Benda
Date
2020 - 2024

Obtain the S-matrix from the definition formula

\[ S = (1 + iK) (1 - iK)^{-1} = 1 + T \]

Definition at line 339 of file multidip_special.F90.

Here is the caller graph for this function:

◆ calculate_t_matrix()

subroutine multidip_special::calculate_t_matrix ( real(wp), dimension(:, :), intent(in)  K,
complex(wp), dimension(:, :), intent(inout)  T,
integer, intent(in)  nopen 
)

Calculate T-matrix from K-matrix.

Authors
J Benda
Date
2024

Use real algebra to obtain the scattering T-matrix defined as

\[ T = S - 1 = 2iK (1 - iK)^{-1} = 2i (1 - iK)^{-1} K = -2K (1 + K^2)^{-1} K + 2i (1 + K^2)^{-1} K \]

Only the open-open sub-block of the K-matrix is used.

Definition at line 273 of file multidip_special.F90.

Here is the caller graph for this function:

◆ cartesian_vector_component_product_average()

real(wp) recursive function multidip_special::cartesian_vector_component_product_average ( integer, dimension(:), intent(in)  q)

Return Cartesian invariant.

Author
J Benda
Date
2022 - 2023

Calculate angular average of a product of two sets of Cartesian components of a unit vector. The general formula is

\[ \frac{1}{4\pi} \int n_{i_1} \dots n_{i_N} = \frac{1}{(N + 1)!!} {\sum_\pi}' \delta_{i_{\pi(1)} i_{\pi(2)}} \dots \delta_{i_{\pi(N-1)} i_{\pi(N)}} . \]

The prime denotes summation only over unique terms. Some explicit examples are:

\[ \frac{1}{4\pi} \int n_i n_j = \frac{1}{3} \delta_{ij} \,, \]

where i = q(1) and j = q(2), and

\[ \frac{1}{4\pi} \int n_i n_j n_k n_l = \frac{1}{15} (\delta_{ij}\delta_{kl} + \delta_{ik}\delta_{jl} + \delta_{il}\delta_{jk}) \,, \]

where i = q(1), j = q(2), k = q(3) and l = q(4).

Definition at line 1248 of file multidip_special.F90.

Here is the caller graph for this function:

◆ complex_gamma()

recursive complex(wp) function multidip_special::complex_gamma ( integer, intent(in)  l,
real(wp), intent(in)  x 
)

Complex Gamma function.

Author
J Benda
Date
2021 - 2024

Evaluate the complex Gamma function Γ(l + 1 + i*x), where l is integer.

Definition at line 466 of file multidip_special.F90.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ coul()

subroutine multidip_special::coul ( real(wp), intent(in)  Z,
integer, intent(in)  l,
real(wp), intent(in)  Ek,
real(wp), intent(in)  r,
real(wp), intent(inout)  F,
real(wp), intent(inout)  Fp,
real(wp), intent(inout)  G,
real(wp), intent(inout)  Gp 
)

Coulomb functions.

Author
J Benda
Date
2020 - 2023

Evaluate the Coulomb wave (regular, irregular and derivatives). Uses GSL or the UKRmol-out library, depending on the configuration. For negative energies, evaluates the exponentially decreasing solution (into G and Gp) obtained from the Whittaker function (if charged) or from solution of the appropriate equation (if neutral).

The derivatives returned are with respect to \( r \) already, so they should not be multiplied by the additional factor of \( k \).

Definition at line 518 of file multidip_special.F90.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ coul_gsl()

subroutine multidip_special::coul_gsl ( real(wp), intent(in)  Z,
integer, intent(in)  l,
real(wp), intent(in)  Ek,
real(wp), intent(in)  r,
real(wp), intent(inout)  F,
real(wp), intent(inout)  Fp,
real(wp), intent(inout)  G,
real(wp), intent(inout)  Gp 
)

Coulomb functions (GSL)

Author
J Benda
Date
2020 - 2023

Coulomb functions (positive- and negative-energy) calculated using GSL. The derivative is with respect to \( r \) in the argument \( kr \), so the obtained derivatives contain an additional multiplication factor \( k \) compared to the standard normalization of the Coulomb functions.

Definition at line 611 of file multidip_special.F90.

Here is the caller graph for this function:

◆ coul_ukrmol()

subroutine multidip_special::coul_ukrmol ( real(wp), intent(in)  Z,
integer, intent(in)  l,
real(wp), intent(in)  Ek,
real(wp), intent(in)  r,
real(wp), intent(inout)  F,
real(wp), intent(inout)  Fp,
real(wp), intent(inout)  G,
real(wp), intent(inout)  Gp 
)

Coulomb functions (UKRmol)

Author
J Benda
Date
2020 - 2023

Coulomb functions (positive- and negative-energy) calculated using UKRmol-out. The derivative is with respect to \( r \) in the argument \( kr \), so the obtained derivatives contain an additional multiplication factor \( k \) compared to the standard normalization of the Coulomb functions.

Definition at line 660 of file multidip_special.F90.

Here is the caller graph for this function:

◆ coulh()

complex(wp) function multidip_special::coulh ( real(wp), intent(in)  Z,
integer, intent(in)  s,
integer, intent(in)  l,
real(wp), intent(in)  Ek,
real(wp), intent(in)  r 
)

Coulomb-Hankel function.

Author
J Benda
Date
2021 - 2023

See coul for explanation of the arguments.

Definition at line 537 of file multidip_special.F90.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ coulh_asy()

complex(wp) function multidip_special::coulh_asy ( real(wp), intent(in)  Z,
integer, intent(in)  s,
integer, intent(in)  l,
real(wp), intent(in)  Ek,
real(wp), intent(in)  r 
)

Coulomb-Hankel function (asymptotic form)

Author
J Benda
Date
2021 - 2023

Implements the asymptotic formula for Coulomb-Hankel function, DLMF §33.11.1. The number of terms is centrally controlled by a parameter in module multidip_params to be consistent with what is used in the integration routines.

See coul for explanation of the arguments.

Definition at line 561 of file multidip_special.F90.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ cphase()

real(wp) function multidip_special::cphase ( real(wp), intent(in)  Z,
integer, intent(in)  l,
real(wp), intent(in)  k 
)

Coulomb phase.

Author
J Benda
Date
2020 - 2023

Return the Coulomb phase, arg Gamma(l + 1 - iZ/k). Uses GSL or the UKRmol-out library, depending on the configuration.

Definition at line 440 of file multidip_special.F90.

Here is the caller graph for this function:

◆ diagonalize_symm_matrix()

subroutine multidip_special::diagonalize_symm_matrix ( real(wp), dimension(:, :), intent(in)  M,
real(wp), dimension(:), intent(inout)  eigs,
real(wp), dimension(:, :), intent(inout)  eigv,
real(wp), intent(in), optional  check 
)

Diagonalize a real symmetric matrix.

Authors
J Benda
Date
2023

Obtain eigenvectors and eigenvalues of a real symmetric matrix. The phase of the eigenvectors is fixed so that the element of each eigenvectors largest in magnitude is positive.

Parameters
[in]MMatrix to diagonalize (N × N)
[in,out]eigsOn exit the eigenvalues (N)
[in,out]eigvOn exit the eigenvectors (N × N)
[in]checkOptional threshold. If positive, check that the obtained eigenvectors are orthonormal to this accuracy.

Definition at line 703 of file multidip_special.F90.

◆ invert_matrix()

subroutine multidip_special::invert_matrix ( complex(wp), dimension(:, :), intent(inout), allocatable  T)

Invert a complex matrix.

Author
J Benda
Date
2020

Calculate inverse of a complex matrix. Use the standard LAPACK decompose+solve sequence.

Definition at line 766 of file multidip_special.F90.

Here is the caller graph for this function:

◆ kahan_add()

subroutine multidip_special::kahan_add ( complex(wp), intent(inout)  X,
complex(wp), intent(in)  dX,
complex(wp), intent(inout)  err 
)

Compensated summation.

Author
J Benda
Date
2020

Add dX to X, keep track of numerical error. Uses Kahan's algorithm. This subroutine is in infinite precision equivalent to just

x = x + dx
err = 0

but in the finite precision arithmetic it compensates the running numerical error. It mustn't be optimized away by the compiler! Flags like -ffast-math or -Ofast are detrimental here. Common optimization flags like -O2 or -O3 should be safe (but it may depend on the compiler).

Definition at line 946 of file multidip_special.F90.

Here is the caller graph for this function:

◆ next_permutation()

logical function multidip_special::next_permutation ( integer, dimension(:), intent(inout)  p)

Construct or advance permutation.

Author
J Benda
Date
2020

If the given integer array contains a negative element, fill it with identical permutation (i.e. the sequence 1, 2, ..., N) and return TRUE. Otherwise attempt to generate the "next" permutation of the N values in the manner compatible with C++ std::next_permutation (lexicographically ordered sequences). When no further permutation is possible, return FALSE.

The algorithm is shamelessly copied from the source of GCC's libstdc++ library and (except for the added initialization option) faithfully mimics the behaviour of the built-on C++ function std::next_permutation.

Definition at line 843 of file multidip_special.F90.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ reverse()

subroutine multidip_special::reverse ( integer, dimension(:), intent(inout)  a)

Reverse order of elements in array.

Author
J Benda
Date
2020

This subroutine mimics the behaviour of the built-in C++ function std::reverse.

Definition at line 918 of file multidip_special.F90.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ scatak()

subroutine multidip_special::scatak ( real(wp), intent(in)  rmatr,
real(wp), dimension(:), intent(in)  eig,
real(wp), intent(in)  etot,
real(wp), dimension(:,:), intent(in)  w,
real(wp), dimension(:), intent(in)  Ek,
integer, dimension(:), intent(in)  l,
real(wp), dimension(:,:), intent(in)  Km,
complex(wp), dimension(:,:), intent(inout)  Ak 
)

Photoionization coefficient.

Author
J Benda
Date
2020

Evaluates the wave function coefficient Ak for the final stationary photoionization wave.

Parameters
[in]rmatrR-matrix radius for Coulomb wave matching
[in]eigInner eigenenergies (R-matrix poles) for this irreducible representation
[in]etotTotal energy of the system
[in]wBoundary amplitudes
[in]EkPhotoelectron kinetic energies in all channels (open and closed)
[in]lPhotoelectron angular momentum in all channels (open and closed)
[in]KmK-matrix
[in,out]AkWave function coefficients, needs to be allocated to neig x nopen and only that part will be written

Definition at line 373 of file multidip_special.F90.

Here is the call graph for this function:

◆ solve_complex_system()

subroutine multidip_special::solve_complex_system ( integer, intent(in)  n,
complex(wp), dimension(:, :), intent(inout), allocatable  A,
real(wp), dimension(:, :), intent(inout), allocatable  X,
real(wp), dimension(:, :), intent(inout), allocatable  Y 
)

Solve system of equations with complex matrix.

Author
J Benda
Date
2020

The matrix A is complex. The columns of matrices X and Y correspond to real and imaginary part of the right-hand side and of the solution, respectively.

Definition at line 801 of file multidip_special.F90.

Here is the caller graph for this function:

◆ swap()

subroutine multidip_special::swap ( integer, intent(inout)  a,
integer, intent(inout)  b 
)

Exchange value of two integers.

Author
J Benda
Date
2020

This subroutine mimics the behaviour of the built-in C++ function std::swap.

Definition at line 900 of file multidip_special.F90.

Here is the caller graph for this function:

◆ wigner_d_multiint()

recursive real(wp) function multidip_special::wigner_d_multiint ( integer, intent(in)  n,
integer, dimension(n), intent(in)  l,
integer, dimension(n), intent(in)  a,
integer, dimension(n), intent(in)  b,
integer, dimension(n), intent(in)  lp,
integer, dimension(n), intent(in)  ap,
integer, dimension(n), intent(in)  bp 
)

Orientation averaging.

Author
J Benda
Date
2020

Calculate the value of the integral

\[ \frac{1}{8\pi^2} \int D_{a_1 b_1}^{(l_1)} D_{a_1' b_1'}^{(l_1')*} \dots D_{a_1 b_1}^{(l_n)} D_{a_n' b_n'}^{(l_n')*} \mathrm{d}\hat{R} \]

over all orientations (Euler angles) \( \hat{R} \). The calculation is done recursively using the formula

\[ D_{a_1 b_1}^{(l_1)} D_{a_2 b_2}^{(l_2)} = \sum_{juv} (-1)^{u - v} (2j + 1) \left(\begin{matrix} l_1 & l_2 & j \\ a_1 & a_2 & -u \end{matrix}\right) \left(\begin{matrix} l_1 & l_2 & j \\ b_1 & b_2 & -v \end{matrix}\right) D_{u v}^{(j)} \]

that is applied to \( D_{p_1 q_1}^{(l_1)} D_{p_2 q_2}^{(l_2)} \) and to \( D_{p_1 q_1'}^{(l_1)} D_{p_2 q_2'}^{(l_2)} \), leading to the linear combination of shorter integrals

\[ \frac{1}{8\pi^2} \int D_{u v}^{(j)} D_{u' v'}^{(j')*} D_{a_3 b_3}^{(l_3)} D_{a_3' b_3'}^{(l_3)*} \dots D_{a_n b_n}^{(l_n)} D_{a_n' b_n'}^{(l_n)*} \mathrm{d}\hat{R} \]

The recursion terminates when only the pair \( D_{u v}^{(j)} D_{u' v'}^{(j')*} \) is left, by means of the orthogonality relation

\[ \frac{1}{8\pi^2} \int D_{u v}^{(j)} D_{u' v'}^{(j')*} \mathrm{d}\hat{R} = \frac{1}{2j + 1} \delta_{jj'} \delta_{uu'} \delta_{vv'} \,. \]

Definition at line 1052 of file multidip_special.F90.

Here is the caller graph for this function: