Skip to content

Documentation

What is in this directory, what each document means, and which one to open for which question. ../README.md is the project front page.

docs/ holds four different kinds of material that are easy to confuse:

kind directories trust it for
How the system works and how to drive it architecture.md, reproducibility.md, guides/, reference/ running the code, and what the interfaces accept
What was checked, by whom, and how audit/, reports/ whether a claim has been independently verified
The published research isac/, eucnc/, icaisf/, supplementary/ the papers, their numbers and their sources
Project context eucnc/project_description.md why this exists, in funder terms

The distinction matters when you are deciding what to believe. A guide tells you what a command accepts; a verification report tells you what someone ran; a master-results file tells you which artifact a published number came from. They are not interchangeable, and only one of the three is generated from code.


if you are… read
new to the codebase architecture.md — the data flow and the model families
trying to run something guides/commands.md — every command with a realistic invocation
looking for an exact option or default reference/cli.md — generated from the program
reviewing the work audit/AUDIT_CHECKLIST.md — what you can verify yourself, and the command for each
taking a model to another machine guides/rust-and-devices.md

document what it means
architecture.md The end-to-end story: WiFi RSSI windows → classification → the model families and how they differ; the registry, sidecars and artifact store. Read first.
reproducibility.md What an independent reader needs to re-run this work: environment, seeds, the split convention, what is and is not reproducible, and the known provenance gaps stated rather than hidden.

Task-oriented, hand-written. Each answers “what do I type, and why”.

document what it means
guides/commands.md Every command, when to reach for it, and a realistic invocation. The map of the whole CLI.
guides/training.md How to train each family, on a workstation or a cluster, including the environment traps (for example MAMBA_SSM_AVAILABLE=0).
guides/running-models.md Using a saved checkpoint: list, inspect, verify, predict, adopt one that has no sidecar, and the known exceptions.
guides/rust-and-devices.md Running inference without Python: export an artifact, cross-build for another device, prove parity on that device, and measure it. Covers the before/after kernel benchmark too.

3. Looking things up — reference (generated)

Section titled “3. Looking things up — reference (generated)”

These five are generated from the code by scripts/docs/generate_reference.py, which is why they cannot silently disagree with it: scripts/check.sh and tests/test_documentation.py both fail if they are stale. Regenerate with uv run python scripts/docs/generate_reference.py.

document generated from what it means
reference/cli.md the typer app in src/inmotion/cli/ every command, argument, option and default the program actually accepts
reference/pipelines.md each pipeline’s RunConfig dataclass every pipeline option, so the option list cannot drift from the code
reference/models.md inmotion.models.registry every registered model: factory, architecture, parameter count, provenance, and what it consumes at its input
reference/modules.md the source tree every module, its purpose and its public API
reference/datasets.md inmotion.datasets every dataset version: checksum, counts, lineage, label audit

Because they are generated, do not hand-edit them — the change will be lost on the next regeneration and the freshness check will fail.

document what it means
audit/AUDIT_CHECKLIST.md What a reviewer can independently verify, and the command for each row. Written so that nothing requires trusting the authors.
audit/MODEL_CARDS.md Per-family model cards following the Model Cards for Model Reporting convention: what the model is, what it was trained on, how it was evaluated, its limitations, and what it is out of scope for.

This is the history, not the current interface. reports/README.md is the folder index; the documents fall into three groups.

Provenance and where things live

document what it means
reports/MIGRATION.md Old command → new command, and what has not been reorganised yet.
reports/REFACTOR_SUMMARY.md What changed in the reorganisation, with before/after measurements.

Measured study. ../results/edge/REPORT.md is the current quantization, device and router-interference study; ../results/edge/TABLES.md holds every table it cites. The old quantization campaign (results/quant, results/campaign, results/perf), its figures and the ESP32 feasibility results were removed with the pipeline that produced them.

6. The published research — papers and results

Section titled “6. The published research — papers and results”
directory what it means
isac/ The FNWF 2026 paper material: LaTeX sources and figures under isac/paper/, and the conference deck under isac/presentation/ (one presentation.md compiled with pandoc to Beamer).
eucnc/ The EuCNC/6G Summit submission, frozen: LaTeX sources under eucnc/paper/, the slide deck under eucnc/presentation/, the call for papers, and eucnc/project_description.md — the inMotion project described in funder terms (Portuguese).
icaisf/ Supplementary hyperparameter-optimisation detail for the ICAISF submission: the best configuration per model.
supplementary/ Hyperparameter-optimisation material: search_spaces.md, optimal_hyperparameters.md, optuna-summary.md and a README that frames them.

Two cautions. These directories are frozen for submission, so editing them changes what was submitted.

path what it is
eucnc/paper/ The LaTeX source of the EuCNC paper: main.tex, chapters/, images/, references.bib, and build output (.aux, .log, .pdf). Build artefacts are committed alongside the source.
eucnc/EuCNC6GS2026_callforPapers_Final.pdf The conference call the submission targets.
  • Generated vs hand-written. Only reference/ is generated. Everything else is hand-written and therefore can go stale — treat a claim in a hand-written document as an assertion about the revision it was written at, not as a description of the current tree.
  • History is kept, not tidied. reports/ records what was found and fixed, including superseded values and retracted diagnoses. Seeing a wrong value in a report usually means it is being described as wrong; check the surrounding sentence before “fixing” it.
  • Pins travel with verdicts. A review or verification document states the revision it judged. If a file it names has since moved, the verdict still holds for that revision and must be re-taken for the current one — it does not silently extend.
  • Keeping it green. uv run python scripts/docs/generate_reference.py --check and uv run pytest tests/test_documentation.py fail on stale generated docs and on references to paths that no longer exist. Run both after moving or renaming anything under docs/.