Skip to content

hfpytrace.model.rt1d

Package

Lean 1D profile API for single-point altitude workflows.

Recent updates include:

  • NVIS_tracer(...) support for stretched nonuniform vertical regridding:
  • use_nonuniform_grid
  • nonuniform_points
  • nonuniform_sharpness
  • tighter tracer behavior for contiguous propagation segments
  • loguru diagnostics in initialization, fetch, and tracer execution paths

Key Classes

Class RT1DProfile
Class RT1D (compatibility shim)

Key Methods

Method RT1DProfile.from_cfg()
Method RT1DProfile.fetch_iri()
Method RT1DProfile.fetch_msise()
Method RT1DProfile.fetch_geomag()
Method RT1DProfile.den_to_plasma_freq_hz()
Method RT1DProfile.plasma_freq_to_den()
Method RT1DProfile.inclination_to_vertical_angle() Method RT1D.NVIS_tracer()

NVIS Tracer Notes

RT1D.NVIS_tracer(...) is the default 1D vertical-forward-style tracer used by the examples. It returns:

  • vh_km
  • turning_height_km
  • n_profile
  • reason

For smoother curves near reflection regions, enable nonuniform regridding (enabled by default in current examples).

API

hfpytrace.model.rt1d

1D single-point ionospheric profile and tracer.

Provides a lightweight vertical-profile container and a 1D ray tracer that evaluates IRI-2016 electron density, NRLMSISE-00 neutral atmosphere, and IGRF geomagnetic fields at a single (lat, lon) location.

Classes

RT1DProfile Dataclass holding all 1D altitude-profile fields (Ne, neutral densities, temperatures, magnetic field components) at one geographic point. RT1D Entry-point that owns an :class:RT1DProfile and exposes dispersion evaluation and absorption calculation methods.

Typical usage

from hfpytrace.model import RT1D rt = RT1D(cfg=cfg, fetch_iri=True, fetch_msise=True, fetch_geomag=True) result = rt.dispersion(freq_hz=7e6, mode="O")

RT1DProfile dataclass

Single-point altitude profile for ray/ionosphere workflows.

Notes
  • alt_km is required and must be strictly increasing.
  • Electron density is stored in both m^-3 and cm^-3 (when available).
  • MSIS and geomagnetic outputs are attached as namespaces.
Source code in hfpytrace/model/rt1d.py 
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
@dataclass
class RT1DProfile:
    """
    Single-point altitude profile for ray/ionosphere workflows.

    Notes
    -----
    - `alt_km` is required and must be strictly increasing.
    - Electron density is stored in both m^-3 and cm^-3 (when available).
    - MSIS and geomagnetic outputs are attached as namespaces.
    """

    alt_km: np.ndarray
    lat: float
    lon: float
    time: dt.datetime
    ne_m3: np.ndarray | None = None
    ne_cm3: np.ndarray | None = None
    source: str = "iri"
    msise: SimpleNamespace | None = None
    geomag: SimpleNamespace | None = None
    collision: object | None = (
        None  # ComputeCollision instance after compute_collision()
    )

    def __post_init__(self) -> None:
        self.alt_km = np.asarray(self.alt_km, dtype=float).ravel()
        self.lat = float(self.lat)
        self.lon = float(self.lon)
        if not isinstance(self.time, dt.datetime):
            self.time = dt.datetime.fromisoformat(str(self.time))
        self.validate()

    def validate(self) -> None:
        if self.alt_km.ndim != 1 or self.alt_km.size < 2:
            raise ValueError("alt_km must be a 1D array with at least 2 points")
        if not np.all(np.diff(self.alt_km) > 0):
            raise ValueError("alt_km must be strictly increasing")
        if not np.isfinite(self.lat) or not np.isfinite(self.lon):
            raise ValueError("lat/lon must be finite")

        if self.ne_m3 is not None:
            self.ne_m3 = np.asarray(self.ne_m3, dtype=float).ravel()
            if self.ne_m3.shape != self.alt_km.shape:
                raise ValueError("ne_m3 must match alt_km shape")
            if np.any(self.ne_m3 < 0):
                raise ValueError("ne_m3 must be non-negative")
            self.ne_cm3 = self.ne_m3 * 1e-6
        elif self.ne_cm3 is not None:
            self.ne_cm3 = np.asarray(self.ne_cm3, dtype=float).ravel()
            if self.ne_cm3.shape != self.alt_km.shape:
                raise ValueError("ne_cm3 must match alt_km shape")
            if np.any(self.ne_cm3 < 0):
                raise ValueError("ne_cm3 must be non-negative")
            self.ne_m3 = self.ne_cm3 * 1e6

        if self.msise is not None:
            for k in ("N2", "O2", "O", "H", "He", "Tn"):
                if not hasattr(self.msise, k):
                    raise ValueError(f"msise missing required field: {k}")
                arr = np.asarray(getattr(self.msise, k), dtype=float).ravel()
                if arr.shape != self.alt_km.shape:
                    raise ValueError(f"msise.{k} must match alt_km shape")
                setattr(self.msise, k, arr)

        if self.geomag is not None:
            for k in ("Bx", "By", "Bz", "bmag_t", "inc_deg", "psi_deg"):
                if not hasattr(self.geomag, k):
                    raise ValueError(f"geomag missing required field: {k}")
                arr = np.asarray(getattr(self.geomag, k), dtype=float).ravel()
                if arr.shape != self.alt_km.shape:
                    raise ValueError(f"geomag.{k} must match alt_km shape")
                setattr(self.geomag, k, arr)

    @classmethod
    def from_cfg(
        cls,
        cfg,
        time: dt.datetime | None = None,
        lat: float | None = None,
        lon: float | None = None,
        alt_km: np.ndarray | None = None,
        fetch_iri: bool = True,
        fetch_msise: bool = True,
        fetch_geomag: bool = True,
        workers: int = 1,
    ) -> "RT1DProfile":
        logger.info("RT1DProfile.from_cfg: build profile from config")
        t = time if time is not None else dt.datetime.fromisoformat(str(cfg.event))
        if lat is None or lon is None:
            if hasattr(cfg, "origin"):
                lat = float(cfg.origin.lat)
                lon = float(cfg.origin.lon)
            elif hasattr(cfg, "route") and hasattr(cfg.route, "start"):
                lat = float(cfg.route.start.lat)
                lon = float(cfg.route.start.lon)
            else:
                raise ValueError("Unable to infer lat/lon from cfg. Provide lat/lon.")

        if alt_km is None:
            h0 = float(getattr(cfg, "start_height_km"))
            h1 = float(getattr(cfg, "end_height_km"))
            dh = float(getattr(cfg, "height_incriment_km", 1.0))
            alt_km = np.arange(h0, h1, dh, dtype=float)

        prof = cls(alt_km=alt_km, lat=float(lat), lon=float(lon), time=t)
        logger.info(
            "RT1DProfile created: lat={:.3f}, lon={:.3f}, alt_points={}",
            prof.lat,
            prof.lon,
            prof.alt_km.size,
        )
        if fetch_iri:
            prof.fetch_iri(cfg)
        if fetch_msise:
            prof.fetch_msise(workers=workers)
        if fetch_geomag:
            gm_cfg = getattr(cfg, "geomag_grid", SimpleNamespace(coord_input="GEO"))
            prof.fetch_geomag(
                coord_input=str(getattr(gm_cfg, "coord_input", "GEO")),
                coeff_dir=getattr(gm_cfg, "coeff_dir", None),
            )
        prof.validate()
        return prof

    def set_electron_density(
        self,
        ne_m3: np.ndarray | None = None,
        ne_cm3: np.ndarray | None = None,
        source: str = "iri",
    ) -> None:
        if (ne_m3 is None) == (ne_cm3 is None):
            raise ValueError("Provide exactly one of ne_m3 or ne_cm3")
        self.source = str(source)
        if ne_m3 is not None:
            self.ne_m3 = np.asarray(ne_m3, dtype=float).ravel()
            self.ne_cm3 = self.ne_m3 * 1e-6
        else:
            self.ne_cm3 = np.asarray(ne_cm3, dtype=float).ravel()
            self.ne_m3 = self.ne_cm3 * 1e6
        self.validate()

    def fetch_iri(self, cfg) -> np.ndarray:
        logger.info(
            "Fetching IRI profile: lat={:.3f}, lon={:.3f}, alt_points={}",
            self.lat,
            self.lon,
            self.alt_km.size,
        )
        model = IRI2d(cfg, self.time)
        ne_cm3, _ = model.fetch_dataset(
            self.time,
            lats=np.array([self.lat], dtype=float),
            lons=np.array([self.lon], dtype=float),
            alts=self.alt_km,
            workers=1,
        )
        self.ne_cm3 = np.asarray(ne_cm3[:, 0], dtype=float)
        self.ne_m3 = self.ne_cm3 * 1e6
        self.source = "iri"
        self.validate()
        logger.info(
            "IRI profile fetched: ne range [{:.3e}, {:.3e}] m^-3",
            float(np.nanmin(self.ne_m3)),
            float(np.nanmax(self.ne_m3)),
        )
        return self.ne_m3

    def fetch_msise(
        self,
        workers: int = 1,
        update_spaceweather: bool = False,
        suppress_spaceweather_warning: bool = True,
    ) -> SimpleNamespace:
        logger.info(
            "Fetching NRLMSISE profile: lat={:.3f}, lon={:.3f}, alt_points={}, workers={}",
            self.lat,
            self.lon,
            self.alt_km.size,
            int(workers),
        )
        ms = NRLMSISE2D(
            date=self.time,
            lats=np.array([self.lat], dtype=float),
            lons=np.array([self.lon], dtype=float),
            heights_km=self.alt_km,
            workers=int(workers),
            update_spaceweather=bool(update_spaceweather),
            suppress_spaceweather_warning=bool(suppress_spaceweather_warning),
        ).msise
        self.msise = SimpleNamespace(
            N2=np.asarray(ms["N2"][:, 0], dtype=float),
            O2=np.asarray(ms["O2"][:, 0], dtype=float),
            O=np.asarray(ms["O"][:, 0], dtype=float),
            H=np.asarray(ms["H"][:, 0], dtype=float),
            He=np.asarray(ms["He"][:, 0], dtype=float),
            Tn=np.asarray(ms["Tn"][:, 0], dtype=float),
            t_nn=np.asarray(ms["t_nn"][:, 0], dtype=float),
        )
        self.validate()
        logger.info("NRLMSISE profile fetched successfully.")
        return self.msise

    def fetch_geomag(
        self,
        coord_input: str = "GEO",
        coeff_dir: str | None = None,
    ) -> SimpleNamespace:
        logger.info(
            "Fetching geomag profile: lat={:.3f}, lon={:.3f}, alt_points={}, coord_input={}",
            self.lat,
            self.lon,
            self.alt_km.size,
            coord_input,
        )
        cdir = None
        if isinstance(coeff_dir, str) and coeff_dir.strip():
            cdir = coeff_dir
        gm = build_geomag_grid(
            lats=np.array([self.lat], dtype=float),
            lons=np.array([self.lon], dtype=float),
            alts_km=self.alt_km,
            time=self.time,
            coord_input=coord_input,
            coeff_dir=cdir,
        )
        self.geomag = SimpleNamespace(
            Bx=np.asarray(gm.Bx[0, 0, :], dtype=float),
            By=np.asarray(gm.By[0, 0, :], dtype=float),
            Bz=np.asarray(gm.Bz[0, 0, :], dtype=float),
            bmag_t=np.asarray(gm.bmag_t[0, 0, :], dtype=float),
            inc_deg=np.asarray(gm.inc_deg[0, 0, :], dtype=float),
            dec_deg=np.asarray(gm.dec_deg[0, 0, :], dtype=float),
            psi_deg=np.asarray(gm.psi_deg[0, 0, :], dtype=float),
        )
        self.validate()
        logger.info("Geomag profile fetched successfully.")
        return self.geomag

    def compute_collision(
        self,
        Te: np.ndarray | float | None = None,
        Ti: np.ndarray | float | None = None,
        edens: np.ndarray | None = None,
        O2p: np.ndarray | None = None,
        Op: np.ndarray | None = None,
    ) -> object:
        """
        Compute collision frequencies using the already-fetched MSIS neutral data.

        Requires ``self.msise`` (call ``fetch_msise()`` first) and electron
        density (call ``fetch_iri()`` or ``set_electron_density()`` first).

        Parameters
        ----------
        Te, Ti : array-like or float, optional
            Electron/ion temperature [K]. Defaults to MSIS neutral temperature Tn.
        edens : array-like, optional
            Electron density [cm^-3]. Defaults to ``self.ne_cm3``.
        O2p, Op : array-like, optional
            O2+ and O+ ion densities [cm^-3].
            Defaults to 10% / 90% of edens (typical F-region mix).

        Returns
        -------
        ComputeCollision
            The collision object is also stored on ``self.collision`` for
            subsequent retrieval by :meth:`RT1D.NVIS_tracer` via
            ``collision_type``.

        Notes
        -----
        Supported collision types for ``NVIS_tracer(collision_type=...)``:

        +-----------+-----------------------------------------------+
        | Key       | Source array                                  |
        +===========+===============================================+
        | ``FT``    | Friedrich-Tonker (nu_ft, a=1.0)               |
        | ``FT_cc`` | Friedrich-Tonker (nu_av_cc, a=2.5)            |
        | ``FT_mb`` | Friedrich-Tonker (nu_av_mb, a=1.5)            |
        | ``SN_en`` | Schunk-Nagy electron-neutral total             |
        | ``SN_ei`` | Schunk-Nagy electron-ion total                 |
        | ``SN``    | Schunk-Nagy full total (en + ei)               |
        | ``atm``   | Atmospheric ion-neutral approximation          |
        +-----------+-----------------------------------------------+
        """
        from hfpytrace.collision import ComputeCollision

        if self.msise is None:
            raise ValueError(
                "MSIS neutral data not available. Call fetch_msise() first."
            )
        if self.ne_cm3 is None:
            raise ValueError(
                "Electron density not set. "
                "Call fetch_iri() or set_electron_density() first."
            )

        Tn = np.asarray(self.msise.Tn, dtype=float)
        ne = np.asarray(self.ne_cm3, dtype=float)

        Te_use = np.asarray(Te, dtype=float) if Te is not None else Tn.copy()
        Ti_use = np.asarray(Ti, dtype=float) if Ti is not None else Tn.copy()
        edens_use = np.asarray(edens, dtype=float) if edens is not None else ne.copy()
        Op_use = np.asarray(Op, dtype=float) if Op is not None else 0.9 * ne
        O2p_use = np.asarray(O2p, dtype=float) if O2p is not None else 0.1 * ne

        # ComputeCollision expects (nh, nr) arrays; wrap 1D profile as (nh, 1).
        cc = ComputeCollision(
            Te=Te_use[:, None],
            Ti=Ti_use[:, None],
            Tn=Tn[:, None],
            edens=edens_use[:, None],
            O2p=O2p_use[:, None],
            Op=Op_use[:, None],
            N2=np.asarray(self.msise.N2, dtype=float)[:, None],
            O2=np.asarray(self.msise.O2, dtype=float)[:, None],
            O=np.asarray(self.msise.O, dtype=float)[:, None],
            H=np.asarray(self.msise.H, dtype=float)[:, None],
            He=np.asarray(self.msise.He, dtype=float)[:, None],
            date=self.time,
        )
        self.collision = cc
        logger.info(
            "Collision computed: nu_ft=[{:.3e},{:.3e}] Hz, nu_sn=[{:.3e},{:.3e}] Hz",
            float(np.nanmin(cc.collision.nu_ft)),
            float(np.nanmax(cc.collision.nu_ft)),
            float(np.nanmin(cc.collision.nu_sn.total)),
            float(np.nanmax(cc.collision.nu_sn.total)),
        )
        return cc

    @staticmethod
    def den_to_plasma_freq_hz(ne_m3: np.ndarray | float) -> np.ndarray:
        ne = np.asarray(ne_m3, dtype=float)
        if np.any(ne < 0):
            raise ValueError("Electron density must be non-negative")
        omega_p = np.sqrt(ne * constants.e**2 / (constants.epsilon_0 * constants.m_e))
        return omega_p / (2.0 * np.pi)

    @staticmethod
    def plasma_freq_to_den(freq_hz: np.ndarray | float) -> np.ndarray:
        f = np.asarray(freq_hz, dtype=float)
        if np.any(f < 0):
            raise ValueError("Plasma frequency must be non-negative")
        return (
            ((2.0 * np.pi * f) ** 2)
            * constants.epsilon_0
            * constants.m_e
            / (constants.e**2)
        )

    @staticmethod
    def inclintation2vertical(
        inclination_deg: np.ndarray | float,
    ) -> np.ndarray:
        return 90.0 - np.abs(np.asarray(inclination_deg, dtype=float))

    @staticmethod
    def inclination_to_vertical_angle(
        inclination_deg: np.ndarray | float,
    ) -> np.ndarray:
        return RT1DProfile.inclintation2vertical(inclination_deg)

    @staticmethod
    def vertical_to_magnetic_angle(inclination_deg: np.ndarray | float) -> np.ndarray:
        return RT1DProfile.inclintation2vertical(inclination_deg)

