Update physics and add vla wm

Signed-off-by: guillemdb <guillem@fragile.tech>

Author: Guillemdb

README.md

@@ -1,87 +1,109 @@
 # Fragile
 
-Fragile is a research codebase for the Fractal Gas optimization algorithm and the
-Fractal Set data structure, with a Jupyter Book that captures the theory, derivations,
+Fragile is a research codebase for the **Fractal Gas** optimization algorithm and the
+**Fractal Set** data structure, with a Jupyter Book that captures the theory, derivations,
 and experiments.
 
-## What This Repo Contains
+## Install
 
-- `src/fragile/`: installable package (core implementation lives in `src/fragile/fractalai/`)
-- `docs/`: Jupyter Book (source in `docs/source/`, build output in `docs/_build/`)
-- `tests/`: pytest suites
-- `examples/`, `media/`, `outputs/`: notebooks, assets, generated artifacts
+```bash
+uv sync --all-extras          # recommended
+uv pip install -e .           # alternative
+uv tool install hatch         # one-time, for hatch commands
+```
 
-## Code Map
+## Dashboards
 
-- `src/fragile/fractalai/core/`: companion selection, fitness, cloning, kinetics,
-  and the Fractal Set data structure
-- `src/fragile/fractalai/experiments/`: simulations, dashboards, convergence studies
-- `src/fragile/fractalai/experiments/gauge/`: U(1) and SU(2) gauge symmetry tests
-- `src/fragile/fractalai/theory/`: theory utilities and analysis scripts
-- CLI entry point: `src/fragile/fractalai/cli.py`
+All dashboards launch via `uv run fragile <command>` and serve a Panel app in the browser.
 
-## Install
+### Videogames — Atari Fractal Gas
 
-- `uv sync --all-extras` (recommended)
-- `uv pip install -e .`
-- Tooling: `uv tool install hatch` (one-time, for `uv run hatch ...` commands)
+Explore Fractal Gas swarm dynamics on Atari environments (Breakout, Pong, etc.).
 
-## Documentation (Jupyter Book)
+```bash
+uv run fragile videogames                # http://localhost:5006
+uv run fragile videogames --port 8080    # custom port
+```
 
-- Build: `uv run hatch run docs:build`
-- Build and serve: `uv run hatch run docs:docs`
+### Robots — DM Control Fractal Gas
 
-## Development
+Visualize Fractal Gas on continuous-control MuJoCo tasks (cartpole, humanoid, etc.).
+
+```bash
+uv run fragile robots                    # http://localhost:5007
+```
+
+### Physics — QFT Swarm Convergence
+
+Analyse lattice QFT simulations: correlator fits, mass extraction, and convergence plots.
+
+```bash
+uv run fragile physics                   # http://localhost:5007
+uv run fragile physics --open            # auto-open browser
+```
+
+### DL — TopoEncoder Learning
+
+Monitor TopoEncoder training runs: loss curves, topology metrics, atlas visualisations.
+
+```bash
+uv run fragile dl                        # http://localhost:5008
+uv run fragile dl --outputs runs/        # custom outputs directory
+```
 
-- Tests: `uv run hatch run test:test`
-- Doctests: `uv run hatch run test:doctest`
-- Lint/format: `uv run hatch run lint:all`
+## Training
 
-## QFT Calibration
+Train the **TopoEncoder** (Attentive Atlas vs Standard VQ-VAE) directly from the CLI.
+All arguments after `--` are forwarded to the training script's argparse.
 
 ```bash
-python src/experiments/calibrate_fractal_gas_qft.py \
-  --history-path outputs/fractal_gas_potential_well/20260123_164153_history.pt \
-  --m-gev 91.1876 \
-  --hbar-eff 1.0 \
-  --d 3
+uv run fragile train -- --help                        # show all training options
+uv run fragile train -- --epochs 500 --dataset mnist  # full run
+uv run fragile train -- --epochs 1 --dataset mnist    # quick smoke test
 ```
 
-## QFT Ensemble Validation
+Key arguments:
 
-Run multi-trial statistical validation of QFT predictions with full Standard Model gauge group (U(1) × SU(2) × SU(3)):
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--dataset` | `mnist` | Dataset (`mnist`, `fashionmnist`, `cifar10`) |
+| `--epochs` | `200` | Training epochs |
+| `--batch-size` | `128` | Batch size |
+| `--latent-dim` | `64` | Latent dimension |
+| `--num-embeddings` | `512` | Codebook size |
+| `--use-atlas` | off | Enable Attentive Atlas |
+| `--num-charts` | `8` | Number of atlas charts |
+| `--output-dir` | `outputs/` | Output directory |
+
+## Documentation (Jupyter Book)
 
 ```bash
