Table Of Contents

Previous topic

3. General use of z-Pares

4. Advanced features

4.1. User defined quadrature rule

The user can set an arbitrary quadrature rule by oneself. The subroutine which returns quadrature rule can be passed as optional argument at the end of argument list (next to info) of any z-Pares main routines.

The interface of the user defined subroutine should be in the form of

subroutine sub(mode, qmax, quad_idx, left, right, z, weight, zeta, lambda, info)

Table 4.1 describes the arguments. To enable the user defined quadrature rule, the user should set prm%quad_type = ZPARES_QUAD_USER.

Table 4.1: Interface definition of a subroutine represents an user defined quadrature rule.

Name Description Type Input or output
mode Mode specifier integer IN
qmax Maximum value of quad_idx integer IN
quad_idx Value of \(j\) integer IN
left left which has been passed to the z-Pares main routine complex(kind(0d0)) IN
right right which has been passed to the z-Pares main routine double precsion IN
z Quadrature point \(z_j\) complex(kind(0d0)) OUT
weight Quadrature weight \(w_j\) complex(kind(0d0)) OUT
zeta \(\zeta_j := f(z_j)\) complex(kind(0d0)) OUT
lambda \(\mu\) as input, \(\lambda:=f^{-1}(\mu)\) as output complex(kind(0d0)) IN/OUT

In z-Pares, approximate the contour integral by a \(N\) point numerical quadrature:

\[\frac{1}{2 \pi \mathrm{i}} \oint_\Gamma f(z)^k (z B - A)^{-1}{BV} \mathrm{d}z \approx \sum_{j=1}^{N} w_j f(z_j)^{k} (z_j B - A)^{-1}{BV} \quad (k=0,1,\dots),\]

where \(\Gamma\) is a counter-clockwise contour path, \(f(z)\) is a holomorphic function which maps z so that z is \(|f(z)| \approx 1\), and \(z_j\) and \(w_j\) are quadrature points and weights \((j = 1, 2, \dots, N)\).

The subroutine should behave differently according to input argument mode:

  • If mode == 0

    In this mode, the user can set the quadrature points and weights. \(j\) is passed in quad_idx by the z-Pares main routine. The corresponding \(z_j\), \(w_j\), and \(\zeta_j := f(z_j)\) should be set in z, weight, and zeta. The output argument lambda does not have to be touched.

  • If mode == 1

    This mode is significant for prm%extract == ZPARES_EXTRACT_EM. In this mode, the user should compute \(\lambda := f^{-1}(\mu)\). \(\mu\) comes in lambda as an input then \(\lambda\) should be passed in lambda as an output. The output arguments z, weight, and zeta do not have to be touched. If prm%extract == ZPARES_EXTRACT_RR it can be ignored.

If the components of each set of \(\{z_j \}_{j=1}^{N}\), \(\{w_j \}_{j=1}^{N}\), and \(\{ \zeta_j \}_{j=1}^{N}\) form complex conjugate pairs, we recommend the user to set prm%sym_contour=.true. for a possible efficiency. If prm%sym_contour==.true., for each set \(\{z_j \}_{j=1}^{N/2}\), \(\{w_j \}_{j=1}^{N/2}\), and \(\{ \zeta_j \}_{j=1}^{N/2}\) should be the counterparts of the complex conjugate pairs.