Sunday, June 12, 2016

Introducing a text-GUI for VOACAP on Linux

UPDATE: 25 June 2016: a Python version available. [Download]
MAJOR UPDATE: 19 June 2016

I have an extra computer running Developer versions of Windows 10, and creating this text-based GUI actually started with experiments with Microsoft's brand-new Bash on Ubuntu on Windows 10, or the Windows Subsystem for Linux (WSL). To be able to run the Bash shell on Windows 10, you will have to have a certain Developer Build, and currently the shell needs to be specifically enabled as a Windows feature, it is not activated by default. See all the vital info here:

1. Getting Ready

Before I begin, please note that the text-based GUI should actually run on any flavor of Linux/Unix where the basic Unix tools and Perl are installed. What I want to say is that this GUI was inspired by the new Bash shell on Windows 10!

So, first you will need to install the VOACAP binaries in the system. You can of course compile the VOACAP Fortran sources by yourselves but the easy way is just to grab Jim Watson's ready-made VOACAP software package, called voacapl, at It's conveniently packaged also for Ubuntu so, on the WSL, you just download the package and, in the download directory, install it by typing this command:
$ sudo apt-get install voacapl_0.6.5-1_amd64.deb
EDIT: 18 June 2016. The correct command to install this package is: 
$ sudo dpkg -i voacapl_0.6.5-1_amd64.deb 

After the installation is complete, you should run the command 'makeitshfbc' logged in as your usual user name to create the itshfbc directory structure in your home directory.

Test the installation by typing the following command:

$ voacapl ~/itshfbc

You should see output similar to the following:

 Run Directory      : /home/jpe/itshfbc/run
 Opening Data File  : voacapx.dat         
 TRANSMIT=+ 15.0 dBi[default/isotrope     ]=ISOTROPE    beam=   0.0  az= 344.0
 RECEIVE =2-D Table [default/swwhip.voa   ]=SWWhip.VOA  beam=   0.0  az= 158.5
 Method 30 Jun 100ssn  Freqs=  6.1  7.2  9.7 11.9 13.7 15.4 17.7 21.6 25.9

If the tests are okay, you are all ready to start!

Ah, one more thing: please change the absorption model used for calculations. The absorption model will be determined at run time by the contents of the file itshfbc/database/version.w32. The default content of this file is: Version 14.0905W. Change this to: Version 14.0905a which implements Alex' (VE3NEA) changes to the VOACAP code using the IONCAP absorption model.

2. Moving the scripts in place

EDIT 19 June 2016:
Be sure to re-download the and scripts below as they run the entire show.

Download these two scripts: (Bash shell script) and (Perl script), and place them into a directory of their own. Use at your own risk. Read this software disclaimer.

You can, for instance, create a voacap directory under your home directory:

$ mkdir ~/voacap

And, provided the scripts are now in your home directory, move them to the voacap directory:

$ mv voacap
$ mv voacap

Go to the voacap directory, and make the scripts "executable" (chmod):

$ cd voacap
$ chmod +x
$ chmod +x

3. Running the scripts and

Let me explain the workings of the Bash shell script in more detail. This is the main script that runs the show: it prompts the user for the transmitter (TX) and receiver (RX) coordinates, and fetches the sunspot number data from the Internet if it's not already available.

If you run this script for the first time, this script will get the SSN data from the Internet, and will not re-fetch it until the user deletes the SSN file. In addition, this script makes sure that the input data which is required by voacapl is formatted correctly. Then the prediction is run, and the output will be filtered and re-directed to the Perl script which then creates an text-based table out of the VOACAP results.

So, as said, the sunspot number data will be fetched from the Internet, so you will need an Internet connection to get that data. Otherwise, no Internet connection is required.

All the necessary files are defined in as follows:

# VOACAP input & output files
# sunspot file location
# source for sunspot numbers

The sunspot file ssn.txt will be created and located in the itshfbc directory. The VOACAP input file voacapx.dat, required for running the prediction, is located in the itshfbc/run/ directory, and the VOACAP output result file voacapx.out will be located in the same place.

To run the script, go to the voacap directory under your home directory, and type:

$ ./ 
EDIT: The screenshots below reflect now the 19 June 2016 version of the text-GUI.
As we don't have the sunspot data yet, first the script will fetch it by using the curl program. The text on the screen is as follows:

Welcome to the VOACAP text-GUI. This script handles the most important input
values needed for running voacapl, writes the input file, runs the VOACAP
prediction, and feeds the results to the Perl script for creating a
text-based result table.

Please wait. Fetching the sunspot number data...
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  4565  100  4565    0     0   1015      0  0:00:04  0:00:04 --:--:--  1088

Predefined values:
TX Antenna: Isotropic, 0 dBi gain
RX Antenna: Isotropic, 0 dBi gain

Choose a year:
1) 2016
2) 2017
3) 2018
#? _

Only the input values for the TX and RX antennas are pre-defined (the 0-dBi isotropic antenna is a good starting point), and other critical input values such as the current month, year, TX power, TX mode, are user-settable.

You can, of course, modify the VOACAP input file to your taste but please note, however, that the structure of the input file is column-based so care is required that the data is placed on right columns.

Let's run a prediction from London (G) to Christmas Island (VK9X) for November 2018, using CW and 1.5 kW. The screen looks like this:

