itmlogic - Longley-Rice Irregular Terrain Model

https://itmlogic.readthedocs.io/en/latest/
Admin
Python implementation of the Longley-Rice Irregular Terrain Model for radio propagation prediction...
Tokens:26,174
Snippets:150
Trust Score:9.6
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install for Development

Source: https://itmlogic.readthedocs.io/en/latest/_sources/index.rst.txt

Clone the repository and run this command to install the itmlogic package in development mode.

```bash
python setup.py develop
```

--------------------------------

### Run Multi-Tile Example Script

Source: https://itmlogic.readthedocs.io/en/latest/getting-started.html

Execute the Python script designed to handle radio propagation scenarios spanning more than one coverage tile.

```python
python scripts/p2p_2tiles.py

```

--------------------------------

### Run P2P Example Script (Multiple Tiles)

Source: https://itmlogic.readthedocs.io/en/latest/_sources/getting-started.rst.txt

Execute a script designed to handle point-to-point propagation scenarios that span more than one coverage tile. This is a command-line operation.

```python
python scripts/p2p_2tiles.py
```

--------------------------------

### Install Optional Conda Packages

Source: https://itmlogic.readthedocs.io/en/latest/_sources/index.rst.txt

Install additional optional packages for the 'itmlogic' conda environment, including scientific and geospatial libraries.

```bash
conda install numpy fiona shapely rtree rasterio pyproj tqdm pytest
```

--------------------------------

### Example Terrain Elevation Values

Source: https://itmlogic.readthedocs.io/en/latest/_sources/getting-started.rst.txt

A sample list representing terrain elevation values in meters obtained from the terrain profile calculation.

```python
measured_terrain_profile = [
    109, 66, 28, 48, 29, 32, 29, 20, 13, 9...
]
```

--------------------------------

### Ascat Function Implementation

Source: https://itmlogic.readthedocs.io/en/latest/_modules/itmlogic/scatter_attenuation/ascat.html

Calculates scatter attenuation using an approximation to NBS TN101 methods. Handles initial constant setup when distance d is 0. Requires propagation parameters in the 'prop' dictionary.

```python
import math
import numpy as np
from itmlogic.scatter_attenuation.h0f import h0f
from itmlogic.scatter_attenuation.ahd import ahd


def ascat(d, prop):
    """
    Finds the scatter attenuation at the distance d using an approximation to the methods of
    NBS TN101 with checks for inadmissable situations (Eqn 4.63 of "The ITS Irregular Terrain
    Model, version 1.2.2: The Algorithm"). A call with d = 0 set up initial constants.

    Parameters
    ----------
    d : float
        Distance in meters.
    prop : dict
        Contains all input propagation parameters

    Returns
    -------
    prop : dict
        Contains all input and output propagation parameters.

    """
    if prop['h0s'] > 15:
        h0 = prop['h0s']

    else:
        th = prop['the'][0] + prop['the'][1] + d * prop['gme']
        r2 = 2 * prop['wn'] * th

        r1 = r2 * prop['he'][0]
        r2 = r2 * prop['he'][1]

        if r1 < 0.2 and r2 < 0.2:
            prop['ascat1'] = 1001

        ss = (d - prop['ad']) / (d + prop['ad'])

        q = prop['rr'] / ss
        ss = max(0.1, ss)
        q = min(max(0.1, q), 10)
        z0 = (d - prop['ad']) * (d + prop['ad']) * th * 0.25 / d

        et = (prop['etq'] * math.exp(-min(1.7, z0 / 8.0e3)**6) + 1) * z0 / 1.7556e3

        ett = max(et, 1)

        h0 = (h0f(r1, ett) + h0f(r2, ett)) * 0.5

        h0 = h0 + min(h0, (1.38 - np.log(ett)) * np.log(ss) * np.log(q) * 0.49)

        h0 = max(h0, 0)

        if et < 1:
            h0 = (
                et * h0 + (1 - et) * 4.343 * np.log(((1 + 1.4142 / r1) *
                (1 + 1.4142 / r2))**2 * (r1 + r2) / (r1 + r2 + 2.8284))
            )

        if h0 > 15 and prop['h0s'] >= 0:
            h0 = prop['h0s']

        if prop['ascat1'] != 1001:

            prop['h0s'] = h0

    th = prop['tha'] + d * prop['gme']

    prop['ascat1'] = (
        ahd(th*d) + 4.343 * np.log(47.7 * prop['wn'] * th**4) -
        0.1 * (prop['ens'] - 301) * math.exp(-th * d / 40e3) + h0
        )

    return prop

```

--------------------------------

### Create Conda Environment

Source: https://itmlogic.readthedocs.io/en/latest/index.html

Use this command to create a new conda environment named 'itmlogic' with Python 3.7 and the GDAL library installed. This is the recommended first step for setting up the project.

```bash
conda create --name itmlogic python=3.7 gdal

```

--------------------------------

### Get Terrain Profile

