Introduction to the FreqDemod Package

This package provides functions for analyzing and plotting the time-dependent frequency and amplitude of a sinusoidally oscillating signal. Additional functions are provided for analyzing fluctuations in oscillator amplitude, phase, or frequency. The provided functions should work equally well for any oscillating signal, although the included data-fitting and -plotting functions have been written with an oscillating atomic force microscope cantilever in mind. The main frequency-demodulation algorithm’s only assumption is that the oscillating signal contains a single frequency component (the carrier, in FM-radio terminology).



This package requires the following packages. If you use the Enthought Canopy Distribution, then you should install these packages first using Enthought’s package manager. If you do not install them first, then pip will install them for you

  • numpy 1.8.1
  • scipy 0.14.1
  • matplotlib 1.4.2
  • h5py 2.4.0

To install the package

pip install FreqDemod

To test that the installation worked, run

python -c "import freqdemod; freqdemod.test()"

Install the development version

To edit the package and compile the documentation, you will need

  • fabric 1.10.1
  • Sphinx 1.2.3
  • ipython 2.3.1

To install the development version, first clone the package

git clone
cd FreqDemod

To confirm that everything is working, in the FreqDemod directory run

python -m unittest discover


python -m unittest discover -v


python test

If you make modifications to the code, and want to test drive your modifications, run

python develop

Your modified code should now load when you import FreqDemod in your code. To recreate the documentation, switch to the docs subdirectory, and run

fab html
fab open

If successful, you should see the documentation appear in your webbrowser. The documentation is created in the directory FreqDemod/docs/_build/html.

There is an example ipython notebook in the FreqDemod/freqdemod/docs directory. Running the following command will convert the notebook to html and copy it to the documentation directory

fab html_full

Scientific Overview

Motivation: The microcantilevers used in an atomic force microscope experiment oscillate with an amplitude between 0.1 to 100 nanometers and with a frequency in the kilohertz range. A number of microcantilever-based experiments rely on measuring the time-dependent oscillation frequency of a cantilever. These experiments include

  • frequency-modulation scanning Kelvin probe force microscopy (FM-SKPM) [1], used to measure a thin film’s local capacitance and electrostatic potential;
  • frequency-modulated magnetic resonance force microscopy (FM-MRFM), used to sensitively detect and image electron-spin or nuclear-spin magnetic resonance as a slow [2] [3] or rapidly-modulated [4] [5] [6] shift in the resonance frequency of a cantilever;
  • experiments studying the frequency fluctuations experienced by a charged microcantilever near a sample surface. This apparent frequency noise can be used to probe dielectric fluctuations arising from thermally-driven atomic motions in the sample below [7] [8] [9], light-induced detrapping of charges in an inorganic [10] or organic semiconductor film [11], and voltage fluctuations arising from correlated charge motion in an organic field effect transistor [12] [13]; and
  • time-resolved electrostatic force microscopy (tr-EFM) [14] [15], used to study the dynamics of photo-generated charges in solar-cell films.

In FM-KPFM, the cantilever frequency must be analyzed in real time; the cantilever frequency is measured with millisecond time resolution and latency, and the resulting output, proportional to the instantaneous cantilever frequency, is passsed to a lock-in detector and a PID loop used to control the cantilever tip voltage. In contrast, the time-dependent cantilever frequency in an FM-MRFM, fluctuation-microscopy, or tr-EFM experiment can be obtained via post-acquisition processing of the cantilever oscillation signal using a software frequency demodulator such as the one presented here.

This package represents a detailed description of the frequency-demodulation algorithm outlined in the Supplementary Information of Reference [8] and in the Ph.D. thesis of Reference [16].

Algorithm. Let

\[x(t) = a(t) \cos{(2 \pi f(t) \: t)}\]

be the oscillating cantilever signal, with \(a(t)\) the cantilever amplitude and \(f(t)\) the cantilever frequency. We want to extract \(a(t)\) and \(f(t)\) from \(x(t)\). We do this by generating a phase-shifted copy of the signal,

\[y(t) = a(t) \sin{(2 \pi f(t) \: t)}\]

via a Hilbert transform. Using the original signal and the phase-shifted signal, we compute the instantaneous amplitude as

\[a(t) = \sqrt{x(t)^2 + y(t)^2}\]

and the instantaneous phase as

\[\phi(t) = \arctan{(y(t)/x(t))}\]

The instantaneous frequency \(f(t)\) is determined from the slope of the \(\phi(t)\) vs \(t\) line.

While straightforward in principle, implementing this algorithm in practice requires careful attention to detail. For example, to avoid aliasing noise present in \(x(t)\) into the \(f(t)\) signal, the signal \(x(t)\) must be properly bandpass filtered and the phase \(\phi(t)\) must be sampled and analyzed in suitably short blocks. These and other details are described in the following documentation.

