Skip to content

API Reference

Jump to bottom
github-actions[bot] edited this page Nov 18, 2025 · 3 revisions

API Reference

Complete API reference for DVOACAP-Python. Classes and methods are organized by phase.

Quick Links

Phase 1: Path Geometry

GeographicPoint

Represents a geographic location with latitude and longitude.

Constructor:

GeographicPoint(lat: float, lon: float)
GeographicPoint.from_degrees(lat_deg: float, lon_deg: float)

Attributes:

  • lat (float) - Latitude in radians
  • lon (float) - Longitude in radians

Example:

from dvoacap import GeoPoint

# Create point from degrees
philadelphia = GeoPoint.from_degrees(40.0, -75.0)

PathGeometry

Utilities for great circle path calculations.

Static Methods:

PathGeometry.distance(p1: GeographicPoint, p2: GeographicPoint) -> float
PathGeometry.bearing(p1: GeographicPoint, p2: GeographicPoint) -> float
PathGeometry.midpoint(p1: GeographicPoint, p2: GeographicPoint) -> GeographicPoint

Parameters:

  • p1, p2 - Geographic points (start and end)
  • Returns: Distance in km, bearing in radians, or midpoint

Example:

from dvoacap import PathGeometry, GeoPoint

tx = GeoPoint.from_degrees(40.0, -75.0)  # Philadelphia
rx = GeoPoint.from_degrees(51.5, -0.1)   # London

distance_km = PathGeometry.distance(tx, rx)
bearing_rad = PathGeometry.bearing(tx, rx)
midpoint = PathGeometry.midpoint(tx, rx)

Phase 2: Solar & Geomagnetic

SolarCalculator

Calculates solar position and illumination.

Methods:

SolarCalculator.compute_zenith_angle(
    location: GeographicPoint,
    utc_time: datetime
) -> float

SolarCalculator.compute_local_time(
    location: GeographicPoint,
    utc_time: datetime
) -> float

SolarCalculator.is_daytime(
    location: GeographicPoint,
    utc_time: datetime
) -> bool

Parameters:

  • location - Geographic point
  • utc_time - UTC datetime
  • Returns: Zenith angle (radians), local time fraction (0-1), or boolean

Example:

from dvoacap import SolarCalculator, GeoPoint
from datetime import datetime

location = GeoPoint.from_degrees(40.0, -75.0)
utc = datetime(2025, 6, 15, 12, 0)

zenith = SolarCalculator.compute_zenith_angle(location, utc)
is_day = SolarCalculator.is_daytime(location, utc)

GeomagneticCalculator

Calculates Earth's magnetic field parameters.

Methods:

GeomagneticCalculator.compute_field(
    location: GeographicPoint,
    altitude_km: float,
    date: datetime
) -> GeomagneticParameters

Returns: GeomagneticParameters with:

  • mag_lat - Magnetic latitude (radians)
  • mag_dip - Magnetic dip angle (radians)
  • gyro_freq - Gyrofrequency (MHz)
  • field_intensity - Total field strength (nT)

Example:

from dvoacap import GeomagneticCalculator, GeoPoint
from datetime import datetime

location = GeoPoint.from_degrees(40.0, -75.0)
params = GeomagneticCalculator.compute_field(
    location,
    altitude_km=300,
    date=datetime(2025, 6, 15)
)

print(f"Magnetic latitude: {params.mag_lat:.2f} rad")
print(f"Gyrofrequency: {params.gyro_freq:.2f} MHz")

Phase 3: Ionospheric Profiles

FourierMaps

CCIR/URSI ionospheric coefficient maps.

Constructor:

FourierMaps(data_dir: str = "DVoaData")

Methods:

def set_conditions(
    self,
    month: int,          # 1-12
    ssn: float,          # Sunspot number (0-200)
    utc_fraction: float  # 0-1 (0 = midnight, 0.5 = noon)
)

def compute_var_map(
    self,
    lat: float,    # Latitude in radians
    lon: float,    # Longitude in radians
    kind: VarMapKind
) -> Distribution  # Returns median, upper decile, lower decile

VarMapKind enum:

  • VarMapKind.F2 - F2 layer critical frequency
  • VarMapKind.ER - E layer critical frequency
  • VarMapKind.FM3 - M(3000)F2 propagation factor

Example:

from dvoacap import FourierMaps, VarMapKind

maps = FourierMaps()
maps.set_conditions(month=6, ssn=100, utc_fraction=0.5)

# Get foF2 at Philadelphia
fof2 = maps.compute_var_map(
    lat=40.0 * 3.14159/180,
    lon=-75.0 * 3.14159/180,
    kind=VarMapKind.F2
)

print(f"foF2: {fof2.median:.2f} MHz")

ControlPoint

Point along propagation path with ionospheric parameters.

