# ITM Backend Notes

## Current Status
SignalReach now has:
- a propagation service layer
- a dedicated `terrain_itm` backend module
- mission schema fields for ITM-oriented parameters
- a vendored copy of `edwardoughton/itmlogic`
- a real LR-ITM point-to-point adapter that samples SignalReach DEM profiles and
  runs them through the vendored core

It does **not** yet have a full end-state propagation stack. The current ITM
backend is specifically:
- a terrain-backbone integration using the vendored `itmlogic` numerical core
- limited to point-to-point Longley-Rice evaluation
- now paired with a first dry clutter synthesis layer for manual/preset
  vegetation and structure penalties
- still missing real clutter samplers and a calibrated moisture layer
- still using the existing SignalReach confidence semantics downstream

## Why This Exists
This is not meant to fake completion.

It exists so we can:
- stabilize the backend seam now
- carry ITM configuration through mission validation and runtime calls
- get real LR-ITM loss numbers into the solver without replacing the rest of the
  solver stack in one giant risky jump
- keep one obvious place to continue adding clutter/environment synthesis later

## Candidate Engine Sources
The most credible sources identified are:

### NTIA official implementation
- `NTIA/itm`
- `NTIA/itm-longley-rice`

These are the official ITM codebases and are the best long-term source of truth.

### Python implementation
- `edwardoughton/itmlogic`

This is the source currently vendored into the repository and used for the first
real ITM integration. It is a practical bootstrap path, but it is not the
official NTIA implementation.

## Recommended Integration Direction
Long-term:
- prefer the official NTIA model as the reference behavior

Short-term bootstrap options:
- wrap an official NTIA binary/library if Windows packaging is acceptable
- or vendor/adapt a Python implementation for faster in-repo experimentation

## Current Adapter Shape
The live adapter in:
- [terrain_itm.py](/C:/dev/rfplanner/signalreach/propagation/terrain_itm.py)

does the following:
- samples a path profile from the active DEM using SignalReach's configured
  terrain source
- translates profile samples into the ITM `pfl` structure
- runs `qlrpfl` and `avar` from the vendored core
- converts ITM basic transmission loss into the project's normal
  fade-margin/confidence outputs
- keeps LOS/Bullington diagnostics from the existing geometry helper for user
  visibility and downstream advisories

## Next Technical Step
Replace the manual/preset non-terrain penalties with real sampled clutter:
- vegetation attenuation from clutter queries
- structure penetration / rooftop penalties from clutter queries
- local clutter penalties from land-cover sampling
- deferred moisture/environment modifiers from real sources

After that, the next likely validation step is comparison runs against the
official NTIA implementation on a fixed profile corpus.
