Skip to content

Navigation Menu

Sign in
Sign up

API Reference

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/cm3)

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/cm3")

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

AltStyle によって変換されたページ (->オリジナル) /