Source: https://itmlogic.readthedocs.io/en/latest/_sources/getting-started.rst.txt

Use the `terrain_p2p` function to obtain the terrain profile over a specified line. Requires a digital elevation model folder and the line feature.

```python
measured_terrain_profile, distance_km, points = terrain_p2p(
    dem_folder, line
)
```

--------------------------------

### Example Area Prediction Output Structure

Source: https://itmlogic.readthedocs.io/en/latest/_sources/getting-started.rst.txt

The output from itmlogic_area is a list of dictionaries, each containing distance in kilometers, confidence level in percent, and estimated propagation loss in decibels.

```python
output = [
    {
        'distance_km': 10,
        'confidence_level_%': 50,
        'propagation_loss_dB': 111.6920084
    },
    {
        'distance_km': 10,
        'confidence_level_%': 90,
        'propagation_loss_dB': 121.5943795
    },
    ...
]
```

--------------------------------

### Example Area Prediction Output

Source: https://itmlogic.readthedocs.io/en/latest/getting-started.html

The output from itmlogic_area is a list of dictionaries, each containing distance, confidence level, and propagation loss. This data is typically written to a CSV file.

```python
output = [
    {
        'distance_km': 10,
        'confidence_level_%': 50,
        'propagation_loss_dB': 111.6920084
    },
    {
        'distance_km': 10,
        'confidence_level_%': 90,
        'propagation_loss_dB': 121.5943795
    },
    ...
]

```

--------------------------------

### Get Terrain Profile

Source: https://itmlogic.readthedocs.io/en/latest/getting-started.html

Use the `terrain_p2p` function to obtain the terrain profile and distance data for the specified line feature.

```python
measured_terrain_profile, distance_km, points = terrain_p2p(
    dem_folder, line
)

```

--------------------------------

### Initialize Diffraction Parameters

Source: https://itmlogic.readthedocs.io/en/latest/_modules/itmlogic/diffraction_attenuation/adiff.html

Sets up initial constants and parameters for diffraction attenuation calculations when the distance is zero. This includes calculating intermediate values based on ground height, median height, and other propagation properties.

```python
import math
import numpy as np

from itmlogic.diffraction_attenuation.aknfe import aknfe
from itmlogic.diffraction_attenuation.fht import fht


[docs]
def adiff(d, prop):
    """
    Returns adiff1 given input parameters. All parameters may not be needed.

    The diffraction region is beyond the smooth-earth horizon and short of where troposhpheric
    scatter takes over. It is an essential region and associated coefficients must be computed.

    The function adiff finds the 'diffraction attenuation' at the distance d, using a convex
    combination of smooth earth diffraction and double knife-edge diffraction (Eqn 4.11 of
    "The ITS Irregular Terrain Model, version 1.2.2: The Algorithm"). A call with d = 0 sets
    up initial constants.

    Parameters
    ----------
    d : float
        Distance in meters.
    prop : dict
        Contains all input propagation parameters

    Returns
    -------
    adiff1 : float
        Returns the estimated diffraction attenuation.
    prop : dict
        Contains all input and output propagation parameters.

    """
    third = 1 / 3

    if d == 0:
        q = prop['hg'][0] * prop['hg'][1]

        prop['qk'] = prop['he'][0] * prop['he'][1] - q

        if prop['mdp'] < 0:
            q = q + 10

        prop['wd1'] = math.sqrt(1 + prop['qk'] / q)
        prop['xd1'] = prop['dla'] + prop['tha'] / prop['gme']

        q = (1 - 0.8 * math.exp(-prop['dlsa'] / 50e3)) * prop['dh']
        q = 0.78 * q * math.exp(-(q / 16) ** 0.25)

        prop['afo'] = (
            min(15, 2.171 * np.log(1 + 4.77e-4 * prop['hg'][0]
            * prop['hg'][1] * prop['wn'] * q))
            )

        prop['qk'] = 1 / abs(prop['zgnd'])
        prop['aht'] = 20
        prop['xht'] = 0

        for j in range(0, 2):
            a = 0.5 * prop['dl'][j] ** 2 / prop['he'][j]
            wa = (a * prop['wn']) ** third
            pk = prop['qk'] / wa

            q = (1.607 - pk) * 151.0 * wa * prop['dl'][j] / a

            prop['xht'] = prop['xht'] + q
            prop['aht'] = prop['aht'] + fht(q, pk)

        adiff1 = 0

    else:

        th = prop['tha'] + d * prop['gme']

        ds = d - prop['dla']

        q = 0.0795775 * prop['wn'] * ds * th**2

        adiff1 = aknfe(q * prop['dl'][0] /
            (ds + prop['dl'][0])) + aknfe(q * prop['dl'][1] /
            (ds + prop['dl'][1]))

        a = ds / th
        wa = (a * prop['wn']) ** third

        pk = prop['qk'] / wa

        q = (1.607 - pk) * 151.0 * wa * th + prop['xht']

        ar = 0.05751 * q - 4.343 * np.log(q) - prop['aht']

        q = (
            (prop['wd1'] + prop['xd1'] / d) *
            min(((1 - 0.8 * math.exp(-d / 50e3)) *
            prop['dh'] * prop['wn']), 6283.2)
            )

        wd = 25.1 / (25.1 + math.sqrt(q))

        adiff1 = ar * wd + (1 - wd) * adiff1 + prop['afo']

    return adiff1, prop
```

