Skip to content

Protocols

Protocol-based interfaces defining the public API contracts for OpenSatCom. All pluggable components implement these protocols.

protocols

Protocol definitions for OpenSatCom public interfaces.

All pluggable components implement these typing.Protocol interfaces. Use runtime_checkable protocols for isinstance checks at configuration time.

AntennaModel

Bases: Protocol

Interface for antenna gain models.

Implementations must provide gain_dbi (vectorised over angles) and eirp_dbw (scalar convenience for link budgets).

gain_dbi 

gain_dbi(theta_deg, phi_deg, f_hz)

Compute antenna gain over an array of directions.

Parameters:

Name Type Description Default
theta_deg ndarray

Elevation angles in degrees.

 required
phi_deg ndarray

Azimuth angles in degrees.

 required
f_hz float

Carrier frequency in Hz.

 required

Returns:

Type Description
ndarray

Gain values in dBi, same shape as theta_deg.
Source code in src/opensatcom/core/protocols.py 
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
def gain_dbi(
    self, theta_deg: np.ndarray, phi_deg: np.ndarray, f_hz: float
) -> np.ndarray:
    """Compute antenna gain over an array of directions.

    Parameters
    ----------
    theta_deg : numpy.ndarray
        Elevation angles in degrees.
    phi_deg : numpy.ndarray
        Azimuth angles in degrees.
    f_hz : float
        Carrier frequency in Hz.

    Returns
    -------
    numpy.ndarray
        Gain values in dBi, same shape as *theta_deg*.
    """
    ...

eirp_dbw 

eirp_dbw(theta_deg, phi_deg, f_hz, tx_power_w)

Compute EIRP toward a specific direction.

Parameters:

Name Type Description Default
theta_deg float

Elevation angle in degrees.

 required
phi_deg float

Azimuth angle in degrees.

 required
f_hz float

Carrier frequency in Hz.

 required
tx_power_w float

Transmit power in watts.

 required

Returns:

Type Description
float

EIRP in dBW.
Source code in src/opensatcom/core/protocols.py 
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
def eirp_dbw(
    self, theta_deg: float, phi_deg: float, f_hz: float, tx_power_w: float
) -> float:
    """Compute EIRP toward a specific direction.

    Parameters
    ----------
    theta_deg : float
        Elevation angle in degrees.
    phi_deg : float
        Azimuth angle in degrees.
    f_hz : float
        Carrier frequency in Hz.
    tx_power_w : float
        Transmit power in watts.

    Returns
    -------
    float
        EIRP in dBW.
    """
    ...

PropagationModel

Bases: Protocol

Interface for propagation loss models.

Implementations compute total one-way path loss in dB for a given frequency, geometry, and environmental conditions.

total_path_loss_db 

total_path_loss_db(f_hz, elev_deg, range_m, cond)

Compute total path loss.

Parameters:

Name Type Description Default
f_hz float

Carrier frequency in Hz.

 required
elev_deg float

Elevation angle in degrees.

 required
range_m float

Slant range in metres.

 required
cond PropagationConditions

Environmental conditions (rain, climate, availability).

 required

Returns:

Type Description
float

Total path loss in dB (positive value).
Source code in src/opensatcom/core/protocols.py 
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
def total_path_loss_db(
    self,
    f_hz: float,
    elev_deg: float,
    range_m: float,
    cond: PropagationConditions,
) -> float:
    """Compute total path loss.

    Parameters
    ----------
    f_hz : float
        Carrier frequency in Hz.
    elev_deg : float
        Elevation angle in degrees.
    range_m : float
        Slant range in metres.
    cond : PropagationConditions
        Environmental conditions (rain, climate, availability).

    Returns
    -------
    float
        Total path loss in dB (positive value).
    """
    ...

PerformanceCurve

Bases: Protocol

Interface for modem performance curves (Eb/N0 vs BLER).

Maps Eb/N0 to block error rate and vice versa for a given ModCod.

bler 

bler(ebn0_db)

Compute BLER at a given Eb/N0.

Parameters:

Name Type Description Default
ebn0_db float

Energy-per-bit to noise-density ratio in dB.

 required

Returns:

Type Description
float

Block error rate (0.0 to 1.0).
Source code in src/opensatcom/core/protocols.py 
120
121
122
123
124
125
126
127
128
129
130
131
132
133
def bler(self, ebn0_db: float) -> float:
    """Compute BLER at a given Eb/N0.

    Parameters
    ----------
    ebn0_db : float
        Energy-per-bit to noise-density ratio in dB.

    Returns
    -------
    float
        Block error rate (0.0 to 1.0).
    """
    ...

required_ebn0_db 

required_ebn0_db(target_bler)

Find the minimum Eb/N0 that achieves the target BLER.

Parameters:

Name Type Description Default
target_bler float

Desired block error rate threshold.

 required

Returns:

Type Description
float

