sidmon5

This package is a VLF receiver for monitoring VLF transmitter signals for evidence of transients indicating ionospheric disturbances. It takes sample pairs from dual-channel sound cards and spectrally processes them to Stokes parameters.

Features

1. Acquires two polarizations from loop antennas via a sound card.
2. Time plots of
   • Stokes parameters,
   • X/Y polarization amplitudes and relative phase,
   • ellipse major and minor axes and orientation,
   • normalized parameters,
   • GOES x-ray flux, and
   • SWPC event start-peak-stop times.
3. Scatter plots of pairs of parameters.
4. Utilities for
   • downloading GOES x-ray data,
   • downloading SWPC events data, and
   • a front end for generating plots (in Bash).

• Written in python (except as noted).
• The acquisition program (sidmon5.py) is inspired by SuperSID, but written independently.
• The viewer (plot.py) evolved from supersid_plot.py.
• There is no interoperability between SuperSID and this code.
• Runs only on linux because it uses ALSA and alsaaudio.

Installation

Run the installation script.

install dependencies
install configure

The first installs linux packages needed by the program. The second creates

• /etc/sidmon5/install_location - for the sidmon installation directory,
• /etc/sidmon5/user - install user,
• /etc/sidmon5/events_location - forthe installation directory for SWPC events reports (default is subdirectory EventsReports), and
• /etc/sidmon5/goes_location - for the directory where GOES x-ray intensities are placed.
• /etc/sidmon5/data_location - for the directory into which data are deposited and from which data are read (default is subdirectory data).

The first path should not be changed, but use the commands

echo "<eventspath>"     | sudo tee /etc/sidmon5/events_location
echo "<goesdatapath>"   | sudo tee /etc/sidmon5/goes_location
echo "<datapath>"       | sudo tee /etc/sidmon5/data_location

to update the others to the actual destination directories. The configuration step when rerun will not modify them once they are defined.

The file sidmon is placed in /etc/init.d/ during installation. To use this file to control sidmon. Edit for the specifics of the installation, particularly the variables

• device - for the sound device, and
• headerfile - for the file that configures sidmon, providing sample rate, transmitters to monitor, etc.

To list available sound devices, enter

install devices

Other utilities:

• install cards - to list installed sound cards,
• install service enable - to install sidmon as a service.

Useful aliases for pasting into .bashrc or elsewhere:

alias sidmon='/etc/init.d/sidmon'
alias plot="$(cat /etc/sidmon5/install_location)/plot"

Usage

To control and monitor sidmon5,

sidmon start        # start
sidmon stop         # stop
sidmon restart      # restart
sidmon status       # view status

There are convenience functions.

sidmon installdir   # print installation directory"
sidmon installuser  # print installation user"
sidmon cards        # print installed sound cards"
sidmon devices      # print installed sound devices"

To plot the data, use 'plot' in the installation directory, for example time plots are

plot selection 20241110 NLKi,NMLi       # for any set of parameters
plot q 20241110 NLK,NML                 # plots Stokes Q for transmitters
plot                                    # displays more options

Three upper-case letters specify the transmitter. Lower-case suffixes specify a quantity:

• Stokes parameters i, q, u, and v,
• total polarization t and linear polarization l,
• Polarization-ellipse major (a) and minor (b) axes, and angular orientation (th); and
• x (x) and y (y) magnitudes, and x - y phase p.

The switch --normalize has the following effects.

• Stokes I is scaled to peak at 1.0.
• Stokes Q, U, V, T (total polarization), and L (linear polarization) are divided by Stokes I.
• Polarization-ellipse major and minor axes, and x and y polarization amplitudes are divided by sqrt(Stokes I).

2d scatter plots of one or more pairs of parameters are by

plot scatter 20241110 NLKu,NLKv,NMLu,NMLv --normalize

Time segments can be plotted with different colors to see what they are doing. For example,

plot scatter 20241110 NLKu,NLKv --trange 14,15:30,18:00,22:15

plots three time segment. Use the command

plot goesdata yyyy-mm-dd

to download and reduce GOES x-ray data files, and the command

plot events yyyymmdd

to download SWPC events reports. These files are needed if their data are to be displayed.

To schedule download of events and GOES files, one can have cron tasks; for example, for daily downloads,

18 17 * * * $(cat /etc/sidmon5/install_location)/plot events   "$(date -u --date yesterday +\%Y\%m\%d)"
42  9 * * * $(cat /etc/sidmon5/install_location)/plot goesdata "$(date -u --date '3 days ago' +\%Y-\%m-\%d)"

GOES files are available after a few-days delay. The data are placed in the directories defined in /etc/sidmon5/events_location and /etc/sidmon5/goes_location, respectively.

See the SuperSID reference below and other sources for information on loop antennas and the ins and outs of SID detection.

src/plot.py and its front end plot accept a number of switches. See src/plot.py -h, or simply plot.

In my experience, the sound device infrequently becomes inaccessible, and acquisition stops. sidmon tries to restart, but this effort can fail. For this reason it is useful to have a cron task that periodically checks that sidmon is running, and if not restarts it, such as

*/15 * * * * if ! /etc/init.d/sidmon status > /dev/null; then /etc/init.d/sidmon start; fi

Configuration files

sidmon5's configuration-file (header) format is rationalized from the format of sidmon2 and sidmon3. Refer to the documentation of sidmon2 to understand sidmon's fitting algorithm and transmitter groups, and the sidmon5 example Header.txt.

The file audio.py has useful utilities, one for displaying spectra.

audio.py spectrum    <device> <framerateHz> [<integrationtimeseconds>]

It is best to use the lowest sample rate that 1) has Nyquist frequency above the maximum observed frequency, 2) has bandwidth (frequency cutoff) above the maximum observed frequency, and 3) the no-input spectrum is clean. One need not limit oneself to 'standard' audio sample rates.

The configuration file provides entries for both the sample-rate setting and measured sample rate at that setting. Measure the sample rate at a candidate setting using another utility in audio.py.

audio.py measurerate <device> <framerateHz> [<durationminutes> [<printintervalseconds>]]

Sample rates are measured against the system clock, so it is necessary that the system have a clock stabilized by NTP. A GPS-disciplined server on the LAN is helpful, but perhaps not necessary.

References

• SuperSID.
• sidmon2.
• sidmon3.
• Gross, N. C., Cohen, M. B., Said, R. K., & Golkowski, M. (2018). Polarization of narrowband VLF transmitter signals as an ionospheric diagnostic. Journal of Geophysical Research: Space Physics, 123, 901–917.