--------------------------------

### qlrps

Source: https://itmlogic.readthedocs.io/en/latest/api/itmlogic.preparatory_subroutines.html

A general preparatory subroutine as described in Section 41 by Hufford. It takes various propagation and system parameters as input.

```APIDOC
## qlrps

### Description
General preparatory subroutine as in Section 41 by Hufford (see references/itm.pdf).

### Parameters
* **fmhz** (int) - Required - Carrier frequency.
* **en0** - Required - Surface refractivity reduced to sea level.
* **zsysz** - Required - General system elevation.
* **eps** - Required - Polarization.
* **sgm** - Required - Ground constants.
* **wn** - Required - Wave number
* **ens** - Required - Surface refractivity.
* **gme** - Required - Effective earth curvature.
* **zgnd** - Required - Ground constants.
```

--------------------------------

### qlrpfl

Source: https://itmlogic.readthedocs.io/en/latest/api/itmlogic.preparatory_subroutines.html

Preparatory subroutine for point-to-point mode, used in Section 43 by Hufford. It processes input propagation parameters and returns updated parameters.

```APIDOC
## qlrpfl

### Description
Preparatory subroutine for point-to-point mode, as in Section 43 by Hufford (see references/itm.pdf).

### Parameters
* **prop** (dict) - Required - Contains all input propagation parameters.

### Returns
* **prop** (dict) - Contains all input and output propagation parameters.
```

--------------------------------

### Activate Conda Environment

Source: https://itmlogic.readthedocs.io/en/latest/_sources/index.rst.txt

Run this command each time you switch to the 'itmlogic' project to activate its conda environment.

```bash
conda activate itmlogic
```

--------------------------------

### Run Tests

Source: https://itmlogic.readthedocs.io/en/latest/_sources/index.rst.txt

Execute the test suite for the itmlogic package using pytest.

```bash
python -m pytest
```

--------------------------------

### zlsq1

Source: https://itmlogic.readthedocs.io/en/latest/api/itmlogic.preparatory_subroutines.html

Performs a linear least squares fit to an input function (terrain profile) between two horizontal locations. It returns interpolated heights at the start and end of the profile segment.

```APIDOC
## zlsq1

### Description
A linear least squares fit between x1 and x2, to the function described by the array z. Evaluates a least squares fit to an input function z (in the form of a terrain profile having first element the number of profile samples, second element the spacing between them, and third through end elements the profile data) between horizontal locations x1 and x2. Returns the interpolated heights at location 0 and the end of the profile.

### Parameters
* **z** (list) - Required - Terrain profile in meters.
* **x1** (float) - Required - Location 1.
* **x2** (float) - Required - Location 2.

### Returns
* **z0** (float) - Interpolated height.
* **zn** (float) - Interpolated height.
```

--------------------------------

### P2P Path Loss Results

Source: https://itmlogic.readthedocs.io/en/latest/_sources/getting-started.rst.txt

The `output` is a list of dictionaries containing path loss results for different reliability and confidence levels, including distance, reliability percentage, confidence percentage, and propagation loss in dB.

```python
output = [
    {
        'distance_km': 77.8,
        'reliability_level_%': 1,
        'confidence_level_%': 50,
        'propagation_loss_dB': 128.5969039310673
    },
    {
        'distance_km': 77.8,
        'reliability_level_%': 1,
        'confidence_level_%': 90,
        'propagation_loss_dB': 137.64279211442656
    },
    ...
]
```

--------------------------------

### Linear Least Squares Fit to Terrain Profile

Source: https://itmlogic.readthedocs.io/en/latest/_modules/itmlogic/preparatory_subroutines/zlsq1.html

Performs a linear least squares fit to a terrain profile z between locations x1 and x2. Returns interpolated heights at the start and end of the profile. Ensure z is formatted correctly with sample count, spacing, and profile data.

