wifi-densepose/v2/crates/wifi-densepose-train

wifi-densepose-train

Complete training pipeline for WiFi-DensePose, integrated with all five ruvector crates.

Overview

wifi-densepose-train provides everything needed to train the WiFi-to-DensePose model: dataset loading, subcarrier interpolation, loss functions, evaluation metrics, and the training loop orchestrator. It supports both the MM-Fi dataset (NeurIPS 2023) and deterministic synthetic data for reproducible experiments.

Without the tch-backend feature the crate still provides the dataset, configuration, and subcarrier interpolation APIs needed for data preprocessing and proof verification.

Features

• MM-Fi dataset loader -- Reads the MM-Fi multimodal dataset (NeurIPS 2023) from disk with memory-mapped .npy files.
• Synthetic dataset -- Deterministic, fixed-seed CSI generation for unit tests and proofs.
• Subcarrier interpolation -- 114 -> 56 subcarrier compression via ruvector-solver sparse interpolation with variance-based selection.
• Loss functions (tch-backend) -- Pose estimation losses including MSE, OKS, and combined multi-task loss.
• Metrics (tch-backend) -- PCKh, OKS-AP, and per-keypoint evaluation with ruvector-mincut-based person matching.
• Training orchestrator (tch-backend) -- Full training loop with learning rate scheduling, gradient clipping, checkpointing, and reproducible proofs.
• All 5 ruvector crates -- ruvector-mincut, ruvector-attn-mincut, ruvector-temporal-tensor, ruvector-solver, and ruvector-attention integrated across dataset loading, metrics, and model attention.

Feature flags

Flag	Default	Description
tch-backend	no	Enable PyTorch training via tch-rs
cuda	no	CUDA GPU acceleration (implies tch)

Binaries

Binary	Description
train	Main training entry point
verify-training	Proof verification (requires tch-backend)

Quick Start

use wifi_densepose_train::config::TrainingConfig;
use wifi_densepose_train::dataset::{SyntheticCsiDataset, SyntheticConfig, CsiDataset};

// Build and validate config
let config = TrainingConfig::default();
config.validate().expect("config is valid");

// Create a synthetic dataset (deterministic, fixed-seed)
let syn_cfg = SyntheticConfig::default();
let dataset = SyntheticCsiDataset::new(200, syn_cfg);

// Load one sample
let sample = dataset.get(0).unwrap();
println!("amplitude shape: {:?}", sample.amplitude.shape());

Architecture

wifi-densepose-train/src/
  lib.rs            -- Re-exports, VERSION
  config.rs         -- TrainingConfig, hyperparameters, validation
  dataset.rs        -- CsiDataset trait, MmFiDataset, SyntheticCsiDataset, DataLoader
  error.rs          -- TrainError, ConfigError, DatasetError, SubcarrierError
  subcarrier.rs     -- interpolate_subcarriers (114->56), variance-based selection
  losses.rs         -- (tch) MSE, OKS, multi-task loss        [feature-gated]
  metrics.rs        -- (tch) PCKh, OKS-AP, person matching     [feature-gated]
  model.rs          -- (tch) Model definition with attention    [feature-gated]
  proof.rs          -- (tch) Deterministic training proofs      [feature-gated]
  trainer.rs        -- (tch) Training loop orchestrator         [feature-gated]

MERIDIAN-MAE — masked-autoencoder pre-training (ADR-027 §2.0)

The csi_mae module implements a CIG-MAE-style dual-stream (amplitude + phase) masked autoencoder for cross-domain CSI pre-training. The thesis (2026-Q2 SOTA survey, arXiv:2511.18792): cross-room generalisation is a data-breadth problem — pre-train one CSI encoder on heterogeneous capture, attach a small task head — not a bigger-pose-net problem.

• Pure-Rust (always built): MaeConfig, MaskStrategy (Random / InfoGuided — the latter variance-weights token selection so high-information tokens are masked), TokenLayout, mask_csi_window, reassemble_tokens. Dependency-free deterministic masking.
• csi_mae::model (feature tch-backend): CsiMae (encoder over visible tokens → latent → decoder reconstructs masked amplitude+phase), reconstruction_loss, MaeBatch, pretrain_step.
• Driver: cargo run -p wifi-densepose-train --features tch-backend --bin pretrain-mae -- --epochs 5 (synthetic data). GPU run: bash scripts/pretrain-mae-gcloud.sh (prototype wiring stub).

See docs/adr/ADR-027-cross-environment-domain-generalization.md §2.0 for the full plan (heterogeneous-CSI ingest, GPU pre-train, fine-tune handoff, cross-domain eval).

Related Crates

Crate	Role
wifi-densepose-signal	Signal preprocessing consumed by dataset loaders
wifi-densepose-nn	Inference engine that loads trained models
ruvector-mincut	Person matching in metrics
ruvector-attn-mincut	Attention-weighted graph cuts
ruvector-temporal-tensor	Compressed CSI buffering in datasets
ruvector-solver	Sparse subcarrier interpolation
ruvector-attention	Spatial attention in model

License

MIT OR Apache-2.0