Query Objects

There are two types of query objects in mrsimulator—TransitionQuery and MixingQuery. A TransitionQuery object contains attributes that query the spin systems for allowed transitions, i.e., transitions that satisfy the query criterion. A MixingQuery, similarly, queries consecutive transitions for allowed transition pathways—pathways that satisfy the mixing query criterion.

TransitionQuery

Transition queries are assigned to the transition_query attribute of a SpectralEvent object as

from mrsimulator.method import SpectralEvent

SpectralEvent(
    # other attributes
    transition_query=[
        # list of TransitionQuery objects
    ]
)

A generic syntax for the TransitionQuery object in python dictionary representation follows,

t_query = {
    "ch1": {"P": [-1, 1], "D": [0, 2]},
    "ch2": {"P": [+1], "D": [0, -2]},
    "ch3": {"P": [0], "D": [0]},
}

where ch- s are the channels over which the query is performed, and its value is a python dictionary of the SymmetryQuery object. SymmetryQuery is based on the spin transition functions. Its attributes,

(3)\[\begin{split}P = [(m_f - m_i)_j]_{j=0}^{N_\text{ch}}, \\ D = [(m_f^2 - m_i^2)_j]_{j=0}^{N_\text{ch}},\end{split}\]

are the site-wise list of \(p = m_f - m_i\) and \(d = m_f^2 - m_i^2\) transition symmetry functions, respectively. In Eq. (3), the index \(j\) runs over the sites within channel ch- and \(N_\text{ch}\) is the total number of sites in the respective channel. The symbols \(m_f\) and \(m_i\) are the spin quantum numbers for the final and initial energy states of the transition associated with the site at index \(j\). For example, consider the following heteronuclear two-site double-quantum transition for a two-site spin system [1H, 13C], with ch1=1H and ch2=13C

(4)\[|0.5, 0.5\rangle \rightarrow |-0.5, -0.5\rangle.\]

To select this transition, we set up the following query,

t_query = {
    "ch1": {"P": [-1]},
    "ch2": {"P": [-1]},
}

The above query selects all transitions where precisely one site in ch1 and one site in ch2 simultaneously undergoes a \(p=-1\) transition. Similarly, for spin system [1H, 1H] with ch1=1H, undergoing a homonuclear two-site double-quantum transition, we write the query as,

t_query = {
    "ch1": {"P": [-1, -1]},
}

Here, the query selects all transitions where exactly two sites in ch1 simultaneously undergo a \(p=-1\) transition.

A transition query selects a set of transitions. In the above two examples, the set consists of a single transition. In the case of a three-site spin system [1H, 1H, 1H], the same query selects six transitions, where two sites in ch1 simultaneously undergo a \(p=-1\) transition, while the third site is at \(p=0\).

Note, while the third site defaults to a \(p=0\), we do not specify the query as "P": [-1, -1, 0]. The query "P": [-1, -1] is not the same as "P": [-1, -1, 0]. While both queries select homonuclear two-site double-quantum transitions, the latter requires a minimum of a three-site spin system, contrary to a minimum of a two-site spin system for the first.

Another example of a query object for selecting homonuclear two-site zero-quantum transitions is

t_query = {
    "ch1": {"P": [-1, +1]},
}

In contrast, a query for selecting single-site multi-quantum transitions follow,

t_query = {
    "ch1": {"P": [-3]},
}

In the case of a single-site spin system [27Al], the above query will select three triple-quantum transitions,

(5)\[\begin{split}|2.5\rangle \rightarrow |-0.5\rangle, \\ |1.5\rangle \rightarrow |-1.5\rangle, \\ |0.5\rangle \rightarrow |-2.5\rangle, \\\end{split}\]

one symmetric, and two asymmetric transitions. To select the symmetric transition, modify the query to

t_query = {
    "ch1": {"P": [-3], "D": [0]},
}

which first selects the three \(p=-3\) transitions, and then filters the selection to transitions where \(m_f^2 - m_i^2=0\), i.e., \(|1.5\rangle \rightarrow |-1.5\rangle\) central transition.

Rule of Union and Intersection

As a general rule, the more query criteria we add to the query objects, the smaller the set of selected transitions. For example, the query from "ch1": {"P": [-3]} to "ch1": {"P": [-3], "D": [0]} narrows the transitions from three to one in the case of a single-site spin system [27Al]. It follows the intersection rule—a set common to all selection criteria.

Now consider a case where we want to select both \(p=-1\) and \(p=+1\) transitions simultaneously. Following the rule of intersection, there are precisely zero transitions that are both \(p=+1\) and \(p=-1\). Here, we use the union rule. Recall that the value of the transition_query attribute of the SpectralEvent object is a list of queries,

SpectralEvent(
    # other attributes
    transition_query=[
        # TransitionQuery(...),  # 0
        # TransitionQuery(...),  # 1
        # TransitionQuery(...),  # 2
    ]
)

The union rule applies to a set of transitions from multiple transition queries. In the above example, the resulting set of selected transitions is the union of transition sets from the three queries. To select \(p=\pm1\) transitions, we write

SpectralEvent(
    # other attributes
    transition_query=[
        # union of set of transitions from query-1 and query-2
        {"ch1": {"P": [-1]}},  # query-1
        {"ch1": {"P": [+1]}},  # query-2
    ]
)

MixingQuery

Mixing query utilizes rotational operations to select connected transitions in a multi SpectralEvent method. A generic syntax of the MixingQuery in python dictionary representation follows,

mix_query = {
    "ch1": {"angle": 3.14159, "phase": 0},  # both in radians
    "ch2": {"angle": 1.57079, "phase": -1.57079},  # both in radians
    "ch3": {"angle": 0, "phase": 0},  # both in radians
}

where ch- s are the channels over which the query is performed. Its value is the python dictionary representation of the RotationalQuery object. A MixingQuery is a channel-wise selective rotation with parameters angle and phase.