flodl

Coming from PyTorch?

Three ways to land. Pick the one that fits how you work.

The training loop is the one you already know:

model.train()
for epoch in range(num_epochs):
    for batch in loader:
        optimizer.zero_grad()
        pred = model(batch[0])
        loss = criterion(pred, batch[1])
        loss.backward()
        optimizer.step()

model.train();
for epoch in 0..num_epochs {
    for batch in loader.epoch(epoch) {
        let batch = batch?;
        optimizer.zero_grad();
        let pred = model.forward(&batch[0].into())?;
        let loss = cross_entropy_loss(&pred, &batch[1].into())?;
        loss.backward()?;
        optimizer.step()?;
    }
}

Not writing Rust yet? fdl still helps.

The CLI is its own published crate. Outside a flodl checkout it's a first-class libtorch manager for tch-rs and PyTorch C++ users -- the installer PyTorch itself never shipped. One binary, zero native dependencies, works before anything else is set up.

fdl libtorch download --cuda 12.8
fdl libtorch list
fdl libtorch activate precompiled/cu128

fdl libtorch build --archs "6.1;12.0"
fdl libtorch build --native --jobs 8

export LIBTORCH=$FLODL_HOME/libtorch/precompiled/cu128
cargo add tch
cargo build

Standalone reference → flodl-cli on crates.io →

Explainable config, per environment

Deep-merge fdl.ci.yml or fdl.local.yml on top of the base manifest with --env. fdl config show prints the resolved result with per-layer origin annotations -- you see exactly which file, which line, contributed each field before running a long job.

$ fdl --env ci config show
# resolved manifest, base + overlay
docker: dev                     # fdl.yml:2
ddp:
  policy: cadence               # fdl.yml:8
  backend: cpu                  # fdl.ci.yml:3 (override)
  divergence_threshold: 0.05    # fdl.yml:10
training:
  epochs: 1                     # fdl.ci.yml:6 (override)
  seed: 42                      # fdl.yml:13
  batch_size: 32                # fdl.yml:14
commands:
  quick:                        # fdl.yml:18 (preset)
    training: { epochs: 1 }
    options: { model: linear, batches: 100 }

Three equivalent ways to apply an overlay: fdl --env ci test, FDL_ENV=ci fdl test, or just fdl ci test when the name doesn't collide with a command. Explicit selectors fail loudly on missing files; the first-arg convention falls through so existing commands are never shadowed.

Build your model

The fluent graph builder reads as data flow. from / through / also / split / merge / loop_body / tag / using compose into residuals, parallel heads, loops, and cross-connections.

use flodl::*;

let model = FlowBuilder::from(Linear::new(4, 32)?)
    .through(GELU::new())                // activation
    .through(LayerNorm::new(32)?)       // normalization
    .also(Linear::new(32, 32)?)          // residual: output = input + Linear(input)
    .through(Linear::new(32, 1)?)        // output projection
    .build()?;

// The same model composes into multi-head, gated, or looped shapes without
// writing a forward() method. Every .tag() makes a point observable.

Graph builder reference →

Up to 31% faster than PyTorch

10 models, 10 interleaved rounds, locked GPU clocks. flodl wins 8 of 10, ties 2, zero regressions.

Full benchmark report →

Multi-GPU that beats published baselines

A mixed consumer cluster reaches better CIFAR-10 accuracy than He et al. (2015), in less wall time than the fastest single GPU. Same training loop. One knob.

ElChe cadence auto-detects per-GPU speed. The slow device anchors synchronization; the fast one ranges ahead and fills what would be idle time. Three policies × two backends, A/B-testable in one line.

Ddp::setup(&model, &builder, |p| Adam::new(p, 0.001))?;

for batch in model.epoch(0) {
    let batch = batch?;
    let loss = model.forward_batch(&batch)?.mse(&target)?;
    loss.backward()?;
    model.step()?;      // AllReduce + sync + optimizer + zero_grad
}

let ddp = Ddp::builder(model_factory, optim_factory, train_fn)
    .dataset(dataset)
    .batch_size(32)
    .num_epochs(10)
    .policy(ApplyPolicy::Cadence)      // Sync | Cadence | Async
    .backend(AverageBackend::Nccl)     // Nccl | Cpu
    .run()?;

let state = ddp.join()?;            // averaged params + buffers on CPU

DDP benchmark report → DDP reference →

Training you can actually see

A live web dashboard with loss curves, GPU and VRAM tracking, per-rank throughput, and ETA. Zero external dependencies. monitor.serve(3000) and open a browser.

Live dashboard from an earlier FBRL letter model run (v0.1.1, GTX 1060), 19% faster with the training monitor running.

Why flodl

A Rust-native framework for researchers who care about what happens between the GPU kernels.

We started this because training in the dark stopped being normal. Loss numbers trickling through a Python interpreter, GPUs stalling behind a wall we couldn't see through. One day, we walked out.

Read the manifesto The trajectory thesis