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

Documentation

The wheel ships its documentation inside the package, in gri_geosim/docs/, so it is available wherever the package is installed:

• overview.md -- building a scenario, simulating, locating, Monte Carlo, atmosphere, fields of view, the array-level locators, and the geometry traps
• api_summary.md -- every public class, function, and signature (generated)

Print the directory with python -c "import gri_geosim, pathlib; print(pathlib.Path(gri_geosim.__file__).parent / 'docs')". Every example in those files is run by the test suite.

Installation

pip install gri-geosim

All ecosystem dependencies (ellipsoids, fusion, atmospheric corrections, motion models) are installed automatically; there are no optional extras to select.

Quick Start

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

Motion models live in the standalone gri-trajectory package (a dependency of gri-geosim). Import them from there and pass to Platform/Emitter, which also accept a bare Pos (wrapped in a StationaryTrajectory internally):

from gri_trajectory import Sgp4Trajectory, WaypointTrajectory

See the gri-trajectory README for the full set (LinearTrajectory, CoordinatedTurnTrajectory, GreatCircleTrajectory, CircularOrbitTrajectory, HermiteTrajectory, SegmentedTrajectory, plus the legs and placement submodules).

FOV Constraints

Sensors support pluggable field-of-view constraints:

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:

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 (needs at least two
# collectors; raises ValueError where the solution leaves position unobservable).
# A ground altitude prior (0 m, 5 km sigma) is on by default: pass
# altitude_prior=None for an airborne emitter. locate_candidates returns every
# solution, such as both roots of the mirror ambiguity of level collectors.
ell = locate(observations)
print(f"Position: {ell.lla}")
print(f"95% ellipse: {ell.ellipse}")

# 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. All of the following are installed automatically:

• 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)
• gri-trajectory: Platform/emitter motion models (also supplies the sgp4 backend)
• gri-obs: Typed observation containers re-exported by gri-geosim
• gri-ell: Covariance ellipsoid objects for locate()
• gri-convolve: Ellipsoid combination (smart_convolve, convolve, cluster_convolve)
• gri-tropo: Tropospheric delay modeling (ITU-R 2019)
• gri-iono: Ionospheric delay modeling (Bent, IRI, NeQuick)
• numpy, scipy: Numerical computing

Examples

See 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 we are building and maintaining.

License

MIT License. See LICENSE for details.