gcodev documentation, example

aewallin · Nov 26, 2023 · 0fbd120 · 0fbd120
1 parent 703592c
commit 0fbd120
Show file tree

Hide file tree

Showing 3 changed files with 26 additions and 5 deletions.
diff --git a/allantools/allantools.py b/allantools/allantools.py
@@ -552,7 +552,17 @@ def calc_gcodev_phase(phase_1, phase_2, rate, mj, stride):
 def gcodev(data_1, data_2, rate=1.0, data_type="phase", taus=None):
     """ Groslambert codeviation  a.k.a. Allan Covariance
 
-    Ref: (arXiv:1904.05849, https://arxiv.org/abs/1904.05849)
+    Similarly to the three-cornered hat method, we consider three uncorrelated
+    oscillators A, B, C. The Groslambert codeviation estimates the noise of
+    one oscillator (e.g. B), given two synchronous measurements AB and BC.
+    Unlike three-cordenred hat, Gcodev is not affected by the (uncorrelated) noise of 
+    the measurement devices (time-interval or frequency counter) used for
+    the measurements AB and BC.
+    
+    References 
+    ----------
+    * arXiv:1904.05849, https://arxiv.org/abs/1904.05849
+    * https://rubiola.org/pdf-articles/conference/2016-IFCS-Three-cornered.pdf
 
     Parameters
     ----------
@@ -572,14 +582,13 @@ def gcodev(data_1, data_2, rate=1.0, data_type="phase", taus=None):
     Returns
     -------
     (taus, gd): tuple
-          Tuple of values
+        Tuple of values
     taus: np.array
-        Tau values for which td computed
+        Tau values for which gcodev computed
     gd: np.array
         Computed gcodev for each tau value
 
     """
-
     phase_1 = input_to_phase(data_1, rate, data_type)
     phase_2 = input_to_phase(data_2, rate, data_type)
     (phase_1, m, taus_used) = tau_generator(phase_1, rate, taus)

diff --git a/docs/references.rst b/docs/references.rst
@@ -77,6 +77,9 @@ Papers
     Fundamental Frequency and Time Metrology - Random Instabilities 
     http://dx.doi.org/10.1109/IEEESTD.2008.4797525
 
+.. [Lantz2019] KLTS: A rigorous method to compute the confidence intervals for the Three-Cornered Hat and for Groslambert Covariance
+    https://arxiv.org/abs/1904.05849
+
 .. [Riley_Stable32] http://www.stable32.com/Handbook.pdf
 
 .. [Riley_CI] Confidence Intervals and Bias Corrections  for the Stable32  Variance Functions

diff --git a/examples/three-cornered-hat-demo.py b/examples/three-cornered-hat-demo.py
@@ -50,7 +50,8 @@ def plotline(plt, alpha, amplitude, taus, style, labeltext):
     N = 10000
     rate = 1.0
     # white phase noise => 1/tau ADEV
-
+    # these are the 'true' phases of the oscillators, which are not observable.
+    # we can only measure phases between two oscillators.
     ampl_A = 1.0
     phaseA = ampl_A*numpy.random.randn(N)
     ampl_B = 5.0
@@ -97,6 +98,14 @@ def plotline(plt, alpha, amplitude, taus, style, labeltext):
                    phaseCA, phaseAB, phaseBC, rate, t, allantools.oadev)
     plt.loglog(taus, devC, 'bv', label='3-C-H estimate for C')
 
+    # GCODEV estimates
+    (taus, devA, err_a, ns_ab) = allantools.gcodev(phaseAB, phaseCA, rate=rate, taus='log10')
+    plt.loglog(taus, devA, 'r*', label='Gcodev estimate for A')
+    (taus, devB, err_b, ns_b) = allantools.gcodev(phaseAB, phaseBC, rate=rate, taus='log10')
+    plt.loglog(taus, devB, 'g*', label='Gcodev estimate for B')
+    (taus, devC, err_c, ns_c) = allantools.gcodev(phaseCA, phaseBC, rate=rate, taus='log10')
+    plt.loglog(taus, devC, 'b*', label='Gcodev estimate for C')
+
     print("TCH done.")
     plt.title('AllanTools three-cornered-hat example')
     plt.xlabel('Tau / s')