-python src/experiments/run_qft_validation_ensemble.py \
-  --n-trials 100 \
-  --n-walkers 1000 \
-  --n-steps 1000 \
-  --parallel-jobs 50 \
-  --use-viscous-coupling \
-  --nu 0.1 \
-  --viscous-length-scale 1.0 \
-  --output-dir outputs/qft_ensemble
+uv run hatch run docs:build   # build only
+uv run hatch run docs:docs    # build and serve
 ```
 
-Quick test (runs in ~30 seconds):
+## Development
 
 ```bash
-python src/experiments/run_qft_validation_ensemble.py \
-  --n-trials 5 \
-  --n-walkers 100 \
-  --n-steps 200 \
-  --parallel-jobs 2 \
-  --use-viscous-coupling \
-  --output-dir outputs/qft_ensemble_test
+uv run hatch run test:test     # tests
+uv run hatch run test:doctest  # doctests
+uv run hatch run lint:all      # lint / format
 ```
 
-Outputs:
-- `ensemble_report.md`: Summary with 95% confidence intervals
-- `ensemble_metrics.json`: Full statistics for all metrics
-- `plots/`: Correlation lengths, Wilson loops, phase distributions, SU(3) color alignment
+## Project Structure
+
+```
+src/fragile/
+  fractalai/          # Fractal Gas algorithm
+    core/             # companion selection, fitness, cloning, kinetics
+    videogames/       # Atari dashboard & environments
+    robots/           # DM Control dashboard & environments
+  physics/            # lattice QFT simulations & analysis dashboard
+  learning/           # TopoEncoder, training script & dashboard
+docs/                 # Jupyter Book (source in docs/source/)
+tests/                # pytest suites
+```
 
 ## License
 
 MIT
-
-/home/guillem/fragiletech/fragile/outputs/qft_calibrated/qft_penalty_thr0p75_pen0p9_m354_ed2p80_nu1p10_N10000_long_history.pt

src/fragile/__main__.py

@@ -99,5 +99,96 @@ def dl(port, open_browser, outputs):
     )
 
 
+@run.command(
+    context_settings={"ignore_unknown_options": True, "allow_extra_args": True},
+)
+@click.argument("args", nargs=-1, type=click.UNPROCESSED)
+def train(args):
+    """Train the TopoEncoder (Attentive Atlas vs Standard VQ-VAE).
+
+    All arguments after 'train' are forwarded to the training script.
+    Run `uv run fragile train -- --help` for all training options.
+    """
+    import sys
+
+    from fragile.learning.topoencoder_mnist import main
+
+    original_argv = sys.argv
+    sys.argv = ["fragile-train", *args]
+    try:
+        main()
+    finally:
+        sys.argv = original_argv
+
+
+@run.command(
+    "vla-train",
+    context_settings={"ignore_unknown_options": True, "allow_extra_args": True},
+)
+@click.argument("args", nargs=-1, type=click.UNPROCESSED)
+def vla_train(args):
+    """Train the TopoEncoder VLA experiment (3-phase pipeline).
+
+    All arguments after 'vla-train' are forwarded to the training script.
+    Run `uv run fragile vla-train -- --help` for all config options.
+    """
+    import sys
+
+    from fragile.learning.vla.train import main
+
+    original_argv = sys.argv
+    sys.argv = ["fragile-vla-train", *args]
+    try:
+        main()
+    finally:
+        sys.argv = original_argv
+
+
+@run.command(
+    "vla-unsup",
+    context_settings={"ignore_unknown_options": True, "allow_extra_args": True},
+)
+@click.argument("args", nargs=-1, type=click.UNPROCESSED)
+def vla_unsup(args):
+    """Unsupervised TopoEncoder training on VLA features.
+
+    All arguments after 'vla-unsup' are forwarded to the training script.
+    Run `uv run fragile vla-unsup -- --help` for all training options.
+    """
+    import sys
+
+    from fragile.learning.vla.train_unsupervised import main
+
+    original_argv = sys.argv
+    sys.argv = ["fragile-vla-unsup", *args]
+    try:
+        main()
+    finally:
+        sys.argv = original_argv
+
+
+@run.command(
+    "vla-joint",
+    context_settings={"ignore_unknown_options": True, "allow_extra_args": True},
+)
+@click.argument("args", nargs=-1, type=click.UNPROCESSED)
+def vla_joint(args):
+    """Joint encoder + world model training (3-phase pipeline).
+
+    All arguments after 'vla-joint' are forwarded to the training script.
+    Run `uv run fragile vla-joint -- --help` for all training options.
+    """
+    import sys
+
+    from fragile.learning.vla.train_joint import main
+
+    original_argv = sys.argv
+    sys.argv = ["fragile-vla-joint", *args]
+    try:
+        main()
+    finally:
+        sys.argv = original_argv
+
+
 if __name__ == "__main__":
     run()