Add comprehensive knowledge base documentation across multiple domains

2026-02-12 14:36:37 +08:00
parent f754f6f383
commit 0fdd35bd78
8 changed files with 336 additions and 0 deletions
@@ -0,0 +1,33 @@
+# MODELING DOMAIN KNOWLEDGE BASE
+
+## OVERVIEW
+`opengait/modeling/` defines model contracts and algorithm implementations: `BaseModel`, loss aggregation, backbones, concrete model classes.
+
+## STRUCTURE
+```text
+opengait/modeling/
+├── base_model.py        # canonical train/test lifecycle
+├── loss_aggregator.py   # training_feat -> weighted summed loss
+├── modules.py           # shared NN building blocks
+├── backbones/           # backbone registry + implementations
+├── losses/              # loss registry + implementations
+└── models/              # concrete methods (Baseline, ScoNet, DeepGaitV2, ...)
+```
+
+## WHERE TO LOOK
+| Task | Location | Notes |
+|------|----------|-------|
+| Add new model | `models/*.py` + `docs/4.how_to_create_your_model.md` | must inherit `BaseModel` |
+| Add new loss | `losses/*.py` | expose via dynamic registry |
+| Change training lifecycle | `base_model.py` | affects every model |
+| Debug feature/loss key mismatches | `loss_aggregator.py` | checks `training_feat` keys vs `loss_cfg.log_prefix` |
+
+## CONVENTIONS
+- `forward()` output contract is fixed dict with keys: `training_feat`, `visual_summary`, `inference_feat`.
+- `training_feat` subkeys must align with configured `loss_cfg[*].log_prefix`.
+- Backbones/losses/models are discovered dynamically via package `__init__.py`; filenames matter operationally.
+
+## ANTI-PATTERNS
+- Do not return arbitrary forward outputs; `LossAggregator` and evaluator assume fixed contract.
+- Do not put model classes outside `models/`; config lookup by `getattr(models, name)` depends on registry.
+- Do not ignore DDP loss wrapping (`get_ddp_module`) in loss construction.