compute_collision(Te=None, Ti=None, edens=None, O2p=None, Op=None)

Compute collision frequencies using the already-fetched MSIS neutral data.

Requires self.msise (call fetch_msise() first) and electron density (call fetch_iri() or set_electron_density() first).

Parameters

Te, Ti : array-like or float, optional Electron/ion temperature [K]. Defaults to MSIS neutral temperature Tn.

array-like, optional

Electron density [cm^-3]. Defaults to self.ne_cm3.

O2p, Op : array-like, optional O2+ and O+ ion densities [cm^-3]. Defaults to 10% / 90% of edens (typical F-region mix).

Returns

ComputeCollision The collision object is also stored on self.collision for subsequent retrieval by :meth:RT1D.NVIS_tracer via collision_type.

Notes

Supported collision types for NVIS_tracer(collision_type=...):

+-----------+-----------------------------------------------+ | Key | Source array | +===========+===============================================+ | FT | Friedrich-Tonker (nu_ft, a=1.0) | | FT_cc | Friedrich-Tonker (nu_av_cc, a=2.5) | | FT_mb | Friedrich-Tonker (nu_av_mb, a=1.5) | | SN_en | Schunk-Nagy electron-neutral total | | SN_ei | Schunk-Nagy electron-ion total | | SN | Schunk-Nagy full total (en + ei) | | atm | Atmospheric ion-neutral approximation | +-----------+-----------------------------------------------+

Source code in hfpytrace/model/rt1d.py 
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
def compute_collision(
    self,
    Te: np.ndarray | float | None = None,
    Ti: np.ndarray | float | None = None,
    edens: np.ndarray | None = None,
    O2p: np.ndarray | None = None,
    Op: np.ndarray | None = None,
) -> object:
    """
    Compute collision frequencies using the already-fetched MSIS neutral data.

    Requires ``self.msise`` (call ``fetch_msise()`` first) and electron
    density (call ``fetch_iri()`` or ``set_electron_density()`` first).

    Parameters
    ----------
    Te, Ti : array-like or float, optional
        Electron/ion temperature [K]. Defaults to MSIS neutral temperature Tn.
    edens : array-like, optional
        Electron density [cm^-3]. Defaults to ``self.ne_cm3``.
    O2p, Op : array-like, optional
        O2+ and O+ ion densities [cm^-3].
        Defaults to 10% / 90% of edens (typical F-region mix).

    Returns
    -------
    ComputeCollision
        The collision object is also stored on ``self.collision`` for
        subsequent retrieval by :meth:`RT1D.NVIS_tracer` via
        ``collision_type``.

    Notes
    -----
    Supported collision types for ``NVIS_tracer(collision_type=...)``:

    +-----------+-----------------------------------------------+
    | Key       | Source array                                  |
    +===========+===============================================+
    | ``FT``    | Friedrich-Tonker (nu_ft, a=1.0)               |
    | ``FT_cc`` | Friedrich-Tonker (nu_av_cc, a=2.5)            |
    | ``FT_mb`` | Friedrich-Tonker (nu_av_mb, a=1.5)            |
    | ``SN_en`` | Schunk-Nagy electron-neutral total             |
    | ``SN_ei`` | Schunk-Nagy electron-ion total                 |
    | ``SN``    | Schunk-Nagy full total (en + ei)               |
    | ``atm``   | Atmospheric ion-neutral approximation          |
    +-----------+-----------------------------------------------+
    """
    from hfpytrace.collision import ComputeCollision

    if self.msise is None:
        raise ValueError(
            "MSIS neutral data not available. Call fetch_msise() first."
        )
    if self.ne_cm3 is None:
        raise ValueError(
            "Electron density not set. "
            "Call fetch_iri() or set_electron_density() first."
        )

    Tn = np.asarray(self.msise.Tn, dtype=float)
    ne = np.asarray(self.ne_cm3, dtype=float)

    Te_use = np.asarray(Te, dtype=float) if Te is not None else Tn.copy()
    Ti_use = np.asarray(Ti, dtype=float) if Ti is not None else Tn.copy()
    edens_use = np.asarray(edens, dtype=float) if edens is not None else ne.copy()
    Op_use = np.asarray(Op, dtype=float) if Op is not None else 0.9 * ne
    O2p_use = np.asarray(O2p, dtype=float) if O2p is not None else 0.1 * ne

    # ComputeCollision expects (nh, nr) arrays; wrap 1D profile as (nh, 1).
    cc = ComputeCollision(
        Te=Te_use[:, None],
        Ti=Ti_use[:, None],
        Tn=Tn[:, None],
        edens=edens_use[:, None],
        O2p=O2p_use[:, None],
        Op=Op_use[:, None],
        N2=np.asarray(self.msise.N2, dtype=float)[:, None],
        O2=np.asarray(self.msise.O2, dtype=float)[:, None],
        O=np.asarray(self.msise.O, dtype=float)[:, None],
        H=np.asarray(self.msise.H, dtype=float)[:, None],
        He=np.asarray(self.msise.He, dtype=float)[:, None],
        date=self.time,
    )
    self.collision = cc
    logger.info(
        "Collision computed: nu_ft=[{:.3e},{:.3e}] Hz, nu_sn=[{:.3e},{:.3e}] Hz",
        float(np.nanmin(cc.collision.nu_ft)),
        float(np.nanmax(cc.collision.nu_ft)),
        float(np.nanmin(cc.collision.nu_sn.total)),
        float(np.nanmax(cc.collision.nu_sn.total)),
    )
    return cc

RT1D

1D model entry-point that owns a single :class:RT1DProfile.

This initializer is intentionally flexible so callers can construct the profile from:

  1. a pre-built RT1DProfile object, or
  2. a TRACE cfg object (config1D-style namespace), or
  3. explicit scalar/array user inputs.
Parameters
RT1DProfile, optional

Existing profile instance. When provided, this takes precedence and is validated directly.

object, optional

Config namespace used by :meth:RT1DProfile.from_cfg. Can also be used only for defaults (event/lat/lon/heights) when explicit values are partially provided.

datetime | str, optional

Profile timestamp. If omitted and cfg has event, cfg event is used. Otherwise current UTC time is used.

lat, lon : float, optional Profile location. If omitted, inferred from cfg.origin or cfg.route.start.

array-like, optional

Altitude grid [km]. If omitted and cfg is provided, built from start_height_km/end_height_km/height_incriment_km.

ne_m3, ne_cm3 : array-like, optional User-provided electron density. Provide exactly one if overriding model fetch.

str, optional

Density source label when user density is supplied.

fetch_iri, fetch_msise, fetch_geomag : bool, optional If True, populate those profile components during initialization.

int, optional

Worker hint passed to MSIS/cfg-based constructor where supported.

coord_input, coeff_dir : str, optional Geomagnetic options passed to fetch_geomag when requested and not provided by cfg.

Notes
  • This class currently provides initialization/validation orchestration.
  • Frequency conversions remain exposed as static compatibility methods.
