API Reference¶
In order to use OpenRSP, C users should first include the header file of OpenRSP in their codes:
#inclde "OpenRSP.h"
while Fortran users should use the OpenRSP module:
use OpenRSP_f
In this chapter, we will describe all the functions defined in OpenRSP API for users. These functions should be invoked as:
ierr = OpenRSP...(...)
where ierr
contains the error information. Users should check if
it equals to QSUCCESS
(constant defined in
QcMatrix library). If not, there
was error happened in the invoked function, and the calculations should
stop.
Functions of OpenRSP API (C version)¶

QErrorCode
OpenRSPCreate
(open_rsp, num_atoms)¶ Creates the context of response theory calculations, should be called at first.
Var open_rsp: context of response theory calculations
Vartype open_rsp: OpenRSP* (struct*)
Parameters:  num_atoms (const QInt) – number of atoms (to be removed after perturbation free scheme implemented)
Return type: QErrorCode (error information)

QErrorCode
OpenRSPSetLinearRSPSolver
(open_rsp, user_ctx, get_linear_rsp_solution)¶ Sets the context of linear response equation solver.
Var open_rsp: context of response theory calculations
Vartype open_rsp: OpenRSP*
Parameters:  user_ctx (void*) – userdefined callback function context
 get_linear_rsp_solution (const GetLinearRSPSolution (function
pointer void (*)(...))) – userspecified callback function of linear
response equation solver, see the callback function
get_linear_rsp_solution()
Return type: QErrorCode

QErrorCode
OpenRSPSetPerturbations
(open_rsp, num_pert_lab, pert_labels, pert_max_orders, pert_num_comps, user_ctx, get_pert_concatenation)¶ Sets all perturbations involved in response theory calculations.
Var open_rsp: context of response theory calculations
Vartype open_rsp: OpenRSP*
Parameters:  num_pert_lab (const QInt) – number of all different perturbation labels involved in calculations
 pert_labels (const QcPertInt*) – all the different perturbation labels involved
 pert_max_orders (const QInt*) – allowed maximal order of a perturbation described by exactly one of the above different labels
 pert_num_comps (const QInt*) – number of components of a perturbation described by
exactly one of the above different labels, up to the allowed maximal
order, size is therefore the sum of
pert_max_orders
 user_ctx (void*) – userdefined callback function context
 get_pert_concatenation (const GetPertCat (function pointer void (*)(...))) – user specified function for getting the ranks of components of subperturbation tuples (with the same perturbation label) for given components of the corresponding concatenated perturbation tuple
Return type: QErrorCode
NOTE: get_pert_concatenation()
will not be invoked in the current
release; OpenRSP will use it after the perturbation free scheme implmented.

QErrorCode
OpenRSPSetOverlap
(open_rsp, num_pert_lab, pert_labels, pert_max_orders, user_ctx, get_overlap_mat, get_overlap_exp)¶ Sets the overlap operator.
Var open_rsp: context of response theory calculations
Vartype open_rsp: OpenRSP*
Parameters:  num_pert_lab (const QInt) – number of all different perturbation labels that can act on the overlap operator
 pert_labels (const QcPertInt*) – all the different perturbation labels involved
 pert_max_orders (const QInt*) – allowed maximal order of a perturbation described by exactly one of the above different labels
 user_ctx (void*) – userdefined callback function context
 get_overlap_mat (const GetOverlapMat (function pointer void (*)(...))) – userspecified callback function to calculate
integral matrices of overlap operator as well as its derivatives with
respect to different perturbations, see the callback function
get_overlap_mat()
 get_overlap_exp (const GetOverlapExp (function pointer void (*)(...))) – userspecified callback function to calculate
expectation values of overlap operator as well as its derivatives with
respect to different perturbations, see the callback function
get_overlap_exp()
Return type: QErrorCode

