flopscalc 0.1.0__tar.gz

flopscalc-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+build/
+dist/
+wheels/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Caches
+.flopscalc_cache/
+*.log
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db

flopscalc-0.1.0/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to FLOPSCalc are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/), and the project adheres to
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-24
+
+Initial release.
+
+### Added
+- Analytical `estimate()` API returning parameters, forward/backward FLOPs
+  (broken down by embedding, attention, MLP, normalization, and output head),
+  weight/activation/KV-cache memory, roofline latency, and energy.
+- Component-wise, GQA/MQA-aware FLOP accounting using the `2 * m * k * n`
+  matmul convention; exact parameter counts validated against 20+ public models
+  (Llama 2/3, Mistral, Qwen2.5, Gemma, Phi-2, GPT-2, Falcon-7B).
+- Bundled model registry plus Hugging Face Hub `config.json` fetch, with a
+  robust parser for non-standard architectures (Falcon, GPT-2 field names,
+  nested multimodal `text_config`).
+- GPU database (A100/H100/H200/V100/L40S/L4/T4/A10G/A6000/RTX 4090/3090) with
+  per-precision peak throughput; roofline model splitting prefill (compute-bound)
+  and decode (memory-bound) phases.
+- Precision support: fp32, tf32, fp16, bf16, fp8, int8, int4.
+- `compare()` for side-by-side model comparison and a `flopscalc` CLI.
+- `flopscalc.groq` provider: run estimates on GroqCloud model IDs fully offline
+  (no HF fetch), with published throughput attached and MoE models guarded.
+- Optional empirical validation (`flopscalc[torch]`) against a real PyTorch
+  forward pass via `FlopCounterMode`.
+- Full pytest suite and usage documentation (README).

flopscalc-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FLOPSCalc contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

flopscalc-0.1.0/PKG-INFO

