Menu
Quick reference for src/vramgeist/calc.py — formulas, public functions, gotchas. Use before editing calc.py.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Keep input small. Use before any Read or Grep call when context budget tight.
Quick reference for src/vramgeist/gguf.py parser. Use before editing gguf.py or adding new metadata keys.
Pick next unfinished task from TASK_BOARD.md. Use at start of every session and after finishing one task.
One-page repo layout. Use to locate files without globbing. First skill to invoke after pick-task.
Required end-of-response format. Use before submitting any response that edited files.
Break a Tier 3 (🔴) task into 3-5 Tier-2-shaped sub-tasks before editing. Use whenever picked task is Tier 3.
| name | calc-quickref |
| description | Quick reference for src/vramgeist/calc.py — formulas, public functions, gotchas. Use before editing calc.py. |
Avoid full re-read of calc.py (554 lines). Use this map.
| Function | Returns | Purpose |
|---|---|---|
calculate_vram_usage(model_mb, n_layers, n_gpu_layers, ctx, cfg) | float MB | Legacy approx |
calculate_ram_usage(...) | float MB | CPU side |
calculate_total_memory_usage(...) | (vram, ram) | Pair |
_per_token_kv_bytes(model_meta, bpe_override) | int bytes | GQA-aware KV/token |
_estimate_tps(ctx, n_layers, hidden, bpe, bw_gbps, beta, model_meta) | float | TPS via bandwidth |
fit_latency_model(measure_func, contexts, runs) | (a, b, r2) | Linear fit |
validate_context(measure_func, C, attempts, step) | (C, tries, ok) | Alloc backoff |
calculate_semantic_throughput_best_context(...) | dict | Score-based picker |
calculate_max_context(...) | int | Memory-bound max ctx |
Model_VRAM = model_mb * min(n_gpu/n_layers, 1.0)
Context_VRAM = ctx * hidden * 2 * bpe / 1024² (legacy, no GQA)
KV_per_token = 2 * n_kv_heads * head_dim * n_layers * bpe (preferred)
kv_bytes = ctx * per_token * batch * (1 + overhead_frac)
TPS = bw_bytes_per_sec / (beta * per_token)
score = tps * usefulness * mem_margin^memory_penalty_pow
usefulness = 1 / (1 + ctx / c_ref)
config.hidden_size (4096 default), config.bytes_per_element (2),
config.vram_overhead_mb (~500), config.vram_safety_margin (~0.9),
config.ram_overhead_mb, config.ram_safety_margin.
model_meta path differs from legacy path — branches on if model_meta:._per_token_kv_bytes falls back chain: explicit → infer from hidden/n_heads → head_dim=64 default.8388608. Returned ctx is rounded DOWN to one of them.estimate_free_vram_bytes may raise → fallback uses available_vram_mb * safety_margin.verify_alloc opt defaults True → calls measure_func; tests pass None.Pure functions. No I/O, no prints. Side-effect-free. If adding logic, keep that invariant.