# OpenRSP Notations and Conventions¶

The following notations and conventions will be used through the OpenRSP program and the documentation:

Perturbation
is described by a label, a complex frequency and its order. Any two perturbations are different if they have different labels, and/or frequencies, and/or orders.
Perturbation label
An integer distinguishing one perturbation from others; all different perturbation labels involved in the calculations should be given by calling the application programming interface (API) OpenRSPSetPerturbations(); OpenRSP will stop if there is any unspecified perturbation label given afterwards when calling the APIs OpenRSPGetRSPFun() or OpenRSPGetResidue().
Perturbation order
Each perturbation can acting on molecules once or many times, that is the order of the perturbation.
Perturbation components and their ranks

Each perturbation may have different numbers of components for their different orders, the position of each component is called its rank.

For instance, there will usually be $$x,y,z$$ components for the electric dipole perturbation, and their ranks are {0,1,2} in zero-based numbering, or {1,2,3} in one-based numbering.

The numbers of different components of perturbations and their ranks are totally decided by the host program. OpenRSP will get such information from callback functions, that is OpenRSP itself is a perturbation free library.

NOTE: the above perturbtion free scheme is however not implemented for the current release so that OpenRSP will use its own internal representations for different perturbations.

Perturbation tuple

An ordered list of perturbation labels, and in which we further require that identical perturbation labels should be consecutive. That means the tuple $$(a,b,b,c)$$ is allowed, but $$(a,b,c,b)$$ is illegal because the identical labels $$b$$ are not consecutive.

As a tuple:

1. Multiple instances of the same labels are allowed so that $$(a,b,b,c)\ne(a,b,c)$$, and
2. The perturbation labels are ordered so that $$(a,b,c)\ne(a,c,b)$$ (because their corresponding response functions or residues are in different shapes).

We will sometimes use an abbreviated form of perturbation tuple as, for instance $$abc\equiv(a,b,c)$$.

Obviously, a perturbation tuple $$+$$ its corresponding complex frequencies for each perturbation label can be viewed as a set of perturbations, in which the number of times a label (with the same frequency) appears is the order of the corresponding perturbation.

Category of perturbation frequencies

We use different integers for distinguishing different values of frequencies within a frequency configuration. The category arrary is determined by:

1. For each frequency configuration, we start at the first perturbation and let its frequency value be designated number 1, then
2. For the next perturbation,
1. If its frequency value corresponds to a frequency value encountered previously in this frequency, then use the same designation as for that previously encountered frequency value, or
2. If its frequency value has not been encountered before, then let that frequency value be designated with the first unused number;
3. Continue like this until the end of the perturbation tuple;
4. Start the numbering over again at the next frequency configuration.
Canonical order
1. In OpenRSP, all perturbation tuples are canonically orderd according to the argument pert_tuple in the API OpenRSPGetRSPFun() or OpenRSPGetResidue(). For instance, when a perturbation tuple $$(a,b,c)$$ given as pert_tuple in the API OpenRSPGetRSPFun(), OpenRSP will use such order ($$a>b>c$$) to arrange all perturbation tuples inside and sent to the callback functions.

2. Moreover, a collection of several perturbation tuples will also follow the canonical order. For instance, a collection of all possible perturbation tuples of labels $$a,b,c,d$$ are $$(0,a,b,ab,c,ac,bc,abc,d,ad,bd,abd,cd,acd,bcd,abcd)$$, where $$0$$ means unperturbed quantities that is always the first one in the collection.

The rules for generating the above collection are:

1. When taking a new perturbation into consideration, always do so in alphabetical order (and begin with the empty set);
2. When taking a new perturbation into consideration, the new subsets are created by making the union of all previous subsets (including the empty set) and the new perturbation (putting the new perturbation at the end).
Perturbation $$a$$
The first perturbation label in the tuple sent to OpenRSP APIs OpenRSPGetRSPFun() or OpenRSPGetResidue(), are the perturbation $$a$$ [Thorvaldsen2008].
1. The addressing of perturbation labels in a tuple is decided by (i) the argument pert_tuple sent to the API OpenRSPGetRSPFun() or OpenRSPGetResidue(), and (ii) the canonical order that OpenRSP uses.
Therefore, the shape of response functions or residues is mostly decided by the host program. Take $$\mathcal{E}^{abbc}$$ as an example, its shape is $$(N_{a},N_{bb},N_{c})$$, where $$N_{a}$$ and $$N_{c}$$ are respectively the numbers of components of the first order of the perturbations $$a$$ and $$c$$, and $$N_{bb}$$ is the number of components of the second order of the perturbation $$b$$, and
1. In OpenRSP, we will use notation [a][bb][c] for $$\mathcal{E}^{abbc}$$, where the leftmost index (a) runs slowest in memory and the rightmost index (c) runs fastest. However, one should be aware that the results are still in a one-dimensional array.
2. If there two different frequencies for the perturbation $$b$$, OpenRSP will return [a][b1][b2][c], where b1 and b2 stand for the components of the first order of the perturbation $$b$$.
3. The notation for a collection of perturbation tuples (still in a one-dimensional array) is {1,[a],[b],[a][b],[c],[a][c],[b][c],[a][b][c]} for $$(0,a,b,ab,c,ac,bc,abc)$$, where as aforementioned the first one is the unperturbed quantities.