Source code in hfpytrace/model/rt1d.py 
 408
 409
 410
 411
 412
 413
 414
 415
 416
 417
 418
 419
 420
 421
 422
 423
 424
 425
 426
 427
 428
 429
 430
 431
 432
 433
 434
 435
 436
 437
 438
 439
 440
 441
 442
 443
 444
 445
 446
 447
 448
 449
 450
 451
 452
 453
 454
 455
 456
 457
 458
 459
 460
 461
 462
 463
 464
 465
 466
 467
 468
 469
 470
 471
 472
 473
 474
 475
 476
 477
 478
 479
 480
 481
 482
 483
 484
 485
 486
 487
 488
 489
 490
 491
 492
 493
 494
 495
 496
 497
 498
 499
 500
 501
 502
 503
 504
 505
 506
 507
 508
 509
 510
 511
 512
 513
 514
 515
 516
 517
 518
 519
 520
 521
 522
 523
 524
 525
 526
 527
 528
 529
 530
 531
 532
 533
 534
 535
 536
 537
 538
 539
 540
 541
 542
 543
 544
 545
 546
 547
 548
 549
 550
 551
 552
 553
 554
 555
 556
 557
 558
 559
 560
 561
 562
 563
 564
 565
 566
 567
 568
 569
 570
 571
 572
 573
 574
 575
 576
 577
 578
 579
 580
 581
 582
 583
 584
 585
 586
 587
 588
 589
 590
 591
 592
 593
 594
 595
 596
 597
 598
 599
 600
 601
 602
 603
 604
 605
 606
 607
 608
 609
 610
 611
 612
 613
 614
 615
 616
 617
 618
 619
 620
 621
 622
 623
 624
 625
 626
 627
 628
 629
 630
 631
 632
 633
 634
 635
 636
 637
 638
 639
 640
 641
 642
 643
 644
 645
 646
 647
 648
 649
 650
 651
 652
 653
 654
 655
 656
 657
 658
 659
 660
 661
 662
 663
 664
 665
 666
 667
 668
 669
 670
 671
 672
 673
 674
 675
 676
 677
 678
 679
 680
 681
 682
 683
 684
 685
 686
 687
 688
 689
 690
 691
 692
 693
 694
 695
 696
 697
 698
 699
 700
 701
 702
 703
 704
 705
 706
 707
 708
 709
 710
 711
 712
 713
 714
 715
 716
 717
 718
 719
 720
 721
 722
 723
 724
 725
 726
 727
 728
 729
 730
 731
 732
 733
 734
 735
 736
 737
 738
 739
 740
 741
 742
 743
 744
 745
 746
 747
 748
 749
 750
 751
 752
 753
 754
 755
 756
 757
 758
 759
 760
 761
 762
 763
 764
 765
 766
 767
 768
 769
 770
 771
 772
 773
 774
 775
 776
 777
 778
 779
 780
 781
 782
 783
 784
 785
 786
 787
 788
 789
 790
 791
 792
 793
 794
 795
 796
 797
 798
 799
 800
 801
 802
 803
 804
 805
 806
 807
 808
 809
 810
 811
 812
 813
 814
 815
 816
 817
 818
 819
 820
 821
 822
 823
 824
 825
 826
 827
 828
 829
 830
 831
 832
 833
 834
 835
 836
 837
 838
 839
 840
 841
 842
 843
 844
 845
 846
 847
 848
 849
 850
 851
 852
 853
 854
 855
 856
 857
 858
 859
 860
 861
 862
 863
 864
 865
 866
 867
 868
 869
 870
 871
 872
 873
 874
 875
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
class RT1D:
    """
    1D model entry-point that owns a single :class:`RT1DProfile`.

    This initializer is intentionally flexible so callers can construct the
    profile from:

    1. a pre-built ``RT1DProfile`` object, or
    2. a TRACE cfg object (``config1D``-style namespace), or
    3. explicit scalar/array user inputs.

    Parameters
    ----------
    profile : RT1DProfile, optional
        Existing profile instance. When provided, this takes precedence and is
        validated directly.
    cfg : object, optional
        Config namespace used by :meth:`RT1DProfile.from_cfg`. Can also be used
        only for defaults (event/lat/lon/heights) when explicit values are
        partially provided.
    time : datetime | str, optional
        Profile timestamp. If omitted and ``cfg`` has ``event``, cfg event is
        used. Otherwise current UTC time is used.
    lat, lon : float, optional
        Profile location. If omitted, inferred from ``cfg.origin`` or
        ``cfg.route.start``.
    alt_km : array-like, optional
        Altitude grid [km]. If omitted and ``cfg`` is provided, built from
        ``start_height_km/end_height_km/height_incriment_km``.
    ne_m3, ne_cm3 : array-like, optional
        User-provided electron density. Provide exactly one if overriding model
        fetch.
    source : str, optional
        Density source label when user density is supplied.
    fetch_iri, fetch_msise, fetch_geomag : bool, optional
        If True, populate those profile components during initialization.
    workers : int, optional
        Worker hint passed to MSIS/cfg-based constructor where supported.
    coord_input, coeff_dir : str, optional
        Geomagnetic options passed to ``fetch_geomag`` when requested and not
        provided by cfg.

    Notes
    -----
    - This class currently provides initialization/validation orchestration.
    - Frequency conversions remain exposed as static compatibility methods.
    """

    def __init__(
        self,
        profile: RT1DProfile | None = None,
        cfg=None,
        time: dt.datetime | str | None = None,
        lat: float | None = None,
        lon: float | None = None,
        alt_km: np.ndarray | None = None,
        ne_m3: np.ndarray | None = None,
        ne_cm3: np.ndarray | None = None,
        source: str = "iri",
        fetch_iri: bool = False,
        fetch_msise: bool = False,
        fetch_geomag: bool = False,
        workers: int = 1,
        coord_input: str = "GEO",
        coeff_dir: str | None = None,
    ):
        logger.info("Initializing RT1D model")
        self.cfg = cfg
        self.workers = int(workers)
        if self.workers < 1:
            raise ValueError("workers must be >= 1")

        # Path 1: caller gives a full profile instance.
        if profile is not None:
            if not isinstance(profile, RT1DProfile):
                raise TypeError("profile must be an RT1DProfile instance")
            if any(v is not None for v in (cfg, lat, lon, alt_km, ne_m3, ne_cm3)):
                raise ValueError(
                    "When `profile` is provided, do not also pass cfg/lat/lon/alt/density inputs."
                )
            self.profile = profile
            self.profile.validate()
            logger.info("RT1D initialized from existing RT1DProfile")
            return

        # Path 2: build directly from cfg when available and no explicit overrides.
        has_explicit_density = (ne_m3 is not None) or (ne_cm3 is not None)
        if (
            cfg is not None
            and lat is None
            and lon is None
            and alt_km is None
            and not has_explicit_density
        ):
            t_cfg = time if time is not None else None
            self.profile = RT1DProfile.from_cfg(
                cfg=cfg,
                time=t_cfg,
                fetch_iri=bool(fetch_iri),
                fetch_msise=bool(fetch_msise),
                fetch_geomag=bool(fetch_geomag),
                workers=self.workers,
            )
            logger.info("RT1D initialized from config-driven profile")
            return

        # Path 3: explicit user assembly, with cfg optionally supplying defaults.
        t = self._resolve_time(time=time, cfg=cfg)
        lat_f, lon_f = self._resolve_location(lat=lat, lon=lon, cfg=cfg)
        alt_arr = self._resolve_altitudes(alt_km=alt_km, cfg=cfg)

        self.profile = RT1DProfile(
            alt_km=alt_arr,
            lat=lat_f,
            lon=lon_f,
            time=t,
        )

        if has_explicit_density:
            self.profile.set_electron_density(
                ne_m3=ne_m3,
                ne_cm3=ne_cm3,
                source=source,
            )
        elif fetch_iri:
            if cfg is None:
                raise ValueError("fetch_iri=True requires cfg for IRI parameters")
            self.profile.fetch_iri(cfg)

        if fetch_msise:
            self.profile.fetch_msise(workers=self.workers)

        if fetch_geomag:
            cdir = coeff_dir
            if cfg is not None and hasattr(cfg, "geomag_grid"):
                coord_input = str(getattr(cfg.geomag_grid, "coord_input", coord_input))
                cdir = getattr(cfg.geomag_grid, "coeff_dir", cdir)
            self.profile.fetch_geomag(coord_input=coord_input, coeff_dir=cdir)

        self.profile.validate()
        logger.info(
            "RT1D ready: lat={:.3f}, lon={:.3f}, alt_points={}, source={}",
            self.profile.lat,
            self.profile.lon,
            self.profile.alt_km.size,
            self.profile.source,
        )

    # ------------------------------------------------------------------
    # Collision type keys understood by NVIS_tracer(collision_type=...)
    # ------------------------------------------------------------------
    _VALID_COLLISION_TYPES: frozenset[str] = frozenset(
        {"FT", "FT_CC", "FT_MB", "SN_EN", "SN_EI", "SN", "ATM"}
    )

    @staticmethod
    def _extract_collision_hz(cc, collision_type: str) -> np.ndarray:
        """
        Extract a 1D collision-frequency array [Hz] from a ComputeCollision
        object using the user-specified type key.

        Parameters
        ----------
        cc : ComputeCollision
            Object returned by ``RT1DProfile.compute_collision()``.
        collision_type : str
            One of ``"FT"``, ``"FT_cc"``, ``"FT_mb"``, ``"SN_en"``,
            ``"SN_ei"``, ``"SN"``, ``"atm"`` (case-insensitive).

        Returns
        -------
        np.ndarray, shape (nh,)
        """
        ct = str(collision_type).strip().upper()
        _map = {
            "FT": lambda c: np.asarray(c.collision.nu_ft[:, 0], dtype=float),
            "FT_CC": lambda c: np.asarray(c.collision.nu_av_cc[:, 0], dtype=float),
            "FT_MB": lambda c: np.asarray(c.collision.nu_av_mb[:, 0], dtype=float),
            "SN_EN": lambda c: np.asarray(
                c.collision.nu_sn.en.total[:, 0], dtype=float
            ),
            "SN_EI": lambda c: np.asarray(
                c.collision.nu_sn.ei.total[:, 0], dtype=float
            ),
            "SN": lambda c: np.asarray(c.collision.nu_sn.total[:, 0], dtype=float),
            "ATM": lambda c: np.asarray(
                c.atmospheric_ion_neutral_collision_frequency()[:, 0], dtype=float
            ),
        }
        if ct not in _map:
            valid = sorted(_map.keys())
            raise ValueError(
                f"Unknown collision_type '{collision_type}'. Valid options: {valid}"
            )
        return _map[ct](cc)

    def fetch_collision(
        self,
        Te: np.ndarray | float | None = None,
        Ti: np.ndarray | float | None = None,
        edens: np.ndarray | None = None,
        O2p: np.ndarray | None = None,
        Op: np.ndarray | None = None,
    ) -> object:
        """
        Compute and attach collision frequencies to the profile.

        Convenience wrapper around :meth:`RT1DProfile.compute_collision`.
        Requires that ``fetch_msise()`` has been called. Plasma defaults
        (Te=Ti=Tn, Op=0.9·Ne, O2p=0.1·Ne) are applied when arguments
        are omitted.

        After calling this, pass ``collision_type`` to
        :meth:`NVIS_tracer` to select which model to use, e.g.::

            rt.fetch_collision()
            result = rt.NVIS_tracer(freq_mhz=freqs, collision_type="SN")

        Returns
        -------
        ComputeCollision
        """
        return self.profile.compute_collision(
            Te=Te,
            Ti=Ti,
            edens=edens,
            O2p=O2p,
            Op=Op,
        )

    @staticmethod
    def _resolve_time(time: dt.datetime | str | None, cfg=None) -> dt.datetime:
        """Resolve profile time from explicit input, cfg event, or UTC now."""
        if time is not None:
            return (
                time
                if isinstance(time, dt.datetime)
                else dt.datetime.fromisoformat(str(time))
            )
        if cfg is not None and hasattr(cfg, "event"):
            return dt.datetime.fromisoformat(str(cfg.event))
        return dt.datetime.utcnow()

    @staticmethod
    def _resolve_location(
        lat: float | None, lon: float | None, cfg=None
    ) -> tuple[float, float]:
        """Resolve lat/lon from explicit values or cfg defaults."""
        if lat is not None and lon is not None:
            return float(lat), float(lon)
        if (lat is None) ^ (lon is None):
            raise ValueError("Provide both lat and lon, or neither")
        if cfg is not None:
            if hasattr(cfg, "origin"):
                return float(cfg.origin.lat), float(cfg.origin.lon)
            if hasattr(cfg, "route") and hasattr(cfg.route, "start"):
                return float(cfg.route.start.lat), float(cfg.route.start.lon)
        raise ValueError(
            "Unable to resolve lat/lon. Provide lat/lon or cfg with origin/route.start."
        )

    @staticmethod
    def _resolve_altitudes(alt_km: np.ndarray | None, cfg=None) -> np.ndarray:
        """Resolve altitude grid from explicit input or cfg height fields."""
        if alt_km is not None:
            arr = np.asarray(alt_km, dtype=float).ravel()
            if arr.size < 2:
                raise ValueError("alt_km must contain at least 2 points")
            return arr
        if cfg is not None:
            h0 = float(getattr(cfg, "start_height_km"))
            h1 = float(getattr(cfg, "end_height_km"))
            dh = float(getattr(cfg, "height_incriment_km", 1.0))
            return np.arange(h0, h1, dh, dtype=float)
        raise ValueError("Unable to resolve altitude grid. Provide alt_km or cfg.")

    def _refractive_index_profile(
        self,
        frequency_hz: float,
        mode: str = "O",
        formulation: str = "appleton",
        collision_hz: np.ndarray | float | None = None,
        b_t: np.ndarray | float | None = None,
        theta_deg: np.ndarray | float | None = None,
    ) -> np.ndarray:
        """
        Build a 1D refractive-index profile n(z) on ``self.profile.alt_km``.

        Parameters
        ----------
        frequency_hz : float
            Wave frequency in Hz.
        mode : str, optional
            Mode selector for the selected formulation.
        formulation : {"appleton", "senwyller"}, optional
            Dispersion relation backend.
        collision_hz, b_t, theta_deg : array-like | scalar, optional
            Optional overrides. If omitted, best-available values are pulled
            from ``self.profile``:
            - collision: 0 (collisionless)
            - b_t: geomag ``bmag_t`` if available else 0
            - theta_deg: geomag ``psi_deg`` if available else 0
        """
        if self.profile.ne_m3 is None:
            raise ValueError("Profile must include electron density (ne_m3).")

        alt = self.profile.alt_km
        ne = self.profile.ne_m3
        nu = (
            np.zeros_like(alt, dtype=float)
            if collision_hz is None
            else np.asarray(collision_hz, dtype=float)
        )
        if b_t is None:
            b = (
                np.asarray(self.profile.geomag.bmag_t, dtype=float)
                if self.profile.geomag is not None
                and hasattr(self.profile.geomag, "bmag_t")
                else np.zeros_like(alt, dtype=float)
            )
        else:
            b = np.asarray(b_t, dtype=float)

        if theta_deg is None:
            psi = (
                np.asarray(self.profile.geomag.psi_deg, dtype=float)
                if self.profile.geomag is not None
                and hasattr(self.profile.geomag, "psi_deg")
                else np.zeros_like(alt, dtype=float)
            )
        else:
            psi = np.asarray(theta_deg, dtype=float)

        form = str(formulation).strip().lower()
        if form == "appleton":
            model = AppletonHartreeDispersion(
                frequency_hz=frequency_hz,
                ne_m3=ne,
                collision_hz=nu,
                b_t=b,
                theta_deg=psi,
            )
        elif form in {"senwyller", "sen-wyller"}:
            model = SenWyllerDispersion(
                frequency_hz=frequency_hz,
                ne_m3=ne,
                collision_hz=nu,
                b_t=b,
                theta_deg=psi,
            )
        else:
            raise ValueError("formulation must be 'appleton' or 'senwyller'")

        n = np.real(model.refractive_index(mode=mode))
        n = np.asarray(n, dtype=float).ravel()
        # guard tiny negatives from numerical noise
        n = np.where(np.isfinite(n), np.clip(n, 0.0, None), np.nan)
        if n.shape != alt.shape:
            raise ValueError("Refractive index profile shape mismatch.")
        return n

    def _dispersion_result_profile(
        self,
        frequency_hz: float,
        mode: str = "O",
        formulation: str = "appleton",
        collision_hz: np.ndarray | float | None = None,
        b_t: np.ndarray | float | None = None,
        theta_deg: np.ndarray | float | None = None,
    ) -> "DispersionResult":
        """Build a full DispersionResult profile on ``self.profile.alt_km``.

        Same model-construction logic as ``_refractive_index_profile`` but
        calls ``model.evaluate()`` so that absorption and phase profiles are
        also returned alongside the complex refractive index.
        """
        if self.profile.ne_m3 is None:
            raise ValueError("Profile must include electron density (ne_m3).")

        alt = self.profile.alt_km
        ne = self.profile.ne_m3
        nu = (
            np.zeros_like(alt, dtype=float)
            if collision_hz is None
            else np.asarray(collision_hz, dtype=float)
        )
        if b_t is None:
            b = (
                np.asarray(self.profile.geomag.bmag_t, dtype=float)
                if self.profile.geomag is not None
                and hasattr(self.profile.geomag, "bmag_t")
                else np.zeros_like(alt, dtype=float)
            )
        else:
            b = np.asarray(b_t, dtype=float)
        if theta_deg is None:
            psi = (
                np.asarray(self.profile.geomag.psi_deg, dtype=float)
                if self.profile.geomag is not None
                and hasattr(self.profile.geomag, "psi_deg")
                else np.zeros_like(alt, dtype=float)
            )
        else:
            psi = np.asarray(theta_deg, dtype=float)

        form = str(formulation).strip().lower()
        if form == "appleton":
            model = AppletonHartreeDispersion(
                frequency_hz=frequency_hz,
                ne_m3=ne,
                collision_hz=nu,
                b_t=b,
                theta_deg=psi,
            )
        elif form in {"senwyller", "sen-wyller"}:
            model = SenWyllerDispersion(
                frequency_hz=frequency_hz,
                ne_m3=ne,
                collision_hz=nu,
                b_t=b,
                theta_deg=psi,
            )
        else:
            raise ValueError("formulation must be 'appleton' or 'senwyller'")
        return model.evaluate(mode=mode)

    @staticmethod
    def _smooth_nonuniform_grid(
        start: float, end: float, n_points: int, sharpness: float
    ) -> np.ndarray:
        """
        Build a smooth nonuniform coordinate in [start, end] with denser
        sampling near ``end``.
        """
        if int(n_points) < 3:
            raise ValueError("n_points must be >= 3")
        u = np.linspace(0.0, 1.0, int(n_points))
        flipped_u = 1.0 - u
        denom = np.exp(float(sharpness)) - 1.0
        if np.isclose(denom, 0.0):
            return np.linspace(float(start), float(end), int(n_points))
        factor = (np.exp(float(sharpness) * flipped_u) - 1.0) / denom
        return 1.0 - (float(start) + (float(end) - float(start)) * factor)

    def NVIS_tracer(
        self,
        freq_mhz: np.ndarray | float,
        mode: str = "O",
        formulation: str = "appleton",
        collision_hz: np.ndarray | float | None = None,
        collision_type: str | None = None,
        b_t: np.ndarray | float | None = None,
        theta_deg: np.ndarray | float | None = None,
        n_floor: float = 1e-8,
        use_nonuniform_grid: bool = True,
        nonuniform_points: int = 240,
        nonuniform_sharpness: float = 10.0,
        compute_absorption_phase: bool = False,
        round_trip: bool = False,
    ) -> SimpleNamespace:
        """
        Vertical-forward-operator style NVIS tracer for a 1D profile.

        Parameters
        ----------
        freq_mhz : array-like or float
            Sounding frequencies in MHz.
        mode : str, optional
            Dispersion mode selector. Supported values are inherited directly
            from the selected dispersion formulation in ``dispersion.py``:
            - Appleton-Hartree: ``N/NO/ISO``, ``O``, ``X``, ``R``, ``L``
            - Sen-Wyller: ``N/NO/ISO``, ``O``, ``X``, ``R``, ``L``
        formulation : {"appleton", "senwyller"}, optional
            Dispersion backend.
        collision_hz : array-like or scalar, optional
            Collision frequency [Hz] as a direct 1D array. Mutually exclusive
            with ``collision_type``.
        collision_type : str, optional
            Named collision model. Requires ``rt.fetch_collision()`` to have
            been called first. Mutually exclusive with ``collision_hz``.
            Valid values: ``"FT"``, ``"FT_cc"``, ``"FT_mb"``, ``"SN_en"``,
            ``"SN_ei"``, ``"SN"``, ``"atm"`` (case-insensitive).
        b_t, theta_deg : array-like or scalar, optional
            Overrides for magnetic field magnitude [T] and wave-normal angle [deg].
        n_floor : float, optional
            Minimum refractive index used to identify valid propagation layers.
        use_nonuniform_grid : bool, optional
            If True, remap each frequency profile onto a stretched vertical
            grid with denser sampling near the turning altitude.
        nonuniform_points : int, optional
            Number of regridded altitude points used when
            ``use_nonuniform_grid=True``.
        nonuniform_sharpness : float, optional
            Stretching strength for nonuniform grid. Larger values concentrate
            more points near the turning altitude.
        compute_absorption_phase : bool, optional
            If True, call ``dispersion.evaluate()`` for each frequency and
            integrate absorption and phase along the propagation path.
            Adds ``absorption_db``, ``phase_rad``, ``absorption_profile``,
            and ``phase_profile`` to the returned namespace.
        round_trip : bool, optional
            If True (and ``compute_absorption_phase=True``), multiply the
            integrated absorption and phase by 2 for a two-way (round-trip)
            path.  Has no effect when ``compute_absorption_phase=False``.

        Returns
        -------
        SimpleNamespace
            - ``freq_mhz``          : frequency array [MHz]
            - ``vh_km``             : virtual-height estimate [km]
            - ``turning_height_km`` : turning heights [km]
            - ``n_profile``         : refractive-index profiles [nfreq, nz]
            - ``reason``            : per-frequency status strings
            - ``absorption_db``     : height-integrated absorption [dB, nfreq]
              (only when ``compute_absorption_phase=True``)
            - ``phase_rad``         : height-integrated phase [rad, nfreq]
              (only when ``compute_absorption_phase=True``)
            - ``absorption_profile``: absorption coefficient [dB/km] on the
              altitude grid [nfreq, nz]
              (only when ``compute_absorption_phase=True``)
            - ``phase_profile``     : phase constant [rad/km] on the altitude
              grid [nfreq, nz]
              (only when ``compute_absorption_phase=True``)

        Notes
        -----
        This method intentionally mirrors a vertical forward operator:
        it integrates an approximate group index ``mu' ~= 1 / n`` from the
        bottom altitude up to the turning point for each frequency.

        **Collision workflow** — two ways to supply collision frequency:

        1. *Direct array*: pass ``collision_hz`` as a 1D array [Hz].
        2. *Named model*: call ``rt.fetch_collision()`` first, then pass
           ``collision_type`` with one of the keys below.  ``collision_hz``
           must be ``None`` when ``collision_type`` is used.

        +-------------+--------------------------------------------------+
        | Key         | Model                                            |
        +=============+==================================================+
        | ``"FT"``    | Friedrich-Tonker (ν_ft, scaling a=1.0)           |
        | ``"FT_cc"`` | Friedrich-Tonker (ν_av_cc, scaling a=2.5)        |
        | ``"FT_mb"`` | Friedrich-Tonker (ν_av_mb, scaling a=1.5)        |
        | ``"SN_en"`` | Schunk-Nagy electron-neutral total               |
        | ``"SN_ei"`` | Schunk-Nagy electron-ion total                   |
        | ``"SN"``    | Schunk-Nagy full (en + ei)                       |
        | ``"atm"``   | Atmospheric ion-neutral approximation            |
        +-------------+--------------------------------------------------+
        """
        # ── Resolve collision frequency ──────────────────────────────────
        if collision_type is not None and collision_hz is not None:
            raise ValueError(
                "Provide at most one of 'collision_hz' or 'collision_type', not both."
            )
        if collision_type is not None:
            if self.profile.collision is None:
                raise ValueError(
                    f"collision_type='{collision_type}' requires pre-computed collision "
                    "data. Call rt.fetch_collision() before NVIS_tracer()."
                )
            collision_hz = self._extract_collision_hz(
                self.profile.collision, collision_type
            )
            logger.info(
                "NVIS_tracer: using collision_type='{}', nu=[{:.3e},{:.3e}] Hz",
                collision_type,
                float(np.nanmin(collision_hz)),
                float(np.nanmax(collision_hz)),
            )

        z = np.asarray(self.profile.alt_km, dtype=float)
        f_mhz = np.atleast_1d(np.asarray(freq_mhz, dtype=float))
        if np.any(f_mhz <= 0.0):
            raise ValueError("All frequencies must be > 0 MHz.")
        mode = str(mode).upper()
        logger.info(
            "NVIS tracer start: mode={}, formulation={}, freq_points={}, "
            "nonuniform_grid={}, collision_type={}",
            mode,
            formulation,
            f_mhz.size,
            bool(use_nonuniform_grid),
            collision_type if collision_type is not None else "none",
        )

        n_all = np.full((f_mhz.size, z.size), np.nan, dtype=float)
        vh = np.full(f_mhz.size, np.nan, dtype=float)
        zt = np.full(f_mhz.size, np.nan, dtype=float)
        reason = np.full(f_mhz.size, "no_propagation", dtype=object)
        if compute_absorption_phase:
            abs_db = np.full(f_mhz.size, np.nan, dtype=float)
            phase_rad_out = np.full(f_mhz.size, np.nan, dtype=float)
            abs_profile_all = np.full((f_mhz.size, z.size), np.nan, dtype=float)
            ph_profile_all = np.full((f_mhz.size, z.size), np.nan, dtype=float)
            _trip = 2.0 if round_trip else 1.0

        z0 = float(np.min(z))
        for i, fm in enumerate(f_mhz):
            # Propagation mask and virtual-height integration use the
            # COLLISIONLESS refractive index (Z = 0).  Any non-zero collision
            # frequency gives Re(n) > 0 even when X > 1 (evanescent wave),
            # which would include sub-cutoff regions and produce absorption
            # hundreds of dB/km.  The collisionless n drops to zero exactly at
            # the plasma cutoff (X = 1), yielding the correct turning point.
            n = self._refractive_index_profile(
                frequency_hz=float(fm) * 1e6,
                mode=mode,
                formulation=formulation,
                collision_hz=0.0,
                b_t=b_t,
                theta_deg=theta_deg,
            )
            n_all[i, :] = n
            if compute_absorption_phase:
                # Full collisional dispersion for absorption/phase; integration
                # bounds are taken from the collisionless mask so the integral
                # never enters the evanescent region.
                dr = self._dispersion_result_profile(
                    frequency_hz=float(fm) * 1e6,
                    mode=mode,
                    formulation=formulation,
                    collision_hz=collision_hz,
                    b_t=b_t,
                    theta_deg=theta_deg,
                )
                abs_profile_all[i, :] = dr.absorption_db_per_km
                ph_profile_all[i, :] = dr.phase_rad_per_km

            mask = np.isfinite(n) & (n > float(n_floor))
            if not np.any(mask):
                reason[i] = "no_propagation"
                continue

            # Use only the first contiguous propagation segment from the bottom.
            # This avoids integrating through disconnected valid layers above a
            # cutoff, which can create non-physical huge virtual heights.
            i_start = int(np.argmax(mask))
            if i_start >= (z.size - 1):
                reason[i] = "no_propagation"
                continue

            i_stop = i_start
            while i_stop < z.size and mask[i_stop]:
                i_stop += 1
            i_top = i_stop - 1
            if (i_top - i_start + 1) < 2:
                reason[i] = "no_propagation"
                continue

            z_raw = z[i_start : i_top + 1]
            z_up = z_raw.copy()
            n_up = n[i_start : i_top + 1]
            if use_nonuniform_grid and z_up.size >= 3:
                m = self._smooth_nonuniform_grid(
                    0.0,
                    1.0,
                    int(nonuniform_points),
                    float(nonuniform_sharpness),
                )
                z_new = z_up[0] + m * (z_up[-1] - z_up[0])
                n_new = np.interp(z_new, z_up, n_up)
                z_up = z_new
                n_up = n_new

            mu_p = 1.0 / np.clip(n_up, float(n_floor), None)
            dz = np.diff(z_up)
            mu_mid = 0.5 * (mu_p[:-1] + mu_p[1:])
            iono_h = np.sum(mu_mid * dz) if dz.size > 0 else 0.0

            zt[i] = float(z_up[-1])
            vh[i] = float(z0 + iono_h)
            reason[i] = "turning" if i_stop < z.size else "top_of_profile"

            if compute_absorption_phase:
                # Integrate absorption on the original fine altitude grid
                # (z_raw, 0.1 km step).  The nonuniform grid concentrates
                # points near the turning height and undersamples the D-layer
                # where most absorption occurs, so we avoid regridding here.
                abs_up = dr.absorption_db_per_km[i_start : i_top + 1]
                ph_up = dr.phase_rad_per_km[i_start : i_top + 1]
                abs_db[i] = _trip * np.trapezoid(abs_up, z_raw)
                phase_rad_out[i] = _trip * np.trapezoid(ph_up, z_raw)

        ns = SimpleNamespace(
            freq_mhz=f_mhz,
            vh_km=vh,
            turning_height_km=zt,
            n_profile=n_all,
            reason=reason,
            alt_km=z,
        )
        if compute_absorption_phase:
            ns.absorption_db = abs_db
            ns.phase_rad = phase_rad_out
            ns.absorption_profile = abs_profile_all
            ns.phase_profile = ph_profile_all
        return ns

    # Compatibility static helpers.
    den_to_plasma_freq_hz = staticmethod(RT1DProfile.den_to_plasma_freq_hz)
    plasma_freq_to_den = staticmethod(RT1DProfile.plasma_freq_to_den)
    vertical_to_magnetic_angle = staticmethod(RT1DProfile.vertical_to_magnetic_angle)
    inclination_to_vertical_angle = staticmethod(
        RT1DProfile.inclination_to_vertical_angle
    )
    inclintation2vertical = staticmethod(RT1DProfile.inclintation2vertical)