QErrorCode
OpenRSPAddOneOper
(open_rsp, num_pert_lab, pert_labels, pert_max_orders, user_ctx, get_one_oper_mat, get_one_oper_exp)¶ Adds a oneelectron operator to the Hamiltonian.
Var open_rsp: context of response theory calculations
Vartype open_rsp: OpenRSP*
Parameters:  num_pert_lab (const QInt) – number of all different perturbation labels that can act on the oneelectron operator
 pert_labels (const QcPertInt*) – all the different perturbation labels involved
 pert_max_orders (const QInt*) – allowed maximal order of a perturbation described by exactly one of the above different labels
 user_ctx (void*) – userdefined callback function context
 get_one_oper_mat (const GetOneOperMat (function pointer void (*)(...))) – userspecified callback function to calculate
integral matrices of oneelectron operator as well as its derivatives
with respect to different perturbations, see the callback function
get_one_oper_mat()
 get_one_oper_exp (const GetOneOperExp (function pointer void (*)(...))) – userspecified callback function to calculate
expectation values of oneelectron operator as well as its derivatives
with respect to different perturbations, see the callback function
get_one_oper_exp()
Return type: QErrorCode

QErrorCode
OpenRSPAddTwoOper
(open_rsp, num_pert_lab, pert_labels, pert_max_orders, user_ctx, get_two_oper_mat, get_two_oper_exp)¶ Adds a twoelectron operator to the Hamiltonian.
Var open_rsp: context of response theory calculations
Vartype open_rsp: OpenRSP*
Parameters:  num_pert_lab (const QInt) – number of all different perturbation labels that can act on the twoelectron operator
 pert_labels (const QcPertInt*) – all the different perturbation labels involved
 pert_max_orders (const QInt*) – allowed maximal order of a perturbation described by exactly one of the above different labels
 user_ctx (void*) – userdefined callback function context
 get_two_oper_mat (const GetTwoOperMat (function pointer void (*)(...))) – userspecified callback function to calculate
integral matrices of twoelectron operator as well as its derivatives
with respect to different perturbations, see the callback function
get_two_oper_mat()
 get_two_oper_exp (const GetTwoOperExp (function pointer void (*)(...))) – userspecified callback function to calculate
expectation values of twoelectron operator as well as its derivatives
with respect to different perturbations, see the callback function
get_two_oper_exp()
Return type: QErrorCode

QErrorCode
OpenRSPAddXCFun
(open_rsp, num_pert_lab, pert_labels, pert_max_orders, user_ctx, get_xc_fun_mat, get_xc_fun_exp)¶ Adds an exchangecorrelation (XC) functional to the Hamiltonian.
Var open_rsp: context of response theory calculations
Vartype open_rsp: OpenRSP*
Parameters:  num_pert_lab (const QInt) – number of all different perturbation labels that can act on the XC functional
 pert_labels (const QcPertInt*) – all the different perturbation labels involved
 pert_max_orders (const QInt*) – allowed maximal order of a perturbation described by exactly one of the above different labels
 user_ctx (void*) – userdefined callback function context
 get_xc_fun_mat (const GetXCFunMat (function pointer void (*)(...))) – userspecified callback function to calculate
integral matrices of XC functional as well as its derivatives with
respect to different perturbations, see the callback function
get_xc_fun_mat()
 get_xc_fun_exp (const GetXCFunExp (function pointer void (*)(...))) – userspecified callback function to calculate
expectation values of XC functional as well as its derivatives with
respect to different perturbations, see the callback function
get_xc_fun_exp()
Return type: QErrorCode

QErrorCode
OpenRSPAddZeroOper
(open_rsp, num_pert_lab, pert_labels, pert_max_orders, user_ctx, get_zero_oper_contrib)¶ Adds a zeroelectron operator to the Hamiltonian.
Var open_rsp: context of response theory calculations
Vartype open_rsp: OpenRSP*
Parameters:  num_pert_lab (const QInt) – number of all different perturbation labels that can act on the zeroelectron operator
 pert_labels (const QcPertInt*) – all the different perturbation labels involved
 pert_max_orders (const QInt*) – allowed maximal order of a perturbation described by exactly one of the above different labels
 user_ctx (void*) – userdefined callback function context
 get_zero_oper_contrib (const GetZeroOperContrib (function pointer void (*)(...))) – userspecified function to calculate
contributions from the zeroelectron operator, see the callback function
get_zero_oper_contrib()
Return type: QErrorCode

