Models¶

Core datamodels used throughout OpenSatCom — terminals, scenarios, link inputs/outputs, and RF chain parameters.

models ¶

Core datamodels for OpenSatCom.

Frozen dataclasses representing terminals, scenarios, link budget inputs/outputs, RF chain parameters, and world simulation state. All fields use SI units internally; dB-domain fields are explicitly named (e.g., eirp_dbw, cn0_dbhz).

Terminal `dataclass` ¶

Terminal(name, lat_deg, lon_deg, alt_m, system_noise_temp_k=None, misc=None)

Ground or space terminal.

Parameters:

Name	Type	Description	Default
`name`	`str`	Human-readable terminal identifier (e.g., `"GEO-Sat"`).	required
`lat_deg`	`float`	Geodetic latitude in degrees (positive north).	required
`lon_deg`	`float`	Geodetic longitude in degrees (positive east).	required
`alt_m`	`float`	Altitude above mean sea level in metres. For GEO satellites use `35_786_000.0`.	required
`system_noise_temp_k`	`float or None`	System noise temperature in Kelvin. Required for receive terminals.	`None`
`misc`	`dict or None`	Arbitrary metadata attached to the terminal.	`None`

Scenario `dataclass` ¶

Scenario(name, direction, freq_hz, bandwidth_hz, polarization, required_metric, required_value, rx_polarization=None, misc=None)

Link scenario definition.

Parameters:

Name	Type	Description	Default
`name`	`str`	Scenario identifier (e.g., `"Ku-DL"`).	required
`direction`	`str`	`"uplink"` or `"downlink"`.	required
`freq_hz`	`float`	Carrier frequency in Hz.	required
`bandwidth_hz`	`float`	Allocated bandwidth in Hz.	required
`polarization`	`str`	Polarization type: `"RHCP"`, `"LHCP"`, `"H"`, or `"V"`.	required
`required_metric`	`str`	Performance metric to evaluate: `"ebn0_db"`, `"cn0_dbhz"`, or `"throughput_mbps"`.	required
`required_value`	`float`	Minimum required value of the metric.	required
`misc`	`dict or None`	Arbitrary metadata.	`None`

PropagationConditions `dataclass` ¶

PropagationConditions(availability_target=None, rain_rate_mm_per_hr=None, climate_region=None, misc=None)

Environmental conditions affecting propagation.

Parameters:

Name	Type	Description	Default
`availability_target`	`float or None`	Link availability target as a fraction (e.g., `0.999` for 99.9 %).	`None`
`rain_rate_mm_per_hr`	`float or None`	Point rain rate exceeded at the availability target, in mm/h.	`None`
`climate_region`	`str or None`	ITU-R climate region letter (`"A"` through `"Q"`).	`None`
`misc`	`dict or None`	Arbitrary metadata.	`None`

ModCod `dataclass` ¶

ModCod(name, bits_per_symbol, code_rate, rolloff=0.2, pilot_overhead=0.0, impl_margin_db=0.0)

Modulation and coding scheme.

Parameters:

Name	Type	Description	Default
`name`	`str`	ModCod identifier (e.g., `"QPSK 1/2"`).	required
`bits_per_symbol`	`float`	Bits per symbol for the modulation (e.g., 2.0 for QPSK).	required
`code_rate`	`float`	FEC code rate as a fraction (e.g., 0.5 for rate-1/2).	required
`rolloff`	`float`	Root-raised-cosine rolloff factor (default 0.2).	`0.2`
`pilot_overhead`	`float`	Pilot symbol overhead as a fraction (default 0.0).	`0.0`
`impl_margin_db`	`float`	Implementation margin in dB (default 0.0).	`0.0`

net_spectral_eff_bps_per_hz ¶

net_spectral_eff_bps_per_hz()

Net spectral efficiency accounting for rolloff, pilots, and coding.

Returns:

Type	Description
`float`	Spectral efficiency in bps/Hz.

Source code in src/opensatcom/core/models.py

def net_spectral_eff_bps_per_hz(self) -> float:
    """Net spectral efficiency accounting for rolloff, pilots, and coding.

    Returns
    -------
    float
        Spectral efficiency in bps/Hz.
    """
    return (
        self.bits_per_symbol
        * self.code_rate
        * (1.0 - self.pilot_overhead)
        / (1.0 + self.rolloff)
    )