```python
def zlsq1(z, x1, x2):
    """
    A linear least squares fit between x1 and x2, to the function described
    by the array z.

    Evaluates a least squares fit to an input function z (in the form of a terrain profile
    having first element the number of profile samples, second element the spacing between
    them, and third through end elements the profile data) between horizontal locations
    x1 and x2.  Returns the interpolated heights at location 0 and the end of the
    profile.

    Parameters
    ----------
    z : list
        Terrain profile in meters.
    x1 : float
        Location 1.
    x2 : float
        Location 2.

    Returns
    -------
    z0 : float
        Interpolated height.
    zn : float
        Interpolated height.

    """
    xn  = z[0]

    xa  = int(max(x1 / z[1], 0))
    xb  = xn - int(max(xn - x2 / z[1], 0))

    if xb <= xa:
        xa = max(xa - 1, 0)
        xb = xn - max(xn - xb + 1, 0)

    ja = xa
    jb = xb
    n  = jb - ja
    xa = xb - xa
    x  = -0.5 * xa
    xb = xb + x

    a  = 0.5 * (z[(ja + 2)] + z[jb + 2])
    b  = 0.5 * (z[ja + 2] - z[jb + 2]) * x

    for i in range(2, n+1):
        ja = ja + 1
        x  = x + 1
        a  = a + z[ja + 2]
        b  = b + z[ja + 2] * x

    a = avoid_zero_division(a, xa)
    b = b * 12 / ((xa * xa + 2) * xa)

    z0 = a - b * xb
    zn = a + (b * (xn - xb))

    return z0, zn

```

--------------------------------

### Run Area Prediction Script (Multiple Tiles)

Source: https://itmlogic.readthedocs.io/en/latest/_sources/getting-started.rst.txt

Execute the script designed for area prediction that spans more than one coverage tile.

```bash
python scripts/area_2tiles.py
```

--------------------------------

### Calculate Attenuation Quantiles with avar

Source: https://itmlogic.readthedocs.io/en/latest/api/itmlogic.statistics.html

Use the avar function to find quantiles of attenuation based on standard normal deviates and propagation parameters. It's efficient for area prediction mode.

```python
itmlogic.statistics.avar.avar(zzt, zzl, zzc, prop)
```

--------------------------------

### Horizon Parameters Calculation

Source: https://itmlogic.readthedocs.io/en/latest/_modules/itmlogic/preparatory_subroutines/hzns.html

Calculates horizon take-off angles and distances using terrain profile data. This subroutine is based on the method described by Hufford.

```python
def hzns(pfl, dist, hg, gme):
    """
    Subroutine to find horizon parameters as described in Section 48 by Hufford
    (see references/itm.pdf).

    Parameters
    ----------
    pfl : List
        Terrain profile in meters.
    dist : float
        Distance in meters.
    hg : list
        Heights of transmitter and receiver off ground (meters).
    gme : float
        Effective earth curvature.

    Returns
    -------
    the : dict
        Horizon take-off angle.
    dl : dict
        Horizon distances.

    """
    the = {}
    dl = {}

    np = pfl[0]
    xi = pfl[1]
    za = pfl[2] + hg[0]
    zb = pfl[np + 2] + hg[1]
    qc = 0.5 * gme
    q = qc * dist
    the[1] = (zb - za) / dist
    the[0] = the[1] - q
    the[1] = -the[1] - q
    dl[0]  = dist
    dl[1]  = dist

    if np >= 2:
        sa = 0
        sb = dist
        wq = 1

        for i in range(2, np + 1):

            sa = sa + xi
            sb = sb - xi

            q = pfl[i+1] - (qc * sa + the[0]) * sa - za

            if q > 0:
                the[0] = the[0] + q / sa
                dl[0] = sa

                wq = 0

            if wq == 0:
                q = pfl[i + 1] - (qc * sb + the[1]) * sb - zb
                if q > 0:
                    the[1] = the[1] + q / sb
                    dl[1] = sb

    return the, dl

```

--------------------------------

### Create Conda Environment

Source: https://itmlogic.readthedocs.io/en/latest/_sources/index.rst.txt

Use this command to create a new conda environment named 'itmlogic' with Python 3.7 and the GDAL library.

```bash
conda create --name itmlogic python=3.7 gdal
```

--------------------------------

### Estimate Terrain Irregularity Parameter (TIP)

Source: https://itmlogic.readthedocs.io/en/latest/_sources/getting-started.rst.txt

Import and use the terrain_area function to calculate the Terrain Irregularity Parameter (tip) for a given Digital Elevation Model (DEM) path and cell range.

```python
tip = terrain_area(dem_path, tx_coordinate_0, tx_coordinate_1, cell_range)
```

--------------------------------

### qlrps Subroutine Implementation

Source: https://itmlogic.readthedocs.io/en/latest/_modules/itmlogic/preparatory_subroutines/qlrps.html

This Python function calculates wave number, effective earth curvature, surface refractivity, and ground impedance. It is used for general radio wave propagation preparatory calculations.

```python
import cmath
import math


[docs]
def qlrps(fmhz, zsys, en0, ipol, eps, sgm):
    """
    General preparatory subroutine as in Section 41 by Hufford (see references/itm.pdf).

    Parameters
    ----------
    fmhz : int
        Carrier frequency.
    en0 :
        Surface refractivity reduced to sea level.
    zsysz :
        General system elevation.
    eps :
        Polarization.
    sgm :
        Ground constants.
    wn :
        Wave number
    ens :
        Surface refractivity.
    gme :
        Effective earth curvature.
    zgnd :
        Surface impedance.

    """
    gma = 157e-9
    wn = fmhz / 47.7
    ens = en0

    if zsys != 0:
        ens = ens * math.exp(-zsys / 9460)

    gme = gma * (1 - 0.04665 * math.exp(ens / 179.3))

    zq = complex(eps, 376.62 * sgm / wn)

    zgnd = cmath.sqrt(zq - 1)

    if ipol != 0:

        zgnd = zgnd / zq

    return wn, gme, ens, zgnd

```

