Diffusion-Explorer and the case for showing rather than telling

A teaching tool, stated plainly

Diffusion Explorer is an interactive tool for communicating the geometric intuitions behind diffusion and flow based generative models. The README is explicit about the purpose, that it is mainly an educational tool, and it says the project is currently a work in progress.

That framing decides how to read everything else in the repository. This is not a training framework and not a library you would depend on. It is an application whose output is understanding, and the code in the repository exists so that the visualisations can be regenerated rather than merely watched.

The four key functionalities are listed plainly. It implements various training objectives like Flow Matching and Denoising Score Matching. It shows the dynamics of generated samples over time for pretrained models. It allows a user to observe how generated samples change through training. And it enables training on custom hand drawn distributions.

The third of those is the one that separates this from a slide deck. Watching a sample evolve as the model trains is a different object from watching a sample evolve as the sampler runs. The first shows what a learning algorithm is doing to a distribution, which is the part that is genuinely hard to picture from equations, and the fourth extends it to a distribution the author drew, which removes the dataset as a variable and lets you reason about the geometry directly.

The repository layout is a monorepo with apps/ for the individual applications, a diffusion-explorer/ directory for the main tool, a media/ directory for assets, a .gitmodules file for submodules, and a CLAUDE.md file for tooling that reads repository instructions. A .claude directory is also present, which is the same idea applied to a different assistant.

The rectified flow explainer and the few-step problem

The second half of the project is a separate artefact, an interactive blog post explaining Rectified Flow, described in the README as a technique for straightening the trajectories learned by flow matching models. A live demo is published at alechelbling.com/blog/rectified-flow, and there is a video embedded in the repository as well.

The explainer is organised around four claims, and the sequence is the argument.

First, how flow matching learns curved trajectories between distributions. The learned paths between a noise distribution and a data distribution are not straight, and they are not the same for every pair of points, which is the geometric fact everything else rests on.

Second, why curved paths are problematic for few-step sampling. A sampler that takes one or a handful of steps has to approximate a curved trajectory with a straight line, and the error compounds along the way. This is the connection between the geometry of training and the engineering parameter of step count, and it is the single most useful thing the explainer teaches.

Third, how rectified flow iteratively straightens trajectories. Rather than accepting the curvature that flow matching produces, the method retrains, or refines, so the paths become straighter, and the explainer animates that process.

Fourth, the connection between straight paths and optimal transport. Straightening is not an aesthetic preference, it is moving the learned coupling toward the optimal transport coupling, which is where the theory says the paths should be.

There is also a beta version of the main tool hosted separately, and the README links it. For a tool that is still in progress, that distinction matters, because the hosted build and the repository can be at different states.

Running it locally

The project is a Node application, and the local setup is three commands after the clone:

git clone https://github.com/helblazer811/Diffusion-Explorer
cd diffusion-explorer
npm install

Then the dev server:

npm run dev

The README says to access it in your browser at the specified port. For the rectified flow explainer application specifically, the instructions are more concrete, and the browser URL is typically http://localhost:5173:

cd diffusion-explorer/apps/rectified-flow-explainer
npm install
npm run dev

The nested directory is a monorepo detail worth noticing, since the explainer is one application inside the apps/ tree and it has its own dependencies. The main tool at the repository root has its own install and dev cycle.

The two instructions disagree slightly on how to reach the port, one saying to use the port shown in the terminal and the other naming 5173 as typical, which is the usual Vite behaviour. Either way, nothing here is exotic: a clone, an install and a dev server, with no model weights to download and no dataset to prepare, because the samples the tool displays are cached.

The cached part matters for what you can expect. The tool shows the dynamics of samples over time for pretrained models, and those trajectories are stored rather than computed at run time, which is what makes the interactive experience start instantly. It also means the visualisations are only as current as the cache, a point the training scripts address directly.

Retraining the models and regenerating the cache

The repository is not only a viewer. Three scripts cover the case where you want the models to match what you see, and the README names them:

npm run train:flow-matching    # Train base flow matching model
npm run train:rectified-flow   # Train rectified flow model (3 steps)
npm run cache-samples          # Regenerate cached trajectories

The three of them form a sequence. The first trains the base flow matching model, the second trains the rectified flow model with three steps, and the third regenerates the cached trajectories that the visualiser then plays back.

The comment on the second script is a small but telling detail. The rectified flow model is trained with 3 steps, and few-step sampling is exactly the regime the explainer is built around.

The separation between training and caching is the sensible design for an educational tool. Recomputing trajectories on every page load would make the explainer slow and would make the animation dependent on the visitor's hardware, and caching turns a training-time cost into a one-off cost. The cost of that choice is staleness, and the cache-samples script exists so that anyone who retrains can bring the visualisation back in line.

The training objectives implemented cover both sides of the modern picture, Flow Matching and Denoising Score Matching, so the tool can be used to compare how two different objectives shape the trajectories rather than showing only the favourable case.

A static blog post cannot show curvature moving

The alternative to this project is a written explanation of flow matching and rectified flow, with equations, and that is the honest comparison.

A static write-up can state that flow matching learns curved trajectories and that straightening them helps few-step sampling. What it cannot do is let the reader drag a slider and watch a trajectory bend, or watch the curvature reduce as the rectified flow model trains. The interactive version turns a claim about geometry into an observation, which is the difference between believing a result and seeing it.

The second alternative is the hosted version. There is a live demo of the explainer at alechelbling.com/blog/rectified-flow and a beta of the main tool at alechelbling.com/Diffusion-Explorer, both of which remove the install step entirely. The trade-off is that a hosted beta is a moving target that you cannot inspect or modify, and the repository version can lag it or lead it depending on when the deploy happened.

The third consideration is what the code is for. In a normal library, you install the package and call it. Here, the code is the instrument that produces the pictures. That reframes the maintenance question: you are not upgrading a dependency, you are checking whether the cached trajectories still match the current code, and the cache-samples script is how you answer that.

No licence file, no releases, and an explicit work in progress

The repository tree lists no LICENSE file, and the licence for the project is not recorded in the repository metadata. That gap is still a gap, and anyone who wants to reuse the code or the visualisations has to ask the author first. This is worth resolving before an article or a course depends on it.

The rest of the release picture is thin in the same way. There are no GitHub releases, so there is no tagged version to pin, and the repository is not archived. The last push was on 2026-09-05, which is a little over a month before the current state of the project.

What the repository does have is a README that describes its own status accurately, calling itself a work in progress and pointing to a beta build, and a table of scripts small enough to read in a minute. For a project whose purpose is explanation, that combination of a candid status note and a short, complete set of commands is a decent sign.

One more detail is worth noting for anyone cloning it. There is a.gitmodules file, so the repository uses submodules, and a clone without the recursive flag will leave those directories empty. That is a small friction point in an otherwise very easy setup, and it is the kind of thing that costs a confused beginner an afternoon.

Editorial conclusion

Adopt Diffusion-Explorer if you teach diffusion or flow matching, or if you are trying to build intuition for why few-step sampling fails on curved trajectories, because the animated rectified flow explainer makes that argument in a way a static blog post cannot. Do not adopt it as a library or a training framework, since the value is in the visualisations and the repository ships an application rather than an API. Verify three things first: that the version you run matches the hosted beta, since the project is explicitly a work in progress, that the cached trajectories you are shown match the models you retrain, which is what the cache-samples script exists for, and whether you can use the code at all, because the repository lists no licence file and no release history. The last push was on 2026-09-05.

Frequently asked questions

Official sources

1. helblazer811/Diffusion-Explorer on GitHub
2. Issues
3. README