# Propagation Models

Propagation models are used for inputting the information gather to predict the radio proapation. The models can be theoretical and empirical depending on the usecases.

## Thoretical Models

Theoretical model is a class which contains the functions for calculating propagation based on the theoretical radio propagation models.

- Initialization
- calculate_free_space_loss
- calculate_reflection_coefficient
- calculate_single_reflection_loss

### Initialization

#### input

- result: Object, a result object with contain the ray tracing information such as line of sight, tx and rx positions.

#### Example

The result from the ray tracer can be calculated by the propagation models in `radio_gyms.models`

.
In this example, `TheoreticalOutdoorModel`

can compute the traced results to predict the signal strength
and delay between the receiver and transmitter based on the theoretical radio propagation models.

```
from radio_gyms.models import TheoreticalOutdoorModel
result = {
'direct': False,
'reflections': {'single': [ [-28.94988531, 4.22886929, 62.39469675],
[-70.80339945, 7.04682531, 15.22840999]],
'double': []},
'roof_edges': [[-19.24403786, 8.5621709 , 28.8660568 ]],
'tx_pos': [ 0, 15, 0],
'rx_pos': [-30., 1.5, 45. ],
}
model = TheoreticalOutdoorModel(result, tx_power_dbm=20)
maximum_received_power = model.calculate_max_received_power(frequency=5.4e9)
# -72.51 dBm
impulses = model.calculate_signal_impulses(freq=5.4e9)
# [{'strength': -85.94590320344925, 'delay': 1.8653420787826134e-07},
# {'strength': -74.3214622218488, 'delay': 2.910702009034143e-07},
# {'strength': -77.80902883055407, 'delay': 4.125241781539828e-07}]
```

### calculate_free_space_loss(tx_pos, rx_pos, frequency, wave_speed)

#### input

- tx_pos: List, transmitting position.
- rx_pos: List, receiving position.
- frequency: float, frequency of radio wave.
- wave_speed: float, speed of propagating wave.

#### output

- free_space_loss: float, free space loss in dB.

### calculate_reflection_coefficient(tx_pos, rx_pos, ref_pos, tx_medium_permittivity,ref_medium_permittivity, polar)

#### input

- tx_pos: List, trasnmitting position.
- rx_pos: List, receiving position.
- ref_pos: List, reflecting position.
- tx_medium_permittivity: float, medium permitivity of the incident wave.
- ref_medium_permittivity: float, medium permitivity of the reflected wave.
- polar: str ('TM' or 'TE'), wave polarization at reflecting point.

#### output

- reflection_coefficient: float, reflection coefficient.

### calculate_single_reflection_loss(tx_pos, rx_pos, ref_pos, frequency, tx_medium_permittivity, ref_medium_permittivity,polar,wave_speed)

#### input

- tx_pos: List, trasnmitting position.
- rx_pos: List, receiving position.
- ref_pos: List, reflecting position.
- frequency: float, frequency of radio wave.
- tx_medium_permittivity: float, medium permitivity of the incident wave.
- ref_medium_permittivity: float, medium permitivity of the reflected wave.
- polar: str ('TM' or 'TE'), wave polarization at reflecting point.
- wave_speed: float, speed of propagating wave.

#### output

- reflection_loss: float, reflection loss in dB.

### calculate_double_reflection_loss(tx_pos, rx_pos, ref1_pos, ref2_pos, frequency, tx_medium_permittivity, ref_medium_permittivity, polar, wave_speed)

#### input

- tx_pos: List, trasnmitting position.
- rx_pos: List, receiving position.
- ref1_pos: List, first reflecting position.
- ref2_pos: List, second reflecting position.
- frequency: float, frequency of radio wave.
- tx_medium_permittivity: float, medium permitivity of the incident wave.
- ref_medium_permittivity: float, medium permitivity of the reflected wave.
- polar: str ('TM' or 'TE'), wave polarization at reflecting point.
- wave_speed: float, speed of propagating wave.

#### output

- reflection_loss: float, reflection loss in dB.

### calculate_knife_edge_diffraction(tx_pos, rx_pos, frequency, edges, wave_speed)

#### input

- tx_pos: List, trasnmitting position.
- rx_pos: List, receiving position.
- frequency: float, frequency of radio wave.
- edges: List[List], List of edge positions.
- wave_speed: float, speed of propagating wave.

#### output

- diffraction_loss: float, diffraction loss in dB.

### calculate_max_received_power(self, frequency: float = 2.4e9, wave_speed)

#### input

- frequency: float, frequency of radio wave.
- wave_speed: float, speed of propagating wave.

#### output

- max_receiving_power: float, expected maximum of receiving power in dBm

### calculate_signal_delay(tx_pos, rx_pos, points, wave_speed)

#### input

- tx_pos: List, trasnmitting position.
- rx_pos: List, receiving position.
- points: List[List], list of radio traveling positions.
- wave_speed: float, speed of propagating wave.

#### output

- delay: float, signal delay in second