voacapgui Manual
voacapgui provides a Graphical User Interface to the VOACAP HF propagation prediction application.

Introduction
voacapgui 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 voacapgui
You can start voacapgui in the following ways:
Applications menu 	 Choose Submenu Name voacapgui .
Command line 	 To start voacapgui from a command line, type the following command, then press Return:
voacapgui

When You Start voacapgui
When you start voacapgui, the following window is displayed.

voacapgui Start Up Window
Shows voacapgui main window. Contains titlebar, menubar, tabbed area, Settings, and Help menus.
The voacapgui 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 voacapgui application to perform the following tasks:
Produce Point-to-Point Predictions VOACAP Point-to-Point Predictions
Produce Area Plots VOACAP Area Predictions

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.

voacapgui Site Chooser
Shows voacapgui 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.

voacapgui Antenna Chooser
Shows voacapgui 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.

voacapgui P2P Notebook Tab
Shows voacapgui 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;

voacapgui P2P Plot Configuration
Shows voacapgui 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.

voacapgui Area Tab
Shows voacapgui 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;

voacapgui Area Plot Configuration
Shows voacapgui 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 SettingsSystem
Sun Spot Numbers (SSN)SSN

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

voacapgui System Tab
Shows voacapgui 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.

voacapgui SSN Tab
Shows voacapgui 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, voacapgui 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 voacapgui
voacapgui was written by J.Watson(M0DNS / HZ1JW) and Fernado Maresca (LU2DFM) (jwatson@neomailbox.ch). To find more information about voacapgui, 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.