Radar Fundmentals

This module adapts and extends concepts and calculations inspired by the CSU Radar Tools and wradlib packages. We acknowledge their foundational contributions to radar meteorology software development.

Attenuation and Scattering Coefficients

Functions related to absorption, scattering, and extinction for spherical particles.

References

• Doviak and Zrnic (1993). Doppler Radar and Weather Observations.

• Battan (1973). Radar Observations of the Atmosphere.

absorption_coefficient	Absorption coefficient Qa for a spherical particle.
extinction_coefficient	Extinction coefficient Qe (absorption + scattering).
k_complex	Complex dielectric factor used in scattering calculations.
scattering_coefficient	Scattering coefficient Qs for a spherical particle.

Beam Geometry and Resolution

Functions related to radar beamwidth and spatial resolution.

References

• Doviak, R. J., & Zrnić, D. S. (1993). Doppler Radar and Weather Observations. Academic Press.

azimuthal_resolution	Compute azimuthal resolution given beamwidth in degrees.
beamwidth_to_radians	Convert beamwidth from degrees to radians.
compute_azimuth_resolution	Compute azimuthal resolution (cross-range resolution).
compute_beamwidth	Compute the beamwidth of a radar.
compute_volume_resolution	Compute radar volume resolution.
volume_resolution	Compute radar volume resolution using horizontal and vertical beamwidth in degrees.

Common Utilities

Shared helper functions for internal use across radarx.fundamentals modules.

dbz_from_z	Alias for z_to_dbz for compatibility with legacy terminology.
dbz_to_z	Convert logarithmic reflectivity dBZ to linear Z [mm^6/m^3].
ensure_positive	Raise a ValueError if the input value is not positive.
kts_to_mps	Convert knots to meters per second.
kts_to_si	Convert knots to meters per second.
km_to_m	Convert kilometers to meters.
km_to_si	Convert kilometers to meters (SI).
kilometers_to_meters	Convert kilometers to meters.
kilometers_to_si	Convert kilometers to meters (SI).
linearize_dbz	Alias for dbz_to_z for compatibility with legacy terminology.
m_to_km	Convert meters to kilometers.
meters_to_kilometers	Convert meters to kilometers.
mps_to_kts	Convert meters per second to knots.
mps_to_knots	Convert meters per second to knots.
si_to_kilometers	Convert SI distance to kilometers.
si_to_km	Convert SI distance (meters) to kilometers.
si_to_kts	Convert meters per second to knots.
z_to_dbz	Convert linear reflectivity Z [mm^6/m^3] to logarithmic dBZ.

Constants

This module contains constants used across radar signal processing and physical modeling, including: - Physical constants (e.g., speed of light, Boltzmann constant) - Radar-specific constants (e.g., dielectric constants, beamwidths)

C	int([x]) -> integer int(x, base=10) -> integer
DBZ_TO_Z_FACTOR	Double-precision floating-point number type, compatible with Python float and C double.
DIELECTRIC_ICE	Convert a string or number to a floating-point number, if possible.
DIELECTRIC_WATER	Convert a string or number to a floating-point number, if possible.
EARTH_RADIUS	Convert a string or number to a floating-point number, if possible.
EFFECTIVE_RADIUS_4_3	Convert a string or number to a floating-point number, if possible.
K_BOLTZMANN	Convert a string or number to a floating-point number, if possible.
RADAR_BANDS	dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2).
T_STANDARD	Convert a string or number to a floating-point number, if possible.
TYPICAL_BEAMWIDTH	dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2).
TYPICAL_PULSE_WIDTHS	dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2).
Z_TO_DBZ_FACTOR	Double-precision floating-point number type, compatible with Python float and C double.

Doppler Radar Calculations

Functions related to Doppler radar performance and velocity limits.

References

• Rinehart, R. E. (1997). Radar for Meteorologists.

• Doviak, R. J., & Zrnić, D. S. (1993). Doppler Radar and Weather Observations.

doppler_dilemma	Solve the Doppler dilemma equation: trade-off between unambiguous range and velocity.
doppler_frequency_shift	Compute Doppler frequency shift.
dual_prf_velocity	Compute Nyquist velocity using dual-PRF scheme.
max_frequency	Compute the maximum observable Doppler frequency.
nyquist_velocity	Compute Nyquist velocity (maximum unambiguous Doppler velocity).
unambiguous_range	Compute maximum unambiguous range for a given PRF.
_doppler_shift_basic
_doppler_shift_exact
_doppler_shift_relativistic

Radar Geometry Calculations

Functions related to beam propagation, height, and sampling volume estimation.

References

• Rinehart, R. E. (1997). Radar for Meteorologists.

• Bech et al. (2003). JAOT, Beam Blockage Corrections.

beam_center_height	Calculate height of beam center above sea level.
effective_radius	Compute effective Earth radius considering atmospheric refraction.
half_power_radius	Compute half-power beam radius.
sample_volume_gaussian	Compute radar sample volume assuming Gaussian beam shape.

Radar Power Calculations

Functions for computing peak power, average power, and minimum detectable signal.

References

• Rinehart, R. E. (2004). Radar for Meteorologists. 4th ed.

• Doviak, R. J., & Zrnić, D. S. (1993). Doppler Radar and Weather Observations.

