scripts/param_count.py

"""Parameter budget of a FACT configuration (meta device, no weights allocated).

Usage::

    python scripts/param_count.py --config configs/fact_base_text.json
    python scripts/param_count.py --config-json '{"dim": 768, "num_layers": 8}'

The T-Rex Track-Force baselines (Wan2.2-TI2V-5B DiT + LoRA r=4 + force stage)
are reported as fixed reference numbers; their model code is not part of this
repository.
"""

from __future__ import annotations

import argparse
import json
from pathlib import Path

import torch
from torch import nn

from fact import FactConfig, FactPolicy

# Deployed / trainable parameter counts of the baselines (same counting rule,
# frozen umT5-XXL, CLIP ViT-H and the VAE excluded), in millions.
BASELINE_PARAMS_M = {
    "trex_track_force (A, track+force)": {"deployed_total": 5686.4, "trainable": 120.2},
    "trex notrack (B)": {"deployed_total": 5686.4, "trainable": 109.0},
}


def count(module: nn.Module, trainable_only: bool = False) -> int:
    return sum(p.numel() for p in module.parameters() if p.requires_grad or not trainable_only)


def main() -> None:
    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    parser.add_argument("--config", default=None, help="FactConfig JSON file (configs/*.json)")
    parser.add_argument("--config-json", default=None, help="inline JSON overrides applied after --config")
    args = parser.parse_args()
    cfg = FactConfig()
    overrides: dict = {}
    if args.config:
        overrides.update(json.loads(Path(args.config).read_text()))
    if args.config_json:
        overrides.update(json.loads(args.config_json))
    for key, value in overrides.items():
        if not hasattr(cfg, key):
            raise KeyError(f"unknown FactConfig field: {key}")
        setattr(cfg, key, value)
    with torch.device("meta"):
        fact = FactPolicy(cfg)
    report = {
        "fact": {
            "coarse_total": count(fact.coarse),
            "force_stage": 0 if fact.force is None else count(fact.force),
            "deployed_total": count(fact),
            "trainable": count(fact),
        }
    }
    print("fact")
    for key, value in report["fact"].items():
        print(f"   {key:20s} {value / 1e6:10.2f} M")
    for name, rec in BASELINE_PARAMS_M.items():
        print(name)
        for key, value in rec.items():
            print(f"   {key:20s} {value:10.2f} M  (reference)")
    print(json.dumps({**report, "baselines_M": BASELINE_PARAMS_M, "config": overrides}, indent=1))


if __name__ == "__main__":
    main()