fetch_collision(Te=None, Ti=None, edens=None, O2p=None, Op=None)

Compute and attach collision frequencies to the profile.

Convenience wrapper around :meth:RT1DProfile.compute_collision. Requires that fetch_msise() has been called. Plasma defaults (Te=Ti=Tn, Op=0.9·Ne, O2p=0.1·Ne) are applied when arguments are omitted.

After calling this, pass collision_type to :meth:NVIS_tracer to select which model to use, e.g.::

rt.fetch_collision()
result = rt.NVIS_tracer(freq_mhz=freqs, collision_type="SN")
Returns

ComputeCollision

Source code in hfpytrace/model/rt1d.py 
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
def fetch_collision(
    self,
    Te: np.ndarray | float | None = None,
    Ti: np.ndarray | float | None = None,
    edens: np.ndarray | None = None,
    O2p: np.ndarray | None = None,
    Op: np.ndarray | None = None,
) -> object:
    """
    Compute and attach collision frequencies to the profile.

    Convenience wrapper around :meth:`RT1DProfile.compute_collision`.
    Requires that ``fetch_msise()`` has been called. Plasma defaults
    (Te=Ti=Tn, Op=0.9·Ne, O2p=0.1·Ne) are applied when arguments
    are omitted.

    After calling this, pass ``collision_type`` to
    :meth:`NVIS_tracer` to select which model to use, e.g.::

        rt.fetch_collision()
        result = rt.NVIS_tracer(freq_mhz=freqs, collision_type="SN")

    Returns
    -------
    ComputeCollision
    """
    return self.profile.compute_collision(
        Te=Te,
        Ti=Ti,
        edens=edens,
        O2p=O2p,
        Op=Op,
    )

NVIS_tracer(freq_mhz, mode='O', formulation='appleton', collision_hz=None, collision_type=None, b_t=None, theta_deg=None, n_floor=1e-08, use_nonuniform_grid=True, nonuniform_points=240, nonuniform_sharpness=10.0, compute_absorption_phase=False, round_trip=False)

Vertical-forward-operator style NVIS tracer for a 1D profile.

Parameters
array-like or float

Sounding frequencies in MHz.

str, optional

Dispersion mode selector. Supported values are inherited directly from the selected dispersion formulation in dispersion.py: - Appleton-Hartree: N/NO/ISO, O, X, R, L - Sen-Wyller: N/NO/ISO, O, X, R, L

{"appleton", "senwyller"}, optional

Dispersion backend.

array-like or scalar, optional

Collision frequency [Hz] as a direct 1D array. Mutually exclusive with collision_type.

str, optional

Named collision model. Requires rt.fetch_collision() to have been called first. Mutually exclusive with collision_hz. Valid values: "FT", "FT_cc", "FT_mb", "SN_en", "SN_ei", "SN", "atm" (case-insensitive).

b_t, theta_deg : array-like or scalar, optional Overrides for magnetic field magnitude [T] and wave-normal angle [deg].

float, optional

Minimum refractive index used to identify valid propagation layers.

bool, optional

If True, remap each frequency profile onto a stretched vertical grid with denser sampling near the turning altitude.

int, optional

Number of regridded altitude points used when use_nonuniform_grid=True.

float, optional

Stretching strength for nonuniform grid. Larger values concentrate more points near the turning altitude.

bool, optional

If True, call dispersion.evaluate() for each frequency and integrate absorption and phase along the propagation path. Adds absorption_db, phase_rad, absorption_profile, and phase_profile to the returned namespace.

bool, optional

If True (and compute_absorption_phase=True), multiply the integrated absorption and phase by 2 for a two-way (round-trip) path. Has no effect when compute_absorption_phase=False.

Returns

SimpleNamespace - freq_mhz : frequency array [MHz] - vh_km : virtual-height estimate [km] - turning_height_km : turning heights [km] - n_profile : refractive-index profiles [nfreq, nz] - reason : per-frequency status strings - absorption_db : height-integrated absorption [dB, nfreq] (only when compute_absorption_phase=True) - phase_rad : height-integrated phase [rad, nfreq] (only when compute_absorption_phase=True) - absorption_profile: absorption coefficient [dB/km] on the altitude grid [nfreq, nz] (only when compute_absorption_phase=True) - phase_profile : phase constant [rad/km] on the altitude grid [nfreq, nz] (only when compute_absorption_phase=True)

Notes

This method intentionally mirrors a vertical forward operator: it integrates an approximate group index mu' ~= 1 / n from the bottom altitude up to the turning point for each frequency.

Collision workflow — two ways to supply collision frequency:

  1. Direct array: pass collision_hz as a 1D array [Hz].
  2. Named model: call rt.fetch_collision() first, then pass collision_type with one of the keys below. collision_hz must be None when collision_type is used.

+-------------+--------------------------------------------------+ | Key | Model | +=============+==================================================+ | "FT" | Friedrich-Tonker (ν_ft, scaling a=1.0) | | "FT_cc" | Friedrich-Tonker (ν_av_cc, scaling a=2.5) | | "FT_mb" | Friedrich-Tonker (ν_av_mb, scaling a=1.5) | | "SN_en" | Schunk-Nagy electron-neutral total | | "SN_ei" | Schunk-Nagy electron-ion total | | "SN" | Schunk-Nagy full (en + ei) | | "atm" | Atmospheric ion-neutral approximation | +-------------+--------------------------------------------------+

