"""The `dnmr` module provides functions for calculating DNMR line shapes, and
classes to describe DNMR systems.
The dnmr module provides the following classes:
* `DnmrTwoSinglets`: a sumulation of the lineshape for two uncoupled nuclei
undergoing exchange.
* `DnmrAB`: a simulation of the lineshape for two coupled nuclei undergoing
exchange (i.e. an AB (or AX) pattern at the slow exchange limit).
The `dnmr` module provides the following functions:
* `dnmr_two_singlets`: for simulating the lineshape for two uncoupled nuclei
undergoing exchange [3]_.
* `dnmr_AB` : for simulating the lineshape for two coupled nuclei undergoing
exchange (i.e. an AB (or AX) pattern at the slow exchange limit) [4]_.
References
----------
.. [3] Sandström, J. Dynamic NMR Spectroscopy; Academic Press: New York, 1982.
.. [4] a) Brown, K.C.; Tyson, R.L.; Weil, J.A. J. Chem. Educ. 1998, 75, 1632.
b) an important math correction to the previous reference:
TODO: add reference to correction
"""
import numpy as np
from nmrsim._utils import is_number, is_decimal_fraction, is_tuple_of_two_numbers, is_positive, is_integer
def _dnmr_two_singlets_func(va, vb, ka, wa, wb, pa):
"""
Create a function that requires only frequency as an argurment, for
calculating the lineshape of a DNMR spectrum for two uncoupled spin-half
nuclei.
This allows the expressions that are independent of frequency to be
calculated only once, outside the returned function. The returned function
can then be applied to a list of frequency (x) coordinates (e.g. a numpy
linspace) to provide a list of the corresponding intensity (y) coordinates.
Parameters
----------
va : int or float
The frequency (Hz) of nucleus 'a' at the slow exchange limit. va > vb
vb : int or float
The frequency (Hz) of nucleus 'b' at the slow exchange limit. vb < va
ka : int or float
The rate constant (Hz) for state a--> state b
wa : int or float
The width at half height of the signal for nucleus a (at the slow
exchange limit).
wb : int or float
The width at half height of the signal for nucleus b (at the slow
exchange limit).
pa : float (0 <= pa <= 1)
The fraction of the population in state a.
Returns
-------
_maker: function
Notes
-----
The nmrsim.dnmr module gives a reference for the algorithm used here.
"""
pi = np.pi
pi_squared = pi**2
T2a = 1 / (pi * wa)
T2b = 1 / (pi * wb)
pb = 1 - pa
tau = pb / ka
dv = va - vb
Dv = (va + vb) / 2
P = tau * (1 / (T2a * T2b) + pi_squared * (dv**2)) + (pa / T2a + pb / T2b)
p = 1 + tau * ((pb / T2a) + (pa / T2b))
Q = tau * (-pi * dv * (pa - pb))
R = pi * dv * tau * ((1 / T2b) - (1 / T2a)) + pi * dv * (pa - pb)
r = 2 * pi * (1 + tau * ((1 / T2a) + (1 / T2b)))
def _maker(v):
"""Calculate the intensity (y coordinate) at a given frequency v(x coordinate)."""
# TODO: fix docstring, explain _P _Q etc correlate to P, Q etc in lit.
# FIXED: previous version of this function used
# nonlocal Dv, P, Q, R
# but apparently when function called repeatedly these values would
# become corrupted (turning into arrays?!)
# Solution: add underscores to create copies of any variables in
# outer scope whose values are changed in the inner scope.
_Dv = Dv - v
_P = P - tau * 4 * pi_squared * (_Dv**2)
_Q = Q + tau * 2 * pi * _Dv
_R = R + _Dv * r
return (_P * p + _Q * _R) / (_P**2 + _R**2)
return _maker
[docs]def dnmr_two_singlets(va, vb, ka, wa, wb, pa, limits=None, points=800):
"""
Create a the lineshape for a DNMR spectrum of two uncoupled spin-half nuclei.
Parameters
----------
va, vb : int or float
The frequencies (Hz) of nuclei 'a' and 'b' at the slow exchange limit.
ka : int or float
The rate constant (Hz) for state a--> state b
wa, wb : int or float
The peak widths at half height for the 'a' and 'b' singlets at the
slow-exchange limit.
pa : float (0 <= pa <= 1)
The fraction of the population in state a
limits : (int or float, int or float), optional
The minimum and maximum frequencies (in any order) for the simulation.
points : int
The length of the returned arrays (i.e. the number of points plotted).
Returns
-------
x, y : numpy.array, numpy.array
Arrays for the x (frequency) and y (intensity) lineshape data points.
See Also
--------
DnmrTwoSinglets : A class representation for this simulation.
References
----------
See the documentation for the nmrsim.dnmr module.
"""
if vb > va:
va, vb = vb, va
wa, wb = wb, wa
pa = 1 - pa
if limits:
l_limit = min(limits)
r_limit = max(limits)
else:
l_limit = vb - 50
r_limit = va + 50
x = np.linspace(l_limit, r_limit, points)
func = _dnmr_two_singlets_func(va, vb, ka, wa, wb, pa)
y = func(x)
return x, y
[docs]class DnmrTwoSinglets:
"""
A DNMR simulation for two uncoupled nuclei undergoing exchange.
Parameters
----------
va, vb : int or float
The frequencies (Hz) of nuclei 'a' and 'b' at the slow exchange limit.
k : int or float
The rate constant (Hz) for state a--> state b
wa, wb : int or float
The peak widths at half height for the 'a' and 'b' singlets at the
slow-exchange limit.
pa : float (0 <= pa <= 1)
The fraction of the population in state a
limits : (int or float, int or float), optional
The minimum and maximum frequencies (in any order) for the simulation.
points : int
The length of the returned arrays (i.e. the number of points plotted).
See Also
--------
DnmrTwoSinglets : A class representation for this simulation
"""
def __init__(self, va=1, vb=0, k=0.01, wa=0.5, wb=0.5, pa=0.5, limits=None, points=800):
# rethink default kwargs for v/k/w
self.va = va
self.vb = vb
self.k = k
self.wa = wa
self.wb = wb
self.pa = pa
if limits:
self.limits = limits
else:
self._vmin = min([va, vb]) - 50
self._vmax = max([va, vb]) + 50
self.points = points
@property
def va(self):
"""
The frequency of nucleus "a" (Hz) at the slow-exchange limit.
Returns
-------
int or float
"""
return self._va
@va.setter
def va(self, value):
self._va = is_number(value)
@property
def vb(self):
"""
The frequency of nucleus "b" (Hz) at the slow-exchange limit.
Returns
-------
int or float
"""
return self._vb
@vb.setter
def vb(self, value):
self._vb = is_number(value)
@property
def k(self):
"""
The rate constant (Hz) for state A--> state B (must be >0).
Returns
-------
int or float
"""
return self._k
@k.setter
def k(self, value):
self._k = is_positive(value)
@property
def wa(self):
"""
The peak width at half height (Hz) for the 'a' singlet at the
slow-exchange limit.
Returns
-------
int or float
"""
return self._wa
@wa.setter
def wa(self, value):
self._wa = is_number(value)
@property
def wb(self):
"""
The peak width at half height (Hz) for the 'b' singlet at the
slow-exchange limit.
Returns
-------
int or float
"""
return self._wb
@wb.setter
def wb(self, value):
self._wb = is_number(value)
@property
def pa(self):
"""
The fraction of the population in state a. Must be >=0 and <=1.
Returns
-------
float
"""
return self._pa
@pa.setter
def pa(self, value):
self._pa = is_decimal_fraction(value)
@property
def limits(self):
"""
The minimum and maximum frequencies for the simulated lineshape.
Returns
-------
(int or float, int or float)
"""
return self._vmin, self._vmax
@limits.setter
def limits(self, limits):
limits = is_tuple_of_two_numbers(limits)
self._vmin = min(limits)
self._vmax = max(limits)
@property
def points(self):
"""
The length of the returned arrays (i.e. the number of points plotted).
Returns
-------
int
"""
return self._points
@points.setter
def points(self, value):
self._points = is_integer(value)
[docs] def lineshape(self):
"""
Calculate and return the lineshape for the DNMR spectrum.
Returns
-------
x, y : numpy.array, numpy.array
Arrays for the x (frequency) and y (intensity) lineshape data
points.
"""
x = np.linspace(self._vmin, self._vmax, self.points)
x, y = dnmr_two_singlets(
self.va, self.vb, self.k, self.wa, self.wb, self.pa, limits=self.limits, points=self.points
)
return x, y
def _dnmr_AB_func(v, v1, v2, J, k, w):
"""
Implement the equation from Weil et al for simulation of the DNMR lineshape
for two coupled nuclei undergoing exchange (AB or AX pattern at the
slow-exchange limit).
Parameters
----------
v : float or array-like
a frequency (x coordinate) or array of frequencies at which an
amplitude (y coordinate) is to be calculated.
v1, v2 : float
frequencies of a and b nuclei (at the slow exchange limit,
in the absence of coupling)
J : float
the coupling constant between the two nuclei.
k : float
rate constant for state A--> state B
w : float
peak widths at half height (slow exchange limit).
Returns
-------
float
amplitude at frequency `v`.
See Also
--------
DnmrAB : A class representation for this simulation.
References
----------
See the documentation for the nmrsim.dnmr module.
"""
pi = np.pi
vo = (v1 + v2) / 2
tau = 1 / k
tau2 = 1 / (pi * w)
a1_plus = 4 * pi**2 * (vo - v + J / 2) ** 2
a1_minus = 4 * pi**2 * (vo - v - J / 2) ** 2
a2 = -(((1 / tau) + (1 / tau2)) ** 2)
a3 = -(pi**2) * (v1 - v2) ** 2
a4 = -(pi**2) * J**2 + (1 / tau**2)
a_plus = a1_plus + a2 + a3 + a4
a_minus = a1_minus + a2 + a3 + a4
b_plus = 4 * pi * (vo - v + J / 2) * ((1 / tau) + (1 / tau2)) - 2 * pi * J / tau
b_minus = 4 * pi * (vo - v - J / 2) * ((1 / tau) + (1 / tau2)) + 2 * pi * J / tau
r_plus = 2 * pi * (vo - v + J)
r_minus = 2 * pi * (vo - v - J)
s = (2 / tau) + (1 / tau2)
n1 = r_plus * b_plus - s * a_plus
d1 = a_plus**2 + b_plus**2
n2 = r_minus * b_minus - s * a_minus
d2 = a_minus**2 + b_minus**2
I = (n1 / d1) + (n2 / d2)
return I
[docs]def dnmr_AB(va, vb, J, k, w, limits=None, points=800):
"""
Simulate the DNMR lineshape for two coupled nuclei undergoing exchange
(AB or AX pattern at the slow-exchange limit).
Parameters
---------
va, vb : float
frequencies of a and b nuclei (at the slow exchange limit,
in the absence of coupling)
J : float
the coupling constant between the two nuclei.
k : float
rate constant for state A--> state B
w : float
peak widths at half height (at the slow-exchange limit).
limits : (int or float, int or float), optional
The minimum and maximum frequencies (in any order) for the simulation.
points : int
The length of the returned arrays (i.e. the number of points plotted).
Returns
-------
x, y : numpy.array, numpy.array
Arrays for the x (frequency) and y (intensity) lineshape data points.
See Also
--------
DnmrAB : A class representation for this simulation.
References
----------
See the documentation for the nmrsim.dnmr module.
"""
if limits:
l_limit = min(limits)
r_limit = max(limits)
else:
l_limit = min(va, vb) - 50
r_limit = max(va, vb) + 50
x = np.linspace(l_limit, r_limit, points)
y = _dnmr_AB_func(x, va, vb, J, k, w)
return x, y
[docs]class DnmrAB:
"""
Simulate the DNMR lineshape for two coupled nuclei undergoing exchange
(AB or AX pattern at the slow-exchange limit).
Parameters
----------
va, vb : int or float
frequencies of a and b nuclei (at the slow exchange limit,
in the absence of coupling)
J : int or float
the coupling constant between the two nuclei.
k : int or float
rate constant for state A--> state B
w : int or float
peak widths at half height (at the slow-exchange limit).
limits : (int or float, int or float), optional
The minimum and maximum frequencies (in any order) for the simulation.
points : int
The length of the returned arrays (i.e. the number of points plotted).
See Also
--------
DnmrAB : A class representation for this simulation.
References
----------
See the documentation for the nmrsim.dnmr module.
"""
def __init__(self, va=165.0, vb=135.0, J=12.0, k=12.0, w=0.5, limits=None, points=800):
self.va = va
self.vb = vb
self.J = J
self.k = k
self.w = w
if limits:
self.limits = limits
else:
self._vmin = min([va, vb]) - 50
self._vmax = max([va, vb]) + 50
self.points = points
@property
def va(self):
"""
The frequency of nucleus "a" (Hz) at the slow-exchange limit, in the absence of coupling.
Returns
-------
int or float
"""
return self._va
@va.setter
def va(self, value):
self._va = is_number(value)
@property
def vb(self):
"""
The frequency of nucleus "b" (Hz) at the slow-exchange limit, in the absence of coupling.
Returns
-------
int or float
"""
return self._vb
@vb.setter
def vb(self, value):
self._vb = is_number(value)
@property
def J(self):
"""
The coupling constant (Hz) between the two nuclei.
Returns
-------
int or float
"""
return self._J
@J.setter
def J(self, value):
self._J = is_number(value)
@property
def k(self):
"""
The rate constant (Hz) for state A--> state B (must be >0).
Returns
-------
int or float
"""
return self._k
@k.setter
def k(self, value):
self._k = is_positive(value)
@property
def w(self):
"""
The peak width (Hz) at half height (at the slow-exchange limit).
Returns
-------
int or float
"""
return self._w
@w.setter
def w(self, value):
self._w = is_number(value)
@property
def limits(self):
"""
Give minimum and maximum frequencies for the simulated lineshape.
Returns
-------
(int or float, int or float)
"""
return self._vmin, self._vmax
@limits.setter
def limits(self, limits):
limits = is_tuple_of_two_numbers(limits)
self._vmin = min(limits)
self._vmax = max(limits)
@property
def points(self):
"""
Give the length of the returned arrays (i.e. the number of points plotted).
Returns
-------
int
"""
return self._points
@points.setter
def points(self, value):
self._points = is_integer(value)
[docs] def lineshape(self):
"""Return the x, y lineshape data for the simulation.
Returns
-------
x, y : numpy.array, numpy.array
Arrays for the x (frequency) and y (intensity) lineshape data
points.
"""
x = np.linspace(self._vmin, self._vmax, self.points)
y = _dnmr_AB_func(x, self.va, self.vb, self.J, self.k, self.w)
return x, y