Tutorials. The authors initially developed the code in this package to analyze fluctuations in cantilever frequency and position. To understand how the included functions process the cantilever signal, it is helpful to have a mathematical understanding of the power spectrum of position- and frequency fluctuations expected for a microcantilever. The expected power spectra are derived and discussed in the following tutorials.


[1][Kikukawa1995jun] Kikukawa, A.; Hosaka, S. & Imura, R. Silicon \(pn\) Junction Imaging and Characterization Using Sensitivity Enhanced Kelvin Probe Microscopy. Appl. Phys. Lett., 1995, 66: 3510 - 3512 [].
[2][Garner2004jun] Garner, S. R.; Kuehn, S.; Dawlaty, J. M.; Jenkins, N. E. & Marohn, J. A. Force-Gradient Detected Nuclear Magnetic Resonance. Appl. Phys. Lett., 2004, 84: 5091 - 5093 [].
[3][Alexson2012jul] Alexson, D. A.; Hickman, S. A.; Marohn, J. A. & Smith, D. D. Single-shot nuclear magnetization recovery curves with force-gradient detection. Appl. Phys. Lett., 2012, 101: 022103 [].
[4][Rugar2004jul] Rugar, D.; Budakian, R.; Mamin, H. J. & Chui, B. W. Single Spin Detection by Magnetic Resonance Force Microscopy. Nature, 2004, 430: 329 - 332 [].
[5][Mamin2007may] Mamin, H. J.; Poggio, M.; Degen, C. L. & Rugar, D. Nuclear Magnetic Resonance Imaging with 90-nm Resolution. Nat. Nanotechnol., 2007, 2: 301 - 306 [].
[6][Moore2009dec] Moore, E. W.; Lee, S.-G.; Hickman, S. A.; Wright, S. J.; Harrell, L. E.; Borbat, P. P.; Freed, J. H. & Marohn, J. A. Scanned-Probe Detection of Electron Spin Resonance from a Nitroxide Spin Probe. Proc. Natl. Acad. Sci. U.S.A., 2009, 106: 22251 - 22256 [].
[7][Yazdanian2008jun] Yazdanian, S. M.; Marohn, J. A. & Loring, R. F. Dielectric Fluctuations in Force Microscopy: Noncontact Friction and Frequency Jitter. J. Chem. Phys., 2008, 128: 224706 [].
[8](1, 2) [Yazdanian2009jun] Yazdanian, S. M.; Hoepker, N.; Kuehn, S.; Loring, R. F. & Marohn, J. A. Quantifying Electric Field Gradient Fluctuations over Polymers Using Ultrasensitive Cantilevers. Nano Lett., 2009, 9: 2273 - 2279 [].
[9][Hoepker2011oct] Hoepker, N.; Lekkala, S.; Loring, R. F. & Marohn, J. A. Dielectric Fluctuations Over Polymer Films Detected Using an Atomic Force Microscope. J. Phys. Chem. B, 2011, 115: 14493 - 14500 [].
[10][Cockins2009mar] Cockins, L.; Miyahara, Y. & Grütter, P. Spatially Resolved Low-Frequency Noise Measured by Atomic Force Microscopy. Phys. Rev. B, 2009, 79: 121309 [].
[11][Luria2012nov] Luria, J. L.; Hoepker, N.; Bruce, R.; Jacobs, A. R.; Groves, C. & Marohn, J. A. Spectroscopic Imaging of Photopotentials and Photoinduced Potential Fluctuations in a Bulk Heterojunction Solar Cell Film. ACS Nano, 2012, 6: 9392 - 9401 [].
[12][Lekkala2012sep] Lekkala, S.; Hoepker, N.; Marohn, J. A. & Loring, R. F. Charge carrier dynamics and interactions in electric force microscopy. J. Chem. Phys., 2012, 137: 124701 [].
[13][Lekkala2013nov] Lekkala, S.; Marohn, J. A. & Loring, R. F. Electric force microscopy of semiconductors: Cantilever frequency fluctuations and noncontact friction. J. Chem. Phys., 2013, 139: 184702 [].
[14][Coffey2006sep] Coffey, D. C. & Ginger, D. S. Time-Resolved Electrostatic Force Microscopy of Polymer Solar Cells. Nat. Mater., 2006, 5: 735 - 740 [].
[15][Giridharagopal2012jan] Giridharagopal, R.; Rayermann, G. E.; Shao, G.; Moore, D. T.; Reid, O. G.; Tillack, A. F.; Masiello, D. J. & Ginger, D. S. Submicrosecond Time Resolution Atomic Force Microscopy for Probing Nanoscale Dynamics. Nano Lett., 2012, 12: 893 - 898 [].
[16][Moore2011sep] Moore, E. W. 1. Mechanical Detection of Electron Spin Resonance from Nitroxide Spin Probes, 2. Ultrasensitive Cantilever Torque Magnetometry of Magnetization Switching in Individual Nickel Nanorods. Ph.D. Thesis, Cornell University, 2011.