@@ -0,0 +1,291 @@
+Metadata-Version: 2.4
+Name: flopscalc
+Version: 0.1.0
+Summary: Accurate FLOPs, memory, latency, and energy estimation for Large Language Models.
+Author-email: Your Name <you@example.com>
+License: MIT
+License-File: LICENSE
+Keywords: energy,flops,inference,kv-cache,latency,llm,memory,profiling,roofline,transformer
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: all
+Requires-Dist: huggingface-hub>=0.20; extra == 'all'
+Requires-Dist: pytest>=7.0; extra == 'all'
+Requires-Dist: torch>=2.1; extra == 'all'
+Requires-Dist: transformers>=4.40; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: hf
+Requires-Dist: huggingface-hub>=0.20; extra == 'hf'
+Provides-Extra: torch
+Requires-Dist: torch>=2.1; extra == 'torch'
+Requires-Dist: transformers>=4.40; extra == 'torch'
+Description-Content-Type: text/markdown
+
+# FLOPSCalc
+
+**Accurate FLOPs, memory, latency, and energy estimation for Large Language Models.**
+
+FLOPSCalc answers questions like *"how much compute, memory, and energy does one
+forward pass of Llama‑3‑8B at bf16 on an A100 actually cost?"* — analytically,
+in milliseconds, without downloading a single weight. It is built for
+transformers specifically (self‑attention, KV cache, GQA/MQA, gated MLPs), gives
+a **layer‑wise breakdown** rather than one opaque total, and models **precision,
+memory, latency, and energy** under different inference settings behind one API.
+
+```python
+from flopscalc import estimate
+
+result = estimate(
+    model="meta-llama/Llama-3-8B",
+    batch_size=4,
+    sequence_length=2048,
+    precision="bf16",
+    gpu="A100",
+)
+print(result)
+```
+
+```
+==============================================================
+ FLOPSCalc estimate: meta-llama/Meta-Llama-3-8B
+  batch=4  seq_len=2048  precision=bf16  gpu=A100-80GB-SXM
+==============================================================
+ Parameters        : 8.03B  (8,030,261,248)
+--------------------------------------------------------------
+ FLOPs (single forward pass over batch x seq)
+   Forward         : 131.885 TFLOP
+   Backward        : 263.770 TFLOP
+     - attention   : 30.880 TFLOP
+     - mlp         : 92.389 TFLOP
+     - embedding   : 0 FLOP
+     - layernorm   : 8.724 GFLOP
+     - output head : 8.607 TFLOP
+--------------------------------------------------------------
+ Memory
+   Total           : 17.268 GB
+     - weights     : 16.061 GB
+     - activations : 134.218 MB
+     - kv cache    : 1.074 GB
+   Fits on GPU     : yes
+--------------------------------------------------------------
+ Performance (roofline)
+   Prefill latency : 845.42 ms  [compute-bound]
+   Decode/token    : 10.50 ms  (381 tok/s)
+   Forward energy  : 287.44 J (0.0798 Wh)
+==============================================================
+```
+
+## Why FLOPSCalc
+
+Existing FLOP counters tend to support only CNNs, report a single total with no
+layer breakdown, ignore transformer‑specific structure (self‑attention cost, KV
+cache), and say nothing about precision, memory, latency, or energy. FLOPSCalc
+targets exactly those gaps:
+
+- **Transformer‑aware** — separate accounting for embeddings, multi‑head
+  attention (with GQA/MQA), the feed‑forward network (standard *and* gated /
+  SwiGLU), normalization, and the output head.
+- **More than FLOPs** — parameter count, weight/activation/KV‑cache memory,
+  roofline latency (prefill *and* decode), and energy.
+- **Precision‑aware** — fp32, tf32, fp16, bf16, fp8, int8, int4.
+- **One API to compare models** under different batch sizes, sequence lengths,
+  precisions, and GPUs.
+- **Hybrid accuracy** — a fast analytical core, plus an optional empirical mode
+  that checks the analytical FLOPs against a real PyTorch forward pass.
+
+## Install
+
+```bash
+pip install flopscalc                # analytical core, zero dependencies
+pip install "flopscalc[hf]"          # + fetch model configs from the HF Hub
+pip install "flopscalc[torch]"       # + empirical validation (torch, transformers)
+```
+
+The analytical core is **pure Python with no required dependencies**, so it runs
+anywhere and can size a 70B model on a laptop.
+
+## The `estimate()` API
+
+```python
+estimate(
+    model,                      # registry name / HF id, ModelConfig, or dict
+    batch_size=1,
+    sequence_length=2048,
+    precision="bf16",           # fp32|tf32|fp16|bf16|fp8|int8|int4 (aliases ok)
+    gpu="A100",                 # GPU name / GPUSpec, or None to skip latency/energy
+    *,
+    include_backward=True,      # also report training (backward) FLOPs
+    causal=False,               # count only causal (lower-triangular) attention
+    num_generated_tokens=128,   # decode horizon for full-request latency/energy
+    kv_cache_precision=None,    # defaults to precision (fp16 when weights are int8/int4)
+    flash_attention=True,       # activation-memory model
+    activation_factor=2.0,
+    compute_efficiency=0.5,     # roofline MFU
+    mem_efficiency=0.8,         # achievable fraction of peak bandwidth
+    power_utilization=0.85,     # mean power draw as a fraction of TDP
+    allow_hf_fetch=True,
+)
+```
+
+The returned `EstimationResult` behaves like a `dict` (so `result["forward_flops"]`
+and `json.dumps(result)` both work) but prints as the report above. Dictionary
+values use SI base units: **FLOPs are raw counts, memory is bytes, latency is
+seconds, energy is joules.** The ten headline keys match the documented shape:
+
+```python
+{
+  "parameters":     8030261248,
+  "forward_flops":  131_885_...,
+  "backward_flops": 263_770_...,
+  "attention_flops": ...,   "mlp_flops": ...,   "embedding_flops": ...,
+  "memory":         ...,    "kv_cache":  ...,
+  "latency":        0.845,  "energy":    287.4,
+}
+```
+
+A full nested breakdown (per‑component FLOPs, parameter and memory breakdowns,
+prefill/decode performance, and the settings used) lives under
+`result["details"]`.
+
+### Comparing models
+
+```python
+from flopscalc import compare
+
+print(compare(
+    ["gpt2", "meta-llama/Llama-3-8B", "mistralai/Mistral-7B-v0.1"],
+    batch_size=1, sequence_length=4096, precision="bf16", gpu="A100",
+))
+```
+
+### Command line
+
+```bash
+flopscalc estimate meta-llama/Llama-3-8B -b 4 -s 2048 -p bf16 -g A100
+flopscalc compare gpt2 meta-llama/Llama-3-8B -p bf16 -g A100
+flopscalc estimate meta-llama/Llama-3-8B --json          # machine-readable
+flopscalc list-models
+flopscalc list-gpus
+```
+
+## Methodology
+
+**FLOPs.** A matmul `[m,k]·[k,n]` costs `2·m·k·n` FLOPs (one multiply + one add
+per MAC) — the standard Kaplan/Chinchilla convention, so results are directly
+comparable to published figures. Per layer FLOPSCalc counts the Q/K/V/output
+projections, the `Q·Kᵀ` and `softmax·V` attention terms (`O(s²)`, halved with
+`causal=True`), and the MLP matmuls (2 matrices for a standard MLP, 3 for a gated
+SwiGLU/GeGLU), plus the small softmax/normalization/activation/RoPE element‑wise
+terms. The token‑embedding lookup is a gather (≈0 FLOPs); the output head is
+`2·N·h·V`. This reproduces the familiar `forward ≈ 2·N·D` per‑token result;
+the backward pass is `≈ 2×` the forward pass, giving the `6·N·D` training
+estimate.
+
+**Memory.** The parameter count is exact and reproduces published model‑card
+figures (see below). Runtime memory = weights (`params × bytes/precision`) +
+KV cache + a first‑order activation estimate. The **KV cache** is
+`2 · batch · seq · layers · (kv_heads · head_dim) · bytes`, so grouped‑query
+attention shrinks it by `num_heads / num_kv_heads`.
+
+**Latency & energy (roofline).** Prefill and decode are modelled separately
+because they behave differently. Prefill (encoding the prompt) is compute‑bound:
+`time = FLOPs / (peak_throughput × MFU)`. Decode (one token at a time) is
+memory‑bandwidth‑bound: each step re‑reads every weight and the KV cache from
+HBM, so `time = bytes_moved / (bandwidth × utilization)`. Each phase takes
+`max(compute_time, memory_time)`. Energy = `time × TDP × power_utilization`.
+The efficiency knobs (`compute_efficiency`/MFU, `mem_efficiency`,
+`power_utilization`) are the dominant source of error and are exposed as
+parameters.
+
+### Validation
+
+Bundled model parameter counts match their public model cards **exactly**:
+
+| Model | FLOPSCalc | Published |
+|---|---|---|
+| GPT‑2 | 124,439,808 | 124M |
+| Llama‑2‑7B | 6,738,415,616 | 6.74B |
+| Mistral‑7B | 7,241,732,096 | 7.24B |
+| Llama‑3‑8B | 8,030,261,248 | 8.03B |
+| Qwen2.5‑7B | 7,615,716,864 | 7.61B |
+| Gemma‑7B | 8,537,680,896 | 8.54B |
+| Llama‑2‑70B | 68,976,648,192 | ~69B |
+| Llama‑3‑70B | 70,553,706,496 | 70.6B |
+
+The optional empirical mode checks FLOPs against a real forward pass:
+
+```python
+import flopscalc as fc
+cfg = fc.ModelConfig(name="tiny", hidden_size=256, num_layers=4,
+                     num_attention_heads=8, num_key_value_heads=4,
+                     vocab_size=1024, intermediate_size=688, model_type="llama")
+print(fc.validate(cfg, batch_size=1, sequence_length=64))
+# {'measured_forward_flops': ..., 'analytical_forward_flops': ..., 'ratio': ~1.0, ...}
+```
+
+## Supported models, GPUs, and precisions
+
+**Models (bundled).** GPT‑2 (base/medium/large/xl), Llama‑2 (7B/13B/70B),
+Llama‑3 / 3.1 / 3.2 (1B/3B/8B/70B), Mistral‑7B, Qwen2.5 (0.5B/7B/72B), Phi‑2,
+Gemma (2B/7B), Falcon‑7B. Anything else resolves via the Hugging Face Hub —
+the parser normalizes field-name variance across architectures (GPT‑2's
+`n_embd`, Falcon's `multi_query` and implicit `intermediate_size`, nested
+`text_config` for multimodal models, etc.). Or pass your own `ModelConfig` /
+dict, or `register_model(...)`. (Mixture‑of‑Experts models fetch fine but their
+FLOPs are overcounted as dense — MoE is on the roadmap.)
+
+**GPUs (bundled).** A100 (40/80GB, SXM/PCIe), H100 (SXM/PCIe), H200, V100, T4,
+L4, L40S, A10G, A6000, RTX 4090, RTX 3090. Define a `GPUSpec` for anything else.
+
+**Precisions.** fp32, tf32, fp16, bf16, fp8, int8, int4.
+
+## Custom models and hardware
+
+```python
+import flopscalc as fc
+
+cfg = fc.ModelConfig(
+    name="my-model", hidden_size=4096, num_layers=32, num_attention_heads=32,
+    num_key_value_heads=8, intermediate_size=14336, vocab_size=128256,
+    mlp_type="gated", norm_type="rmsnorm", positional="rope",
+)
+print(fc.estimate(cfg, gpu="H100", precision="fp8"))
+
+gpu = fc.GPUSpec(name="MI300X", memory_gb=192, memory_bandwidth_gbps=5300,
+                 tdp_watts=750, peak_tflops={"bf16": 1307, "fp16": 1307, "fp8": 2615})
+print(fc.estimate("meta-llama/Llama-3-8B", gpu=gpu, precision="bf16"))
+```
+
+## Accuracy & limitations
+
+Estimates are analytical, first‑order, and meant for planning and comparison,
+not cycle‑accurate profiling. Real throughput depends heavily on the
+implementation, kernel quality, and achieved MFU — hence the tunable efficiency
+knobs. Activation memory is a rough estimate (inference is dominated by weights +
+KV cache). Mixture‑of‑Experts routing, speculative decoding, tensor/pipeline
+parallelism overheads, and multi‑GPU communication are **not** modelled yet.
+Parameter counts and matmul FLOP counts, however, are exact.
+
+## Roadmap
+
+Mixture‑of‑Experts models, multi‑GPU/parallelism cost models, encoder–decoder and
+vision‑language architectures, a curated empirical‑throughput calibration table,
+and prompt‑vs‑generation energy attribution.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