QErrorCode
OpenRSPAssemble
(open_rsp)¶ Assembles the context of response theory calculations and checks its validity, should be called before any function
OpenRSPGet...()
, otherwise the results might be incorrect.Var open_rsp: context of response theory calculations Vartype open_rsp: OpenRSP* Return type: QErrorCode

QErrorCode
OpenRSPWrite
(open_rsp, fp_rsp)¶ Writes the context of response theory calculations.
Parameters:  open_rsp (const OpenRSP*) – context of response theory calculations
 fp_rsp (FILE*) – file pointer
Return type: QErrorCode

QErrorCode
OpenRSPGetRSPFun
(open_rsp, ref_ham, ref_state, ref_overlap, num_props, len_tuple, pert_tuple, num_freq_configs, pert_freqs, kn_rules, r_flag, write_threshold, size_rsp_funs, rsp_funs)¶ Gets the response functions for given perturbations.
Parameters:  open_rsp (OpenRSP*) – context of response theory calculations
 ref_ham (const QcMat*) – Hamiltonian of referenced state
 ref_state (const QcMat*) – electronic state of referenced state
 ref_overlap (const QcMat*) – overlap integral matrix of referenced state
 num_props (const QInt) – number of properties to calculate
 len_tuple (const QInt*) – length of perturbation tuple for each property,
size is the number of properties (
num_props
)  pert_tuple (const QcPertInt*) – ordered list of perturbation labels (perturbation
tuple) for each property, size is
sum(len_tuple)
, the first label of each property is the perturbation \(a\)  num_freq_configs (const QInt*) – number of different frequency configurations
for each property, size is
num_props
 pert_freqs (const QReal*) – complex frequencies of each perturbation label (except
for the perturbation \(a\)) over all frequency configurations, size is
2
\(\times\)(dot_product(len_tuple,num_freq_configs)sum(num_freq_configs))
, and arranged as[num_freq_configs[i]][len_tuple[i]1][2]
(i
runs from0
tonum_props1
) and the real and imaginary parts of each frequency are consecutive in memory  kn_rules (const QInt*) – number \(k\) for the \((k,n)\) rule [1] for each
property (OpenRSP will determine the number \(n\)), size is the
number of properties (
num_props
)  r_flag (const QInt) – flag to determine the restarting setup; 0 means “do not load/use any existing restarting data and do not save any new restarting data”, and 3 means “use any existing restarting data and extend existing restarting data with all new restarting data”
 write_threshold (const QReal) – tensor elements with absolute value below
write_threshold
will not be output by OpenRSP  size_rsp_funs (const QInt) – size of the response functions, equals to the sum of
the size of each property to calculate—which is the product of the
size of added perturbations (specified by the perturbation tuple
pert_tuple
) and the number of frequency configurationsnum_freq_configs
for each property
Var rsp_funs: the response functions, size is
2
\(\times\)size_rsp_funs
and arranged as[num_props][num_freq_configs][pert_tuple][2]
, where the real and imaginary parts of the response functions are consecutive in memoryVartype rsp_funs: QReal*
Return type: QErrorCode
[1]  The description of the \((k,n)\) rule can be found, for instance, in [Ringholm2014]. 

QErrorCode
OpenRSPGetResidue
(open_rsp, ref_ham, ref_state, ref_overlap, order_residue, num_excit, excit_energy, eigen_vector, num_props, len_tuple, pert_tuple, residue_num_pert, residue_idx_pert, num_freq_configs, pert_freqs, kn_rules, r_flag, write_threshold, size_residues, residues)¶ Gets the residues for given perturbations.
Parameters:  open_rsp (OpenRSP*) – context of response theory calculations
 ref_ham (const QcMat*) – Hamiltonian of referenced state
 ref_state (const QcMat*) – electronic state of referenced state
 ref_overlap (const QcMat*) – overlap integral matrix of referenced state
 order_residue (const QInt) – order of residues, that is also the length of each excitation tuple
 num_excit (const QInt) – number of excitation tuples that will be used for residue calculations
 excit_energy (const QReal*) – excitation energies of all tuples, size is
