pyAIEM 0.0.161
advanced integral equation model (AIEM)
License: MIT license

# AIEM: Advanced Integral Equation Model

<!-- Add badges here: e.g., PyPI version, build status, license -->
<!-- [![PyPI version](https://badge.fury.io/py/aiem.svg)](https://badge.fury.io/py/aiem) -->
<!-- [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) -->

The `AIEM` class, implemented in `aiem/core.py`, provides a sophisticated theoretical framework for predicting radar backscattering from a randomly rough dielectric surface. This model is widely used in microwave remote sensing to understand how radar signals interact with various natural and man-made surfaces.


## Overview

The Advanced Integral Equation Model (AIEM) calculates the normalized radar cross-section (NRCS), often denoted as sigma-naught (σ⁰), for different polarization combinations (VV, HH, HV, VH). It accounts for:

*   The frequency of the incident radar wave.
*   The geometry of illumination and observation (incidence and scattering angles).
*   The physical properties of the surface:
    *   Roughness (RMS height and correlation length).
    *   Dielectric constant (permittivity).
    *   Type of surface roughness (e.g., Gaussian, Exponential).

## Features

*   Calculates radar backscattering (NRCS/σ⁰) for VV, HH, HV, and VH polarizations.
*   Supports various surface autocorrelation functions (Gaussian, Exponential, 1.5 power-law).
*   Accounts for radar frequency, incidence/scattering geometry, surface roughness (RMS height, correlation length), and material permittivity.
*   Provides outputs in linear scale or decibels (dB).

## Installation

It is recommended to install `aiem` in a virtual environment.

1.  Create and activate a virtual environment (optional but recommended):
    ```bash
    python -m venv venv
    source venv/bin/activate  # On Windows use `venv\Scripts\activate`
    ```

2.  Install `aiem` using pip:
    ```bash
    pip install pyAIEM
    ```

## `AIEM` Class

### Initialization (`__init__`)

The model is initialized with the physical and geometrical parameters of the scenario.

**Purpose:**
Sets up the AIEM model instance by storing input parameters, converting units (degrees to radians), and pre-calculating several essential quantities that will be used repeatedly in the backscattering calculations.

**Parameters:**

*   `frq_ghz` (float): Frequency of the incident radar wave in Gigahertz (GHz).
*   `theta_i` (float): Incidence zenith angle in degrees.
*   `theta_s` (float): Scattering zenith angle in degrees.
*   `phi_i` (float): Incidence azimuth angle in degrees.
*   `phi_s` (float): Scattering azimuth angle in degrees.
*   `sigma` (float): Root mean square (RMS) height of the surface roughness in meters [m].
*   `cl` (float): Surface correlation length in meters [m].
*   `eps` (complex): Complex relative permittivity of the surface material (dimensionless).
*   `acf_type` (str): Type of autocorrelation function (ACF) for the surface roughness (e.g., "1" for Gaussian, "2" for Exponential, "3" for 1.5 power-law).

**Key Internal Operations:**
1.  Stores input parameters (e.g., permittivity `self.er`, relative permeability `self.ur` assumed to be 1).
2.  Converts angles from degrees to radians.
3.  Calculates the wavelength (`lam`) and angular wavenumber (`k`).
4.  Computes normalized roughness parameters: `ks` (RMS height normalized by wavenumber) and `kl` (correlation length normalized by wavenumber).
5.  Pre-computes sines and cosines of the angles for efficiency.
6.  Calculates the surface roughness spectrum (`self.spectra_1`) and the number of terms for series convergence (`self.iterm`) via the `_roughness_spectrum()` method.

### Main Execution (`run`)

This method orchestrates the full AIEM calculation to compute the backscattering coefficients.

**Purpose:**
To execute the sequence of calculations required by the AIEM theory to arrive at the final backscattering coefficients (σ⁰).

**Parameter:**

*   `todB` (bool, default: `True`): If `True`, the output backscattering coefficients are converted to decibels (dB). Otherwise, they are returned in linear scale.

**Sequence of Operations:**
The `run` method calls a series of internal ("private") methods in a specific order:
1.  `_reflection_coefficients_incident()`: Calculates Fresnel reflection coefficients for the incident wave.
2.  `_reflection_coefficients_specular()`: Calculates Fresnel reflection coefficients for the specular direction.
3.  `_reflection_coefficients_transition()`: Calculates transition reflection coefficients that blend incident and specular behavior based on roughness.
4.  `_kirchhoff_field_coefficients()`: Computes field coefficients based on the Kirchhoff (high-frequency) approximation.
5.  `_complementary_field_coefficients()`: Calculates complementary field coefficients, which are crucial for the "Advanced" part of the Itegral Equation Model, refining the Kirchhoff approximation.
6.  `_calculate_sigma0()`: Combines all previously calculated coefficients and the roughness spectrum to compute the final σ⁰ values.

**Returns:**

*   `VV` (float): Backscattering coefficient for Vertical transmit, Vertical receive polarization.
*   `HH` (float): Backscattering coefficient for Horizontal transmit, Horizontal receive polarization.
*   `HV` (float): Backscattering coefficient for Horizontal transmit, Vertical receive polarization.
*   `VH` (float): Backscattering coefficient for Vertical transmit, Horizontal receive polarization.

(Values are in dB if `todB=True`, otherwise linear).

### Core Internal Calculation Steps

The AIEM relies on several complex intermediate calculations, encapsulated in helper methods:

*   **Reflection Coefficients (`_reflection_coefficients_incident`, `_reflection_coefficients_specular`, `_reflection_coefficients_transition`):** These methods determine the basic reflection properties of the surface material at different angles and how these properties transition from smooth-surface-like (specular) to rough-surface-like behavior.
*   **Kirchhoff Field Coefficients (`_kirchhoff_field_coefficients`):** These provide an initial estimate of the scattered fields based on the Physical Optics or Kirchhoff Approximation, which assumes the surface is locally flat.
*   **Complementary Field Coefficients (`_complementary_field_coefficients`):** This is a key part of the AIEM. These coefficients correct and extend the Kirchhoff approximation, particularly for rougher surfaces or lower frequencies, by incorporating a series expansion related to the surface roughness. This involves numerous sub-functions (`_favv`, `_fbvv`, etc.) that represent complex mathematical terms from the integral equation solution.
*   **Roughness Spectrum (`_roughness_spectrum`):** This method calculates the power spectral density of the surface roughness. It describes how the "power" or variance of the surface height is distributed across different spatial frequencies. The choice of `acf_type` (Gaussian, Exponential, etc.) determines the shape of this spectrum.
*   **Sigma0 Calculation (`_calculate_sigma0`):** This final step combines the field coefficients (both Kirchhoff and complementary) with the roughness spectrum, applying appropriate weighting and exponential factors, to compute the NRCS (σ⁰) for each polarization.

### Helper Methods

Numerous other private helper methods (e.g., `_wavelength`, `_todB`, `_expal`, `_c1_func` to `_c6_func`, `_b1_func` to `_b6_func`, `_calculate_z_values`) are used to:
*   Perform specific unit conversions or simple calculations.
*   Encapsulate the detailed and often lengthy mathematical formulas derived from the AIEM theory, breaking down the overall complexity into manageable, reusable components.

## Basic Usage Example

```python
from aiem import AIEM
import numpy as np

# Define input parameters
frequency_ghz = 5.3  # C-band
incidence_angle_deg = 30.0
scattering_angle_deg = 30.0 # For backscatter, same as incidence
azimuth_inc_deg = 0.0
azimuth_scat_deg = 180.0 # For backscatter
rms_height_m = 0.01 # 1 cm
correlation_length_m = 0.1 # 10 cm
permittivity = complex(6.0, 0.6) # Example for moist soil
acf = '2' # Exponential ACF

# Initialize the AIEM model
model = AIEM(frq_ghz=frequency_ghz,
             theta_i=incidence_angle_deg,
             theta_s=scattering_angle_deg,
             phi_i=azimuth_inc_deg,
             phi_s=azimuth_scat_deg,
             sigma=rms_height_m,
             cl=correlation_length_m,
             eps=permittivity,
             acf_type=acf)

# Run the model to get backscattering coefficients (in dB by default)
vv_db, hh_db, hv_db, vh_db = model.run()

print(f"Sigma0 VV: {vv_db:.2f} dB")
print(f"Sigma0 HH: {hh_db:.2f} dB")
print(f"Sigma0 HV: {hv_db:.2f} dB")
print(f"Sigma0 VH: {vh_db:.2f} dB")

# To get linear scale results:
# vv_lin, hh_lin, hv_lin, vh_lin = model.run(todB=False)
```

# Reference
[1] Wu, T. D., Chen, K. S., Shi, J., Lee, H. W., &amp; Fung, A. K. (2008). A study of an AIEM model for bistatic scattering from randomly rough surfaces. IEEE Transactions on Geoscience and Remote Sensing, 46(9), 2584-2598.