--------------------------------

### qlra Function Definition

Source: https://itmlogic.readthedocs.io/en/latest/_modules/itmlogic/preparatory_subroutines/qlra.html

Defines the qlra function which calculates preparatory parameters for area prediction mode. It takes siting criteria (kst) and propagation parameters (prop) as input and returns updated propagation parameters.

```python
import math
import numpy as np


[docs]
def qlra(kst, prop):
    """
    Preparatory subroutine for area prediction mode, as described in equations (3.1)-(3.4)
    of "The ITS Irregular Terrain Model, version 1.2.2: The Algorithm" and as a function of
    the siting criteria for the transmit and receive terminals described using 2 element
    array KST (0=random, 1= "with care", 2= "with great care").

    Parameters
    ----------
    kst : list
        Siting criteria for the transmitter and receiver.
    prop : dict
        Contains all input propagation parameters.

    Returns
    -------
    prop : dict
        Contains all input and output propagation parameters.

    """
    prop['he'] = [0, 0]
    prop['dl'] = [0, 0]
    prop['the'] = [0, 0]

    for j in range(0, 2):

        if kst[j] <= 0:

            prop['he'][j] = prop['hg'][j]
        else:
            q = 4

            if kst[j] != 1:
                q = 9

            if prop['hg'][j] < 5:
                q = q * math.sin(0.3141593 * prop['hg'][j])

            prop['he'][j] = (
                prop['hg'][j] + (1 + q) *
                math.exp(-min(20, 2 * prop['hg'][j] / max(1e-3, prop['dh'])))
                )

        q = np.sqrt(2 * prop['he'][j] / prop['gme'])

        prop['dl'][j] = (
            q * math.exp(-0.07 * np.sqrt(prop['dh'] /
            max(prop['he'][j], 5)))
            )

        prop['the'][j] = (
            (0.65 * prop['dh'] * (q / prop['dl'][j] - 1) -
            2 * prop['he'][j]) / q
            )

    prop['mdp'] = 1
    prop['lvar'] = max(prop['lvar'], 3)

    if prop['mdvarx'] >= 0:
        prop['mdvar'] = prop['mdvarx']
        prop['lvar'] = max(prop['lvar'], 4)

    if prop['klimx'] > 0:
        prop['klim'] = prop['klimx']
        prop['lvar'] = 5

    return prop

```

--------------------------------

### Path Loss Results

Source: https://itmlogic.readthedocs.io/en/latest/getting-started.html

The `output` variable contains a list of dictionaries, each detailing path loss at specific reliability and confidence levels over the link distance.

```python
output = [
    {
        'distance_km': 77.8,
        'reliability_level_%': 1,
        'confidence_level_%': 50,
        'propagation_loss_dB': 128.5969039310673
    },
    {
        'distance_km': 77.8,
        'reliability_level_%': 1,
        'confidence_level_%': 90,
        'propagation_loss_dB': 137.64279211442656
    },
    ...
]

```

--------------------------------

### qlrpfl Function Definition

Source: https://itmlogic.readthedocs.io/en/latest/_modules/itmlogic/preparatory_subroutines/qlrpfl.html

Defines the qlrpfl subroutine for point-to-point mode propagation. It takes a dictionary of propagation parameters and returns the updated dictionary.