order_residue
\(\times\)num_excit
, and arranged as[num_excit][order_residue]
; that is, there will beorder_residue
frequencies of perturbation labels (or sums of frequencies of perturbation labels) respectively equal to theorder_residue
excitation energies per tupleexcit_energy[i][:]
(i
runs from0
tonum_excit1
)  eigen_vector (QcMat*[]) – eigenvectors (obtained from the generalized
eigenvalue problem) of all excitation tuples, size is
order_residue
\(\times\)num_excit
, and also arranged in memory as[num_excit][order_residue]
so that each eigenvector has its corresponding excitation energy inexcit_energy
 num_props (const QInt) – number of properties to calculate
 len_tuple (const QInt*) – length of perturbation tuple for each property,
size is the number of properties (
num_props
)  pert_tuple (const QcPertInt*) – ordered list of perturbation labels (perturbation
tuple) for each property, size is
sum(len_tuple)
, the first label of each property is the perturbation \(a\)  residue_num_pert (const QInt*) – for each property and each excitation energy
in the tuple, the number of perturbation labels whose sum of
frequencies equals to that excitation energy, size is
order_residue
\(\times\)num_props
, and arragned as[num_props][order_residue]
; a negativeresidue_num_pert[i][j]
(i
runs from0
tonum_props1
) means that the sum of frequencies of perturbation labels equals toexcit_energy[:][j]
 residue_idx_pert (const QInt*) – for each property and each excitation energy
in the tuple, the indices of perturbation labels whose sum of
frequencies equals to that excitation energy, size is
sum(residue_num_pert)
, and arranged as[residue_num_pert]
 num_freq_configs (const QInt*) – number of different frequency configurations
for each property, size is
num_props
 pert_freqs (const QReal*) – complex frequencies of each perturbation label (except
for the perturbation \(a\)) over all frequency configurations and
excitation tuples, size is
2
\(\times\)(dot_product(len_tuple,num_freq_configs)sum(num_freq_configs))
\(\times\)num_excit
, and arranged as[num_excit][num_freq_configs[i]][len_tuple[i]1][2]
(i
runs from0
tonum_props1
) and the real and imaginary parts of each frequency are consecutive in memory; notice that the (sums of) frequencies of perturbation labels specified byresidue_idx_pert
should equal to the corresponding excitation energies for all frequency configurations and excitation tuples  kn_rules (const QInt*) – number \(k\) for the \((k,n)\) rule for each property
(OpenRSP will determine the number \(n\)), size is the number of
properties (
num_props
)  r_flag (const QInt) – flag to determine the restarting setup; 0 means “do not load/use any existing restarting data and do not save any new restarting data”, and 3 means “use any existing restarting data and extend existing restarting data with all new restarting data”
 write_threshold (const QReal) – tensor elements with absolute value below
write_threshold
will not be output by OpenRSP  size_residues (const QInt) – size of the residues, equals to the sum of the
size of each property to calculate—which is the product of the
size of added perturbations (specified by the perturbation tuple
pert_tuple
), the number of excitation tuples (num_excit
) and the number of frequency configurationsnum_freq_configs
for each property
Var residues: the residues, size is
2
\(\times\)size_residues
and arranged as[num_props][num_excit][num_freq_configs][pert_tuple][2]
, where the real and imaginary parts of the residues are consecutive in memoryVartype residues: QReal*
Return type: QErrorCode

QErrorCode
OpenRSPDestroy
(open_rsp)¶ Destroys the context of response theory calculations, should be called at the end.
Var open_rsp: context of response theory calculations Vartype open_rsp: OpenRSP* Return type: QErrorCode
Functions of OpenRSP API (Fortran version)¶
Functions of OpenRSP API (Fortran) are similar to those of the C version, except
that an extra _f
should be appended to each function. Other differences are
the (ii) argument types and (iii) callback functions (subroutines for Fortran).
The latter will be described in Chapter Callback Function Scheme. The
former relates to the convention of types in Fortran, please refer to the manual
of QcMatrix library and the following
table for the convention:
Type in OpenRSP  Fortran 

struct OpenRSP 
type(OpenRSP) 
void* user_ctx 
type(C_PTR) user_ctx 
callback functions  external subroutines 
We also want to mention that users can also pass their own defined Fortran type
as the userdefined callback function context to OpenRSP, by encapsulated into
the type(C_PTR) user_ctx
.