Metadata-Version: 2.4
Name: gri-geosim
Version: 0.3.4
Summary: Geometric simulation of geolocation scenarios with platforms, sensors, and emitters
Project-URL: Homepage, https://geosolresearch.com
Project-URL: Repository, https://gitlab.com/geosol-foss/python/gri-geosim
Project-URL: Issues, https://gitlab.com/geosol-foss/python/gri-geosim/-/issues
Project-URL: Changelog, https://gitlab.com/geosol-foss/python/gri-geosim/-/releases
Author-email: GeoSol Research Inc <contact@geosolresearch.com>
License-Expression: MIT
License-File: LICENSE
Keywords: AOA,FDOA,TDOA,geolocation,simulation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.12
Requires-Dist: gri-convolve>=0.2.0
Requires-Dist: gri-ell>=0.2.0
Requires-Dist: gri-iono>=0.2.3
Requires-Dist: gri-nsepoch>=0.2.2
Requires-Dist: gri-obs>=0.1.0
Requires-Dist: gri-pos>=0.2.0
Requires-Dist: gri-tropo>=0.2.2
Requires-Dist: gri-utils>=0.3.3
Requires-Dist: numpy>=2.3.3
Requires-Dist: scipy>=1.16.2
Requires-Dist: sgp4>=2.23
Description-Content-Type: text/markdown

