# 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: Vartype open_rsp: context of response theory calculations OpenRSP* (struct*) num_atoms (const QInt) – number of atoms (to be removed after perturbation free scheme implemented) QErrorCode (error information)
QErrorCode OpenRSPSetLinearRSPSolver(open_rsp, user_ctx, get_linear_rsp_solution)

Sets the context of linear response equation solver.

Var open_rsp: Vartype open_rsp: context of response theory calculations OpenRSP* user_ctx (void*) – user-defined callback function context get_linear_rsp_solution (const GetLinearRSPSolution (function pointer void (*)(...))) – user-specified callback function of linear response equation solver, see the callback function get_linear_rsp_solution() 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: Vartype open_rsp: context of response theory calculations OpenRSP* 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*) – user-defined callback function context get_pert_concatenation (const GetPertCat (function pointer void (*)(...))) – user specified function for getting the ranks of components of sub-perturbation tuples (with the same perturbation label) for given components of the corresponding concatenated perturbation tuple 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: Vartype open_rsp: context of response theory calculations OpenRSP* 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*) – user-defined callback function context get_overlap_mat (const GetOverlapMat (function pointer void (*)(...))) – user-specified 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 (*)(...))) – user-specified 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() 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 one-electron operator to the Hamiltonian.

Var open_rsp: Vartype open_rsp: context of response theory calculations OpenRSP* num_pert_lab (const QInt) – number of all different perturbation labels that can act on the one-electron 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*) – user-defined callback function context get_one_oper_mat (const GetOneOperMat (function pointer void (*)(...))) – user-specified callback function to calculate integral matrices of one-electron 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 (*)(...))) – user-specified callback function to calculate expectation values of one-electron operator as well as its derivatives with respect to different perturbations, see the callback function get_one_oper_exp() 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 two-electron operator to the Hamiltonian.

Var open_rsp: Vartype open_rsp: context of response theory calculations OpenRSP* num_pert_lab (const QInt) – number of all different perturbation labels that can act on the two-electron 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*) – user-defined callback function context get_two_oper_mat (const GetTwoOperMat (function pointer void (*)(...))) – user-specified callback function to calculate integral matrices of two-electron 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 (*)(...))) – user-specified callback function to calculate expectation values of two-electron operator as well as its derivatives with respect to different perturbations, see the callback function get_two_oper_exp() 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 exchange-correlation (XC) functional to the Hamiltonian.

Var open_rsp: Vartype open_rsp: context of response theory calculations OpenRSP* 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*) – user-defined callback function context get_xc_fun_mat (const GetXCFunMat (function pointer void (*)(...))) – user-specified 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 (*)(...))) – user-specified 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() QErrorCode
QErrorCode OpenRSPAddZeroOper(open_rsp, num_pert_lab, pert_labels, pert_max_orders, user_ctx, get_zero_oper_contrib)

Adds a zero-electron operator to the Hamiltonian.

Var open_rsp: Vartype open_rsp: context of response theory calculations OpenRSP* num_pert_lab (const QInt) – number of all different perturbation labels that can act on the zero-electron 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*) – user-defined callback function context get_zero_oper_contrib (const GetZeroOperContrib (function pointer void (*)(...))) – user-specified function to calculate contributions from the zero-electron operator, see the callback function get_zero_oper_contrib() 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: Vartype open_rsp: context of response theory calculations OpenRSP* 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 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: Var rsp_funs: 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 from 0 to num_props-1) 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 configurations num_freq_configs for each property 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 memory QReal* 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: Var residues: 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 be order_residue frequencies of perturbation labels (or sums of frequencies of perturbation labels) respectively equal to the order_residue excitation energies per tuple excit_energy[i][:] (i runs from 0 to num_excit-1) 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 in excit_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 negative residue_num_pert[i][j] (i runs from 0 to num_props-1) means that the sum of frequencies of perturbation labels equals to -excit_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 from 0 to num_props-1) and the real and imaginary parts of each frequency are consecutive in memory; notice that the (sums of) frequencies of perturbation labels specified by residue_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 configurations num_freq_configs for each property 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 memory QReal* QErrorCode
QErrorCode OpenRSPDestroy(open_rsp)

Destroys the context of response theory calculations, should be called at the end.

Var open_rsp: Vartype open_rsp: context of response theory calculations OpenRSP* 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 user-defined callback function context to OpenRSP, by encapsulated into the type(C_PTR) user_ctx.