Choose a year:
1) 2016
2) 2017
3) 2018
#? 3

Choose a month:
1) January      4) April       7) July       10) October
2) February     5) May         8) August     11) November
3) March        6) June        9) September  12) December
#? 11

TX latitude  (-90...90)   : 51.5
TX longitude (-180...180) : -0.08

RX latitude  (-90...90)   : -10.5
RX longitude (-180...180) : 105.67

Choose TX Power (in Watts):
1) 1500
2) 500
3) 100
4) 5
#? 1

Choose TX Mode:
1) CW
2) SSB
3) AM
#? 1

Thank you! Your input file is as follows:

LINEMAX     999       number of lines-per-page
TIME          1   24    1    1
MONTH      2018 11.00
SUNSPOT     11.1
LABEL     TX                  RX
CIRCUIT   51.50N     0.08W    10.50S   105.67E  S     0
SYSTEM       1. 155. 3.00  90. 24.0 3.00 0.10
FPROB      1.00 1.00 1.00 0.00
ANTENNA       1    1    2   30     0.000[samples/sample.00    ]  0.0    1.2000
ANTENNA       2    2    2   30     0.000[samples/sample.00    ]  0.0    0.0000
FREQUENCY  3.60 5.30 7.1010.1014.1018.1021.1024.9028.20 0.00 0.00
METHOD       30    0
BOTLINES      8   12   21
TOPLINES      1    2    3    4    6

Press ENTER to run the prediction...

After you have pressed ENTER at the choice of the TX Mode, the script will show you the structure of the input file to be written to ~/itshfbc/run/voacapx.dat. You can now visually inspect that everything is as should be. Note that the input file will be for a short-path prediction, although both the short-path and long-path circuits will be calculated and displayed. The default antennas are omnidirectional isotropics with zero dBi gain. The minimum take-off angle is set to 3 degrees.

Then press ENTER to run voacapl. You will see this:

Calculating Short-Path...
Calculating Long-Path... 
Press ENTER to view the results...

This is where the execution of practically ends. Now when you press ENTER, the script will extract the REL (Reliability) and S DBW (Signal Power) values from the VOACAP output file, and feed those values to the Perl script,

OK, let's press ENTER and see how the Perl script massages the results into two text tables:

VOACAP Prediction via Short-Path. Nov 2018: SSN 11. Power = 1.200kW, CW
TX (51.50N, 0.08W) to RX (10.50S, 105.67E): 12006 km, 7460 mi, 84 deg

  | 01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|
10|                   f  e  d  d  d  e  f                                  |10
12|                   d  C  C  C  C  C  d  f                               |12
15|                f  C  C  C  C  B  B  B  C  f                            |15
17|                d  C  d  d  C  C  C  C  B  C  f                         |17
20|             e  f  *  *  C  f  e  C  C  C  C  C  d  f  f  f  f  e  e  f |20
30| d  e  f                    *  *  f  f  C  C  C  C  C  C  C  C  C  C  C |30
40| d  *                                *  f  f  d  d  C  C  C  C  C  C  C |40
60| f                                      *  *  f  d  C  C  C  C  d  d  e |60
80|                                              *  f  e  e  d  d  f  e  f |80
  | 01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|

A = 90 - 100%   d = 25 - 49%  * = REL 0%, but Signal Power over Noise
B = 75 -  89%   e = 10 - 24%
C = 50 -  74%   f =  1 -  9%

VOACAP Prediction via Long-Path. Nov 2018: SSN 11. Power = 1.200kW, CW
TX (51.50N, 0.08W) to RX (10.50S, 105.67E): 28018 km, 17410 mi, 264 deg

  | 01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|
10|                                  f  f                                  |10
12|                            f  f  e  d  f  f                            |12
15|                            e  d  d  C  d  d  e                         |15
17|                         f  d  d  d  d  d  d  e  e        f             |17
20|                      f  e  f  *                 f  f  e  f  f  f       |20
30|                                                             f  f  f    |30
40|                                                                        |40
60|                                                                        |60
80|                                                                        |80
  | 01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|

A = 90 - 100%   d = 25 - 49%  * = REL 0%, but Signal Power over Noise
B = 75 -  89%   e = 10 - 24%
C = 50 -  74%   f =  1 -  9%

On top of the Short-Path and Long-Path tables, a good number of details are being displayed. Please note that the SSN value is not the daily sunspot number but a monthly smoothed (predicted) SSN. The band axis is the vertical one and the UTC hours run horizontally starting from 01 UTC (i.e. from 00:30 to 01:30 UTC).

The letters in the table show the probability (in VOACAP parlance, the REL) values for making a QSO from London to Christmas Island from 10 meters to 80 meters. The best probabilities (A to C, or 50% to 100%) are displayed in upper case letters whereas the "less probable" slots are displayed in lower case letters (d to f). You can see the probability legends below the tables.

Please note the use of the star (*). This means that the calculated probability (REL) is zero but the Signal Power (S DBW) still shows values which could be above the Noise level and could produce a detectable signal. This feature is something which is not available in the circular 24-hour (REL) prediction graph at (see below).

Here's the result graph on the same circuit, Short-Path, calculated at VOACAP Online, for reference:

VOACAP Online graphical prediction from London (G) to Christmas Isl (VK9X), November 2018.