Skip to content

PHaRLAP + IRI 3D Ray Trace

3D Geoplot3 Status

MATLAB geoplot3 rendering is temporarily disabled in examples/run_pharlap_iri_3d.py.

End-to-End 3D Workflow

Build 3D IRI density + 3D collision grids, run PHaRLAP 3D, and generate lat/lon faces plus a 3-panel route-aligned visualization.

This page explains the example script:

  • examples/run_pharlap_iri_3d.py

It is an end-to-end wrapper that builds volumetric ionosphere/background inputs, runs PHaRLAP 3D through MATLAB Engine, and generates:

  1. a Python side/front face plot over ne_grid
  2. a Python 3-panel route-aligned plot:
  3. along-track vs height
  4. bearing-spread vs height
  5. top view (along-track vs bearing-spread)

PyIRI Backend Config

TRACE now uses PyIRI for IRI density fetch (PyIRI.sh_library.IRI_density_1day). Use iri_param in hfpytrace/cfg/config3D.json:

"iri_param": {
  "f107": 150.0,
  "foF2_coeff": "CCIR",
  "hmF2_model": "SHU2015",
  "coord": "GEO"
}

iri_version is deprecated and ignored by the current backend.

Call Flow

  1. main() parses CLI args (--config, --event, --no-matlab) and loads config.
  2. _run(...) builds 3D spatial axes from cfg.iono_grid:
  3. latitude vector
  4. longitude vector
  5. height vector
  6. IRI electron density is fetched into a 3D cube:
  7. IRI3d.fetch_dataset(...) -> ne_grid(lat, lon, height)
  8. Collision frequency is computed on the same 3D cube:
  9. ComputeCollision.from_nrlmsise_3d(...) -> collision_freq(lat, lon, height)
  10. Geomagnetic grids are built from PyIRI IGRF:
  11. hfpytrace.geomag.build_geomag_grid(...) -> Bx/By/Bz(lat, lon, height)
  12. fallback to a uniform default field if geomag evaluation fails
  13. Ray launch vectors are built from elevation + bearing fan:
  14. elevs, ray_bearings, freqs
  15. PHaRLAP is executed:
  16. Engine.run_pharlap_3d_sp(...) when use_spherical=true
  17. otherwise Engine.run_pharlap_3d(...)
  18. Plot product is generated:
  19. _plot_ray_faces(...) with PlotRays3D
  20. _plot_route_faces(...) with PlotRays3DRouteFaces

Key Code (From run_pharlap_iri_3d.py)

1) 3D Grid Construction

iono_cfg = cfg.iono_grid
lats = _build_axis(float(iono_cfg.lat_start), float(iono_cfg.lat_step), int(iono_cfg.num_lats))
lons = _build_axis(float(iono_cfg.lon_start), float(iono_cfg.lon_step), int(iono_cfg.num_lons))
heights = _build_axis(
    float(iono_cfg.height_start_km),
    float(iono_cfg.height_step_km),
    int(iono_cfg.num_heights),
)

2) 3D IRI + 3D Collision

ne_grid = _build_iri_3d(cfg, event_time, lats, lons, heights)
collision_freq = _build_collision_3d(
    cfg, event_time, ne_grid, lats, lons, heights
)
iono_en_grid_5 = ne_grid.copy()

Internally:

iri = IRI3d(cfg, event_time)
ne_grid, _ = iri.fetch_dataset(event_time, lats, lons, heights, workers=int(cfg.worker))

and

cc = ComputeCollision.from_nrlmsise_3d(
    date=event_time,
    lats=lats,
    lons=lons,
    heights_km=heights,
    Te=te_3d, Ti=ti_3d, edens=ne_grid, O2p=o2p_3d, Op=op_3d,
    workers=int(cfg.worker),
)
collision_freq = cc.collision.nu_ft

3) PHaRLAP 3D Call

if bool(getattr(cfg, "use_spherical", True)):
    ray_data, ray_path_data, ray_state_vec = eng.run_pharlap_3d_sp(
        origin_lat=origin_lat, origin_lon=origin_lon, origin_ht=origin_ht,
        elevs=elevs, ray_bearings=ray_bearings, freqs=freqs,
        OX_mode=int(cfg.OX_mode), nhops=int(cfg.nhops), tol=float(cfg.threshold),
        rad_earth_m=float(cfg.radius_earth_m),
        iono_en_grid=ne_grid, iono_en_grid_5=iono_en_grid_5,
        collision_freq=collision_freq, iono_grid_parms=iono_grid_parms,
        Bx=Bx, By=By, Bz=Bz, geomag_grid_parms=geomag_grid_parms,
    )
else:
    ray_data, ray_path_data, ray_state_vec = eng.run_pharlap_3d(...)

4) Python Face Plot

_plot_ray_faces(
    ne_grid=ne_grid, ray_path_data=ray_path_data,
    lats=lats, lons=lons, heights=heights,
    origin_lat=origin_lat, origin_lon=origin_lon,
    out_file=out_file,
)

and

_plot_route_faces(
    ne_grid=ne_grid,
    ray_path_data=ray_path_data,
    lats=lats,
    lons=lons,
    heights=heights,
    origin_lat=origin_lat,
    origin_lon=origin_lon,
    bearing_deg=bearing_ref,
    out_file=out_file_route,
)

Run

From repository root:

cd /home/chakras4/Research/CodeBase/trace
python examples/run_pharlap_iri_3d.py

Custom timestamp:

python examples/run_pharlap_iri_3d.py --event 2017-05-27T16:00:00Z

Build-only (skip MATLAB raytrace):

python examples/run_pharlap_iri_3d.py --no-matlab

Output Figures

  • docs/examples/figures/pharlap_iri_3d_ray_faces.png
  • docs/examples/figures/pharlap_iri_3d_route_faces.png

Side/Front Faces (Python)

PHaRLAP IRI 3D Faces

Route-Aligned 3-Panel View (Python)

PHaRLAP IRI 3D Route Faces

  • examples/run_pharlap_iri_3d.py
  • hfpytrace/pharlap.py
  • hfpytrace/collision.py
  • hfpytrace/density/iri.py
  • hfpytrace/plottrace.py

See Also