Friday, November 18, 2016

VOACAP Greyline User Manual

VOACAP Greyline is an online service that provides a number of sun-related data for any given location such as sunrise/sunset times, dawn, dusk, solar midnight, and, for circuits, the solar midnight time for the circuit's half-way point. The idea is to offer data which would help DXers/contesters leverage any "grayline" related low-band openings.

The URL:

What's in it for you?

The greyline service offers three types of solar calculations:

  1. Daily sunrise and sunset times for a wide selection of DXCC locations
  2. All-year sun calendar: sunrise and sunset times for a user-defined location for every day of the year selected
  3. A deep analysis of DXCC countries that are located along the grayline terminator or in darkness at sunrise and sunset in a user-defined location

1. Daily sunrise and sunset times for a wide selection of DXCC locations

This is the default calculation when you go to the site at The DXCC locations are the pre-defined locations used in VOACAP Online. In reality, VOACAP Greyline offers much more than simple sunrise or sunset times. Let's look into the times calculated; all times in all calculations are UTC.


There are actually seven different times which will be calculated: three related to sunrise, three related to sunset, and one related to solar midnight.

Sunrise-related times:

DAWN = a point in time when the sun is 6 degrees below the horizon before sunrise
RISE = the sunrise time at the horizon
POST = a point in time when the sun is 3 degrees above the horizon after sunrise

Sunset-related times:

PRE  = a point in time when the sun is degrees above the horizon before sunset
SET  = the sunset time at the horizon
DUSK = a point in time when the sun is 6 degrees below the horizon after sunset

Solar midnight

MNITE = This is the time opposite to solar noon when the sun is closest to the nadir (the direction pointing directly below a particular location), and the night is equidistant from dusk and dawn. The solar midnight rarely coincides with midnight on a clock. Solar midnight is dependent on longitude and time of the year rather than on a time zone. [Wikipedia:]

POST and PRE times

The POST and PRE times are based on an educated choice; there is no conscious theory behind "the 3 degrees above the horizon". We know from experience that the low-band propagation starts to deteriorate at some point after sunrise, and that the propagation starts to get enhanced before the actual sunset, and "3 degrees" was my personal choice for this purpose. So, in effect, I am using the time periods from DAWN to POST, and from PRE to DUSK as my internal limits in my calculations when filtering the results in the deep analysis (the calculation type 3).

The default date for daily calculations in the currect UTC day. If you wish to calculate times for all DXCC sites for a specific date, just select the date from the calendar, and press "Go".

To make this calculation again for the current date after setting the date (or after setting a location), just press first "Reset" and then "Go".

There can be cases where no time is calculated but "--:--" is shown instead. This means that the sun does not reach the degree position set for the calculation.

For example, let's take some Finland locations at midsummer (June 21):

CITY                          DAWN   RISE   POST   |  PRE    SET    DUSK   |  MNITE
OH6 Seinajoki                 --:--  00:25  01:26  |  19:34  20:35  --:--  |  22:30
OH6 Vaasa                     --:--  00:23  01:28  |  19:43  20:47  --:--  |  22:35
OH7 Joensuu                   --:--  00:00  01:01  |  19:04  20:05  --:--  |  22:02
OH7 Kuopio                    --:--  00:03  01:06  |  19:15  20:18  --:--  |  22:11
OH8 Kajaani                   --:--  23:34  00:50  |  19:31  20:47  --:--  |  22:10
OH8 Oulu                      --:--  23:19  00:49  |  19:50  21:20  --:--  |  22:19

As the times for DAWN and DUSK are labelled as "--:--", it means that the sun does not reach 6 degrees before sunrise nor does it go below 6 degrees after sunset. On the other hand, for instance, if all columns are labelled as "--:--", it can mean that it's either midnight sun (polar day) or polar night.

2. All-year sun calendar: sunrise and sunset times for a user-defined location for every day of the year selected

If you wish to run the solar data above for every day of the chosen year for your own location, just enter your Maidenhead grid locator in the "Locator" field, choose any date (click on a date) in the year you are interested in, and checkmark the "Calendar" option. Then press "Go".

The locator needs to be given in six characters. If you do not know your locator, please click on the "Locator" link to go to which shows you the coordinates and the corresponding grod locator with the precision required (6 characters).