StateECEF `dataclass` ¶

StateECEF(t_s, r_m, v_mps=None)

Time-tagged satellite state in ECEF coordinates.

Parameters:

Name	Type	Description	Default
`t_s`	`float`	Epoch time in seconds since simulation start.	required
`r_m`	`ndarray`	Position vector in ECEF frame, shape `(3,)`, in metres.	required
`v_mps`	`ndarray or None`	Velocity vector in ECEF frame, shape `(3,)`, in m/s.	`None`

OpsPolicy `dataclass` ¶

OpsPolicy(min_elevation_deg=10.0, max_scan_deg=60.0, handover_hysteresis_s=5.0)

Operational policy constraints.

Parameters:

Name	Type	Description	Default
`min_elevation_deg`	`float`	Minimum elevation angle for link viability (default 10.0).	`10.0`
`max_scan_deg`	`float`	Maximum antenna scan angle from boresight (default 60.0).	`60.0`
`handover_hysteresis_s`	`float`	Minimum dwell time before handover in seconds (default 5.0).	`5.0`

LinkInputs `dataclass` ¶

LinkInputs(tx_terminal, rx_terminal, scenario, tx_antenna, rx_antenna, propagation, rf_chain, modem=None)

Inputs to a snapshot link budget evaluation.

Parameters:

Name	Type	Description	Default
`tx_terminal`	`Terminal`	Transmitting terminal (satellite for downlink).	required
`rx_terminal`	`Terminal`	Receiving terminal (ground station for downlink).	required
`scenario`	`Scenario`	Link scenario definition.	required
`tx_antenna`	`AntennaModel`	Transmit antenna model.	required
`rx_antenna`	`AntennaModel`	Receive antenna model.	required
`propagation`	`PropagationModel`	Propagation loss model (e.g., FSPL or composite).	required
`rf_chain`	`RFChainModel`	RF chain parameters.	required
`modem`	`ModemModel or None`	Optional modem model for throughput computation.	`None`

LinkOutputs `dataclass` ¶

LinkOutputs(eirp_dbw, gt_dbk, path_loss_db, cn0_dbhz, ebn0_db, margin_db, throughput_mbps=None, interference_dbw=None, sinr_db=None, breakdown=None)

Outputs from a snapshot link budget evaluation.

Parameters:

Name	Type	Description	Default
`eirp_dbw`	`float`	Effective isotropic radiated power in dBW.	required
`gt_dbk`	`float`	Receive figure of merit (G/T) in dB/K.	required
`path_loss_db`	`float`	Total propagation path loss in dB.	required
`cn0_dbhz`	`float`	Carrier-to-noise-density ratio in dB-Hz.	required
`ebn0_db`	`float`	Energy-per-bit to noise-density ratio in dB.	required
`margin_db`	`float`	Link margin above the required threshold in dB.	required
`throughput_mbps`	`float or None`	Achievable throughput in Mbps (when modem is enabled).	`None`
`interference_dbw`	`float or None`	Total interference power in dBW (multi-beam scenarios).	`None`
`sinr_db`	`float or None`	Signal-to-interference-plus-noise ratio in dB.	`None`
`breakdown`	`dict or None`	Itemised link budget breakdown (keys are parameter names, values in dB or dBW).	`None`

RFChainModel `dataclass` ¶

RFChainModel(tx_power_w, tx_losses_db, rx_noise_temp_k, misc=None)

RF chain parameters for TX and RX paths.

Parameters:

Name	Type	Description	Default
`tx_power_w`	`float`	Transmitter output power in watts.	required
`tx_losses_db`	`float`	Total transmit-side losses in dB (cables, filters, radome).	required
`rx_noise_temp_k`	`float`	Additional receive noise temperature contribution in Kelvin.	required
`misc`	`dict or None`	Arbitrary metadata.	`None`

effective_tx_power_w ¶

effective_tx_power_w()

TX power after losses, in watts.

Returns:

Type	Description
`float`	Effective transmit power in watts.

Source code in src/opensatcom/core/models.py

