Change time definition in RIDME (#436)

* fix time definitions in RIDME

* more edits

* update documentation

deerlab/dipolarkernel.py

@@ -130,7 +130,7 @@ def dipolarkernel(t, r, *, pathways=None, mod=None, bg=None, method='fresnel', e
         Requires the ``'grid'`` or ``'integral'`` methods.
 
     excbandwidth : scalar, optional
-        Excitation bandwidth of the pulses in MHz to account for limited excitation bandwidth [5]_.
+        Excitation bandwidth of the pulses in MHz to account for limited excitation bandwidth.
         If not specified, an infinite excitation bandwidth is used.
         Requires the ``'grid'`` or ``'integral'`` methods.
 

deerlab/dipolarmodel.py

@@ -770,6 +770,8 @@ def ex_4pdeer(tau1, tau2, pathways=[1,2,3,4], pulselength=0.016):
     The middle table summarizes all detectable modulated dipolar pathways `p` along their dipolar phase accumulation factors `\mathbf{s}_p`,
     harmonics `\delta_p` and refocusing times `t_{\mathrm{ref},p}`. The most commonly encountered pathways are highlighted in color. 
     The bottom panel shows a decomposition of the dipolar signal into the individual intramolecular contributions (shown as colored lines).
+    
+    The dipolar time axis is defined such that `t=0` right after the second observer pulse.
 
     .. figure:: ../images/ex_4pdeer_pathways.png
         :width: 350px
@@ -1048,6 +1050,8 @@ def ex_ridme(tau1, tau2, pathways=[1,2,3,4], pulselength=0.016):
     The middle table summarizes all detectable modulated dipolar pathways `p` along their dipolar phase accumulation factors `\mathbf{s}_p`,
     harmonics `\delta_p` and refocusing times `t_{\mathrm{ref},p}`. The most commonly encountered pathways are highlighted in color. 
     The bottom panel shows a decomposition of the dipolar signal into the individual intramolecular contributions (shown as colored lines).
+    
+    The dipolar time axis is defined such that `t=0` right after the second pulse.
 
     (Note that the model does not account for any relaxation-induced effects)
 
@@ -1058,18 +1062,18 @@ def ex_ridme(tau1, tau2, pathways=[1,2,3,4], pulselength=0.016):
     ----------
 
     tau1 : float scalar
-        1st static interpulse delay `\tau_1`. 
+        1st static interpulse delay `\tau_1`.
 
     tau2 : float scalar
-        2nd static interpulse delay `\tau_2`.  
+        2nd static interpulse delay `\tau_2`.
 
     pathways :  array_like, optional 
         Pathways to include in the model. The pathways are specified as a list of pathways labels `p`. 
         By default, pathways 1-4 are included as shown in the table above.
 
-    pulselength : float scalar, optional 
-        Length of the longest microwave pulse in the sequence in microseconds. Used to determine the uncertainty in the 
-        boundaries of the pathway refocusing times.
+    pulselength : float scalar, optional
+        Length of the longest microwave pulse in the sequence, in microseconds. Used to determine
+        the uncertainty in the boundaries of the pathway refocusing times.
 
     Returns
     -------
@@ -1079,25 +1083,25 @@ def ex_ridme(tau1, tau2, pathways=[1,2,3,4], pulselength=0.016):
 
     """
     # Theoretical refocusing times
-    def reftimes(tau1,tau2):
-        tref = [   0,
-                tau2,
-               -tau1,
-           tau2-tau1]
+    def reftimes(tau1, tau2):
+        tref = [tau1,
+                tau1+tau2,
+                0,
+                tau2]
         # Sort according to pathways order
         if pathways is not None:
             tref = [tref[pathway-1] for pathway in pathways]
         return tref
     # Pulse delays 
-    delays = [tau1,tau2]
+    delays = [tau1, tau2]
     # Theoretical dipolar harmonics
-    harmonics = [ 1, 1, 1, 1]
+    harmonics = [1, 1, 1, 1]
     # Pathway labels
-    pathwaylabels = np.arange(1,len(harmonics)+1)
+    pathwaylabels = np.arange(1, len(harmonics)+1)
 
     # Sort according to pathways order
     if pathways is not None:
-        _checkpathways(pathways,Nmax=len(harmonics))
+        _checkpathways(pathways, Nmax=len(harmonics))
         harmonics = [harmonics[pathway-1] for pathway in pathways] 
         pathwaylabels = [pathwaylabels[pathway-1] for pathway in pathways]
 

docsrc/source/changelog.rst

@@ -26,6 +26,8 @@ Release Notes
 
 Release ``v1.0.2`` - July 2023
 ------------------------------------------
+- |api| : The definition of the dipolar time axis for RIDME has changed to match the one for 4-pulse DEER (:pr:`436`).
+
 - |fix| : Fixes errors in documentation (:pr:`429`).
 
   * Changes the file name of figures 'modelling*.png` to `modeling*.png`. To keep all spelling consistent with American english.

docsrc/source/dipolar_guide_modeling.rst

@@ -27,10 +27,12 @@ The time range
 The time range depends the expected range of distances, but is typically beteen about 0.5 and several microseconds. If you are planning to use this model to fit experimental data, the time vector should be the same as the one used in the experiment. Otherwise, to construct a time vector, use the ``linspace`` or ``arange`` functions from NumPy: ::
 
    # time from 0.2 µs to 3.0 µs with a resolution of 0.01 µs, 321 points
-   t = np.linspace(0.2,3.0,321)  # start, stop, number of points
-   t = np.arange(0.2,3.0,0.01)   # start, stop, step size
+   t = np.linspace(0.2, 3.0, 321)  # start, stop, number of points
+   t = np.arange(0.2, 3.0, 0.01)   # start, stop, step size
  
-Note that DeerLab interprets ``t`` such that its zero point is right at the end of the preceding pulse (e.g. right after the second observer pulse in 4-pulse DEER) rather than at the refocusing point of the signal (after `\tau_1` after the second observer pulse).
+Note that DeerLab's definition of ``t`` depends on the type of dipolar experiment, and it might differ from how the time is conventionally defined in the literature or in experimental acquired data.
+
+For example, for 4-pulse DEER and 5-pulse RIDME, ``t`` in DeerLab is defined such that it is zero right at the end of the second observer pulse rather than at the refocusing point of the main dipolar signal (after `\tau_1` after the second observer pulse). Make sure to check the time definition in the :ref:`list of experiment models <modelsref>`.
 
 The distance range
 *************************