```python
import math
from itmlogic.preparatory_subroutines.hzns import hzns
from itmlogic.preparatory_subroutines.dlthx import dlthx
from itmlogic.preparatory_subroutines.zlsq1 import zlsq1
from itmlogic.lrprop import lrprop


[docs]def qlrpfl(prop):
    """
    Preparatory subroutine for point-to-point mode, as in Section 43 by Hufford
    (see references/itm.pdf).

    Parameters
    ----------
    prop : dict
        Contains all input propagation parameters.

    Returns
    -------
    prop : dict
        Contains all input and output propagation parameters.

    """
    prop['dist'] = prop['pfl'][0] * prop['pfl'][1]

    np = prop['pfl'][0]

    prop['the'], prop['dl'] = (
        hzns(prop['pfl'], prop['dist'], prop['hg'], prop['gme'])
        )

    xl = {}
    for j in range(0,2):
        xl[j] = min(15 * prop['hg'][j], 0.1 * prop['dl'][j])

    xl[1] = prop['dist'] - xl[1]

    prop['dh'] = dlthx(prop['pfl'], xl[0], xl[1])

    if prop['dl'][0] + prop['dl'][1] >= 1.5 * prop['dist']:
        prop['he'] = []
        za, zb = zlsq1(prop['pfl'], xl[0], xl[1])
        prop['he'].append(prop['hg'][0] + max(prop['pfl'][2] - za, 0))
        prop['he'].append(prop['hg'][1] + max(prop['pfl'][np+1] - zb, 0))

        for j in range(1, 2):
            prop['dl'][j] = (
                math.sqrt(2 *prop['he'][j] / prop['gme']) *
                math.exp(-0.07 * math.sqrt(prop['dh'] / max(prop['he'][j], 5)))
                )

        q = prop['dl'][0] + prop['dl'][1]

        if q <= prop['dist']:
            q = (prop['dist'] / q)**2
            for j in range(1, 2):
                prop['he'][j] = prop['he'][j] * q
                prop['dl'][j] = (
                    math.sqrt(2 * prop['he'][j] / prop['gme']) *
                    math.exp(-0.07 * math.sqrt(prop['dh'] / max(prop['he'][j], 5)))
                )

        for j in range(0,2):
            q = math.sqrt(2 * prop['he'][j] / prop['gme'])
            prop['the'][j] = (
                (0.65 * prop['dh'] * (q / prop['dl'][j] - 1) -
                2 *
                prop['he'][j]) / q
                )
    else:
        za, q = zlsq1(prop['pfl'], xl[0], 0.9 * prop['dl'][0])

        q, zb = zlsq1(prop['pfl'], prop['dist'] - 0.9 * prop['dl'][1], xl[1])

        prop['he'] = []
        prop['he'].append(prop['hg'][0] + max(prop['pfl'][2] - za, 0))
        prop['he'].append(prop['hg'][1] + max(prop['pfl'][np+2] - zb, 0))

    prop['mdp'] = -1
    prop['lvar'] = max(prop['lvar'], 3)

    if prop['mdvarx'] >= 0:
        prop['mdvar'] = prop['mdvarx']
        prop['lvar'] = max(prop['lvar'], 4)

    if prop['klimx'] > 0:
        prop['klim'] = prop['klimx']
        prop['lvar'] = 5

    prop = lrprop(0, prop)

    return prop

```

--------------------------------

### qtile Function Implementation

Source: https://itmlogic.readthedocs.io/en/latest/_modules/itmlogic/misc/qtile.html

This function takes a list 'a' and an index 'ir' to return the element at that index after sorting the list in descending order. It's useful for directly accessing a specific percentile value when the list is already sorted.

```python
import numpy as np


[docs]
def qtile(a, ir):
    """
    This routine returns the ith entry of vector after sorting in
    descending order.

    Parameters
    ----------
    a : list
        Input data distribution.
    ir : int
        Desired percentile.

    Returns
    -------
    qtile : float
        Percentile value.

    """
    as_sorted = sorted(a, reverse=True)
    qtile1 = as_sorted[ir]

    return qtile1


```

--------------------------------

### qerfi

Source: https://itmlogic.readthedocs.io/en/latest/api/itmlogic.misc.html

Computes the inverse of the qerf function, solving for x in q = Q(x). The approximation is by Hastings, Jr. (1995) with a maximum error of 4.5x10^-4.

```APIDOC
## qerfi

### Description
Computes the inverse of the qerf function, solving for x in q = Q(x). The approximation is by Hastings, Jr. (1995) with a maximum error of 4.5x10^-4.

### Parameters
#### Path Parameters
- **q** (list of float) - Required - Confidence levels for predictions (e.g. [0.01, 0.1, 0.5, 0.9, 0.99]).

### Returns
- **qerfi1** (list of float) - Inverse of the standard normal complementary probability.
```

--------------------------------

### Run Point-to-Point Prediction

Source: https://itmlogic.readthedocs.io/en/latest/_sources/index.rst.txt

Execute the point-to-point prediction script using the itmlogic package.

```bash
python scripts/p2p.py
```

--------------------------------

### Run Point-to-Point Prediction Script

Source: https://itmlogic.readthedocs.io/en/latest/index.html

Executes the point-to-point prediction mode script. This allows for quick generation of results for radio propagation between two specific points.

```bash
python scripts/p2p.py

```

--------------------------------

### adiff Function

Source: https://itmlogic.readthedocs.io/en/latest/_modules/itmlogic/diffraction_attenuation/adiff.html

Calculates the diffraction attenuation at a given distance 'd' using propagation parameters 'prop'. When d=0, it initializes constants. Otherwise, it computes diffraction attenuation based on a combination of smooth earth and knife-edge diffraction models.

```APIDOC
## adiff(d, prop)

### Description
Returns the estimated diffraction attenuation (adiff1) at a given distance 'd' using propagation parameters 'prop'. This function models the diffraction region beyond the smooth-earth horizon.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **d** (float) - Distance in meters. If d is 0, the function initializes constants.
* **prop** (dict) - A dictionary containing all input propagation parameters. This dictionary is also updated with output parameters.

### Returns
* **adiff1** (float) - The estimated diffraction attenuation.
* **prop** (dict) - The updated propagation parameters dictionary.

### Method
None (Python function)

### Endpoint
None (Python function)

### Request Example
```python
# Example for initialization (d=0)
prop_init = {
    'hg': [value1, value2], 
    'he': [value1, value2],
    'mdp': value,
    'dla': value,
    'tha': value,
    'gme': value,
    'wn': value,
    'dh': value,
    'dlsa': value,
    'dl': [value1, value2],
    'zgnd': value
}