Attributes:

  • location - Geographic point
  • e - E layer info (LayerInfo)
  • f1 - F1 layer info
  • f2 - F2 layer info
  • es - Sporadic E info

LayerInfo fields:

  • fo - Critical frequency (MHz)
  • hm - Peak height (km)
  • ym - Semi-thickness (km)

Example:

from dvoacap import ControlPoint, FourierMaps, compute_iono_params
import math

maps = FourierMaps()
maps.set_conditions(month=6, ssn=100, utc_fraction=0.5)

pnt = ControlPoint(
    location=GeographicPoint.from_degrees(40.0, -75.0),
    east_lon=-75.0 * math.pi/180,
    distance_rad=0.0,
    local_time=0.5,
    zen_angle=0.3,
    zen_max=1.5,
    mag_lat=50.0 * math.pi/180,
    mag_dip=60.0 * math.pi/180,
    gyro_freq=1.2
)

compute_iono_params(pnt, maps)

print(f"E layer:  foE  = {pnt.e.fo:.2f} MHz at {pnt.e.hm:.0f} km")
print(f"F2 layer: foF2 = {pnt.f2.fo:.2f} MHz at {pnt.f2.hm:.0f} km")

IonosphericProfile

Electron density profile vs altitude.

Methods:

def compute_profile(
    self,
    control_point: ControlPoint,
    altitude_km: float
) -> float  # Returns electron density (electrons/cm³)

Example:

from dvoacap import IonosphericProfile

profile = IonosphericProfile(control_point)

# Get electron density at 300 km
density = profile.compute_profile(control_point, 300)
print(f"Electron density at 300 km: {density:.2e} e/cm³")

Phase 4: Raytracing

MufCalculator

Maximum Usable Frequency calculations.

Constructor:

MufCalculator(profile: IonosphericProfile)

Methods:

def compute_circuit_muf(
    self,
    distance_km: float,
    min_elevation_deg: float = 3.0
) -> CircuitMuf

CircuitMuf attributes:

  • muf - Maximum Usable Frequency (MHz)
  • fot - Frequency of Optimum Traffic (MHz)
  • hpf - High Probability Frequency (MHz)
  • e_muf - E layer MUF
  • f1_muf - F1 layer MUF
  • f2_muf - F2 layer MUF

Example:

from dvoacap import MufCalculator

calc = MufCalculator(ionospheric_profile)
circuit = calc.compute_circuit_muf(distance_km=5000)

print(f"MUF: {circuit.muf:.2f} MHz")
print(f"FOT: {circuit.fot:.2f} MHz (optimum)")
print(f"HPF: {circuit.hpf:.2f} MHz (high reliability)")

Reflectrix

Ray path calculations through ionosphere.

Constructor:

Reflectrix(profile: IonosphericProfile)

Methods:

def compute_modes(
    self,
    frequency_mhz: float,
    distance_km: float
) -> List[ModeInfo]

def compute_skip_distance(
    self,
    frequency_mhz: float,
    layer: str  # 'E', 'F1', 'F2'
) -> float

ModeInfo attributes:

  • mode - Mode name (e.g., '1F2', '2F2')
  • hops - Number of hops
  • layer - Reflection layer ('E', 'F1', 'F2')
  • elevation_angle - Takeoff angle (degrees)
  • virtual_height - Virtual reflection height (km)

Example:

from dvoacap import Reflectrix

reflx = Reflectrix(ionospheric_profile)

# Find all modes for 14 MHz, 5000 km path
modes = reflx.compute_modes(frequency_mhz=14.0, distance_km=5000)

for mode in modes:
    print(f"Mode {mode.mode}: {mode.hops} hops, "
          f"takeoff {mode.elevation_angle:.1f}°")

# Get skip distance for F2 layer at 28 MHz
skip = reflx.compute_skip_distance(frequency_mhz=28.0, layer='F2')
print(f"Skip distance: {skip:.0f} km")

Phase 5: Signal Predictions

NoiseModel

Atmospheric, galactic, and man-made noise calculations.

Constructor:

NoiseModel(
    frequency_mhz: float,
    location: GeographicPoint,
    utc_time: datetime,
    noise_type: str = "rural"  # 'rural', 'suburban', 'urban'
)

Methods:

def compute_noise(self) -> Distribution

Returns: Distribution with median, upper, lower decile noise levels (dB)

Example:

from dvoacap import NoiseModel, GeoPoint
from datetime import datetime

location = GeoPoint.from_degrees(40.0, -75.0)
noise = NoiseModel(
    frequency_mhz=14.2,
    location=location,
    utc_time=datetime(2025, 6, 15, 12, 0),
    noise_type="suburban"
)

levels = noise.compute_noise()
print(f"Noise level: {levels.median:.1f} dB")

AntennaModel

Base class for antenna gain patterns.

Subclasses:

  • IsotropicAntenna - 0 dBi gain in all directions
  • HalfWaveDipole - Dipole pattern (2.15 dBi gain)
  • VerticalMonopole - Vertical antenna pattern
  • Custom antennas via subclassing

