# &app; Manual

&app; provides a Graphical User Interface to the VOACAP HF propagation prediction application.

2014-2020
J.Watson
J.Watson
&legal;

James
Watson
v&manrevision;
2016-02-01

J.Watson jwatson@neomailbox.ch

This manual describes version &appversion; of &app;.

## Feedback

To report a bug or make a suggestion regarding &app; application or this manual, please contact the author.

## Introduction

&app; is a front end to the VOACAP engine and may be used to;

- Produce HF propagation predictions between two fixed locations (Point-to-Point / P2P mode).

- Produce HF propagation plots over a user defined area from a fixed transmit site (Area Mode).

voacapgui requires a working copy of the VOACAP engine installed on the host machine. Installation of VOACAP is beyond the scope of this manual.

## Installation

### Desktop File

Run the update-desktop-database application to rebuild the desktop file database.

### Icon

The Gnome desktop looks for icons in the selected theme directory of /usr/share/icons/. Copy the the icon into /usr/share/icons/hicolor/48x48/apps/.

Run gtk-update-icon-cache to update the icon database.

## Getting Started

### Starting &app;

You can start &app; in the following ways:

Applications menu

  Choose Submenu Name &app; .

Command line

  To start &app; from a command line, type the following command, then press Return:

  `&app;`

### When You Start &app;

When you start &app;, the following window is displayed.

#### &app; Start Up Window

Shows &app; main window. Contains titlebar, menubar, tabbed area, Settings, and Help menus.

The &app; window contains the following elements:

Menubar

  The menu contains submenus alowing users to quit the application and access the help documentation.

Tabbed Notebook

  The tabs are divided into functional sections and most users will enter the required input data working left to right along the tabs.

  Applications Tab

    Used to define the geographic location of sites and associated properties (transmitter power, antennas etc.).

  Applications Tab

    Used to define the geographic location of sites and associated properties (transmitter power, antennas etc.).

  P2P Tab

    Used to define parameters unique to Point-to-Point predictions.

  Area Tab

    Used to define parameters unique to Area predictions.

  System Tab

    Used to define the common system parameters.

  SSN Tab

    Used to define the Sun Spot Numbers (SSN) used by the VOACAP prediction engine.

## Usage

You can use the &app; application to perform the following tasks:

- Produce Point-to-Point Predictions

- Produce Area Plots

### VOACAP Point-to-Point Predictions

To perform a P2P prediction, select the Site tab in the notebook and click the Site button in the Tx. Site panel to open the Site Chooser dialog window.

#### &app; Site Chooser

Shows &app; main window. Contains titlebar, menubar, tabbed area, Settings, and Help menus.

Sites may be defined by either;

- Clicking on the map.

- Using the Locator combo boxes.

- Entering latitude and longitude directly into the Lat: and Lon: text entry fields.

- Selecting from a list of predefined sites acessed by clicking the Select From File expander.

Once the required site information has been entered, click the OK to close the Site Chooser dialog and return to the main window.

Antenna Selection is made by clicking the Antenna button to open the Antenna Chooser dialog window.

#### &app; Antenna Chooser

Shows &app; main window. Contains titlebar, menubar, tabbed area, Settings, and Help menus.

Specific antenna models may be selected by browsing through the available models by clicking on the expander buttons in the left panel. Click the OK button to accept the selected antenna and return to the main window.

The bearing of the antenna is defined in the bearing text entry and may be either entered directly or directed to the Rx. Site by clicking the Bearing button.

The transmitter power (in Watts) is then entered using the Power (W) entry field.

Site data for the receive site may then be entered in the Rx. Site panel.

After entering the receive site coordinate, it may be necessary to click the Bearing button in the Tx. Site panel to redirect the transmit antenna to the newly defined receive site.

Click the P2P tab to move to the Point-to-Point panel to define the predictions to be performed.

#### &app; P2P Notebook Tab

Shows &app; main window. Contains titlebar, menubar, tabbed area, Settings, and Help menus.

Define the time for the prediction by specifying a year and month in the Year and Month entry fields respectively. If required, a day may also be specified by selecting the Use Day checkbox and entering a day value in the Day entry field.

Enabling the Days value will force the VOACAP engine to use the URSI88 coefficients instead of the preferred CCIR values.

#### Cicuit Calculations

The default behavior of voacapgui is to produce graphical output showing the performance of frequencies in the range 2-30MHz over a 24 hour period. While this may be useful for most applications, text based 'cicuit' predictions may be used when an analysis of performance at spot frequencies is required