Suppose we want a all-year sun calendar for Valletta (9H) for the year 2017. Then I would first check the grid locator (JM75gv) and select any date from the calendar in 2017. Then I would checkmark the "Calendar" box, and press "Go".

The result will be as follows:


3. A deep analysis of DXCC countries that are located along the grayline terminator or in darkness at sunrise and sunset in a user-defined location

This calculation type is the most elaborate. First of all, it requires that you set a location (as a 6-character Maidenhead grid locator), and set a date you are interested in. Do not checkmark the "Calendar" box! Then press "Go".

Two calculations will be done for all circuits from the location you set to the pre-defined locations in VOACAP Greyline's DXCC country list: sunrise and sunset calculations.

New columns

There will be a number of new columns on the result page as we are now dealing with point-to-point circuits. The columns are:

  • HALFW = This is the solar midnight at the half-way point along the circuit in question. This is the time ON4UN says can be one of the peak times along that circuit.
  • KM/SP and DEG = This is the distance from the Location to the DXCC location in kilometers via short-path (SP). DEG is the corresponding bearing from Locator to the DXCC location.
  • KM/LP and DEG = This is the distance from the Location to the DXCC location in kilometers via long-path (SP). DEG is the corresponding bearing from Locator to the DXCC location. If you want the distance in miles, divide kilometers by 1.609 ...

As said, the service calculates the sunrise and sunset times for the given Locator. Then it tries first to find the locations in DXCC countries that are along the grayline terminator. In those locations, the sun can either be rising or setting. The time frame for the terminator is determined by DAWN-POST and PRE-DUSK times. If the sun is rising, you will only see the sunrise-related times for that particular DXCC location, and consequently, if the sun is setting in that particular DXCC location, you will only see the sunset-related times.

Secondly, the service finds all locations in the DXCC country list where the location is in darkness. So, this is the situation when the sun rises or sets in the Location but it's still dark in the DXCC location. Think about the morning propagation of signals from the west when the sun start to rise in your location.

An example

Let me illustrate what's happening. In the image below, this is an excerpt of the result page for my locator KP03sd on November 15, 2016.


In Bullet 1, we can see that at my sunrise, the sun is rising also in 1A SMOM and in 3A Monaco. Bullet 2 reveals, on the other hand, that - at the same time - the sun is setting in 3D2/C Conway Reef and 3D2/R Rotuma. Note that in these two cases, only the sunrise or sunset times are shown, so that the user can more easily distinguish whether there is a sunset or sunrise in the DXCC location.

And finally, Bullet 3 shows that there are locations which are in darkness at my sunrise. When a DXCC location is in darkness, both the sunrise and sunset times are given for the location. The darkness period is calculated to be the time period from PRE to POST in that particular DXCC location. This actually means that the darkness period also includes the twilight period.

For instance, 8P Barbados is in "darkness" from 21:11 UTC (PRE) to 10:14 UTC (POST). And we can see that the twilight period for KP03sd is from 05:58 UTC (DAWN) to 07:47 UTC (POST). So, 8P is filtered to be part of the results as it's in darkness when the sun is rising in the given Location.

A similar kind of analysis is made for the sunset at Locator, too.

Saturday, November 12, 2016

VOACAP Online now offers multiple coverage maps at one go

The VOACAP Online Coverage Maps Service at is now able to plot multiple coverage maps at one go. This was made possible by a major code re-factoring at Earlier, only one map could be plotted at a time.

In a nutshell, while entering the input values, at "Time UTC:", choose the start time for your maps. The default is the currect UTC hour. See image below.

Then there is a pop-up menu for "Period". There you will need to choose the time period for your maps, defaulting to 1, i.e. the map for the current hour. You can choose a time period up to 12 hours, so to cover a 24-hour period, you will only need to make two runs. Unfortunately, running and plotting 24 hours, or 24 coverage maps, at one go takes a considerable amount of time, resulting in a server connection time-out, hence 12 hours is the limit.

So when viewing the result page with the maps, you can then conveniently print that page to PDF. You may need to install some extra tools such as CutePDF Writer if this functionality is not offered to you by your operating system as standard.

Please be also advised that all the coverage maps created in the service will be deleted in a more frequent cycle than before so please do not link directly to the maps produced.

Also, earlier this month, I added the option of choosing the noise level at RX sites. This option was also added to VOACAP Online Point-to-Point Service.

Give it a spin and let me know what you think!

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.