Required Eb/N0 in dB.
Source code in src/opensatcom/core/protocols.py 
135
136
137
138
139
140
141
142
143
144
145
146
147
148
def required_ebn0_db(self, target_bler: float) -> float:
    """Find the minimum Eb/N0 that achieves the target BLER.

    Parameters
    ----------
    target_bler : float
        Desired block error rate threshold.

    Returns
    -------
    float
        Required Eb/N0 in dB.
    """
    ...

ACMPolicy

Bases: Protocol

Interface for adaptive coding and modulation selection.

Selects the best ModCod for current channel conditions, optionally with hysteresis to prevent rapid switching.

select_modcod 

select_modcod(ebn0_db, t_s)

Select a ModCod for the current Eb/N0 and time.

Parameters:

Name Type Description Default
ebn0_db float

Current Eb/N0 in dB.

 required
t_s float

Current simulation time in seconds.

 required

Returns:

Type Description
ModCod

Selected modulation and coding scheme.
Source code in src/opensatcom/core/protocols.py 
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
def select_modcod(self, ebn0_db: float, t_s: float) -> ModCod:
    """Select a ModCod for the current Eb/N0 and time.

    Parameters
    ----------
    ebn0_db : float
        Current Eb/N0 in dB.
    t_s : float
        Current simulation time in seconds.

    Returns
    -------
    ModCod
        Selected modulation and coding scheme.
    """
    ...

LinkEngine

Bases: Protocol

Interface for link budget evaluation.

Computes a full snapshot link budget from geometry and link parameters.

evaluate_snapshot 

evaluate_snapshot(elev_deg, az_deg, range_m, inputs, cond)

Evaluate a snapshot link budget.

Parameters:

Name Type Description Default
elev_deg float

Elevation angle in degrees.

 required
az_deg float

Azimuth angle in degrees.

 required
range_m float

Slant range in metres.

 required
inputs LinkInputs

Link configuration (terminals, antennas, propagation, RF chain).

 required
cond PropagationConditions

Environmental conditions.

 required

Returns:

Type Description
LinkOutputs

Complete link budget results.
Source code in src/opensatcom/core/protocols.py 
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
def evaluate_snapshot(
    self,
    elev_deg: float,
    az_deg: float,
    range_m: float,
    inputs: LinkInputs,
    cond: PropagationConditions,
) -> LinkOutputs:
    """Evaluate a snapshot link budget.

    Parameters
    ----------
    elev_deg : float
        Elevation angle in degrees.
    az_deg : float
        Azimuth angle in degrees.
    range_m : float
        Slant range in metres.
    inputs : LinkInputs
        Link configuration (terminals, antennas, propagation, RF chain).
    cond : PropagationConditions
        Environmental conditions.

    Returns
    -------
    LinkOutputs
        Complete link budget results.
    """
    ...

TrajectoryProvider

Bases: Protocol

Interface for satellite trajectory generation.

Provides time-tagged ECEF states for a satellite over a simulation window.

states_ecef 

states_ecef(t0_s, t1_s, dt_s)

Generate satellite states over a time window.

Parameters:

Name Type Description Default
t0_s float

Start time in seconds.

 required
t1_s float

End time in seconds.

 required
dt_s float

Time step in seconds.

 required

Returns:

Type Description
list of StateECEF

Satellite states at each time step.
Source code in src/opensatcom/core/protocols.py 
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
def states_ecef(
    self, t0_s: float, t1_s: float, dt_s: float
) -> list[StateECEF]:
    """Generate satellite states over a time window.

    Parameters
    ----------
    t0_s : float
        Start time in seconds.
    t1_s : float
        End time in seconds.
    dt_s : float
        Time step in seconds.

    Returns
    -------
    list of StateECEF
        Satellite states at each time step.
    """
    ...

EnvironmentProvider

Bases: Protocol

Interface for time-varying propagation conditions.

Returns propagation conditions that may vary with time and terminal locations.

conditions 

conditions(t_s, terminal_a, terminal_b)

Get propagation conditions at a given time and link geometry.

Parameters:

Name Type Description Default
t_s float

Simulation time in seconds.

 required
terminal_a Terminal

First terminal (typically satellite).

 required
terminal_b Terminal

Second terminal (typically ground station).

 required

Returns:

Type Description
PropagationConditions

Environmental conditions at this time step.
Source code in src/opensatcom/core/protocols.py 
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
def conditions(
    self, t_s: float, terminal_a: Terminal, terminal_b: Terminal
) -> PropagationConditions:
    """Get propagation conditions at a given time and link geometry.

    Parameters
    ----------
    t_s : float
        Simulation time in seconds.
    terminal_a : Terminal
        First terminal (typically satellite).
    terminal_b : Terminal
        Second terminal (typically ground station).

    Returns
    -------
    PropagationConditions
        Environmental conditions at this time step.
    """
    ...