Source code in hfpytrace/model/rt1d.py 
 852
 853
 854
 855
 856
 857
 858
 859
 860
 861
 862
 863
 864
 865
 866
 867
 868
 869
 870
 871
 872
 873
 874
 875
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
def NVIS_tracer(
    self,
    freq_mhz: np.ndarray | float,
    mode: str = "O",
    formulation: str = "appleton",
    collision_hz: np.ndarray | float | None = None,
    collision_type: str | None = None,
    b_t: np.ndarray | float | None = None,
    theta_deg: np.ndarray | float | None = None,
    n_floor: float = 1e-8,
    use_nonuniform_grid: bool = True,
    nonuniform_points: int = 240,
    nonuniform_sharpness: float = 10.0,
    compute_absorption_phase: bool = False,
    round_trip: bool = False,
) -> SimpleNamespace:
    """
    Vertical-forward-operator style NVIS tracer for a 1D profile.

    Parameters
    ----------
    freq_mhz : array-like or float
        Sounding frequencies in MHz.
    mode : str, optional
        Dispersion mode selector. Supported values are inherited directly
        from the selected dispersion formulation in ``dispersion.py``:
        - Appleton-Hartree: ``N/NO/ISO``, ``O``, ``X``, ``R``, ``L``
        - Sen-Wyller: ``N/NO/ISO``, ``O``, ``X``, ``R``, ``L``
    formulation : {"appleton", "senwyller"}, optional
        Dispersion backend.
    collision_hz : array-like or scalar, optional
        Collision frequency [Hz] as a direct 1D array. Mutually exclusive
        with ``collision_type``.
    collision_type : str, optional
        Named collision model. Requires ``rt.fetch_collision()`` to have
        been called first. Mutually exclusive with ``collision_hz``.
        Valid values: ``"FT"``, ``"FT_cc"``, ``"FT_mb"``, ``"SN_en"``,
        ``"SN_ei"``, ``"SN"``, ``"atm"`` (case-insensitive).
    b_t, theta_deg : array-like or scalar, optional
        Overrides for magnetic field magnitude [T] and wave-normal angle [deg].
    n_floor : float, optional
        Minimum refractive index used to identify valid propagation layers.
    use_nonuniform_grid : bool, optional
        If True, remap each frequency profile onto a stretched vertical
        grid with denser sampling near the turning altitude.
    nonuniform_points : int, optional
        Number of regridded altitude points used when
        ``use_nonuniform_grid=True``.
    nonuniform_sharpness : float, optional
        Stretching strength for nonuniform grid. Larger values concentrate
        more points near the turning altitude.
    compute_absorption_phase : bool, optional
        If True, call ``dispersion.evaluate()`` for each frequency and
        integrate absorption and phase along the propagation path.
        Adds ``absorption_db``, ``phase_rad``, ``absorption_profile``,
        and ``phase_profile`` to the returned namespace.
    round_trip : bool, optional
        If True (and ``compute_absorption_phase=True``), multiply the
        integrated absorption and phase by 2 for a two-way (round-trip)
        path.  Has no effect when ``compute_absorption_phase=False``.

    Returns
    -------
    SimpleNamespace
        - ``freq_mhz``          : frequency array [MHz]
        - ``vh_km``             : virtual-height estimate [km]
        - ``turning_height_km`` : turning heights [km]
        - ``n_profile``         : refractive-index profiles [nfreq, nz]
        - ``reason``            : per-frequency status strings
        - ``absorption_db``     : height-integrated absorption [dB, nfreq]
          (only when ``compute_absorption_phase=True``)
        - ``phase_rad``         : height-integrated phase [rad, nfreq]
          (only when ``compute_absorption_phase=True``)
        - ``absorption_profile``: absorption coefficient [dB/km] on the
          altitude grid [nfreq, nz]
          (only when ``compute_absorption_phase=True``)
        - ``phase_profile``     : phase constant [rad/km] on the altitude
          grid [nfreq, nz]
          (only when ``compute_absorption_phase=True``)

    Notes
    -----
    This method intentionally mirrors a vertical forward operator:
    it integrates an approximate group index ``mu' ~= 1 / n`` from the
    bottom altitude up to the turning point for each frequency.

    **Collision workflow** — two ways to supply collision frequency:

    1. *Direct array*: pass ``collision_hz`` as a 1D array [Hz].
    2. *Named model*: call ``rt.fetch_collision()`` first, then pass
       ``collision_type`` with one of the keys below.  ``collision_hz``
       must be ``None`` when ``collision_type`` is used.

    +-------------+--------------------------------------------------+
    | Key         | Model                                            |
    +=============+==================================================+
    | ``"FT"``    | Friedrich-Tonker (ν_ft, scaling a=1.0)           |
    | ``"FT_cc"`` | Friedrich-Tonker (ν_av_cc, scaling a=2.5)        |
    | ``"FT_mb"`` | Friedrich-Tonker (ν_av_mb, scaling a=1.5)        |
    | ``"SN_en"`` | Schunk-Nagy electron-neutral total               |
    | ``"SN_ei"`` | Schunk-Nagy electron-ion total                   |
    | ``"SN"``    | Schunk-Nagy full (en + ei)                       |
    | ``"atm"``   | Atmospheric ion-neutral approximation            |
    +-------------+--------------------------------------------------+
    """
    # ── Resolve collision frequency ──────────────────────────────────
    if collision_type is not None and collision_hz is not None:
        raise ValueError(
            "Provide at most one of 'collision_hz' or 'collision_type', not both."
        )
    if collision_type is not None:
        if self.profile.collision is None:
            raise ValueError(
                f"collision_type='{collision_type}' requires pre-computed collision "
                "data. Call rt.fetch_collision() before NVIS_tracer()."
            )
        collision_hz = self._extract_collision_hz(
            self.profile.collision, collision_type
        )
        logger.info(
            "NVIS_tracer: using collision_type='{}', nu=[{:.3e},{:.3e}] Hz",
            collision_type,
            float(np.nanmin(collision_hz)),
            float(np.nanmax(collision_hz)),
        )

    z = np.asarray(self.profile.alt_km, dtype=float)
    f_mhz = np.atleast_1d(np.asarray(freq_mhz, dtype=float))
    if np.any(f_mhz <= 0.0):
        raise ValueError("All frequencies must be > 0 MHz.")
    mode = str(mode).upper()
    logger.info(
        "NVIS tracer start: mode={}, formulation={}, freq_points={}, "
        "nonuniform_grid={}, collision_type={}",
        mode,
        formulation,
        f_mhz.size,
        bool(use_nonuniform_grid),
        collision_type if collision_type is not None else "none",
    )

    n_all = np.full((f_mhz.size, z.size), np.nan, dtype=float)
    vh = np.full(f_mhz.size, np.nan, dtype=float)
    zt = np.full(f_mhz.size, np.nan, dtype=float)
    reason = np.full(f_mhz.size, "no_propagation", dtype=object)
    if compute_absorption_phase:
        abs_db = np.full(f_mhz.size, np.nan, dtype=float)
        phase_rad_out = np.full(f_mhz.size, np.nan, dtype=float)
        abs_profile_all = np.full((f_mhz.size, z.size), np.nan, dtype=float)
        ph_profile_all = np.full((f_mhz.size, z.size), np.nan, dtype=float)
        _trip = 2.0 if round_trip else 1.0

    z0 = float(np.min(z))
    for i, fm in enumerate(f_mhz):
        # Propagation mask and virtual-height integration use the
        # COLLISIONLESS refractive index (Z = 0).  Any non-zero collision
        # frequency gives Re(n) > 0 even when X > 1 (evanescent wave),
        # which would include sub-cutoff regions and produce absorption
        # hundreds of dB/km.  The collisionless n drops to zero exactly at
        # the plasma cutoff (X = 1), yielding the correct turning point.
        n = self._refractive_index_profile(
            frequency_hz=float(fm) * 1e6,
            mode=mode,
            formulation=formulation,
            collision_hz=0.0,
            b_t=b_t,
            theta_deg=theta_deg,
        )
        n_all[i, :] = n
        if compute_absorption_phase:
            # Full collisional dispersion for absorption/phase; integration
            # bounds are taken from the collisionless mask so the integral
            # never enters the evanescent region.
            dr = self._dispersion_result_profile(
                frequency_hz=float(fm) * 1e6,
                mode=mode,
                formulation=formulation,
                collision_hz=collision_hz,
                b_t=b_t,
                theta_deg=theta_deg,
            )
            abs_profile_all[i, :] = dr.absorption_db_per_km
            ph_profile_all[i, :] = dr.phase_rad_per_km

        mask = np.isfinite(n) & (n > float(n_floor))
        if not np.any(mask):
            reason[i] = "no_propagation"
            continue

        # Use only the first contiguous propagation segment from the bottom.
        # This avoids integrating through disconnected valid layers above a
        # cutoff, which can create non-physical huge virtual heights.
        i_start = int(np.argmax(mask))
        if i_start >= (z.size - 1):
            reason[i] = "no_propagation"
            continue

        i_stop = i_start
        while i_stop < z.size and mask[i_stop]:
            i_stop += 1
        i_top = i_stop - 1
        if (i_top - i_start + 1) < 2:
            reason[i] = "no_propagation"
            continue

        z_raw = z[i_start : i_top + 1]
        z_up = z_raw.copy()
        n_up = n[i_start : i_top + 1]
        if use_nonuniform_grid and z_up.size >= 3:
            m = self._smooth_nonuniform_grid(
                0.0,
                1.0,
                int(nonuniform_points),
                float(nonuniform_sharpness),
            )
            z_new = z_up[0] + m * (z_up[-1] - z_up[0])
            n_new = np.interp(z_new, z_up, n_up)
            z_up = z_new
            n_up = n_new

        mu_p = 1.0 / np.clip(n_up, float(n_floor), None)
        dz = np.diff(z_up)
        mu_mid = 0.5 * (mu_p[:-1] + mu_p[1:])
        iono_h = np.sum(mu_mid * dz) if dz.size > 0 else 0.0

        zt[i] = float(z_up[-1])
        vh[i] = float(z0 + iono_h)
        reason[i] = "turning" if i_stop < z.size else "top_of_profile"

        if compute_absorption_phase:
            # Integrate absorption on the original fine altitude grid
            # (z_raw, 0.1 km step).  The nonuniform grid concentrates
            # points near the turning height and undersamples the D-layer
            # where most absorption occurs, so we avoid regridding here.
            abs_up = dr.absorption_db_per_km[i_start : i_top + 1]
            ph_up = dr.phase_rad_per_km[i_start : i_top + 1]
            abs_db[i] = _trip * np.trapezoid(abs_up, z_raw)
            phase_rad_out[i] = _trip * np.trapezoid(ph_up, z_raw)

    ns = SimpleNamespace(
        freq_mhz=f_mhz,
        vh_km=vh,
        turning_height_km=zt,
        n_profile=n_all,
        reason=reason,
        alt_km=z,
    )
    if compute_absorption_phase:
        ns.absorption_db = abs_db
        ns.phase_rad = phase_rad_out
        ns.absorption_profile = abs_profile_all
        ns.phase_profile = ph_profile_all
    return ns

Source Code

hfpytrace/model/rt1d.py
   1
   2
   3
   4
   5
   6
   7
   8
   9
  10
  11
  12
  13
  14
  15
  16
  17
  18
  19
  20
  21
  22
  23
  24
  25
  26
  27
  28
  29
  30
  31
  32
  33
  34
  35
  36
  37
  38
  39
  40
  41
  42
  43
  44
  45
  46
  47
  48
  49
  50
  51
  52
  53
  54
  55
  56
  57
  58
  59
  60
  61
  62
  63
  64
  65
  66
  67
  68
  69
  70
  71
  72
  73
  74
  75
  76
  77
  78
  79
  80
  81
  82
  83
  84
  85
  86
  87
  88
  89
  90
  91
  92
  93
  94
  95
  96
  97
  98
  99
 100
 101
 102
 103
 104
 105
 106
 107
 108
 109
 110
 111
 112
 113
 114
 115
 116
 117
 118
 119
 120
 121
 122
 123
 124
 125
 126
 127
 128
 129
 130
 131
 132
 133
 134
 135
 136
 137
 138
 139
 140
 141
 142
 143
 144
 145
 146
 147
 148
 149
 150
 151
 152
 153
 154
 155
 156
 157
 158
 159
 160
 161
 162
 163
 164
 165
 166
 167
 168
 169
 170
 171
 172
 173
 174
 175
 176
 177
 178
 179
 180
 181
 182
 183
 184
 185
 186
 187
 188
 189
 190
 191
 192
 193
 194
 195
 196
 197
 198
 199
 200
 201
 202
 203
 204
 205
 206
 207
 208
 209
 210
 211
 212
 213
 214
 215
 216
 217
 218
 219
 220
 221
 222
 223
 224
 225
 226
 227
 228
 229
 230
 231
 232
 233
 234
 235
 236
 237
 238
 239
 240
 241
 242
 243
 244
 245
 246
 247
 248
 249
 250
 251
 252
 253
 254
 255
 256
 257
 258
 259
 260
 261
 262
 263
 264
 265
 266
 267
 268
 269
 270
 271
 272
 273
 274
 275
 276
 277
 278
 279
 280
 281
 282
 283
 284
 285
 286
 287
 288
 289
 290
 291
 292
 293
 294
 295
 296
 297
 298
 299
 300
 301
 302
 303
 304
 305
 306
 307
 308
 309
 310
 311
 312
 313
 314
 315
 316
 317
 318
 319
 320
 321
 322
 323
 324
 325
 326
 327
 328
 329
 330
 331
 332
 333
 334
 335
 336
 337
 338
 339
 340
 341
 342
 343
 344
 345
 346
 347
 348
 349
 350
 351
 352
 353
 354
 355
 356
 357
 358
 359
 360
 361
 362
 363
 364
 365
 366
 367
 368
 369
 370
 371
 372
 373
 374
 375
 376
 377
 378
 379
 380
 381
 382
 383
 384
 385
 386
 387
 388
 389
 390
 391
 392
 393
 394
 395
 396
 397
 398
 399
 400
 401
 402
 403
 404
 405
 406
 407
 408
 409
 410
 411
 412
 413
 414
 415
 416
 417
 418
 419
 420
 421
 422
 423
 424
 425
 426
 427
 428
 429
 430
 431
 432
 433
 434
 435
 436
 437
 438
 439
 440
 441
 442
 443
 444
 445
 446
 447
 448
 449
 450
 451
 452
 453
 454
 455
 456
 457
 458
 459
 460
 461
 462
 463
 464
 465
 466
 467
 468
 469
 470
 471
 472
 473
 474
 475
 476
 477
 478
 479
 480
 481
 482
 483
 484
 485
 486
 487
 488
 489
 490
 491
 492
 493
 494
 495
 496
 497
 498
 499
 500
 501
 502
 503
 504
 505
 506
 507
 508
 509
 510
 511
 512
 513
 514
 515
 516
 517
 518
 519
 520
 521
 522
 523
 524
 525
 526
 527
 528
 529
 530
 531
 532
 533
 534
 535
 536
 537
 538
 539
 540
 541
 542
 543
 544
 545
 546
 547
 548
 549
 550
 551
 552
 553
 554
 555
 556
 557
 558
 559
 560
 561
 562
 563
 564
 565
 566
 567
 568
 569
 570
 571
 572
 573
 574
 575
 576
 577
 578
 579
 580
 581
 582
 583
 584
 585
 586
 587
 588
 589
 590
 591
 592
 593
 594
 595
 596
 597
 598
 599
 600
 601
 602
 603
 604
 605
 606
 607
 608
 609
 610
 611
 612
 613
 614
 615
 616
 617
 618
 619
 620
 621
 622
 623
 624
 625
 626
 627
 628
 629
 630
 631
 632
 633
 634
 635
 636
 637
 638
 639
 640
 641
 642
 643
 644
 645
 646
 647
 648
 649
 650
 651
 652
 653
 654
 655
 656
 657
 658
 659
 660
 661
 662
 663
 664
 665
 666
 667
 668
 669
 670
 671
 672
 673
 674
 675
 676
 677
 678
 679
 680
 681
 682
 683
 684
 685
 686
 687
 688
 689
 690
 691
 692
 693
 694
 695
 696
 697
 698
 699
 700
 701
 702
 703
 704
 705
 706
 707
 708
 709
 710
 711
 712
 713
 714
 715
 716
 717
 718
 719
 720
 721
 722
 723
 724
 725
 726
 727
 728
 729
 730
 731
 732
 733
 734
 735
 736
 737
 738
 739
 740
 741
 742
 743
 744
 745
 746
 747
 748
 749
 750
 751
 752
 753
 754
 755
 756
 757
 758
 759
 760
 761
 762
 763
 764
 765
 766
 767
 768
 769
 770
 771
 772
 773
 774
 775
 776
 777
 778
 779
 780
 781
 782
 783
 784
 785
 786
 787
 788
 789
 790
 791
 792
 793
 794
 795
 796
 797
 798
 799
 800
 801
 802
 803
 804
 805
 806
 807
 808
 809
 810
 811
 812
 813
 814
 815
 816
 817
 818
 819
 820
 821
 822
 823
 824
 825
 826
 827
 828
 829
 830
 831
 832
 833
 834
 835
 836
 837
 838
 839
 840
 841
 842
 843
 844
 845
 846
 847
 848
 849
 850
 851
 852
 853
 854
 855
 856
 857
 858
 859
 860
 861
 862
 863
 864
 865
 866
 867
 868
 869
 870
 871
 872
 873
 874
 875
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
"""1D single-point ionospheric profile and tracer.

Provides a lightweight vertical-profile container and a 1D ray tracer that
evaluates IRI-2016 electron density, NRLMSISE-00 neutral atmosphere, and IGRF
geomagnetic fields at a single (lat, lon) location.

Classes
-------
RT1DProfile
    Dataclass holding all 1D altitude-profile fields (Ne, neutral densities,
    temperatures, magnetic field components) at one geographic point.
RT1D
    Entry-point that owns an :class:`RT1DProfile` and exposes dispersion
    evaluation and absorption calculation methods.

Typical usage
-------------
>>> from hfpytrace.model import RT1D
>>> rt = RT1D(cfg=cfg, fetch_iri=True, fetch_msise=True, fetch_geomag=True)
>>> result = rt.dispersion(freq_hz=7e6, mode="O")
"""

