Source code for mstar.model.waypoint.ring_geometry

import dataclasses

import torch

from mstar.model.waypoint.config import WaypointConfig

__all__ = ["describe_ring_memory", "ring_memory_bytes"]


[docs] def ring_memory_bytes( config: WaypointConfig, *, num_sessions: int = 1, dtype: torch.dtype = torch.bfloat16 ) -> list[int]: """Per-layer ring bytes for ``config``, computed without allocating anything (so it can be called on a laptop while sizing a deployment). ``num_sessions`` is a straight multiplier: the world dimension is folded into the token axis, so N worlds is N times one world's slots and the per-slot arithmetic is untouched. That it is a multiplier is the whole reason ``num_sessions`` is a deployment sizing knob and the geometry is not.""" per_slot = 2 * num_sessions * config.n_kv_heads * config.d_head * dtype.itemsize return [per_slot * config.kv_capacity(i) for i in range(config.n_layers)]
def _fmt_bytes(n: int) -> str: return f"{n / 2**20:.1f} MiB" if n < 2**30 else f"{n / 2**30:.2f} GiB"
[docs] def describe_ring_memory( config: WaypointConfig, *, num_sessions: int = 1, dtype: torch.dtype = torch.bfloat16 ) -> str: """Geometry and footprint of every ring, grouped local vs global, with the counterfactual under the opposite ``full_global_ring`` setting. The compacted default is what a reviewer should see; the ``full_global_ring`` line is the reference's allocation, 8/9ths of whose global storage is permanently unwritten. """ per_layer = ring_memory_bytes(config, num_sessions=num_sessions, dtype=dtype) total = sum(per_layer) lines = [ f"Waypoint ring KV variant={config.variant} worlds={num_sessions} dtype={dtype} " f"full_global_ring={config.full_global_ring}" ] groups = ( ("local ", [i for i in range(config.n_layers) if not config.is_global_layer(i)]), ("global", sorted(config.global_layers)), ) for name, indices in groups: if not indices: continue i = indices[0] lines.append( f" {name} x{len(indices):2d} " f"{config.ring_frames(i):3d} ring frames @ stride {config.pinned_dilation(i)} " f"({config.ring_buckets(i)} addressable) + 1 scratch " f"= {config.kv_capacity(i):6d} tok " f"= {_fmt_bytes(per_layer[i]):>9s}/layer " f"= {_fmt_bytes(sum(per_layer[j] for j in indices)):>9s}" ) lines.append(f" total {_fmt_bytes(total)} ({total} bytes)") other = dataclasses.replace(config, full_global_ring=not config.full_global_ring) other_total = sum(ring_memory_bytes(other, num_sessions=num_sessions, dtype=dtype)) delta = other_total - total lines.append( f" full_global_ring={other.full_global_ring} would use {_fmt_bytes(other_total)} " f"({'+' if delta > 0 else '-'}{_fmt_bytes(abs(delta))})" ) return "\n".join(lines)