To enable circuit predictions, click the Circuit checkbox and use the Frequency entry panel and associated Add button to populate the frequency table

Select the method from the Method combo box at the bottom of the entry panel

Most users will want to select method 30, 'Complete System Performance'

### Displaying the results

Results of circuit mode calculations are displayed directly in a text dialog.

In the case of graphical reults, the Plot Control opens and offers the following selections;

#### &app; P2P Plot Configuration

Shows &app; main window. Contains titlebar, menubar, tabbed area, Settings, and Help menus.

Plot Type

  Specify the data to be displayed behind the MUF / FOT curves. Available data sets are Reliability, MUFday, DBW, SNR and none.

Group

  Specify the SSN groups to plot

Timezone

  Specify a timezone to shift the plotted data to.

colour Map

  Specify the colour map to use for plotting the background data set.

Click the OK button to open the image file.

### VOACAP Area Predictions

To perform an area prediction, select the Site tab in the notebook and click the Site in the Tx. Site panel to open the Site Chooser dialog window.

Sites may be defined by either;

- Clicking on the map.

- Using the Locator combo boxes.

- Entering latitude and longitude directly into the Lat: and Lon: text entry fields.

- Selecting from a list of predefined sites acessed by clicking the Select From File expander.

Once the required site information has been entered, click the OK to close the Site Chooser dialog and return to the main window.

Antenna Selection is made by clicking the Antenna button to open the Antenna Chooser dialog window. Specific antenna models may be selected by browsing through the available models by clicking on the expander buttons in the left panel. Click the OK button to accept the selected antenna and return to the main window.

The bearing of the antenna is defined in the bearing text entry and may be either entered directly or directed to the Rx. Site by clicking the Bearing button.

The transmitter power (in Watts) is then entered using the Power (W) entry field.

Details of the receive antenna then be entered in the Rx. Site panel.

When performing area calculations only the receive site antenna definition is used. All other information in the Rx Site is ignored.

Click the Area tab to move to the Area panel to define the predictions to be performed.

#### &app; Area Tab

Shows &app; main window. Contains titlebar, menubar, tabbed area, Settings, and Help menus.

Define the time for the prediction by specifying a year and month in the Year and Month entry fields respectively.

Define the frequency of operation for the prediction in the Freq text entry then click the Add button to add the selected values to the main panel. Additional plots may be defined by selecting required Year, Month UTC and Freq values and adding them to the main panel with the Add.

Click the Area button to open the Area Chooser dialog panel which supports defining the receive area in two ways;

- Dragging the cursor across the map.

- Entering values for the North East corner and South West corners directly into the entry fields.

Click the OK to accept the displayed values and return to the main window.

Select the required grid size from the Gridsize entry and start the prediction by clicking the Execute button.

The VOACAP `GRID` parameter specifies a grid overlayed onto the specifed coverage area. Predictions are performed at each intersection within the grid. Large `GRID` values are used to produce print quality plots but at teh expennse of computing time. Users amy find it better to specify a small grid size for initial runs to check that the inputs are correct prior to setting higher values for final printing.

### Displaying the Area Results

The Plot Control dialog is opened as soon as the prediction calculations are complete and offers the following selections;

#### &app; Area Plot Configuration

Shows &app; main window. Contains titlebar, menubar, tabbed area, Settings, and Help menus.

Plot Type

  Specify the data to be displayed behind the MUF / FOT curves. Available data sets are Reliability, MUFday, DBW, SNR and none.

Group

  Specify the SSN groups to plot

Timezone

  Specify a timezone to shift the plotted data to.

Colour Map

  Specify the colour map to use for plotting the background data set.

Contours

  Produces a filled contour plot.

Greyline

  Controls the plotting of a greyline on the area map.

Parallels

  Controls the plotting of paralells on the area map.

Meridians

  Controls the plotting of meridians on the area map.

Prediction data may be stored in a '.vgz' file; a zip file containing the source .voa file along with the output .vg_ files. These files may be saved and retreived using the File Open VGA File menu item.

Click the OK button to open the area plot image.

## System Settings

- System

- SSN

### System Settings

The System Notebook Tab is used to define a number of system side VOACAP parameters.

#### &app; System Tab

Shows &app; main window. Contains titlebar, menubar, tabbed area, Settings, and Help menus.