from __future__ import annotations

import datetime as dt
from dataclasses import dataclass
from types import SimpleNamespace

import numpy as np
from loguru import logger
from scipy import constants

from hfpytrace.collision import NRLMSISE2D
from hfpytrace.density.iri import IRI2d
from hfpytrace.geomag import build_geomag_grid
from hfpytrace.model.dispersion import AppletonHartreeDispersion, SenWyllerDispersion


@dataclass
class RT1DProfile:
    """
    Single-point altitude profile for ray/ionosphere workflows.

    Notes
    -----
    - `alt_km` is required and must be strictly increasing.
    - Electron density is stored in both m^-3 and cm^-3 (when available).
    - MSIS and geomagnetic outputs are attached as namespaces.
    """

    alt_km: np.ndarray
    lat: float
    lon: float
    time: dt.datetime
    ne_m3: np.ndarray | None = None
    ne_cm3: np.ndarray | None = None
    source: str = "iri"
    msise: SimpleNamespace | None = None
    geomag: SimpleNamespace | None = None
    collision: object | None = (
        None  # ComputeCollision instance after compute_collision()
    )

    def __post_init__(self) -> None:
        self.alt_km = np.asarray(self.alt_km, dtype=float).ravel()
        self.lat = float(self.lat)
        self.lon = float(self.lon)
        if not isinstance(self.time, dt.datetime):
            self.time = dt.datetime.fromisoformat(str(self.time))
        self.validate()

    def validate(self) -> None:
        if self.alt_km.ndim != 1 or self.alt_km.size < 2:
            raise ValueError("alt_km must be a 1D array with at least 2 points")
        if not np.all(np.diff(self.alt_km) > 0):
            raise ValueError("alt_km must be strictly increasing")
        if not np.isfinite(self.lat) or not np.isfinite(self.lon):
            raise ValueError("lat/lon must be finite")

        if self.ne_m3 is not None:
            self.ne_m3 = np.asarray(self.ne_m3, dtype=float).ravel()
            if self.ne_m3.shape != self.alt_km.shape:
                raise ValueError("ne_m3 must match alt_km shape")
            if np.any(self.ne_m3 < 0):
                raise ValueError("ne_m3 must be non-negative")
            self.ne_cm3 = self.ne_m3 * 1e-6
        elif self.ne_cm3 is not None:
            self.ne_cm3 = np.asarray(self.ne_cm3, dtype=float).ravel()
            if self.ne_cm3.shape != self.alt_km.shape:
                raise ValueError("ne_cm3 must match alt_km shape")
            if np.any(self.ne_cm3 < 0):
                raise ValueError("ne_cm3 must be non-negative")
            self.ne_m3 = self.ne_cm3 * 1e6

        if self.msise is not None:
            for k in ("N2", "O2", "O", "H", "He", "Tn"):
                if not hasattr(self.msise, k):
                    raise ValueError(f"msise missing required field: {k}")
                arr = np.asarray(getattr(self.msise, k), dtype=float).ravel()
                if arr.shape != self.alt_km.shape:
                    raise ValueError(f"msise.{k} must match alt_km shape")
                setattr(self.msise, k, arr)

        if self.geomag is not None:
            for k in ("Bx", "By", "Bz", "bmag_t", "inc_deg", "psi_deg"):
                if not hasattr(self.geomag, k):
                    raise ValueError(f"geomag missing required field: {k}")
                arr = np.asarray(getattr(self.geomag, k), dtype=float).ravel()
                if arr.shape != self.alt_km.shape:
                    raise ValueError(f"geomag.{k} must match alt_km shape")
                setattr(self.geomag, k, arr)

    @classmethod
    def from_cfg(
        cls,
        cfg,
        time: dt.datetime | None = None,
        lat: float | None = None,
        lon: float | None = None,
        alt_km: np.ndarray | None = None,
        fetch_iri: bool = True,
        fetch_msise: bool = True,
        fetch_geomag: bool = True,
        workers: int = 1,
    ) -> "RT1DProfile":
        logger.info("RT1DProfile.from_cfg: build profile from config")
        t = time if time is not None else dt.datetime.fromisoformat(str(cfg.event))
        if lat is None or lon is None:
            if hasattr(cfg, "origin"):
                lat = float(cfg.origin.lat)
                lon = float(cfg.origin.lon)
            elif hasattr(cfg, "route") and hasattr(cfg.route, "start"):
                lat = float(cfg.route.start.lat)
                lon = float(cfg.route.start.lon)
            else:
                raise ValueError("Unable to infer lat/lon from cfg. Provide lat/lon.")

        if alt_km is None:
            h0 = float(getattr(cfg, "start_height_km"))
            h1 = float(getattr(cfg, "end_height_km"))
            dh = float(getattr(cfg, "height_incriment_km", 1.0))
            alt_km = np.arange(h0, h1, dh, dtype=float)

        prof = cls(alt_km=alt_km, lat=float(lat), lon=float(lon), time=t)
        logger.info(
            "RT1DProfile created: lat={:.3f}, lon={:.3f}, alt_points={}",
            prof.lat,
            prof.lon,
            prof.alt_km.size,
        )
        if fetch_iri:
            prof.fetch_iri(cfg)
        if fetch_msise:
            prof.fetch_msise(workers=workers)
        if fetch_geomag:
            gm_cfg = getattr(cfg, "geomag_grid", SimpleNamespace(coord_input="GEO"))
            prof.fetch_geomag(
                coord_input=str(getattr(gm_cfg, "coord_input", "GEO")),
                coeff_dir=getattr(gm_cfg, "coeff_dir", None),
            )
        prof.validate()
        return prof

    def set_electron_density(
        self,
        ne_m3: np.ndarray | None = None,
        ne_cm3: np.ndarray | None = None,
        source: str = "iri",
    ) -> None:
        if (ne_m3 is None) == (ne_cm3 is None):
            raise ValueError("Provide exactly one of ne_m3 or ne_cm3")
        self.source = str(source)
        if ne_m3 is not None:
            self.ne_m3 = np.asarray(ne_m3, dtype=float).ravel()
            self.ne_cm3 = self.ne_m3 * 1e-6
        else:
            self.ne_cm3 = np.asarray(ne_cm3, dtype=float).ravel()
            self.ne_m3 = self.ne_cm3 * 1e6
        self.validate()

    def fetch_iri(self, cfg) -> np.ndarray:
        logger.info(
            "Fetching IRI profile: lat={:.3f}, lon={:.3f}, alt_points={}",
            self.lat,
            self.lon,
            self.alt_km.size,
        )
        model = IRI2d(cfg, self.time)
        ne_cm3, _ = model.fetch_dataset(
            self.time,
            lats=np.array([self.lat], dtype=float),
            lons=np.array([self.lon], dtype=float),
            alts=self.alt_km,
            workers=1,
        )
        self.ne_cm3 = np.asarray(ne_cm3[:, 0], dtype=float)
        self.ne_m3 = self.ne_cm3 * 1e6
        self.source = "iri"
        self.validate()
        logger.info(
            "IRI profile fetched: ne range [{:.3e}, {:.3e}] m^-3",
            float(np.nanmin(self.ne_m3)),
            float(np.nanmax(self.ne_m3)),
        )
        return self.ne_m3

    def fetch_msise(
        self,
        workers: int = 1,
        update_spaceweather: bool = False,
        suppress_spaceweather_warning: bool = True,
    ) -> SimpleNamespace:
        logger.info(
            "Fetching NRLMSISE profile: lat={:.3f}, lon={:.3f}, alt_points={}, workers={}",
            self.lat,
            self.lon,
            self.alt_km.size,
            int(workers),
        )
        ms = NRLMSISE2D(
            date=self.time,
            lats=np.array([self.lat], dtype=float),
            lons=np.array([self.lon], dtype=float),
            heights_km=self.alt_km,
            workers=int(workers),
            update_spaceweather=bool(update_spaceweather),
            suppress_spaceweather_warning=bool(suppress_spaceweather_warning),
        ).msise
        self.msise = SimpleNamespace(
            N2=np.asarray(ms["N2"][:, 0], dtype=float),
            O2=np.asarray(ms["O2"][:, 0], dtype=float),
            O=np.asarray(ms["O"][:, 0], dtype=float),
            H=np.asarray(ms["H"][:, 0], dtype=float),
            He=np.asarray(ms["He"][:, 0], dtype=float),
            Tn=np.asarray(ms["Tn"][:, 0], dtype=float),
            t_nn=np.asarray(ms["t_nn"][:, 0], dtype=float),
        )
        self.validate()
        logger.info("NRLMSISE profile fetched successfully.")
        return self.msise

    def fetch_geomag(
        self,
        coord_input: str = "GEO",
        coeff_dir: str | None = None,
    ) -> SimpleNamespace:
        logger.info(
            "Fetching geomag profile: lat={:.3f}, lon={:.3f}, alt_points={}, coord_input={}",
            self.lat,
            self.lon,
            self.alt_km.size,
            coord_input,
        )
        cdir = None
        if isinstance(coeff_dir, str) and coeff_dir.strip():
            cdir = coeff_dir
        gm = build_geomag_grid(
            lats=np.array([self.lat], dtype=float),
            lons=np.array([self.lon], dtype=float),
            alts_km=self.alt_km,
            time=self.time,
            coord_input=coord_input,
            coeff_dir=cdir,
        )
        self.geomag = SimpleNamespace(
            Bx=np.asarray(gm.Bx[0, 0, :], dtype=float),
            By=np.asarray(gm.By[0, 0, :], dtype=float),
            Bz=np.asarray(gm.Bz[0, 0, :], dtype=float),
            bmag_t=np.asarray(gm.bmag_t[0, 0, :], dtype=float),
            inc_deg=np.asarray(gm.inc_deg[0, 0, :], dtype=float),
            dec_deg=np.asarray(gm.dec_deg[0, 0, :], dtype=float),
            psi_deg=np.asarray(gm.psi_deg[0, 0, :], dtype=float),
        )
        self.validate()
        logger.info("Geomag profile fetched successfully.")
        return self.geomag

    def compute_collision(
        self,
        Te: np.ndarray | float | None = None,
        Ti: np.ndarray | float | None = None,
        edens: np.ndarray | None = None,
        O2p: np.ndarray | None = None,
        Op: np.ndarray | None = None,
    ) -> object:
        """
        Compute collision frequencies using the already-fetched MSIS neutral data.

        Requires ``self.msise`` (call ``fetch_msise()`` first) and electron
        density (call ``fetch_iri()`` or ``set_electron_density()`` first).

        Parameters
        ----------
        Te, Ti : array-like or float, optional
            Electron/ion temperature [K]. Defaults to MSIS neutral temperature Tn.
        edens : array-like, optional
            Electron density [cm^-3]. Defaults to ``self.ne_cm3``.
        O2p, Op : array-like, optional
            O2+ and O+ ion densities [cm^-3].
            Defaults to 10% / 90% of edens (typical F-region mix).

        Returns
        -------
        ComputeCollision
            The collision object is also stored on ``self.collision`` for
            subsequent retrieval by :meth:`RT1D.NVIS_tracer` via
            ``collision_type``.

        Notes
        -----
        Supported collision types for ``NVIS_tracer(collision_type=...)``:

        +-----------+-----------------------------------------------+
        | Key       | Source array                                  |
        +===========+===============================================+
        | ``FT``    | Friedrich-Tonker (nu_ft, a=1.0)               |
        | ``FT_cc`` | Friedrich-Tonker (nu_av_cc, a=2.5)            |
        | ``FT_mb`` | Friedrich-Tonker (nu_av_mb, a=1.5)            |
        | ``SN_en`` | Schunk-Nagy electron-neutral total             |
        | ``SN_ei`` | Schunk-Nagy electron-ion total                 |
        | ``SN``    | Schunk-Nagy full total (en + ei)               |
        | ``atm``   | Atmospheric ion-neutral approximation          |
        +-----------+-----------------------------------------------+
        """
        from hfpytrace.collision import ComputeCollision

        if self.msise is None:
            raise ValueError(
                "MSIS neutral data not available. Call fetch_msise() first."
            )
        if self.ne_cm3 is None:
            raise ValueError(
                "Electron density not set. "
                "Call fetch_iri() or set_electron_density() first."
            )

        Tn = np.asarray(self.msise.Tn, dtype=float)
        ne = np.asarray(self.ne_cm3, dtype=float)

        Te_use = np.asarray(Te, dtype=float) if Te is not None else Tn.copy()
        Ti_use = np.asarray(Ti, dtype=float) if Ti is not None else Tn.copy()
        edens_use = np.asarray(edens, dtype=float) if edens is not None else ne.copy()
        Op_use = np.asarray(Op, dtype=float) if Op is not None else 0.9 * ne
        O2p_use = np.asarray(O2p, dtype=float) if O2p is not None else 0.1 * ne

        # ComputeCollision expects (nh, nr) arrays; wrap 1D profile as (nh, 1).
        cc = ComputeCollision(
            Te=Te_use[:, None],
            Ti=Ti_use[:, None],
            Tn=Tn[:, None],
            edens=edens_use[:, None],
            O2p=O2p_use[:, None],
            Op=Op_use[:, None],
            N2=np.asarray(self.msise.N2, dtype=float)[:, None],
            O2=np.asarray(self.msise.O2, dtype=float)[:, None],
            O=np.asarray(self.msise.O, dtype=float)[:, None],
            H=np.asarray(self.msise.H, dtype=float)[:, None],
            He=np.asarray(self.msise.He, dtype=float)[:, None],
            date=self.time,
        )
        self.collision = cc
        logger.info(
            "Collision computed: nu_ft=[{:.3e},{:.3e}] Hz, nu_sn=[{:.3e},{:.3e}] Hz",
            float(np.nanmin(cc.collision.nu_ft)),
            float(np.nanmax(cc.collision.nu_ft)),
            float(np.nanmin(cc.collision.nu_sn.total)),
            float(np.nanmax(cc.collision.nu_sn.total)),
        )
        return cc

    @staticmethod
    def den_to_plasma_freq_hz(ne_m3: np.ndarray | float) -> np.ndarray:
        ne = np.asarray(ne_m3, dtype=float)
        if np.any(ne < 0):
            raise ValueError("Electron density must be non-negative")
        omega_p = np.sqrt(ne * constants.e**2 / (constants.epsilon_0 * constants.m_e))
        return omega_p / (2.0 * np.pi)

    @staticmethod
    def plasma_freq_to_den(freq_hz: np.ndarray | float) -> np.ndarray:
        f = np.asarray(freq_hz, dtype=float)
        if np.any(f < 0):
            raise ValueError("Plasma frequency must be non-negative")
        return (
            ((2.0 * np.pi * f) ** 2)
            * constants.epsilon_0
            * constants.m_e
            / (constants.e**2)
        )

    @staticmethod
    def inclintation2vertical(
        inclination_deg: np.ndarray | float,
    ) -> np.ndarray:
        return 90.0 - np.abs(np.asarray(inclination_deg, dtype=float))

    @staticmethod
    def inclination_to_vertical_angle(
        inclination_deg: np.ndarray | float,
    ) -> np.ndarray:
        return RT1DProfile.inclintation2vertical(inclination_deg)

    @staticmethod
    def vertical_to_magnetic_angle(inclination_deg: np.ndarray | float) -> np.ndarray:
        return RT1DProfile.inclintation2vertical(inclination_deg)