[![GeoSol Research Logo](https://geosolresearch.com/logos/foss_logo.png "GeoSol Research")](https://geosolresearch.com)

# GeoSim (Geometric Simulation)

A Python library for geometric simulation of geolocation scenarios. GeoSim models platforms (satellites, ground stations, aircraft) with attached sensors that observe emitters and generate measurements (AOA, TDOA, FDOA) for testing geolocation algorithms. Requires Python 3.12+.

## Mathematical Background

The sensor models compute measurements from geometry:

**AOA (Angle of Arrival).** Direction cosines `(u, v)` from the collector-to-emitter unit vector projected into the sensor's local coordinate frame. For ENU-based sensors, `u = east component`, `v = north component` of the unit direction.

**TDOA (Time Difference of Arrival).** The difference in propagation time between two collectors:

    dt = (||x - c1|| - ||x - c2||) / c

where `x` is the emitter position, `c1` and `c2` are collector positions, and `c` is the speed of light. The iso-surface is a hyperboloid with foci at the two collectors.

**FDOA (Frequency Difference of Arrival).** The differential Doppler shift observed between two collectors:

    df = (f / c) * (v1 . r1_hat - v2 . r2_hat)

where `f` is the carrier frequency, `v1`, `v2` are collector velocities, and `r1_hat`, `r2_hat` are unit vectors from each collector to the emitter.

References: Torrieri (1984), "Statistical Theory of Passive Location Systems"; Ho & Chan (1997), "Geolocation of a Known Altitude Object from TDOA and FDOA Measurements."

## Key Features

- **Platform modeling**: Stationary, TLE (SGP4), Keplerian orbit, and waypoint trajectories
- **Sensor types**: AOA (Angle of Arrival), TDOA (Time Difference of Arrival), FDOA (Frequency Difference of Arrival)
- **FOV constraints**: Elevation masks, conical FOV, Earth occlusion
- **Observation generation**: Self-contained measurements with embedded collector state
- **Geolocation pipeline**: Observation -> Ell (ellipsoid) conversion and fusion
- **Monte Carlo support**: Statistical analysis via multiple simulation iterations
- **Atmospheric corrections**: Integration with gri-tropo/gri-iono for delay modeling

## Core Classes

| Class              | Purpose                                                                 |
| ------------------ | ----------------------------------------------------------------------- |
| `Scenario`         | Orchestrates simulation timeline and all participants                   |
| `Platform`         | Moving or stationary observer (satellite, ground station, aircraft)     |
| `Emitter`          | Target being observed (stationary or moving)                            |
| `AoaSensor`        | Angle of Arrival measurements (azimuth/elevation or direction cosines)  |
| `TdoaSensor`       | Time Difference of Arrival measurements (paired platforms)              |
| `FdoaSensor`       | Frequency Difference of Arrival measurements (Doppler-based)            |
| `LocatorResult`    | Geolocation solution with position, covariance, and chi-squared         |

## Installation

```bash
# Basic installation
pip install gri-geosim

# With geolocation support (gri-ell for ellipsoids)
pip install gri-geosim[all]

# With atmospheric corrections
pip install gri-geosim[atmosphere]
```

## Quick Start

```python
from gri_geosim import Scenario, Platform, Emitter, filter_aoa
from gri_geosim.sensors import AoaSensor
from gri_pos import Pos
from gri_nsepoch import Time

# Create a ground-based emitter (target)
emitter = Emitter(Pos.LLA(39.0, -76.5, 0.0), frequency_hz=1.5e9, name="TARGET")

# Create sensor platform
ground = Platform(Pos.LLA(38.0, -77.0, 100.0), name="GROUND_STATION")
ground.add_sensor(AoaSensor("aoa", azimuth_std_rad=0.001, elevation_std_rad=0.001))

# Run single-instant simulation
scenario = Scenario.for_instant(platforms=[ground], emitters=[emitter])
observations = scenario.simulate_at(Time.from_str("2024-01-15T12:00:00Z"))

# Access observations
for obs in filter_aoa(observations):
    print(f"Azimuth: {obs.azimuth:.4f} rad, Elevation: {obs.elevation:.4f} rad")
```

## Trajectories

| Trajectory             | Description                                           |
| ---------------------- | ----------------------------------------------------- |
| `StationaryTrajectory` | Fixed position, zero velocity                         |
| `Sgp4Trajectory`       | SGP4/SDP4 TLE propagation (python-sgp4 backend)       |
| `KeplerianTrajectory`  | Two-body orbital mechanics (gri-utils backend)        |
| `WaypointTrajectory`   | Interpolated path through waypoints (cubic/linear)    |

## FOV Constraints

Sensors support pluggable field-of-view constraints:

| Constraint          | Description                                                 |
| ------------------- | ----------------------------------------------------------- |
| `NoFov`             | No restriction (always visible)                             |
| `ConeFov`           | Conical field of view with half-angle                       |
| `ElevationMaskFov`  | Elevation angle constraints (auto-detects ground reference) |
| `EarthOcclusionFov` | Earth line-of-sight blockage check                          |

```python
from gri_geosim.sensors import AoaSensor, ElevationMaskFov

# Ground station with 10-degree elevation mask
sensor = AoaSensor(
    "ground_aoa",
    azimuth_std_rad=0.001,
    fov=ElevationMaskFov(min_elev_deg=10.0),
)
```

## Geolocation Pipeline

Convert observations to position estimates with covariance:

```python
from gri_geosim import locate
from gri_convolve import smart_convolve

# Generate observations
observations = scenario.simulate_at(observation_time)

# Convert to position estimate with covariance ellipsoid
ell = locate(observations)
print(f"Position: {ell.lla}")
print(f"95% horizontal error: {ell.cep95_m:.1f} m")

# Combine multiple ellipsoids (with outlier rejection)
combined, used, discarded = smart_convolve([ell1, ell2, ell3])
```

## Dependencies

This is a Layer 3 application package in the GRI FOSS ecosystem:

**Required**:

- `gri-utils`: Coordinate conversions, orbit propagation, observable calculations
- `gri-pos`: Position objects (Pos class) with LLA/XYZ support
- `gri-nsepoch`: Nanosecond-accurate timestamps (Time, Delta classes)
- `numpy`, `scipy`: Numerical computing
- `sgp4`: TLE orbit propagation

**Optional** (installed with `[all]`):

- `gri-ell`: Covariance ellipsoid objects for `locate()`
- `gri-convolve`: Ellipsoid combination (`smart_convolve`, `convolve`, `cluster_convolve`)

**Optional** (installed with `[atmosphere]`):

- `gri-tropo`: Tropospheric delay modeling (ITU-R 2019)
- `gri-iono`: Ionospheric delay modeling (Bent, IRI, NeQuick)

## Examples

See [examples/README.md](https://gitlab.com/geosol-foss/python/gri-geosim/-/blob/main/examples/README.md) for detailed examples:

- `basic_scenario.py` - Multi-platform AOA with ground/aircraft/satellite sensors
- `tdoa_scenario.py` - TDOA sensor pairs with paired platforms
- `monte_carlo.py` - Statistical analysis via multiple simulation runs
- `locate_and_fuse.py` - Full geolocation pipeline with ellipsoid fusion
- `atmosphere_effects.py` - Tropospheric and ionospheric delay demonstration
- `multi_platform_geo.py` - Complex hybrid AOA/TDOA/FDOA scenario


## Other Projects

Current list of other [GRI FOSS Projects](https://gitlab.com/geosol-foss/python/gri-geosim/-/blob/main/.docs_other_projects.md) we are building and maintaining.

## License

MIT License. See [LICENSE](https://gitlab.com/geosol-foss/python/gri-geosim/-/blob/main/LICENSE) for details.
