space::irbem::api

Each is one line over transform, so the physics lives in exactly one place; what these add is the name, the argument order and the @test tag a caller can grep for. Geographic to solar-magnetospheric — the frame every external field model is defined in.

Hoisted deliberately: IRBEM rebuilds this per call, but the matrices depend only on the epoch, so a batch over one timestamp should pay for the trigonometry once. This is the single largest structural difference between calling the two libraries in a loop.

East longitude comes back in (-180, 180], this module's convention everywhere; coord_trans with sysaxes_out = 7 folds the SAME answer into the reference's [0, 360) instead. Both name one meridian; see detail::sph_in_irbem_longitude.

MLT is the SM azimuth read as a clock: MLT = 12 + λ_SM / 15°, so local magnetic noon (the SM +X half-plane, which by construction contains the Sun-facing side of the dipole meridian) is 12 h and midnight is 0 h. Nothing but the SM rotation enters it, which is why this routine takes the epoch's Rotations and no field model.

Verified as a black box against the shipped reference: over forty points spanning 1965–2029, get_mlt1_ agrees with this expression to 9.6e-5 h — 0.34 s of local time — once the dipole epochs are matched (see the file brief). That is the measurement that fixed the definition; no Fortran was read.

This is the ONE routine in the module where the frames are runtime values rather than template arguments, which is exactly why it is written as a hub through GEO over frame_from_sysaxes rather than as a switch that picks a default. An unrecognised code is reported; it never silently becomes GEO. (The reference prints sysaxesOUT out of range ! to stdout and returns baddata — measured — which a caller redirecting stdout will never see.)

coord_trans_vec is the runtime-code lane and pays a switch per point per side; this is the lane for code that knows its frames, and it hoists the 3×3 out of the loop when the epoch is shared, leaving nine multiplies and six adds per point with no branch and no dispatch. Both exist because both callers exist — a generic converter driven by a configuration file, and an inner loop that has known it was going GEO→GSM since it was written.

One L* point is Nder = 25 independent root-finds of a few field lines each. That is an order of magnitude below the ~512-line crossover gpu/dispatch.hpp measures, so a single point runs on the host no matter what hardware is present. Hand over ntime points and every stage of the root-find becomes ntime × Nder wide, which is where the trace kernel's measured 48.9× lands. A loop calling make_lstar per point cannot be accelerated — that is a property of the problem, not of this implementation.

Measured through THIS entry point on an RTX 3070 Ti against its own fp64 host lane (-O3 -march=native, IGRF-14, points spread over L = 3…5, Nder = 25):

The crossover is the one gpu/dispatch.hpp measures, reached here in POINTS rather than lines because each point contributes Nder of them. Re-measured on an RTX 3070 Ti with the device flag confirmed true: 20.16 ms/point at n = 64 against the host's 13.13 (device loses 0.65×) and 0.739 ms/point at n = 512 against 13.77 (device wins 18.6×). Both lanes are bit-identical run-to-run, and the device lane also serves the call on llvmpipe (8.27 ms/point) and on an Intel iGPU (14.42), so the shape is not NVIDIA-only.

The device lane traces in fp32, and over 512 points spread across L = 3…5 the two lanes' L* differ by at most 4.2e-3 absolute and L_m by 4.0e-3 — inside docs/ERROR_BUDGET.md's 0.01 absolute on L*, which is what makes the fp32 trace admissible, but ABOVE its 1e-3 on L_m, so a caller who needs L_m to that budget must pin the host lane with CHEATAH_SPACE_IRBEM_NO_GPU=1. (An earlier revision of this comment quoted 2.8e-3 and 2.4e-3; those are one point set's numbers, not the routine's.)

ONE CONSEQUENCE THAT BITES: which lane runs depends on the BATCH SIZE, so make_lstar_vec over n points and n separate make_lstar calls are NOT bit-identical on a machine with a device. n = 1 is 25 field lines and stays on the host; n = 6 is 150, which crosses irbem_igrf_f32's measured crossover of 128, and the flux quadrature then runs in fp32 on the device. The two answers agree to the budget above, not to the last bit. == between the two lanes is only meaningful with the device pinned off, which is what IrbemApi.MakeLstarVecAgreesWithTheScalarLane does.

The epoch is ONE Rotations for the whole batch, not one per point as IRBEM takes. That is deliberate: the drift shell is organised about the dipole axis, so points at different epochs belong to different shells and cannot share a dispatch. Splitting the batch internally would hand back the speed the batch form exists to provide, silently. Group by epoch in the caller, which is what a caller must do anyway to get the throughput.

Shell splitting is the phenomenon that particles of different pitch angle at the SAME point drift on DIFFERENT shells once the field is not a dipole, so L* is a function of α and not just of position. Computationally it is the batch form's best case: ntime × Nipa points that all share one epoch, so the whole grid is one dispatch of ntime × Nipa × Nder field lines.

Φ = 2π k₀ / L*, the relation driftshell.hpp computes L* with, and the one the reference documents for LSTAR_PHI as Φ = 2π B₀/L*. The reference takes iyear and idoy, and MEASURED it uses that epoch's own dipole moment rather than a frozen one: lstar_phi1_(whichinv = 1) at L* = 4 returns 48599.478358059241 nT·Re² in 1965 and 46590.805305975191 in 2029, whose implied B₀ — 30939.3888 and 29660.6279 nT — is dipole_moment of Igrf<>::at(year + 0.5) to the last bit. So this routine reproduces the reference EXACTLY, 0 to 1.5e-16 relative over 1965, 1990, 2015 and 2029 in both directions, and there is no convention to reconcile. Taking k₀ from the epoch is therefore agreement, not the divergence an earlier revision of this comment claimed. mcilwain_l documents why a frozen moment would be wrong: it has fallen several percent over the last century, and freezing it shows up as a constant offset at every shell rather than as an obvious error.