compute_average_power	Compute average power from peak power and duty cycle.
compute_min_detectable_signal	Compute minimum detectable signal power.
compute_peak_power	Compute peak power from voltage and impedance.

Radar Principles

Core physical and theoretical principles in radar meteorology.

References

• Rinehart, R. E. (2004). Radar for Meteorologists. 4th ed. Rinehart Publications.

• Doviak, R. J., & Zrnić, D. S. (1993). Doppler Radar and Weather Observations. Academic Press.

compute_doppler_shift	Compute Doppler frequency shift.
compute_nyquist_velocity	Compute the Nyquist velocity for Doppler radar.
compute_range_resolution	Compute the radar range resolution.
compute_snr	Compute signal-to-noise ratio (SNR).
doppler_frequency_shift	Compute Doppler frequency shift given radial velocity and wavelength.
radar_range	Compute maximum radar detection range using the radar range equation.
range_resolution	Alias for compute_range_resolution for compatibility.
round_trip_time	Compute round trip time for a given distance.
snr	Compute signal-to-noise ratio in linear scale.

Reflectivity-Based Retrievals

Functions for reflectivity-based rainfall estimation, attenuation correction, and reflectivity conversions. These functions are based on established meteorological principles and are commonly used in radar meteorology.

References: - Marshall, J. S., & Palmer, W. M. (1948). The distribution of raindrops with size. Journal of Meteorology, 5(4), 165-166. - Bringi, V. N., & Chandrasekar, V. (2001). Polarimetric Doppler Weather Radar: Principles and Applications. Cambridge University Press.

dbz_attenuation_correction	Simple attenuation correction using a power-law fit.
z_to_r_custom	Custom Z-R relation to estimate rain rate [mm/hr].
z_to_r_marshall_palmer	Estimate rain rate [mm/hr] from reflectivity [dBZ] using Marshall-Palmer Z-R relation.

Rayleigh Scattering Approximations

Functions for computing backscatter cross-sections, size parameters, and absorption, scattering, and extinction coefficients under Rayleigh scattering assumptions.

References

• Rinehart (1997). Radar for Meteorologists.

• Battan (1973). Radar Observations of the Atmosphere.

backscatter_cross_section	Rayleigh backscatter cross-section for a water sphere.
normalized_backscatter_cross_section	Normalize Rayleigh backscatter cross-section by projected area.
size_parameter	Calculate size parameter alpha = π * D / λ.
absorption_coefficient	Compute Rayleigh absorption coefficient.
scattering_coefficient	Compute Rayleigh scattering coefficient.
extinction_coefficient	Compute Rayleigh extinction coefficient (Qa + Qs).

Radar System Characteristics

Core functions related to radar system components like antenna gain, pulse parameters, wavelength/frequency conversion, and radar constants.

ant_eff_area(gain_dbi, wavelength)	Compute effective antenna area from gain and wavelength.
antenna_gain(p_beam, p_iso)	Compute antenna gain in dB from power ratio.
frequency(wavelength)	Alias for frequency_from_wavelength.
frequency_from_wavelength(wavelength)	Compute frequency from radar wavelength.
power_return_target(power_tx, gain_dbi, ...)	Compute received power from a radar target using the radar equation.
pulse_duration(pulse_length_val)	Alias for pulse_duration_from_length.
pulse_duration_from_length(pulse_length)	Compute pulse duration from physical pulse length.
pulse_length(pulse_duration)	Alias for pulse_length_from_duration.
pulse_length_from_duration(pulse_duration)	Compute physical pulse length from pulse duration.
radar_const(power_t, gain, tau, wavelength, ...)	Compute the radar constant (unitless).
radar_equation(pt, g_tx, g_rx, wavelength, ...)	Compute the received power using the radar range equation.
size_param(diameter, wavelength)	Compute size parameter alpha.
solve_peak_power(pr, g_tx, g_rx, wavelength, ...)	Solve for transmitter peak power using the radar equation.
wavelength(freq)	Alias for wavelength_from_frequency.
wavelength_from_frequency(freq)	Compute wavelength from radar frequency.

Timing Calculations

Functions for radar timing-related calculations: PRF, duty cycle, blind range, etc.

References

• Doviak, R. J., & Zrnić, D. S. (1993). Doppler Radar and Weather Observations. Academic Press.

compute_blind_range	Compute blind range (minimum detectable range) caused by transmission pulse.
compute_duty_cycle	Compute the duty cycle of the radar.
compute_max_unambiguous_range	Compute the maximum unambiguous range.
compute_max_unambiguous_velocity	Compute the maximum unambiguous velocity.
compute_prf	Compute Pulse Repetition Frequency (PRF).
compute_pulse_repetition_interval	Compute Pulse Repetition Interval (PRI) from PRF.

Radar-Derived Variables

Functions related to reflectivity, differential reflectivity, and radial velocity.

References

• Rinehart, R. E. (1997). Radar for Meteorologists.

• Doviak and Zrnic (1993). Doppler Radar and Weather Observations.

reflectivity_factor	Compute reflectivity factor Z [mm^6/m^3].
differential_reflectivity	Compute differential reflectivity ZDR [dB].
linear_depolarization_ratio	Compute linear depolarization ratio LDR [dB].
circular_depolarization_ratio	Compute circular depolarization ratio CDR [dB].
radial_velocity	Compute radial velocity from Doppler frequency shift.