adiff1, prop_updated = adiff(0, prop_init)

# Example for calculation (d > 0)
prop_calc = prop_updated # Use updated props from initialization

adiff1, prop_final = adiff(distance_in_meters, prop_calc)
```

### Response
#### Success Response
* **adiff1** (float) - The calculated diffraction attenuation.
* **prop** (dict) - The dictionary containing updated propagation parameters.

#### Response Example
```json
{
  "adiff1": 10.5, 
  "prop": { ... updated propagation parameters ... }
}
```
```

--------------------------------

### alos Function for Line-of-Sight Attenuation

Source: https://itmlogic.readthedocs.io/en/latest/_modules/itmlogic/los_attenuation/alos.html

Calculates line-of-sight attenuation. A call with d = 0 can be used to set up initial constants. Requires distance 'd' in meters and a 'prop' dictionary containing propagation parameters.

```python
import math
import numpy as np


def alos(d, prop):
    """
    Find the 'line-of-sight attenuation' at the distance d using a combination of plane
    earth fields and directed fields (Eqn 4.44 of "The ITS Irregular Terrain Model,
    version 1.2.2: The Algorithm"). A call with d = 0 sets up initial constants.

    Parameters
    ----------
    d : float
        Distance in meters.
    prop : dict
        Contains all input propagation parameters

    Returns
    -------
    alos : float
        The estimated line-of-sight attenuation.

    """
    q = (1 - 0.8 * math.exp(-d / 50e3)) * prop['dh']

    s = 0.78 * q * math.exp(-(q / 16)**0.25)

    q = prop['he'][0] + prop['he'][1]

    sps = q / math.sqrt(d**2 + q**2)

    r = (
        (sps - prop['zgnd']) /
        (sps + prop['zgnd']) *
        math.exp(-min(10, prop['wn'] * s * sps))
        )

    q = abs(r)**2

    if q < 0.25 or q < sps:
        r = r * math.sqrt(sps / q)

    alos1  = prop['emd'] * d + prop['aed']

    q = prop['wn'] * prop['he'][0] * prop['he'][1] * 2 / d

    if q > 1.57:
        q = 3.14 - 2.4649 / q

    alos1 = (
        (-4.343 *
        np.log(abs(complex(math.cos(q),-math.sin(q)) + r)**2)- alos1) *
        prop['wis'] + alos1
        )

    return alos1

```

--------------------------------

### Radio Propagation Calculation Logic

Source: https://itmlogic.readthedocs.io/en/latest/_modules/itmlogic/lrprop.html

This snippet outlines the core logic for calculating radio propagation parameters based on distance and other environmental factors. It handles different distance conditions and updates the 'prop' dictionary with calculated values.

```python
prop['ael'] = a2 - prop['ak1'] * d2 - prop['ak2'] * np.log(d2)
prop['wlos'] = 1

if prop['dist'] > 0:
    prop['aref'] = (
        prop['ael'] + prop['ak1'] *
        prop['dist'] + prop['ak2'] * np.log(prop['dist'])
        )

if prop['dist'] <= 0 or prop['dist'] >= prop['dlsa']:

    if prop['wscat'] == 0:
        prop['ad'] = prop['dl'][0] - prop['dl'][1]
        prop['rr'] = prop['he'][1] / prop['he'][0]
        if prop['ad'] < 0:
            prop['ad'] = -prop['ad']
            prop['rr'] = 1 / prop['rr']

        prop['etq'] = (
            (5.67e-6 * prop['ens'] - 2.32e-3) *
            prop['ens'] + 0.031
            )

        prop['h0s'] = -15

        d5 = prop['dla'] + 200e3
        d6 = d5 + 200e3

        prop = ascat(d6, prop)
        a6 = prop['ascat1']
        prop = ascat(d5, prop)
        a5 = prop['ascat1']

        if a5 < 1000:
            prop['ems'] = (a6 - a5) / 200e3
            prop['dx'] = (
                max([prop['dlsa'], prop['dla'] + 0.3 * prop['xae'] *
                np.log(47.7 * prop['wn']), (a5 - prop['aed'] -
                prop['ems'] * d5) / (prop['emd'] - prop['ems'])])
                )
            prop['aes'] = (
                (prop['emd'] - prop['ems']) *
                prop['dx'] + prop['aed']
                )

        else:
            prop['ems'] = prop['emd']
            prop['aes'] = prop['aed']
            prop['dx'] = 10e6

        prop['wscat'] = 1

    if prop['dist'] > prop['dx']:
        prop['aref'] = prop['aes'] + prop['ems'] * prop['dist']
    else:
        prop['aref'] = prop['aed'] + prop['emd'] * prop['dist']

prop['aref'] = max(prop['aref'], 0)

return prop
```

