/tau-sigma

A command-line utility for clock stability analysis (e.g., Allan deviation)

Primary LanguageHaskellBSD 3-Clause "New" or "Revised" LicenseBSD-3-Clause

tau-sigma: A Simple Utility for Frequency Stability Analysis

Build Status

This is a simple command-line utilty for analyzing the frequency stability of clocks in terms of their Allan deviation and related statistics.

Subcommands

Statistics

All of these commands take time error data as input, one item per line:

Command Description
tau-sigma adev Allan deviation (overlapped estimator)
tau-sigma mdev Modified Allan deviation
tau-sigma tdev Time deviation
tau-sigma hdev Hadamard deviation (overlapped estimator)
tau-sigma totdev Total deviation
tau-sigma theo1 Theo1 deviation
tau-sigma theobr TheoBR deviation (bias-reduced Theo1)
tau-sigma theoh TheoH deviation (Allan at low taus, TheoBR at high taus)

Output is CSV with "tau" and "sigma" column headers.

I have not yet found good example data sets for the following two statistics, so they are supported experimentally:

Command Description
tau-sigma theobr TheoBR deviation (bias-reduced Theo1)
tau-sigma theoh TheoH deviation (Allan at low taus, TheoBR at high taus)

Charting

This isn't meant to be a full-powered charting tool, but it's useful to be able to generate quick-and-dirty plots.

The tau-sigma chart command generate a line chart from time series data. This is meant for plotting time or frequency error series.

The tau-sigma loglog commands generates a tau/sigma log-log chart from the output of the stability statistic subcommands. The data is plotted with square decades to help judge the slopes of the curve.

Noise

The tau-sigma noise command generates random spectral noises and mixes thereof.

Convert

The tau-sigma convert command converts between phase/frequency data series and units.

Examples

Random Noise

These examples are scripted in scripts/examples.sh.

Noise Type Time errors Frequency errors ADEV
White phase modulation WPM WPM WPM
Flicker phase modulation FPM FPM FPM
White frequency modulation WFM WFM WFM
Flicker frequency modulation FFM FFM FFM
Random walk frequency modulation RWFM RWFM RWFM

Earth Rotation, 1962-2015

The rotation of our planet is not stable. We can illustrate by applying tau-sigma to data from the International Earth Rotation Service:

Stability of mean solar day

This example is scripted in scripts/iers.sh. More about the data in example-data/README.md.

Arnold #36 pocket chronometer

I wrote this utilty to help my efforts to understand the performance of historical precision timepieces. Here's a fine example: the 1779/80 Greenwich trial of John Arnold's pocket chronometer #36, one of the very earliest successful precision watches. Read more in example-data/README.md.

Arnold #36 TheoBR

(The discontinuity evident around 3.4e1 on the x axis is the switch point of the TheoH hybrid statistic, which is ADEV at short averaging intervals and TheoBR at longer ones.)

Daily Rates Time error
rates phase

Performance and correctness

This tool has so far been written primarily with simplicity and correctness in mind, not performance. The code for the statistical functions sticks very closely to the mathematical formulas in the reference materials.

I do not warranty that the results of this program are always correct. Nevertheless, I have taken care to test that the results at least look sensible. The following properties are tested:

  1. The results of most of the frequency stability functions are compared against the ones published by Riley and Howe (2008) for two public data sets. See:
  1. The Theo1 statistic is tested against an example in Appendix A of Howe (2006). See:
  1. There's also tests that check that the slopes of the statistics are more or less what they should be on various noise types. See:

Not all statistics are subjected to all the tests just yet. In particular, I don't have example data sets of the TheoBR or TheoH statistics to compare against. (These are derived from the Allan and Theo1 deviations, which I do test.)

Compilation and Installation

This is a pure Haskell program built with the Stack tool, so you need to install that to compile the program.

Once you've done that the installation follows standard Stack procedure:

  1. Clone this Git repo.
  2. Change into the base directory and run stack install.

This will install the tau-sigma commandline program to the location where the Stack tool puts executable programs (default ~/.local/bin/ in Unix and OS X systems).

TODO

  • Error bars!
  • Triple check the flicker noise generation code.
  • Smart scaling of log/log chart axes. We need same-sized decades in both axes.
  • Generate charts in other formats than SVG.
  • Frequency spectra
  • Other stability statistics

References