Methods:

def compute_gain(
    self,
    elevation_angle_deg: float,
    azimuth_deg: float = 0
) -> float  # Returns gain in dBi

Example:

from dvoacap import HalfWaveDipole

dipole = HalfWaveDipole(height_m=10, orientation_deg=0)
gain = dipole.compute_gain(elevation_angle_deg=15)
print(f"Gain at 15°: {gain:.1f} dBi")

PredictionEngine

Main prediction engine for complete propagation predictions.

Constructor:

PredictionEngine()

Methods:

def predict(
    self,
    tx_lat: float,           # Degrees
    tx_lon: float,           # Degrees
    rx_lat: float,           # Degrees
    rx_lon: float,           # Degrees
    frequency: float,        # MHz
    utc_time: datetime,
    ssn: float = 100,        # Sunspot number
    tx_power: float = 100,   # Watts
    tx_antenna_gain: float = 0,  # dBi
    rx_antenna_gain: float = 0   # dBi
) -> Prediction

Prediction attributes:

  • muf - Maximum Usable Frequency (MHz)
  • fot - Frequency of Optimum Traffic (MHz)
  • snr - Signal-to-Noise Ratio (dB)
  • signal_strength - Field strength (dBµV/m)
  • reliability - Service probability (%)
  • mode - Best propagation mode
  • distance_km - Path distance

Example:

from dvoacap import PredictionEngine
from datetime import datetime

engine = PredictionEngine()

result = engine.predict(
    tx_lat=40.0, tx_lon=-75.0,  # Philadelphia
    rx_lat=51.5, rx_lon=-0.1,   # London
    frequency=14.2,              # 20m band
    utc_time=datetime(2025, 6, 15, 12, 0),
    ssn=100,
    tx_power=100,
    tx_antenna_gain=2.0
)

print(f"Distance: {result.distance_km:.0f} km")
print(f"MUF: {result.muf:.2f} MHz")
print(f"SNR: {result.snr:.1f} dB")
print(f"Reliability: {result.reliability:.0f}%")
print(f"Best mode: {result.mode}")

Utilities

Distribution

Represents statistical distribution with median and deciles.

Attributes:

  • median - Median value (50th percentile)
  • upper - Upper decile (90th percentile)
  • lower - Lower decile (10th percentile)

Example:

from dvoacap import Distribution

dist = Distribution(median=10.0, upper=15.0, lower=5.0)
print(f"Range: {dist.lower:.1f} to {dist.upper:.1f} dB")

Version Information

from dvoacap import get_version_info, get_phase_status

version = get_version_info()
print(f"DVOACAP-Python v{version['version']}")
print(f"Progress: {version['progress']}")

status = get_phase_status()
for phase, desc in status.items():
    print(f"{phase}: {desc}")

Complete Example: End-to-End Prediction

from dvoacap import PredictionEngine
from datetime import datetime

# Initialize engine
engine = PredictionEngine()

# Configure transmitter and receiver
tx_lat, tx_lon = 40.0, -75.0  # Philadelphia
rx_lat, rx_lon = 51.5, -0.1   # London

# Run prediction for 20m band
result = engine.predict(
    tx_lat=tx_lat,
    tx_lon=tx_lon,
    rx_lat=rx_lat,
    rx_lon=rx_lon,
    frequency=14.2,
    utc_time=datetime(2025, 6, 15, 12, 0),
    ssn=100,
    tx_power=100,
    tx_antenna_gain=2.0,
    rx_antenna_gain=0.0
)

# Display results
print(f"Philadelphia → London Propagation Prediction")
print(f"=============================================")
print(f"Distance:     {result.distance_km:>8.0f} km")
print(f"Frequency:    {14.2:>8.1f} MHz")
print(f"MUF:          {result.muf:>8.2f} MHz")
print(f"FOT:          {result.fot:>8.2f} MHz")
print(f"SNR:          {result.snr:>8.1f} dB")
print(f"Reliability:  {result.reliability:>8.0f} %")
print(f"Best Mode:    {result.mode}")

Expected Output:

Philadelphia → London Propagation Prediction
=============================================
Distance:        5120 km
Frequency:       14.2 MHz
MUF:            18.50 MHz
FOT:            15.72 MHz
SNR:            25.3 dB
Reliability:       85 %
Best Mode:      2F2

Type Hints

DVOACAP-Python includes type hints throughout the codebase:

from typing import List, Tuple, Optional
from datetime import datetime
from dvoacap import GeographicPoint, ModeInfo, Distribution

def my_function(
    location: GeographicPoint,
    frequency: float,
    utc: datetime
) -> Tuple[float, List[ModeInfo]]:
    # Your code here
    pass

See Also

API Status: v1.0.0 Production Ready. API is stable.

Clone this wiki locally