space::irbem::gpu

The registry entry for name.

The runtime half of the availability question: true only when the device stack was compiled in, the operator has not switched it off, and cheatah-gpu-linalg's own cached bring-up probe succeeds. Never throws — that is the point of asking instead of trying.

Deliberately NOT cached here, although the probe underneath it is: the environment override has to take effect when it is set, and the cost of the query is a getenv plus a load of a function-local static.

Resolution order deliberately mirrors cheatah-gpu-linalg's own spv_bytes, so one habit covers both: the CHEATAH_SPACE_IRBEM_SPV_DIR environment variable, then the same-named compile definition, then <repo>/build/shaders derived from __FILE__ — which means a consumer that passes no definitions at all still finds the kernels of the checkout it compiled against.

Derived from __FILE__ rather than assumed relative to the working directory, so the registry-completeness test can read the source no matter where it is run from.

Normally KernelInfo::crossover_points, i.e. the measurement recorded next to the kernel. CHEATAH_SPACE_IRBEM_GPU_CROSSOVER overrides it process-wide with a decimal batch size, which is what makes the policy re-tunable on a machine whose bus and cores are not this one's without a rebuild — and what lets the suite drive the device lane through Lane::Auto. A value that is not a whole decimal number is ignored rather than read as zero, because reading a typo as "always use the GPU" is the expensive direction to be wrong in.

The single door to the device. The order of the checks is itself part of the contract, and each step is diagnosed before the next is attempted: an unregistered kernel (UnknownKernel), then a malformed batch (std::invalid_argument), then a shader that was never compiled (ShaderMissing), then a machine or build with no device (GpuUnavailable). Shader existence is checked BEFORE availability on purpose — a machine with no GPU is exactly where a skipped shader-build step is likeliest, and reporting "no GPU" there would hide it.

Identical contract to launch_trace, with one more upload: ext carries the T89 parameter block for the batch's Kp bin followed by the epoch's gsm_from_geo rotation, column-major — 39 floats that make the external field evaluable on the device without a host round-trip per RK4 stage. The bin is selected on the HOST because a batch shares one epoch and one Kp; a per-thread bin branch would diverge the warp for nothing.

dispatch_batch above is for the pos/out/params/dims kernels: one vector in, one vector out. The tracer takes positions AND pitch angles AND two coefficient tables, and writes four floats plus a status word per line. Rather than generalise the four-binding helper into something that describes every shape badly, this is the tracer's own launcher — the kernel that carries the module's whole performance argument earns fifty lines of its own.

dispatch_batch cannot express this one: it uploads a scalar parameter block, and IGRF has no scalars, only two tables. The tables arrive ALREADY interpolated to the epoch, because interpolating IGRF's 26-epoch table per thread would be one redundant copy per point of a calculation the host does once per batch.

L*'s flux integral is what made this worth exposing on the seam rather than leaving it inside a benchmark: Phi is one field evaluation per polar-cap cell, ~2 400 cells per L* point and nothing else — exactly the ~20 flops/byte regime the registry measures the device winning by 8.37x in.

The companion to launch_trace, and the step that turns a converged drift shell into the polar-cap boundary L*'s flux integral is taken over. Each line walks from its magnetic-equator seed down to r = 1 along dir, halving its step onto the sphere rather than interpolating across it; see the kernel's own header in irbem.slang for why that distinction is worth ~30 extra steps.

The degree-1 order-0 term of the IAGA spherical-harmonic expansion that defines IGRF (Alken et al., International Geomagnetic Reference Field: the thirteenth generation, Earth Planets Space 73:49 (2021), eq. 1). With V = a (a/r)^2 g10 P_1^0(cos θ) and B = -∇V, B_r = 2 g10 (a/r)^3 cos θ and B_θ = g10 (a/r)^3 sin θ, which in the MAG frame — where the dipole axis IS ẑ — is the single identity B = g10 (a/r)^3 (3 (ẑ·r̂) r̂ − ẑ); componentwise, with a = 1 Re, Bx = 3 g10 x z / r⁵, By = 3 g10 y z / r⁵, Bz = g10 (3z² − r²) / r⁵. The derivation is written out in full in irbem.slang, whose kernel evaluates exactly these expressions in exactly this order.

The real g10 is negative (−29404.8 nT at IGRF-13 epoch 2020.0), which is what makes the field point into the ground at the northern dipole pole; the sign lives in the coefficient, so this routine never encodes a hemisphere.

The host twin of irbem_dipole_f32: the same expressions, in the same order, in the same precision, which is what makes a disagreement between the two attributable to the DEVICE (contraction, a driver's transcendental) rather than to the arithmetic having been written differently on the two sides. It is also the lane a machine without a GPU actually runs.

The production entry point. Under Lane::Auto the choice is prefer_gpu's, which means a build with no device stack, a machine with no device, and a batch too small to pay for its transfers all quietly run the host lane — while a forced Lane::Gpu on any of those throws, because a test that meant to exercise the device must not silently pass on the CPU.

The compile-time half of the availability question, and a constant — usable in if constexpr and in a static_assert for a build that means to require the device stack. It says nothing about whether a device exists on the machine running the binary; that is available.

Not a "not measured yet" placeholder — it is the answer for a transfer-bound kernel, and a kernel carrying it runs on the host under Lane::Auto no matter how large the batch is.

This is the value the integral kernels carry, and it is what "the GPU is the default" means in practice. It is not a policy override — it is what the arithmetic says. One L* point is roughly 10^5 field evaluations, ~5 x 10^7 flops; at even 10% of this device's fp32 peak that is ~25 us of compute against a measured ~30 us synchronous dispatch floor, so a batch of TWO points already pays for the round trip and every realistic batch dwarfs it. The transfer is ~60 bytes per point for ~5 x 10^7 flops — an arithmetic intensity of ~8 x 10^5 flops/byte, some 350x beyond the PCIe ridge point, which is why the bus simply does not appear in the accounting.

The contrast with never_faster_on_device is the whole reason this is per-kernel rather than one library-wide switch. Measured on this machine, same seam, same transfers, same device:

| kernel | flops/byte | device | host | verdict | | dipole | 0.5 | 243 Mpts/s | 352 Mpts/s | 0.69x LOSES | | IGRF-14 | ~20 | 27.3 Mpts/s | 3.3 Mpts/s | 8.37x WINS | | trace | ~9 400 | the integrals — the point never leaves the device |

A blanket "always use the GPU" would make the dipole kernel 45% SLOWER. Defaulting to the device where the arithmetic earns it, and only there, is the honest form of the same intent.

A constexpr table rather than a function, so it costs nothing, can be iterated at compile time, and cannot drift into a registry that allocates. Adding a kernel means adding a row here AND an entry point there; the completeness test fails if only one of the two happens.

Auto is what production uses; the two explicit values exist because the differential suite has to be able to run the SAME inputs through both lanes and compare, which it cannot do if the choice is only ever made for it.