flopscalc-0.1.0/README.md

@@ -0,0 +1,254 @@
+# FLOPSCalc
+
+**Accurate FLOPs, memory, latency, and energy estimation for Large Language Models.**
+
+FLOPSCalc answers questions like *"how much compute, memory, and energy does one
+forward pass of Llama‑3‑8B at bf16 on an A100 actually cost?"* — analytically,
+in milliseconds, without downloading a single weight. It is built for
+transformers specifically (self‑attention, KV cache, GQA/MQA, gated MLPs), gives
+a **layer‑wise breakdown** rather than one opaque total, and models **precision,
+memory, latency, and energy** under different inference settings behind one API.
+
+```python
+from flopscalc import estimate
+
+result = estimate(
+    model="meta-llama/Llama-3-8B",
+    batch_size=4,
+    sequence_length=2048,
+    precision="bf16",
+    gpu="A100",
+)
+print(result)
+```
+
+```
+==============================================================
+ FLOPSCalc estimate: meta-llama/Meta-Llama-3-8B
+  batch=4  seq_len=2048  precision=bf16  gpu=A100-80GB-SXM
+==============================================================
+ Parameters        : 8.03B  (8,030,261,248)
+--------------------------------------------------------------
+ FLOPs (single forward pass over batch x seq)
+   Forward         : 131.885 TFLOP
+   Backward        : 263.770 TFLOP
+     - attention   : 30.880 TFLOP
+     - mlp         : 92.389 TFLOP
+     - embedding   : 0 FLOP
+     - layernorm   : 8.724 GFLOP
+     - output head : 8.607 TFLOP
+--------------------------------------------------------------
+ Memory
+   Total           : 17.268 GB
+     - weights     : 16.061 GB
+     - activations : 134.218 MB
+     - kv cache    : 1.074 GB
+   Fits on GPU     : yes
+--------------------------------------------------------------
+ Performance (roofline)
+   Prefill latency : 845.42 ms  [compute-bound]
+   Decode/token    : 10.50 ms  (381 tok/s)
+   Forward energy  : 287.44 J (0.0798 Wh)
+==============================================================
+```
+
+## Why FLOPSCalc
+
+Existing FLOP counters tend to support only CNNs, report a single total with no
+layer breakdown, ignore transformer‑specific structure (self‑attention cost, KV
+cache), and say nothing about precision, memory, latency, or energy. FLOPSCalc
+targets exactly those gaps:
+
+- **Transformer‑aware** — separate accounting for embeddings, multi‑head
+  attention (with GQA/MQA), the feed‑forward network (standard *and* gated /
+  SwiGLU), normalization, and the output head.
+- **More than FLOPs** — parameter count, weight/activation/KV‑cache memory,
+  roofline latency (prefill *and* decode), and energy.
+- **Precision‑aware** — fp32, tf32, fp16, bf16, fp8, int8, int4.
+- **One API to compare models** under different batch sizes, sequence lengths,
+  precisions, and GPUs.
+- **Hybrid accuracy** — a fast analytical core, plus an optional empirical mode
+  that checks the analytical FLOPs against a real PyTorch forward pass.
+
+## Install
+
+```bash
+pip install flopscalc                # analytical core, zero dependencies
+pip install "flopscalc[hf]"          # + fetch model configs from the HF Hub
+pip install "flopscalc[torch]"       # + empirical validation (torch, transformers)
+```
+
+The analytical core is **pure Python with no required dependencies**, so it runs
+anywhere and can size a 70B model on a laptop.
+
+## The `estimate()` API
+
+```python
+estimate(
+    model,                      # registry name / HF id, ModelConfig, or dict
+    batch_size=1,
+    sequence_length=2048,
+    precision="bf16",           # fp32|tf32|fp16|bf16|fp8|int8|int4 (aliases ok)
+    gpu="A100",                 # GPU name / GPUSpec, or None to skip latency/energy
+    *,
+    include_backward=True,      # also report training (backward) FLOPs
+    causal=False,               # count only causal (lower-triangular) attention
+    num_generated_tokens=128,   # decode horizon for full-request latency/energy
+    kv_cache_precision=None,    # defaults to precision (fp16 when weights are int8/int4)
+    flash_attention=True,       # activation-memory model
+    activation_factor=2.0,
+    compute_efficiency=0.5,     # roofline MFU
+    mem_efficiency=0.8,         # achievable fraction of peak bandwidth
+    power_utilization=0.85,     # mean power draw as a fraction of TDP
+    allow_hf_fetch=True,
+)
+```
+
+The returned `EstimationResult` behaves like a `dict` (so `result["forward_flops"]`
+and `json.dumps(result)` both work) but prints as the report above. Dictionary
+values use SI base units: **FLOPs are raw counts, memory is bytes, latency is
+seconds, energy is joules.** The ten headline keys match the documented shape:
+
+```python
+{
+  "parameters":     8030261248,
+  "forward_flops":  131_885_...,
+  "backward_flops": 263_770_...,
+  "attention_flops": ...,   "mlp_flops": ...,   "embedding_flops": ...,
+  "memory":         ...,    "kv_cache":  ...,
+  "latency":        0.845,  "energy":    287.4,
+}
+```
+
+A full nested breakdown (per‑component FLOPs, parameter and memory breakdowns,
+prefill/decode performance, and the settings used) lives under
+`result["details"]`.
+
+### Comparing models
+
+```python
+from flopscalc import compare
+
+print(compare(
+    ["gpt2", "meta-llama/Llama-3-8B", "mistralai/Mistral-7B-v0.1"],
+    batch_size=1, sequence_length=4096, precision="bf16", gpu="A100",
+))
+```
+
+### Command line
+
+```bash
+flopscalc estimate meta-llama/Llama-3-8B -b 4 -s 2048 -p bf16 -g A100
+flopscalc compare gpt2 meta-llama/Llama-3-8B -p bf16 -g A100
+flopscalc estimate meta-llama/Llama-3-8B --json          # machine-readable
+flopscalc list-models
+flopscalc list-gpus
+```
+
+## Methodology
+
+**FLOPs.** A matmul `[m,k]·[k,n]` costs `2·m·k·n` FLOPs (one multiply + one add
+per MAC) — the standard Kaplan/Chinchilla convention, so results are directly
+comparable to published figures. Per layer FLOPSCalc counts the Q/K/V/output
+projections, the `Q·Kᵀ` and `softmax·V` attention terms (`O(s²)`, halved with
+`causal=True`), and the MLP matmuls (2 matrices for a standard MLP, 3 for a gated
+SwiGLU/GeGLU), plus the small softmax/normalization/activation/RoPE element‑wise
+terms. The token‑embedding lookup is a gather (≈0 FLOPs); the output head is
+`2·N·h·V`. This reproduces the familiar `forward ≈ 2·N·D` per‑token result;
+the backward pass is `≈ 2×` the forward pass, giving the `6·N·D` training
+estimate.
+
+**Memory.** The parameter count is exact and reproduces published model‑card
+figures (see below). Runtime memory = weights (`params × bytes/precision`) +
+KV cache + a first‑order activation estimate. The **KV cache** is
+`2 · batch · seq · layers · (kv_heads · head_dim) · bytes`, so grouped‑query
+attention shrinks it by `num_heads / num_kv_heads`.
+
+**Latency & energy (roofline).** Prefill and decode are modelled separately
+because they behave differently. Prefill (encoding the prompt) is compute‑bound:
+`time = FLOPs / (peak_throughput × MFU)`. Decode (one token at a time) is
+memory‑bandwidth‑bound: each step re‑reads every weight and the KV cache from
+HBM, so `time = bytes_moved / (bandwidth × utilization)`. Each phase takes
+`max(compute_time, memory_time)`. Energy = `time × TDP × power_utilization`.
+The efficiency knobs (`compute_efficiency`/MFU, `mem_efficiency`,
+`power_utilization`) are the dominant source of error and are exposed as
+parameters.
+
+### Validation
+
+Bundled model parameter counts match their public model cards **exactly**:
+
+| Model | FLOPSCalc | Published |
+|---|---|---|
+| GPT‑2 | 124,439,808 | 124M |
+| Llama‑2‑7B | 6,738,415,616 | 6.74B |
+| Mistral‑7B | 7,241,732,096 | 7.24B |
+| Llama‑3‑8B | 8,030,261,248 | 8.03B |
+| Qwen2.5‑7B | 7,615,716,864 | 7.61B |
+| Gemma‑7B | 8,537,680,896 | 8.54B |
+| Llama‑2‑70B | 68,976,648,192 | ~69B |
+| Llama‑3‑70B | 70,553,706,496 | 70.6B |
+
+The optional empirical mode checks FLOPs against a real forward pass:
+
+```python
+import flopscalc as fc
+cfg = fc.ModelConfig(name="tiny", hidden_size=256, num_layers=4,
+                     num_attention_heads=8, num_key_value_heads=4,
+                     vocab_size=1024, intermediate_size=688, model_type="llama")
+print(fc.validate(cfg, batch_size=1, sequence_length=64))
+# {'measured_forward_flops': ..., 'analytical_forward_flops': ..., 'ratio': ~1.0, ...}
+```
+
+## Supported models, GPUs, and precisions
+
+**Models (bundled).** GPT‑2 (base/medium/large/xl), Llama‑2 (7B/13B/70B),
+Llama‑3 / 3.1 / 3.2 (1B/3B/8B/70B), Mistral‑7B, Qwen2.5 (0.5B/7B/72B), Phi‑2,
+Gemma (2B/7B), Falcon‑7B. Anything else resolves via the Hugging Face Hub —
+the parser normalizes field-name variance across architectures (GPT‑2's
+`n_embd`, Falcon's `multi_query` and implicit `intermediate_size`, nested
+`text_config` for multimodal models, etc.). Or pass your own `ModelConfig` /
+dict, or `register_model(...)`. (Mixture‑of‑Experts models fetch fine but their
+FLOPs are overcounted as dense — MoE is on the roadmap.)
+
+**GPUs (bundled).** A100 (40/80GB, SXM/PCIe), H100 (SXM/PCIe), H200, V100, T4,
+L4, L40S, A10G, A6000, RTX 4090, RTX 3090. Define a `GPUSpec` for anything else.
+
+**Precisions.** fp32, tf32, fp16, bf16, fp8, int8, int4.
+
+## Custom models and hardware
+
+```python
+import flopscalc as fc
+
+cfg = fc.ModelConfig(
+    name="my-model", hidden_size=4096, num_layers=32, num_attention_heads=32,
+    num_key_value_heads=8, intermediate_size=14336, vocab_size=128256,
+    mlp_type="gated", norm_type="rmsnorm", positional="rope",
+)
+print(fc.estimate(cfg, gpu="H100", precision="fp8"))
+
+gpu = fc.GPUSpec(name="MI300X", memory_gb=192, memory_bandwidth_gbps=5300,
+                 tdp_watts=750, peak_tflops={"bf16": 1307, "fp16": 1307, "fp8": 2615})
+print(fc.estimate("meta-llama/Llama-3-8B", gpu=gpu, precision="bf16"))
+```
+
+## Accuracy & limitations
+
+Estimates are analytical, first‑order, and meant for planning and comparison,
+not cycle‑accurate profiling. Real throughput depends heavily on the
+implementation, kernel quality, and achieved MFU — hence the tunable efficiency
+knobs. Activation memory is a rough estimate (inference is dominated by weights +
+KV cache). Mixture‑of‑Experts routing, speculative decoding, tensor/pipeline
+parallelism overheads, and multi‑GPU communication are **not** modelled yet.
+Parameter counts and matmul FLOP counts, however, are exact.
+
+## Roadmap
+
+Mixture‑of‑Experts models, multi‑GPU/parallelism cost models, encoder–decoder and
+vision‑language architectures, a curated empirical‑throughput calibration table,
+and prompt‑vs‑generation energy attribution.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

flopscalc-0.1.0/conftest.py

@@ -0,0 +1,6 @@
+"""Make the ``src`` layout importable during tests without installation."""
+
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "src"))