iHELIX

One architecture for fields on any geometry. Spheres, images, volumes, periodic boxes, particle clouds, and whatever you describe next.

pip install ihelix

import torch
from ihelix import Axis, Geometry, FieldGrid, IHelixConfig, IHelixField

geometry = Geometry.atmosphere()                    # (latitude, longitude, pressure)
grid = FieldGrid.from_points(coords, geometry, num_neighbours=64, cluster_size=64)
model = IHelixField(IHelixConfig(in_channels=8), geometry)

forecast = model(fields, grid)                      # (B, T, N, C) in, same out

ihelix info       # what it is and which geometries it covers
ihelix domains    # run every shape of problem through one class
ihelix converge   # read one field at rising resolution
ihelix demo       # build a model and check the invariances

The problem

Flatten a 3-D atmosphere into a 1-D sequence and the model has to learn spherical topology from scratch, because nothing in an index tells it. Rotary embeddings do not help: they encode distance in array steps, and on a latitude-longitude grid an array step means different things in different places.

• Cells one row apart sit n_lon positions apart in the sequence.
• The date line becomes a cliff: longitude 359.9° and 0.1° are neighbours on the planet and thousands of positions apart in the array.
• The meridians converge. Near the pole, a step of longitude is a few hundred metres; at the equator it is a hundred kilometres. The sequence calls both "one step".

A multi-mesh GNN fixes the topology by building the geometry into the wiring, which is honest but rigid: the mesh is chosen up front, reaching across the domain costs hops, and a new resolution means a new mesh.

The approach

Declare what your axes are. Everything downstream then works in a metric space where the geometry is already correct, and no part of the model ever sees an index.

Three things follow, and they are what the package actually is:

Neighbours are the nearest samples on the manifold, not the adjacent entries in an array. A sample beside the date line draws neighbours from both sides of it, because they are near.

Displacements are expressed in each sample's own local frame — east, north, up. "300 km east" produces the same input vector at the equator and at 70°N. Polar distortion is not corrected; it is never introduced.

Receptive fields are lengths, and attention is weighted by area. Each head carries a physical radius with compact support, and every sample is weighted by the share of the domain it stands for. Attention becomes a quadrature of a continuous operator,

out(x)  =  ∫ a(x,y) v(y) dμ(y)  /  ∫ a(x,y) dμ(y)

estimated on whatever samples you have. Refine the grid and it converges instead of drifting.

The three strands

The braid from helix-lm, with "position in a sequence" replaced by "position on a manifold" in the two spatial strands:

The index strand is the part a fixed mesh cannot do. Message passing couples regions by distance along edges chosen in advance, so reaching the far side costs hops. Here the route is content-addressed and learned: a ridge over the Atlantic can read the Pacific in one step, and nothing in the wiring had to anticipate it. Teleconnections, distant vortices, the other side of an image — same mechanism.

Space has no order, so nothing recurrent runs across it. Time does, and that is the only place a recurrence appears. Its state is a matrix per sample that does not grow with the rollout, so frame 1000 costs what frame 1 costs.

What has been measured

On untrained models — these are properties of the arithmetic, not of training.

The first row is the formal statement of "no flattening artefact", and it is exact rather than approximate. A sequence model reading a flattened grid cannot say the same at any precision.

The one precondition

Fixed-count neighbourhoods and fixed-length receptive fields pull against each other: refine the grid and a fixed count covers less ground. Every attention module reports whether its neighbour list actually reaches its radius:

grid = FieldGrid.from_points(coords, geometry, num_neighbours=grid.suggest_neighbours(radius))
model.blocks[0].local.coverage(grid)     # 1.0 = every head decided by its radius, not by the list length

At 1.0 the invariances above are exact. Below it they degrade smoothly, and the number tells you so. The neighbour count is a preprocessing choice — the weights never change.

Regular grids, the way the sphere wants them (0.6)

The data does not arrive as points. Satellite archives and reanalyses come as latitude-longitude arrays, and three things have to happen to them before any attention runs. ihelix.sphere does each of them without the usual artefact:

All three are static: the geometry is worked out once, the forward pass is matrix products and indexed reductions with fixed shapes. A full GridSat infrared mosaic (2000 × 5143) regrids to 0.25° in about 0.15 s on four CPU cores, mean, spread and extremes included.

from ihelix import ConservativeRegrid, GridToMesh, SphericalConv2d

regrid = ConservativeRegrid(src_lat, src_lon, dst_lat, dst_lon)
mean, coverage = regrid(brightness_temperature)           # NaN = missing; coverage = observed share
mean, spread, coverage = regrid.moments(brightness_temperature)
coldest, warmest = regrid.extremes(brightness_temperature)
on_mesh = GridToMesh(dst_lat, dst_lon, mesh)(mean, extremes=True)   # {"mean", "coverage", "min", "max"}

The index strand's write-back now uses integer indices fixed per grid instead of a boolean mask, so a compiled graph no longer breaks there. Results are bit-identical.

Honest limits

• No trained checkpoints. Nothing here has been trained on real data. Every claim above is about geometry, invariance and complexity, not about forecast skill or sample quality.
• The region partition is a discretization. The index strand carves the domain into regions, and no finite partition of a sphere commutes with arbitrary rotation — a fixed icosahedral mesh has exactly the same property. A longitude shift moves the local strand by round-off and the full model by ~5e-2.
• Neighbour counts grow with density. Holding a fixed physical reach at 4× the samples needs ~4× the neighbours. That is inherent to fixed-count neighbourhoods; suggest_neighbours computes it.
• Vectors are not parallel-transported. Components are read in each sample's local frame and the frame rotation is supplied to the model, but nothing forces it to transport them correctly.
• Brute-force neighbour search. Exact and cached per grid, which is right when the grid is static. Pass a precomputed index for very large point sets.

License

Apache-2.0. The normalization, convolution, delta-rule and pooling kernels carry over from helix-lm and ultimately from HuggingFace Transformers (Apache-2.0); see NOTICE. The geometry, grid, geodesic attention, regional index and cross-grid reader are original.

Made by Nathan.