def effective_tx_power_w(self) -> float:
    """TX power after losses, in watts.

    Returns
    -------
    float
        Effective transmit power in watts.
    """
    from opensatcom.core.units import db10_to_lin

    return self.tx_power_w * db10_to_lin(-self.tx_losses_db)

effective_tx_power_dbw ¶

effective_tx_power_dbw()

TX power after losses, in dBW.

Returns:

Type	Description
`float`	Effective transmit power in dBW.

Source code in src/opensatcom/core/models.py

def effective_tx_power_dbw(self) -> float:
    """TX power after losses, in dBW.

    Returns
    -------
    float
        Effective transmit power in dBW.
    """
    from opensatcom.core.units import w_to_dbw

    return w_to_dbw(self.tx_power_w) - self.tx_losses_db

system_temp_k ¶

system_temp_k(base_temp_k)

Total system noise temperature.

Parameters:

Name	Type	Description	Default
`base_temp_k`	`float`	Antenna noise temperature in Kelvin.	required

Returns:

Type	Description
`float`	Combined system noise temperature in Kelvin.

Source code in src/opensatcom/core/models.py

def system_temp_k(self, base_temp_k: float) -> float:
    """Total system noise temperature.

    Parameters
    ----------
    base_temp_k : float
        Antenna noise temperature in Kelvin.

    Returns
    -------
    float
        Combined system noise temperature in Kelvin.
    """
    return base_temp_k + self.rx_noise_temp_k

WorldSimInputs `dataclass` ¶

WorldSimInputs(link_inputs, sat_traj, ops, env, t0_s, t1_s, dt_s)

Inputs to a world/mission simulation.

Parameters:

Name	Type	Description	Default
`link_inputs`	`LinkInputs`	Link budget configuration.	required
`sat_traj`	`TrajectoryProvider`	Satellite trajectory source.	required
`ops`	`OpsPolicy`	Operational policy constraints.	required
`env`	`EnvironmentProvider`	Time-varying propagation environment.	required
`t0_s`	`float`	Simulation start time in seconds.	required
`t1_s`	`float`	Simulation end time in seconds.	required
`dt_s`	`float`	Time step in seconds.	required

WorldSimOutputs `dataclass` ¶

WorldSimOutputs(times_s, elev_deg, range_m, margin_db, throughput_mbps, selected_modcod, outages_mask, summary, breakdown_timeseries=None, az_deg=None, doppler_hz=None)

Outputs from a world/mission simulation.

Parameters:

Name	Type	Description	Default
`times_s`	`ndarray`	Time stamps in seconds, shape `(N,)`.	required
`elev_deg`	`ndarray`	Elevation angles in degrees, shape `(N,)`.	required
`range_m`	`ndarray`	Slant ranges in metres, shape `(N,)`.	required
`margin_db`	`ndarray`	Link margin time series in dB, shape `(N,)`.	required
`throughput_mbps`	`ndarray or None`	Throughput time series in Mbps (when modem is enabled).	required
`selected_modcod`	`list of str or None`	Selected ModCod name at each time step.	required
`outages_mask`	`ndarray`	Boolean mask where `True` indicates an outage, shape `(N,)`.	required
`summary`	`dict`	Scalar summary metrics (e.g., `availability`, `margin_db_mean`).	required
`breakdown_timeseries`	`dict or None`	Per-parameter time series for detailed analysis.	`None`

Models¶

models ¶

Terminal dataclass ¶

Scenario dataclass ¶

PropagationConditions dataclass ¶

ModCod dataclass ¶

net_spectral_eff_bps_per_hz ¶

StateECEF dataclass ¶

OpsPolicy dataclass ¶

LinkInputs dataclass ¶

LinkOutputs dataclass ¶

RFChainModel dataclass ¶

effective_tx_power_w ¶

effective_tx_power_dbw ¶

system_temp_k ¶

WorldSimInputs dataclass ¶

WorldSimOutputs dataclass ¶

Terminal `dataclass` ¶

Scenario `dataclass` ¶

PropagationConditions `dataclass` ¶

ModCod `dataclass` ¶

StateECEF `dataclass` ¶

OpsPolicy `dataclass` ¶

LinkInputs `dataclass` ¶

LinkOutputs `dataclass` ¶

RFChainModel `dataclass` ¶

WorldSimInputs `dataclass` ¶

WorldSimOutputs `dataclass` ¶