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, and experiments.

Install

uv sync --all-extras          # recommended
uv pip install -e .           # alternative
uv tool install hatch         # one-time, for hatch commands

Dashboards

All dashboards launch via uv run fragile <command> and serve a Panel app in the browser.

Videogames — Atari Fractal Gas

Explore Fractal Gas swarm dynamics on Atari environments (Breakout, Pong, etc.).

uv run fragile videogames                # http://localhost:5006
uv run fragile videogames --port 8080    # custom port

Robots — DM Control Fractal Gas

Visualize Fractal Gas on continuous-control MuJoCo tasks (cartpole, humanoid, etc.).

uv run fragile robots                    # http://localhost:5007

Physics — QFT Swarm Convergence

Analyse lattice QFT simulations: correlator fits, mass extraction, and convergence plots.

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.

uv run fragile dl                        # http://localhost:5008
uv run fragile dl --outputs runs/        # custom outputs directory

Training

Train the TopoEncoder (Attentive Atlas vs Standard VQ-VAE) directly from the CLI. All arguments after -- are forwarded to the training script's argparse.

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

Key arguments:

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

The documentation portal links to the two-volume Theory lectures and the independent Control Laboratory guide.

make docs    # build the portal, Theory, and Lab sites
make serve   # build and serve the assembled documentation
make docs-serve  # serve an existing build without rebuilding

Open http://127.0.0.1:8000/docs/; the server root redirects to this portal. Theory lives at /docs/theory/, the lab guide at /docs/lab/, and the simulator at /lab/. Set DOCS_PORT=8001 to use another port. Documentation dependencies run in an isolated uv environment, without installing the training stack.

To build the simulator, run make control-web, then make control-lab and open http://127.0.0.1:8080/lab/. The browser build automatically activates an existing Emscripten SDK or downloads version 6.0.8 into .cache/emsdk/6.0.8 on first use. Use EMSDK_DIR=/path/to/emsdk make control-web for a custom SDK. Both local servers also serve the documentation after make docs.

Development

uv run hatch run test:test     # tests
uv run hatch run test:doctest  # doctests
uv run hatch run lint:all      # lint / format

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/                 # Documentation portal and Jupyter Books
tests/                # pytest suites

License

MIT