narumii.functions

narumii.functions

redor_bessel

redor_bessel(max_order)

Return a Bessel series with a given maximum order for analytical prediction of REDOR curves:

\[ \frac{\Delta S}{S_0} = 1 - \left[J_0\left(\sqrt{2}\lambda_n\right)\right]^2 + 2\sum^\infty_{k=1}\frac{1}{16k^2-1}\left[J_k\left(\sqrt{2}\lambda_n\right)\right]^2 \]

where \(\lambda_n = nD\tau\) is the product of the number of rotor cycles \(n\), the dipolar coupling strength \(D\), and the rotor period \(\tau\).

References

Mueller, K.T. (1995). Analytical Solutions for the Time Evolution of Dipolar-Dephasing NMR Signals. Journal of Magnetic Resonance Series A, 113, 81-93. https://doi.org/10.1006/jmra.1995.1059

Parameters:

Name	Type	Description	Default
max_order	int	Maximum order of the Bessel series expansion. Must not exceed 5.	required

Returns:

Name	Type	Description
func	Callable	A function that calculates the REDOR difference curve using Bessel functions. The function signature is: 'calculator(t, b) -> np.ndarray' where t is the evolution time and b is the effective dipolar coupling constant.

Raises:

Type	Description
ValueError	If max_order exceeds 5.

Examples:

>>> redor_func = redor_bessel(max_order=5)
>>> t = np.linspace(0, 10, 100)
>>> difference = redor_func(t, 2.5)  # b = 2.5 kHz

redor_parabola

redor_parabola(t, b)

Calculate the REDOR difference curve using parabolic approximation.

Parameters:

Name	Type	Description	Default
t	ndarray	Evolution time, in ms.	required
b	float	Effective dipolar coupling constant, in kHz.	required

Returns:

Name	Type	Description
predict	ndarray	Predicted REDOR difference values (1 - S'/S₀).

Examples:

>>> import numpy as np
>>> t = np.linspace(0, 10, 100)
>>> difference = redor_parabola(t, 2.5)  # b = 2.5 kHz

redor_threehalf

redor_threehalf(t, b)

Analytical calculation for the REDOR difference in an I=1/2, S=3/2 spin system:

\[ \frac{\Delta S}{S_0} = 1 - \frac{1}{2}\left[\frac{\sqrt{2}\pi}{4}J_{1/4}(\sqrt{2}\lambda_n)J_{-1/4}(\sqrt{2}\lambda_n) + \frac{\sqrt{2}\pi}{4}J_{1/4}(3\sqrt{2}\lambda_n)J_{-1/4}(3\sqrt{2}\lambda_n)\right] \]

where \(\lambda_n = nD\tau\) is the product of the number of rotor cycles \(n\), the dipolar coupling strength \(D\), and the rotor period \(\tau\).

References

Gullion, T., Vega, A.J. (2005). Measuring heteronuclear dipolar couplings for I=1/2, S>1/2 spin pairs by REDOR and REAPDOR NMR. Progress in Nuclear Magnetic Resonance Spectroscopy, 47, 123-136. https://doi.org/10.1016/j.pnmrs.2005.08.004

Parameters:

Name	Type	Description	Default
t	ndarray	Evolution time, in ms.	required
b	float	Effective dipolar coupling constant, in kHz.	required

Returns:

Name	Type	Description
predict	ndarray	Predicted REDOR difference values (1 - S'/S₀).

Examples:

>>> t = np.linspace(0, 10, 100)
>>> difference = redor_threehalf(t, 2.5)  # b = 2.5 kHz

reapdor_threehalf

reapdor_threehalf(t, b)

Analytical calculation for the REAPDOR difference in an I=1/2, S=3/2 spin system:

\[ \frac{\Delta S}{S_0} = 0.7(1 - \exp[-(1.82\lambda_n)^2]) \]

where \(\lambda_n = nD\tau\) is the product of the number of rotor cycles \(n\), the dipolar coupling strength \(D\), and the rotor period \(\tau\).

References

Gullion, T., Vega, A.J. (2005). Measuring heteronuclear dipolar couplings for I=1/2, S>1/2 spin pairs by REDOR and REAPDOR NMR. Progress in Nuclear Magnetic Resonance Spectroscopy, 47, 123-136. https://doi.org/10.1016/j.pnmrs.2005.08.004

Parameters:

Name	Type	Description	Default
t	ndarray	Evolution time, in ms.	required
b	float	Effective dipolar coupling constant, in kHz.	required

Returns:

Name	Type	Description
predict	ndarray	Predicted REAPDOR difference values.

Examples:

>>> t = np.linspace(0, 10, 100)
>>> difference = reapdor_threehalf(t, 2.5)  # b = 2.5 kHz

reapdor_fivehalf

reapdor_fivehalf(t, b)

Analytical calculation for the REAPDOR difference in an I=1/2, S=5/2 spin system:

\[ \frac{\Delta S}{S_0} = 0.63(1 - \exp[-(3.0\lambda_n)^2]) + 0.2(1 - \exp[-(0.7\lambda_n)^2]) \]

where \(\lambda_n = nD\tau\) is the product of the number of rotor cycles \(n\), the dipolar coupling strength \(D\), and the rotor period \(\tau\).

References

Gullion, T., Vega, A.J. (2005). Measuring heteronuclear dipolar couplings for I=1/2, S>1/2 spin pairs by REDOR and REAPDOR NMR. Progress in Nuclear Magnetic Resonance Spectroscopy, 47, 123-136. https://doi.org/10.1016/j.pnmrs.2005.08.004

Parameters:

Name	Type	Description	Default
t	ndarray	Evolution time, in ms.	required
b	float	Effective dipolar coupling constant, in kHz.	required

Returns:

Name	Type	Description
predict	ndarray	Predicted REAPDOR difference values.

Examples:

>>> t = np.linspace(0, 10, 100)
>>> difference = reapdor_fivehalf(t, 2.5)  # b = 2.5 kHz

reapdor_PB_natural_abundance

reapdor_PB_natural_abundance(t, r)

Analytical calculation for the REAPDOR difference between an I=1/2 and S=B11 (in natural abundance) spin system:

\[ \frac{\Delta S}{S_0} = 0.60(1 - \exp[-(16.9t)^2r^{-6}]) \]

References

Nimerovsky, E. & Goldbourt, A. (2012). Distance measurements between boron and carbon at natural abundance using magic angle spinning REAPDOR NMR and a universal curve. Phys. Chem. Chem. Phys., 14, 13437-13443. https://doi.org/10.1039/C2CP41851G

Parameters:

Name	Type	Description	Default
t	ndarray	Evolution time, in ms.	required
r	float	Internuclear distance, in Å.	required

Returns:

Name	Type	Description
predict	ndarray	Predicted REAPDOR difference values.

Examples:

>>> t = np.linspace(0, 10, 100)
>>> difference = reapdor_PB_natural_abundance(t, 3.0)  # r = 3.0 Å

ctdrenar

ctdrenar(theta, z)

Analytical approximation to BaBa-xy16 CT-DRENAR.

References

Ren, J. & Eckert, H. (2015). Measurement of homonuclear magnetic dipole-dipole interactions in multiple 1/2-spin systems using constant-time DQ-DRENAR NMR. Journal of Magnetic Resonance, 260(1), 46-53. https://doi.org/10.1016/j.jmr.2015.08.022

Parameters:

Name	Type	Description	Default
theta	ndarray	Phase angles, in degrees.	required
z	float	Dephasing parameter (Dt)², where D is the dipolar coupling constant and t is dephasing time, the units should match so that z is dimentionless.	required

Returns:

Name	Type	Description
intensity	ndarray	Normalized DQ intensity in CT-DRENAR experiments.

Examples:

>>> theta = np.linspace(0, 180, 100)
>>> z = 0.5
>>> intensity = ctdrenar(theta, z)

drenar_postc7

drenar_postc7(t, b)

Analytical approximation to POST-C7 VT-DRENAR.

References

Ren, J. & Eckert, H. (2013). DQ-DRENAR: A new NMR technique to measure siteresolved magnetic dipole-dipole interactions in multispin-1/2 systems: Theory and validation on crystalline phosphates. Journal of Chemical Physics, 138, 164201. https://doi.org/10.1063/1.4801634

Parameters:

Name	Type	Description	Default
t	ndarray	Dephasing time, in ms.	required
b	float	Effective dipolar coupling constant, in kHz.	required

Returns:

Name	Type	Description
intensity	ndarray	Predicted DQ intensity.

Examples:

>>> t = np.linspace(0, 10, 100)
>>> intensity = drenar_parabola(t, 2.5)  # b = 2.5 kHz

drenar_babaxy16

drenar_babaxy16(t, b)

Analytical approximation to BaBa-xy16 VT-DRENAR.

References

Ren, J. & Eckert, H. (2013). DQ-DRENAR with back-to-back (BABA) excitation: Measuring homonuclear dipole-dipole interactions in multiple spin-1/2 systems. Solid State Nuclear Magnetic Resonance, 71, 11-18. https://doi.org/10.1016/j.ssnmr.2015.10.007

Parameters:

Name	Type	Description	Default
t	ndarray	Dephasing time, in ms.	required
b	float	Effective dipolar coupling constant, in kHz.	required

Returns:

Name	Type	Description
intensity	ndarray	Predicted DQ intensity.

Examples:

>>> t = np.linspace(0, 10, 100)
>>> intensity = drenar_parabola(t, 2.5)  # b = 2.5 kHz

codex

codex(t, k, m)

Calculate the magnetization in CODEX (COherence Decay Experiment) pulse sequence.

Parameters:

Name	Type	Description	Default
t	ndarray	Evolution time, in ms.	required
k	float	Decay rate constant.	required
m	float	Magnetization asymptotic parameter.	required

Returns:

Name	Type	Description
s	ndarray	Predicted magnetization values.

Examples:

>>> t = np.linspace(0, 10, 100)
>>> s = codex(t, 0.5, 0.3)  # k = 0.5, m = 0.3

expdec

expdec(t, a, b, R)

Calculate exponential decay with baseline offset (single exponential).

Parameters:

Name	Type	Description	Default
t	ndarray	Time, in ms.	required
a	float	Baseline/offset value.	required
b	float	Amplitude of the decaying component.	required
R	float	Relaxation rate, in ms⁻¹.	required

Returns:

Name	Type	Description
signal	ndarray	Predicted signal values following: a + bexp(-Rt).

Examples:

>>> t = np.linspace(0, 100, 100)
>>> signal = expdec(t, 0.1, 0.9, 0.02)  # a=0.1, b=0.9, R=0.02 ms⁻¹

expdec2

expdec2(t, a, b1, b2, R1, R2)

Calculate exponential decay with baseline offset (double exponential).

Parameters:

Name	Type	Description	Default
t	ndarray	Time, in ms.	required
a	float	Baseline/offset value.	required
b1	float	Amplitude of the first decaying component.	required
b2	float	Amplitude of the second decaying component.	required
R1	float	Relaxation rate of the first component, in ms⁻¹.	required
R2	float	Relaxation rate of the second component, in ms⁻¹.	required

Returns:

Name	Type	Description
signal	ndarray	Predicted signal values following: a + b₁exp(-R₁t) + b₂exp(-R₂t).

Examples:

>>> t = np.linspace(0, 100, 100)
>>> signal = expdec2(t, 0.1, 0.5, 0.4, 0.01, 0.05)  # two exponential components

satrec

satrec(t, a, b, R)

Calculate saturation recovery signal (inverse exponential).

Parameters:

Name	Type	Description	Default
t	ndarray	Delay time, in ms.	required
a	float	Equilibrium magnetization value.	required
b	float	Amplitude of recovery.	required
R	float	Recovery rate, in ms⁻¹.	required

Returns:

Name	Type	Description
signal	ndarray	Predicted signal values following: a - bexp(-Rt).

Examples:

>>> t = np.linspace(0, 100, 100)
>>> signal = satrec(t, 1.0, 1.0, 0.02)  # equilibrium at 1.0, recovery rate 0.02 ms⁻¹

linear

linear(x, a, b)

Linear function: f(x) = a*x + b.

Parameters:

Name	Type	Description	Default
x	ndarray	Independent variable.	required
a	float	Slope of the line.	required
b	float	Y-intercept.	required

Returns:

Name	Type	Description
f_x	ndarray	Computed linear function values.

Examples:

>>> x = np.linspace(0, 10, 100)
>>> y = linear(x, 2.0, 3.0)  # y = 2*x + 3

parabola

parabola(x, a, x0, c)

Parabolic function: f(x) = a*(x - x0)² + c.

Parameters:

Name	Type	Description	Default
x	ndarray	Independent variable.	required
a	float	Coefficient for the quadratic term.	required
x0	float	Vertex position along x-axis.	required
c	float	Vertical offset.	required

Returns:

Name	Type	Description
f_x	ndarray	Computed parabolic function values.

Examples:

>>> x = np.linspace(0, 10, 100)
>>> y = parabola(x, 1.0, 5.0, 2.0)  # vertex at (5, 2)

compute_rmsd

compute_rmsd(data1, data2, weights=1)

Compute the root mean square deviation (RMSD) between two datasets with optional weighting.

Parameters:

Name	Type	Description	Default
data1	ndarray	First dataset.	required
data2	ndarray	Second dataset.	required
weights	ndarray | float	Weights for each data point. Default is 1 (uniform weighting).	1

Returns:

Name	Type	Description
rmsd	float	Root mean square deviation between data1 and data2 weighted by weights.

Examples:

>>> rmsd = compute_rmsd(data1, data2)
>>> rmsd_weighted = compute_rmsd(data1, data2, weights=weights)

compute_ssd

compute_ssd(data1, data2, weights=1)

Compute the sum squared deviations (SSD) between two datasets with optional weighting.

Parameters:

Name	Type	Description	Default
data1	ndarray	First dataset.	required
data2	ndarray	Second dataset.	required
weights	ndarray | float	Weights for each data point. Default is 1 (uniform weighting).	1

Returns:

Name	Type	Description
ssd	float	Sum squared deviations between data1 and data2 weighted by weights.

Examples:

>>> ssd = compute_ssd(data1, data2)
>>> ssd_weighted = compute_ssd(data1, data2, weights=weights)