gensbi.recipes.id_strategies

Structured id-builder strategies for the recipe pipelines.

Two DIFFERENT vocabularies share the word “rope” — they collided once (2026-07-19 handoff) and are deliberately kept distinct:

• Model-side strategy strings (e.g. Flux1Params.id_embedding_strategy): "rope" means apply RoPE to whatever ids arrive at the forward pass.

• Pipeline-side builder strategies (ConditionalPipeline’s id_embedding_strategy): strings like "rope1d"/"rope2d" — and the objects in this module — build the id arrays themselves.

A HealpixRope pipeline strategy pairs with model-side ("absolute", "rope") plus a 3-entry even axes_dim summing to the per-head dim (e.g. (22, 22, 20) for 64).

Classes

HealpixRope	Spherical RoPE ids for tokens on a HEALPix grid (name: "healpix-rope").
IdStrategy	Structural interface for pipeline id-builder strategy objects.

Module Contents

class gensbi.recipes.id_strategies.HealpixRope

Spherical RoPE ids for tokens on a HEALPix grid (name: “healpix-rope”).

Wraps gensbi.recipes.utils.init_ids_healpix() (see there for the method and its rationale) with the geometry needed to build the ids — which the string-enum API cannot carry, since the pipeline only passes a token count.

Parameters:

• nside (int) – HEALPix resolution of the token grid (power of 2).

• base_pixels (sequence of int, optional) – Base pixels (0..11) covered by the grid; None = full sky.

__post_init__()

build(dim)

Return (ids, num_tokens); dim must match the grid.

base_pixels: Tuple[int, Ellipsis] | Sequence[int] | None = None

name: ClassVar[str] = 'healpix-rope'

nside: int

property num_tokens: int

n_faces * nside**2.

Type:

Token count of the grid

Return type:

int

property theta: int

healpix_rope_theta().

Type:

Suggested model-side RoPE theta

Return type:

int

class gensbi.recipes.id_strategies.IdStrategy

Bases: Protocol

Structural interface for pipeline id-builder strategy objects.

Any object with a name and a build(dim) -> (ids, resolved_dim) method can be passed in an id_embedding_strategy tuple slot; the pipeline calls build with the corresponding dim_obs/dim_cond. Strategies own their full geometry — unlike the string strategies they receive no semantic_id/size.

build(dim)

Return (ids, resolved_dim) for a stream of dim tokens.

name: str