Skip to content

Scenarios API

Scenario classes for defining operating conditions.

Overview

from phased_array_systems.scenarios import (
    ScenarioBase,
    CommsLinkScenario,
    RadarDetectionScenario,
)

Classes

ScenarioBase

Bases: BaseModel

Base class for all scenario types.

All scenarios must have a frequency, which is used to compute wavelength and other frequency-dependent parameters.

ATTRIBUTE DESCRIPTION
freq_hz

Operating frequency in Hz

TYPE: float

name

Optional name for the scenario

TYPE: str | None

wavelength_m property 

wavelength_m: float

Wavelength in meters.

freq_ghz property 

freq_ghz: float

Frequency in GHz.

CommsLinkScenario

Bases: ScenarioBase

Scenario for communications link budget analysis.

Defines the parameters needed for a point-to-point or satellite communications link budget calculation.

ATTRIBUTE DESCRIPTION
freq_hz

Operating frequency (Hz)

TYPE: float

bandwidth_hz

Signal bandwidth (Hz)

TYPE: float

range_m

Link range/distance (meters)

TYPE: float

required_snr_db

Required SNR for demodulation (dB)

TYPE: float

scan_angle_deg

Beam scan angle from boresight (degrees)

TYPE: float

rx_antenna_gain_db

Receive antenna gain (dB), None for isotropic

TYPE: float | None

rx_noise_temp_k

Receive system noise temperature (K)

TYPE: float

path_loss_model

Propagation model to use

TYPE: Literal['fspl', 'two_ray', 'log_distance']

path_loss_exponent

Path loss exponent for log-distance model

TYPE: float

rain_rate_mmh

Rain rate for rain attenuation (mm/hr)

TYPE: float

elevation_deg

Link elevation angle for atmospheric model (degrees)

TYPE: float

atmospheric_loss_db

Additional atmospheric losses (dB)

TYPE: float

rain_loss_db

Rain fade margin (dB)

TYPE: float

polarization_loss_db

Polarization mismatch loss (dB)

TYPE: float

total_extra_loss_db property 

total_extra_loss_db: float

Total additional losses beyond free space path loss.

RadarDetectionScenario

Bases: ScenarioBase

Scenario for radar detection analysis.

Defines the operating conditions for monostatic radar detection, including target characteristics, detection requirements, pulse integration parameters, clutter environment, and propagation effects.

ATTRIBUTE DESCRIPTION
freq_hz

Operating frequency (Hz)

TYPE: float

bandwidth_hz

Signal bandwidth (Hz)

TYPE: float

range_m

Target range (meters)

TYPE: float

target_rcs_dbsm

Target radar cross section (dBsm)

TYPE: float

rx_noise_temp_k

Receiver noise temperature (K)

TYPE: float

pfa

Probability of false alarm

TYPE: float

pd_required

Required probability of detection

TYPE: float

n_pulses

Number of pulses integrated

TYPE: int

scan_angle_deg

Beam scan angle from boresight (degrees)

TYPE: float

integration_type

Coherent or non-coherent integration

TYPE: Literal['coherent', 'noncoherent']

clutter_type

Type of clutter environment

TYPE: ClutterType

sea_state

Sea state for sea clutter (0-6 Douglas scale)

TYPE: int

terrain_type

Terrain type for ground clutter

TYPE: TerrainType

rain_rate_mm_hr

Rain rate for rain clutter/attenuation

TYPE: float

grazing_angle_deg

Grazing angle for clutter calculations

TYPE: float | None

antenna_height_m

Antenna height above surface

TYPE: float

target_height_m

Target height above surface

TYPE: float

polarization

Antenna polarization

TYPE: PolarizationType

cfar_type

CFAR detector type

TYPE: CFARType

cfar_ref_cells

Number of CFAR reference cells

TYPE: int

cfar_guard_cells

Number of CFAR guard cells

TYPE: int

include_atmos_loss

Include atmospheric attenuation

TYPE: bool

temperature_c

Ambient temperature for atmos model

TYPE: float

humidity_pct

Relative humidity for atmos model

TYPE: float

wavelength_m property 

wavelength_m: float

Wavelength in meters.

target_rcs_m2 property 

target_rcs_m2: float

Target RCS in square meters.

range_resolution_m property 

range_resolution_m: float

Range resolution in meters (c / 2B).

Usage Examples

Communications Scenario

from phased_array_systems.scenarios import CommsLinkScenario

# Point-to-point link
scenario = CommsLinkScenario(
    freq_hz=10e9,
    bandwidth_hz=10e6,
    range_m=100e3,
    required_snr_db=10.0,
    scan_angle_deg=0.0,
    rx_antenna_gain_db=30.0,
    rx_noise_temp_k=290.0,
)

print(f"Wavelength: {scenario.wavelength_m * 100:.2f} cm")
print(f"Total extra loss: {scenario.total_extra_loss_db:.1f} dB")

Radar Scenario

from phased_array_systems.scenarios import RadarDetectionScenario

scenario = RadarDetectionScenario(
    freq_hz=10e9,
    target_rcs_m2=1.0,
    range_m=100e3,
    required_pd=0.9,
    pfa=1e-6,
    pulse_width_s=10e-6,
    prf_hz=1000,
    n_pulses=10,
    integration_type="coherent",
    swerling_model=1,
)

geo_scenario = CommsLinkScenario(
    freq_hz=12e9,
    bandwidth_hz=36e6,
    range_m=36000e3,
    required_snr_db=8.0,
    rx_antenna_gain_db=45.0,
    rx_noise_temp_k=80.0,
    atmospheric_loss_db=0.3,
    rain_loss_db=5.0,
)

See Also