class RT1D:
    """
    1D model entry-point that owns a single :class:`RT1DProfile`.

    This initializer is intentionally flexible so callers can construct the
    profile from:

    1. a pre-built ``RT1DProfile`` object, or
    2. a TRACE cfg object (``config1D``-style namespace), or
    3. explicit scalar/array user inputs.

    Parameters
    ----------
    profile : RT1DProfile, optional
        Existing profile instance. When provided, this takes precedence and is
        validated directly.
    cfg : object, optional
        Config namespace used by :meth:`RT1DProfile.from_cfg`. Can also be used
        only for defaults (event/lat/lon/heights) when explicit values are
        partially provided.
    time : datetime | str, optional
        Profile timestamp. If omitted and ``cfg`` has ``event``, cfg event is
        used. Otherwise current UTC time is used.
    lat, lon : float, optional
        Profile location. If omitted, inferred from ``cfg.origin`` or
        ``cfg.route.start``.
    alt_km : array-like, optional
        Altitude grid [km]. If omitted and ``cfg`` is provided, built from
        ``start_height_km/end_height_km/height_incriment_km``.
    ne_m3, ne_cm3 : array-like, optional
        User-provided electron density. Provide exactly one if overriding model
        fetch.
    source : str, optional
        Density source label when user density is supplied.
    fetch_iri, fetch_msise, fetch_geomag : bool, optional
        If True, populate those profile components during initialization.
    workers : int, optional
        Worker hint passed to MSIS/cfg-based constructor where supported.
    coord_input, coeff_dir : str, optional
        Geomagnetic options passed to ``fetch_geomag`` when requested and not
        provided by cfg.

    Notes
    -----
    - This class currently provides initialization/validation orchestration.
    - Frequency conversions remain exposed as static compatibility methods.
    """

    def __init__(
        self,
        profile: RT1DProfile | None = None,
        cfg=None,
        time: dt.datetime | str | None = None,
        lat: float | None = None,
        lon: float | None = None,
        alt_km: np.ndarray | None = None,
        ne_m3: np.ndarray | None = None,
        ne_cm3: np.ndarray | None = None,
        source: str = "iri",
        fetch_iri: bool = False,
        fetch_msise: bool = False,
        fetch_geomag: bool = False,
        workers: int = 1,
        coord_input: str = "GEO",
        coeff_dir: str | None = None,
    ):
        logger.info("Initializing RT1D model")
        self.cfg = cfg
        self.workers = int(workers)
        if self.workers < 1:
            raise ValueError("workers must be >= 1")

        # Path 1: caller gives a full profile instance.
        if profile is not None:
            if not isinstance(profile, RT1DProfile):
                raise TypeError("profile must be an RT1DProfile instance")
            if any(v is not None for v in (cfg, lat, lon, alt_km, ne_m3, ne_cm3)):
                raise ValueError(
                    "When `profile` is provided, do not also pass cfg/lat/lon/alt/density inputs."
                )
            self.profile = profile
            self.profile.validate()
            logger.info("RT1D initialized from existing RT1DProfile")
            return

        # Path 2: build directly from cfg when available and no explicit overrides.
        has_explicit_density = (ne_m3 is not None) or (ne_cm3 is not None)
        if (
            cfg is not None
            and lat is None
            and lon is None
            and alt_km is None
            and not has_explicit_density
        ):
            t_cfg = time if time is not None else None
            self.profile = RT1DProfile.from_cfg(
                cfg=cfg,
                time=t_cfg,
                fetch_iri=bool(fetch_iri),
                fetch_msise=bool(fetch_msise),
                fetch_geomag=bool(fetch_geomag),
                workers=self.workers,
            )
            logger.info("RT1D initialized from config-driven profile")
            return

        # Path 3: explicit user assembly, with cfg optionally supplying defaults.
        t = self._resolve_time(time=time, cfg=cfg)
        lat_f, lon_f = self._resolve_location(lat=lat, lon=lon, cfg=cfg)
        alt_arr = self._resolve_altitudes(alt_km=alt_km, cfg=cfg)

        self.profile = RT1DProfile(
            alt_km=alt_arr,
            lat=lat_f,
            lon=lon_f,
            time=t,
        )

        if has_explicit_density:
            self.profile.set_electron_density(
                ne_m3=ne_m3,
                ne_cm3=ne_cm3,
                source=source,
            )
        elif fetch_iri:
            if cfg is None:
                raise ValueError("fetch_iri=True requires cfg for IRI parameters")
            self.profile.fetch_iri(cfg)

        if fetch_msise:
            self.profile.fetch_msise(workers=self.workers)

        if fetch_geomag:
            cdir = coeff_dir
            if cfg is not None and hasattr(cfg, "geomag_grid"):
                coord_input = str(getattr(cfg.geomag_grid, "coord_input", coord_input))
                cdir = getattr(cfg.geomag_grid, "coeff_dir", cdir)
            self.profile.fetch_geomag(coord_input=coord_input, coeff_dir=cdir)

        self.profile.validate()
        logger.info(
            "RT1D ready: lat={:.3f}, lon={:.3f}, alt_points={}, source={}",
            self.profile.lat,
            self.profile.lon,
            self.profile.alt_km.size,
            self.profile.source,
        )

    # ------------------------------------------------------------------
    # Collision type keys understood by NVIS_tracer(collision_type=...)
    # ------------------------------------------------------------------
    _VALID_COLLISION_TYPES: frozenset[str] = frozenset(
        {"FT", "FT_CC", "FT_MB", "SN_EN", "SN_EI", "SN", "ATM"}
    )

    @staticmethod
    def _extract_collision_hz(cc, collision_type: str) -> np.ndarray:
        """
        Extract a 1D collision-frequency array [Hz] from a ComputeCollision
        object using the user-specified type key.

        Parameters
        ----------
        cc : ComputeCollision
            Object returned by ``RT1DProfile.compute_collision()``.
        collision_type : str
            One of ``"FT"``, ``"FT_cc"``, ``"FT_mb"``, ``"SN_en"``,
            ``"SN_ei"``, ``"SN"``, ``"atm"`` (case-insensitive).

        Returns
        -------
        np.ndarray, shape (nh,)
        """
        ct = str(collision_type).strip().upper()
        _map = {
            "FT": lambda c: np.asarray(c.collision.nu_ft[:, 0], dtype=float),
            "FT_CC": lambda c: np.asarray(c.collision.nu_av_cc[:, 0], dtype=float),
            "FT_MB": lambda c: np.asarray(c.collision.nu_av_mb[:, 0], dtype=float),
            "SN_EN": lambda c: np.asarray(
                c.collision.nu_sn.en.total[:, 0], dtype=float
            ),
            "SN_EI": lambda c: np.asarray(
                c.collision.nu_sn.ei.total[:, 0], dtype=float
            ),
            "SN": lambda c: np.asarray(c.collision.nu_sn.total[:, 0], dtype=float),
            "ATM": lambda c: np.asarray(
                c.atmospheric_ion_neutral_collision_frequency()[:, 0], dtype=float
            ),
        }
        if ct not in _map:
            valid = sorted(_map.keys())
            raise ValueError(
                f"Unknown collision_type '{collision_type}'. Valid options: {valid}"
            )
        return _map[ct](cc)

    def fetch_collision(
        self,
        Te: np.ndarray | float | None = None,
        Ti: np.ndarray | float | None = None,
        edens: np.ndarray | None = None,
        O2p: np.ndarray | None = None,
        Op: np.ndarray | None = None,
    ) -> object:
        """
        Compute and attach collision frequencies to the profile.

        Convenience wrapper around :meth:`RT1DProfile.compute_collision`.
        Requires that ``fetch_msise()`` has been called. Plasma defaults
        (Te=Ti=Tn, Op=0.9·Ne, O2p=0.1·Ne) are applied when arguments
        are omitted.

        After calling this, pass ``collision_type`` to
        :meth:`NVIS_tracer` to select which model to use, e.g.::

            rt.fetch_collision()
            result = rt.NVIS_tracer(freq_mhz=freqs, collision_type="SN")

        Returns
        -------
        ComputeCollision
        """
        return self.profile.compute_collision(
            Te=Te,
            Ti=Ti,
            edens=edens,
            O2p=O2p,
            Op=Op,
        )

    @staticmethod
    def _resolve_time(time: dt.datetime | str | None, cfg=None) -> dt.datetime:
        """Resolve profile time from explicit input, cfg event, or UTC now."""
        if time is not None:
            return (
                time
                if isinstance(time, dt.datetime)
                else dt.datetime.fromisoformat(str(time))
            )
        if cfg is not None and hasattr(cfg, "event"):
            return dt.datetime.fromisoformat(str(cfg.event))
        return dt.datetime.utcnow()

    @staticmethod
    def _resolve_location(
        lat: float | None, lon: float | None, cfg=None
    ) -> tuple[float, float]:
        """Resolve lat/lon from explicit values or cfg defaults."""
        if lat is not None and lon is not None:
            return float(lat), float(lon)
        if (lat is None) ^ (lon is None):
            raise ValueError("Provide both lat and lon, or neither")
        if cfg is not None:
            if hasattr(cfg, "origin"):
                return float(cfg.origin.lat), float(cfg.origin.lon)
            if hasattr(cfg, "route") and hasattr(cfg.route, "start"):
                return float(cfg.route.start.lat), float(cfg.route.start.lon)
        raise ValueError(
            "Unable to resolve lat/lon. Provide lat/lon or cfg with origin/route.start."
        )

    @staticmethod
    def _resolve_altitudes(alt_km: np.ndarray | None, cfg=None) -> np.ndarray:
        """Resolve altitude grid from explicit input or cfg height fields."""
        if alt_km is not None:
            arr = np.asarray(alt_km, dtype=float).ravel()
            if arr.size < 2:
                raise ValueError("alt_km must contain at least 2 points")
            return arr
        if cfg is not None:
            h0 = float(getattr(cfg, "start_height_km"))
            h1 = float(getattr(cfg, "end_height_km"))
            dh = float(getattr(cfg, "height_incriment_km", 1.0))
            return np.arange(h0, h1, dh, dtype=float)
        raise ValueError("Unable to resolve altitude grid. Provide alt_km or cfg.")

    def _refractive_index_profile(
        self,
        frequency_hz: float,
        mode: str = "O",
        formulation: str = "appleton",
        collision_hz: np.ndarray | float | None = None,
        b_t: np.ndarray | float | None = None,
        theta_deg: np.ndarray | float | None = None,
    ) -> np.ndarray:
        """
        Build a 1D refractive-index profile n(z) on ``self.profile.alt_km``.

        Parameters
        ----------
        frequency_hz : float
            Wave frequency in Hz.
        mode : str, optional
            Mode selector for the selected formulation.
        formulation : {"appleton", "senwyller"}, optional
            Dispersion relation backend.
        collision_hz, b_t, theta_deg : array-like | scalar, optional
            Optional overrides. If omitted, best-available values are pulled
            from ``self.profile``:
            - collision: 0 (collisionless)
            - b_t: geomag ``bmag_t`` if available else 0
            - theta_deg: geomag ``psi_deg`` if available else 0
        """
        if self.profile.ne_m3 is None:
            raise ValueError("Profile must include electron density (ne_m3).")

        alt = self.profile.alt_km
        ne = self.profile.ne_m3
        nu = (
            np.zeros_like(alt, dtype=float)
            if collision_hz is None
            else np.asarray(collision_hz, dtype=float)
        )
        if b_t is None:
            b = (
                np.asarray(self.profile.geomag.bmag_t, dtype=float)
                if self.profile.geomag is not None
                and hasattr(self.profile.geomag, "bmag_t")
                else np.zeros_like(alt, dtype=float)
            )
        else:
            b = np.asarray(b_t, dtype=float)

        if theta_deg is None:
            psi = (
                np.asarray(self.profile.geomag.psi_deg, dtype=float)
                if self.profile.geomag is not None
                and hasattr(self.profile.geomag, "psi_deg")
                else np.zeros_like(alt, dtype=float)
            )
        else:
            psi = np.asarray(theta_deg, dtype=float)

        form = str(formulation).strip().lower()
        if form == "appleton":
            model = AppletonHartreeDispersion(
                frequency_hz=frequency_hz,
                ne_m3=ne,
                collision_hz=nu,
                b_t=b,
                theta_deg=psi,
            )
        elif form in {"senwyller", "sen-wyller"}:
            model = SenWyllerDispersion(
                frequency_hz=frequency_hz,
                ne_m3=ne,
                collision_hz=nu,
                b_t=b,
                theta_deg=psi,
            )
        else:
            raise ValueError("formulation must be 'appleton' or 'senwyller'")

        n = np.real(model.refractive_index(mode=mode))
        n = np.asarray(n, dtype=float).ravel()
        # guard tiny negatives from numerical noise
        n = np.where(np.isfinite(n), np.clip(n, 0.0, None), np.nan)
        if n.shape != alt.shape:
            raise ValueError("Refractive index profile shape mismatch.")
        return n

    def _dispersion_result_profile(
        self,
        frequency_hz: float,
        mode: str = "O",
        formulation: str = "appleton",
        collision_hz: np.ndarray | float | None = None,
        b_t: np.ndarray | float | None = None,
        theta_deg: np.ndarray | float | None = None,
    ) -> "DispersionResult":
        """Build a full DispersionResult profile on ``self.profile.alt_km``.

        Same model-construction logic as ``_refractive_index_profile`` but
        calls ``model.evaluate()`` so that absorption and phase profiles are
        also returned alongside the complex refractive index.
        """
        if self.profile.ne_m3 is None:
            raise ValueError("Profile must include electron density (ne_m3).")

        alt = self.profile.alt_km
        ne = self.profile.ne_m3
        nu = (
            np.zeros_like(alt, dtype=float)
            if collision_hz is None
            else np.asarray(collision_hz, dtype=float)
        )
        if b_t is None:
            b = (
                np.asarray(self.profile.geomag.bmag_t, dtype=float)
                if self.profile.geomag is not None
                and hasattr(self.profile.geomag, "bmag_t")
                else np.zeros_like(alt, dtype=float)
            )
        else:
            b = np.asarray(b_t, dtype=float)
        if theta_deg is None:
            psi = (
                np.asarray(self.profile.geomag.psi_deg, dtype=float)
                if self.profile.geomag is not None
                and hasattr(self.profile.geomag, "psi_deg")
                else np.zeros_like(alt, dtype=float)
            )
        else:
            psi = np.asarray(theta_deg, dtype=float)

        form = str(formulation).strip().lower()
        if form == "appleton":
            model = AppletonHartreeDispersion(
                frequency_hz=frequency_hz,
                ne_m3=ne,
                collision_hz=nu,
                b_t=b,
                theta_deg=psi,
            )
        elif form in {"senwyller", "sen-wyller"}:
            model = SenWyllerDispersion(
                frequency_hz=frequency_hz,
                ne_m3=ne,
                collision_hz=nu,
                b_t=b,
                theta_deg=psi,
            )
        else:
            raise ValueError("formulation must be 'appleton' or 'senwyller'")
        return model.evaluate(mode=mode)

    @staticmethod
    def _smooth_nonuniform_grid(
        start: float, end: float, n_points: int, sharpness: float
    ) -> np.ndarray:
        """
        Build a smooth nonuniform coordinate in [start, end] with denser
        sampling near ``end``.
        """
        if int(n_points) < 3:
            raise ValueError("n_points must be >= 3")
        u = np.linspace(0.0, 1.0, int(n_points))
        flipped_u = 1.0 - u
        denom = np.exp(float(sharpness)) - 1.0
        if np.isclose(denom, 0.0):
            return np.linspace(float(start), float(end), int(n_points))
        factor = (np.exp(float(sharpness) * flipped_u) - 1.0) / denom
        return 1.0 - (float(start) + (float(end) - float(start)) * factor)

    def NVIS_tracer(
        self,
        freq_mhz: np.ndarray | float,
        mode: str = "O",
        formulation: str = "appleton",
        collision_hz: np.ndarray | float | None = None,
        collision_type: str | None = None,
        b_t: np.ndarray | float | None = None,
        theta_deg: np.ndarray | float | None = None,
        n_floor: float = 1e-8,
        use_nonuniform_grid: bool = True,
        nonuniform_points: int = 240,
        nonuniform_sharpness: float = 10.0,
        compute_absorption_phase: bool = False,
        round_trip: bool = False,
    ) -> SimpleNamespace:
        """
        Vertical-forward-operator style NVIS tracer for a 1D profile.

        Parameters
        ----------
        freq_mhz : array-like or float
            Sounding frequencies in MHz.
        mode : str, optional
            Dispersion mode selector. Supported values are inherited directly
            from the selected dispersion formulation in ``dispersion.py``:
            - Appleton-Hartree: ``N/NO/ISO``, ``O``, ``X``, ``R``, ``L``
            - Sen-Wyller: ``N/NO/ISO``, ``O``, ``X``, ``R``, ``L``
        formulation : {"appleton", "senwyller"}, optional
            Dispersion backend.
        collision_hz : array-like or scalar, optional
            Collision frequency [Hz] as a direct 1D array. Mutually exclusive
            with ``collision_type``.
        collision_type : str, optional
            Named collision model. Requires ``rt.fetch_collision()`` to have
            been called first. Mutually exclusive with ``collision_hz``.
            Valid values: ``"FT"``, ``"FT_cc"``, ``"FT_mb"``, ``"SN_en"``,
            ``"SN_ei"``, ``"SN"``, ``"atm"`` (case-insensitive).
        b_t, theta_deg : array-like or scalar, optional
            Overrides for magnetic field magnitude [T] and wave-normal angle [deg].
        n_floor : float, optional
            Minimum refractive index used to identify valid propagation layers.
        use_nonuniform_grid : bool, optional
            If True, remap each frequency profile onto a stretched vertical
            grid with denser sampling near the turning altitude.
        nonuniform_points : int, optional
            Number of regridded altitude points used when
            ``use_nonuniform_grid=True``.
        nonuniform_sharpness : float, optional
            Stretching strength for nonuniform grid. Larger values concentrate
            more points near the turning altitude.
        compute_absorption_phase : bool, optional
            If True, call ``dispersion.evaluate()`` for each frequency and
            integrate absorption and phase along the propagation path.
            Adds ``absorption_db``, ``phase_rad``, ``absorption_profile``,
            and ``phase_profile`` to the returned namespace.
        round_trip : bool, optional
            If True (and ``compute_absorption_phase=True``), multiply the
            integrated absorption and phase by 2 for a two-way (round-trip)
            path.  Has no effect when ``compute_absorption_phase=False``.

        Returns
        -------
        SimpleNamespace
            - ``freq_mhz``          : frequency array [MHz]
            - ``vh_km``             : virtual-height estimate [km]
            - ``turning_height_km`` : turning heights [km]
            - ``n_profile``         : refractive-index profiles [nfreq, nz]
            - ``reason``            : per-frequency status strings
            - ``absorption_db``     : height-integrated absorption [dB, nfreq]
              (only when ``compute_absorption_phase=True``)
            - ``phase_rad``         : height-integrated phase [rad, nfreq]
              (only when ``compute_absorption_phase=True``)
            - ``absorption_profile``: absorption coefficient [dB/km] on the
              altitude grid [nfreq, nz]
              (only when ``compute_absorption_phase=True``)
            - ``phase_profile``     : phase constant [rad/km] on the altitude
              grid [nfreq, nz]
              (only when ``compute_absorption_phase=True``)

        Notes
        -----
        This method intentionally mirrors a vertical forward operator:
        it integrates an approximate group index ``mu' ~= 1 / n`` from the
        bottom altitude up to the turning point for each frequency.

        **Collision workflow** — two ways to supply collision frequency:

        1. *Direct array*: pass ``collision_hz`` as a 1D array [Hz].
        2. *Named model*: call ``rt.fetch_collision()`` first, then pass
           ``collision_type`` with one of the keys below.  ``collision_hz``
           must be ``None`` when ``collision_type`` is used.

        +-------------+--------------------------------------------------+
        | Key         | Model                                            |
        +=============+==================================================+
        | ``"FT"``    | Friedrich-Tonker (ν_ft, scaling a=1.0)           |
        | ``"FT_cc"`` | Friedrich-Tonker (ν_av_cc, scaling a=2.5)        |
        | ``"FT_mb"`` | Friedrich-Tonker (ν_av_mb, scaling a=1.5)        |
        | ``"SN_en"`` | Schunk-Nagy electron-neutral total               |
        | ``"SN_ei"`` | Schunk-Nagy electron-ion total                   |
        | ``"SN"``    | Schunk-Nagy full (en + ei)                       |
        | ``"atm"``   | Atmospheric ion-neutral approximation            |
        +-------------+--------------------------------------------------+
        """
        # ── Resolve collision frequency ──────────────────────────────────
        if collision_type is not None and collision_hz is not None:
            raise ValueError(
                "Provide at most one of 'collision_hz' or 'collision_type', not both."
            )
        if collision_type is not None:
            if self.profile.collision is None:
                raise ValueError(
                    f"collision_type='{collision_type}' requires pre-computed collision "
                    "data. Call rt.fetch_collision() before NVIS_tracer()."
                )
            collision_hz = self._extract_collision_hz(
                self.profile.collision, collision_type
            )
            logger.info(
                "NVIS_tracer: using collision_type='{}', nu=[{:.3e},{:.3e}] Hz",
                collision_type,
                float(np.nanmin(collision_hz)),
                float(np.nanmax(collision_hz)),
            )

        z = np.asarray(self.profile.alt_km, dtype=float)
        f_mhz = np.atleast_1d(np.asarray(freq_mhz, dtype=float))
        if np.any(f_mhz <= 0.0):
            raise ValueError("All frequencies must be > 0 MHz.")
        mode = str(mode).upper()
        logger.info(
            "NVIS tracer start: mode={}, formulation={}, freq_points={}, "
            "nonuniform_grid={}, collision_type={}",
            mode,
            formulation,
            f_mhz.size,
            bool(use_nonuniform_grid),
            collision_type if collision_type is not None else "none",
        )

        n_all = np.full((f_mhz.size, z.size), np.nan, dtype=float)
        vh = np.full(f_mhz.size, np.nan, dtype=float)
        zt = np.full(f_mhz.size, np.nan, dtype=float)
        reason = np.full(f_mhz.size, "no_propagation", dtype=object)
        if compute_absorption_phase:
            abs_db = np.full(f_mhz.size, np.nan, dtype=float)
            phase_rad_out = np.full(f_mhz.size, np.nan, dtype=float)
            abs_profile_all = np.full((f_mhz.size, z.size), np.nan, dtype=float)
            ph_profile_all = np.full((f_mhz.size, z.size), np.nan, dtype=float)
            _trip = 2.0 if round_trip else 1.0

        z0 = float(np.min(z))
        for i, fm in enumerate(f_mhz):
            # Propagation mask and virtual-height integration use the
            # COLLISIONLESS refractive index (Z = 0).  Any non-zero collision
            # frequency gives Re(n) > 0 even when X > 1 (evanescent wave),
            # which would include sub-cutoff regions and produce absorption
            # hundreds of dB/km.  The collisionless n drops to zero exactly at
            # the plasma cutoff (X = 1), yielding the correct turning point.
            n = self._refractive_index_profile(
                frequency_hz=float(fm) * 1e6,
                mode=mode,
                formulation=formulation,
                collision_hz=0.0,
                b_t=b_t,
                theta_deg=theta_deg,
            )
            n_all[i, :] = n
            if compute_absorption_phase:
                # Full collisional dispersion for absorption/phase; integration
                # bounds are taken from the collisionless mask so the integral
                # never enters the evanescent region.
                dr = self._dispersion_result_profile(
                    frequency_hz=float(fm) * 1e6,
                    mode=mode,
                    formulation=formulation,
                    collision_hz=collision_hz,
                    b_t=b_t,
                    theta_deg=theta_deg,
                )
                abs_profile_all[i, :] = dr.absorption_db_per_km
                ph_profile_all[i, :] = dr.phase_rad_per_km

            mask = np.isfinite(n) & (n > float(n_floor))
            if not np.any(mask):
                reason[i] = "no_propagation"
                continue

            # Use only the first contiguous propagation segment from the bottom.
            # This avoids integrating through disconnected valid layers above a
            # cutoff, which can create non-physical huge virtual heights.
            i_start = int(np.argmax(mask))
            if i_start >= (z.size - 1):
                reason[i] = "no_propagation"
                continue

            i_stop = i_start
            while i_stop < z.size and mask[i_stop]:
                i_stop += 1
            i_top = i_stop - 1
            if (i_top - i_start + 1) < 2:
                reason[i] = "no_propagation"
                continue

            z_raw = z[i_start : i_top + 1]
            z_up = z_raw.copy()
            n_up = n[i_start : i_top + 1]
            if use_nonuniform_grid and z_up.size >= 3:
                m = self._smooth_nonuniform_grid(
                    0.0,
                    1.0,
                    int(nonuniform_points),
                    float(nonuniform_sharpness),
                )
                z_new = z_up[0] + m * (z_up[-1] - z_up[0])
                n_new = np.interp(z_new, z_up, n_up)
                z_up = z_new
                n_up = n_new

            mu_p = 1.0 / np.clip(n_up, float(n_floor), None)
            dz = np.diff(z_up)
            mu_mid = 0.5 * (mu_p[:-1] + mu_p[1:])
            iono_h = np.sum(mu_mid * dz) if dz.size > 0 else 0.0

            zt[i] = float(z_up[-1])
            vh[i] = float(z0 + iono_h)
            reason[i] = "turning" if i_stop < z.size else "top_of_profile"

            if compute_absorption_phase:
                # Integrate absorption on the original fine altitude grid
                # (z_raw, 0.1 km step).  The nonuniform grid concentrates
                # points near the turning height and undersamples the D-layer
                # where most absorption occurs, so we avoid regridding here.
                abs_up = dr.absorption_db_per_km[i_start : i_top + 1]
                ph_up = dr.phase_rad_per_km[i_start : i_top + 1]
                abs_db[i] = _trip * np.trapezoid(abs_up, z_raw)
                phase_rad_out[i] = _trip * np.trapezoid(ph_up, z_raw)

        ns = SimpleNamespace(
            freq_mhz=f_mhz,
            vh_km=vh,
            turning_height_km=zt,
            n_profile=n_all,
            reason=reason,
            alt_km=z,
        )
        if compute_absorption_phase:
            ns.absorption_db = abs_db
            ns.phase_rad = phase_rad_out
            ns.absorption_profile = abs_profile_all
            ns.phase_profile = ph_profile_all
        return ns

    # Compatibility static helpers.
    den_to_plasma_freq_hz = staticmethod(RT1DProfile.den_to_plasma_freq_hz)
    plasma_freq_to_den = staticmethod(RT1DProfile.plasma_freq_to_den)
    vertical_to_magnetic_angle = staticmethod(RT1DProfile.vertical_to_magnetic_angle)
    inclination_to_vertical_angle = staticmethod(
        RT1DProfile.inclination_to_vertical_angle
    )
    inclintation2vertical = staticmethod(RT1DProfile.inclintation2vertical)

Collision Frequency Support

RT1DProfile and RT1D support user-defined collision frequency models.

Workflow

from hfpytrace.model.rt1d import RT1D

rt = RT1D(cfg=cfg, fetch_iri=True, fetch_msise=True)
rt.fetch_collision()                    # compute all models; store on profile.collision

result = rt.NVIS_tracer(
    freq_mhz=freqs,
    mode="O",
    collision_type="SN",                # Schunk-Nagy full (en + ei)
)

Supported collision_type Keys

Key Model
"FT" Friedrich-Tonker (ν_ft, a=1.0)
"FT_cc" Friedrich-Tonker (ν_av_cc, a=2.5)
"FT_mb" Friedrich-Tonker (ν_av_mb, a=1.5)
"SN_en" Schunk-Nagy electron-neutral total
"SN_ei" Schunk-Nagy electron-ion total
"SN" Schunk-Nagy full (en + ei)
"atm" Atmospheric ion-neutral approximation

Custom Plasma State

rt.fetch_collision(
    Te=Te_array,  # shape (nz,), K
    Ti=Ti_array,
    Op=Op_array,  # cm^-3
    O2p=O2p_array,
)

collision_hz (direct array) and collision_type (named model) are mutually exclusive in NVIS_tracer.