--------------------------------

### Calculate Path Loss

Source: https://itmlogic.readthedocs.io/en/latest/_sources/getting-started.rst.txt

Pass the terrain profile data and link distance to the `itmlogic_p2p` function to calculate propagation loss. The function requires the original surface profile in meters and the distance in kilometers.

```python
output = itmlogic_p2p(original_surface_profile_m, distance_km)
```

--------------------------------

### ITM Logic Statistics AVAR Calculation

Source: https://itmlogic.readthedocs.io/en/latest/_modules/itmlogic/statistics/avar.html

This snippet contains the core logic for calculating the Average Variance (AVAR) based on various environmental and signal properties. It involves complex calculations for signal strength, distance, and variance.

```python
            ((prop['cfm3'] * q)**2 + 1)
            )

            prop['gp'] = (
                prop['cfp1'] + prop['cfp2'] /
                ((prop['cfp3'] * q)**2 + 1)
                )

        if prop['lvar'] > 1:

            prop['dexa'] = (
                math.sqrt(18e6 * prop['he'][0]) +
                math.sqrt(18e6 * prop['he'][1]) +
                (575.7e12 / prop['wn']) ** third
                )

        if prop['dist'] < prop['dexa']:
            de = 130e3 * prop['dist'] / prop['dexa']

        else:
            de = 130e3 + prop['dist'] - prop['dexa']

        prop['vmd'] = curv(
            prop['cv1'], prop['cv2'], prop['yv1'],
            prop['yv2'], prop['yv3'], de
            )

        prop['sgtm'] = curv(
            prop['csm1'], prop['csm2'], prop['ysm1'],
            prop['ysm2'], prop['ysm3'], de) * prop['gm']

        prop['sgtp'] = curv(
            prop['csp1'], prop['csp2'], prop['ysp1'],
            prop['ysp2'], prop['ysp3'], de) * prop['gp']

        prop['sgtd'] = prop['sgtp'] * prop['csd1']

        prop['tgtd'] = (prop['sgtp'] - prop['sgtd']) * prop['zd']

        if prop['wl']:
            prop['sgl'] = 0
        else:
            q = (
                (1 - 0.8 * math.exp(-prop['dist'] / 50e3)) *
                prop['dh'] * prop['wn']
                )
            prop['sgl'] = 10 * q / (q + 13)

        if prop['ws']:
            prop['vs0'] = 0
        else:
            prop['vs0'] = (5 + 3 * math.exp(-de / 100e3))**2

        prop['lvar'] = 0

    zt = zzt
    zl = zzl
    zc = zzc

    if prop['kdv'] == 0:
        zt = zc
        zl = zc
    elif prop['kdv'] == 1:
        zl = zc
    elif prop['kdv'] == 2:
        zl = zt

    if abs(zt) > 3.10 or abs(zl) > 3.10 or abs(zc) > 3.10:
        prop['kwx'] = max(prop['kwx'], 1)

    if zt < 0:
        sgt = prop['sgtm']
    elif zt <= prop['zd']:
        sgt = prop['sgtp']
    else:
        sgt = prop['sgtd'] + prop['tgtd'] / zt

    vs = (
        prop['vs0'] + (sgt * zt)**2 / (rt + zc**2) +
        (prop['sgl'] * zl)**2 / (rl + zc**2)
        )

    if prop['kdv'] == 0:
        yr = 0
        sgc = math.sqrt(sgt**2 + prop['sgl']**2 + vs)
    elif prop['kdv'] == 1:
        yr = sgt * zt
        sgc = math.sqrt(prop['sgl']**2 + vs)
    elif prop['kdv'] == 2:
        yr = math.sqrt(sgt**2 + prop['sgl']**2) * zt
        sgc = math.sqrt(vs)
    else:
        yr = sgt * zt + prop['sgl'] * zl
        sgc = math.sqrt(vs)

    avar1 = prop['aref'] - prop['vmd'] - yr - sgc * zc

    if avar1 < 0:
        avar1 = avar1 * (29 - avar1) / (29 - 10 * avar1)

    return avar1, prop
```

--------------------------------

### qtile

Source: https://itmlogic.readthedocs.io/en/latest/_modules/itmlogic/misc/qtile.html

Calculates the specified percentile from a list of data after sorting it in descending order.

```APIDOC
## qtile

### Description
This routine returns the ith entry of vector after sorting in descending order.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **a** (list) - Input data distribution.
- **ir** (int) - Desired percentile.

### Returns
- **qtile** (float) - Percentile value.

### Example
```python
import numpy as np

# Assuming qtile function is imported
# from itmlogic.misc import qtile

data = [1, 5, 2, 8, 3]
percentile_index = 1 # Corresponds to the 2nd element after sorting descending
result = qtile(data, percentile_index)
print(result) # Output: 5
```
```
Tokens:
Raw