Man-Made Noise

  This is an important parameter, used to characterise the level of man-made noise at the receive location.

  Valid values are in the range 100-200 -dBw/Hz

  dBW/Hz | Environment
  --- | ---
  -164.1 | Remote
  -152.7 | Quiet
  -150.0 | Rural
  -144.7 | Residential
  -140.4 | Industrial
  -138.7 | Noisy

Min. Take-Off Angle

  This value is normally very small unless antenna performance is anticipated to be so poor at low angles that these angles should not be used in the estimation of upper useful frequencies, or if the horizon is so obstructed that low take off angles and reception angles appear unlikely.

  Valid values are in the rangle 0.1 - 90.0 degrees

Reliability

  An estimate of the percent of days within a month that the signal quality will meet the level defined by the Required SNR parameter.

Required SNR (dB/Hz)

  An important parameter used to specify the required Signal-to-Noise ratio of the hourly median power relative to the hourly median noise in a 1Hz bandwidth.

  Typical values of Required SNR are;

  dB/Hz | Traffic
  --- | ---
  45.0 | Voice / 600bps Data
  47.0 | Voice / 1200bps Data
  49.0 | Voice / 2400bps Data
  52.0 | 4800 bps MIL-STD-110B Data
  63.0 | 9600 bps MIL-STD-110B Data

Multipath Tolerance

  Specifies the maximum difference in power between the sky-wave modes to permit satisfactory system peformance in the presence of multiple signals. Modes weaker than the specified level are not considered multipath problems.

  The valid range is 0-40dB (Default = 3.dB)

Max Delay (mS)

  Specifies the maximum tolerable delay in between sky-wave modes to permit satisfactory system performance in the presence of multiple signals. Modes within the specified linit are not considered multipath problems.

  The valid range is 0-99.99 mSec (Default = 10.00 mSec)

Ionospheric Variables foE, foF1, foF2, foEs

  Multipliers that adjust the predicted critical frequency for the associated layer.

  Default values for foE, foF1 & foF2 are 1.0, foEs = 0.0

Model

  Define the coefficients used for the calculations

  Default is CCIR

Path

  Specifies if a long or short path calaculation should be performed.

  Default: Short

### Sun Spot Numbers (SSN)

This tab is used to display the Sun Spot Numers (SSN) read by voacapgui and passed to VOACAP.

#### &app; SSN Tab

Shows &app; main window. Contains titlebar, menubar, tabbed area, Settings, and Help menus.

The information is derived from data published by NOAA and made available at ftp://ftp.ngdc.noaa.gov/STP/space-weather/solar-data/solar-indices/sunspot-numbers/predicted/table_international-sunspot-numbers_monthly-predicted.txt .

The Web Update may be used to updated the table (requires an Internet connection). Alternatively, a copy of the `table_international-sunspot-numbers_monthly-predicted.txt` file can be placed in the user's `~/.voacapgui` directory.

## Templates

Voacapgui supports the use of templates to facilte the prepation of repeated input data.

Each file must implement only one class named "templates" which can implement one or more templates.

The "templates" class has to define the following methods:

__init__(self, parent)

  parent is the parent window in case a dialog has to be used.

get_names(self)
  return a list of the names of the templates
get_params(self)
  Return a list of strings with properties the caller should set on the object. For example, for getting the parent property "prop" set in the templates object scope, this function must return ['prop'].
load(self)
  This is the last step performed by the caller prior to read the names of the templates implemented. This method should do the minimum amount of work because is always called in program start, not upon template usage.
set_ini(self, model)
  The argument this method gets is the TreeModel object of the area plot tab as is at the moment the method is invoked. This method is called once before calling run(), so the model is actualized.
run(self)
  This method is called upon the object to let it build the template values. It should put the result in the self.ret_templates dict, where the caller will retrieve the values. If a non zero value is returned to the caller, the procedure will be canceled, i.e. the template values will not be added to the model.

## Known Bugs and Limitations

Apart from when starting the application for the very first time, &app; does not check for updated SSN values. The user is responsible for periodically checking / updating the SSN values using the Web Update button on the SSN tab.

## About &app;

&app; was written by J.Watson(M0DNS / HZ1JW) and Fernado Maresca (LU2DFM) (jwatson@neomailbox.ch). To find more information about &app;, please visit the pythonprop homepage.

To report a bug or make a suggestion regarding this application or this manual, please contact the author at the email address provided above.

This program is distributed under the terms of the GNU General Public license as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. A copy of this license is included with this documentation; another can be found in the file COPYING included with the source code of this program.