gfnx: Generative Flow Networks in jaX¶
gfnx is a JAX-native toolkit for building and studying Generative Flow
Networks (GFlowNets). It brings together a collection of benchmark environments
and reproducible baselines so you can iterate quickly on new ideas.
Start here¶
If you are new to gfnx, read these three pages in order:
-
1. Background
What a GFlowNet is, forward and backward policies, and the training objectives (DB, TB, SubTB) used throughout the library.
-
2. Walkthrough
A line-by-line tour of a complete Detailed Balance baseline on the Hypergrid, ending with a version vmapped over random seeds.
-
Environments, reward modules, rollout utilities and metrics, generated from the docstrings.
Prefer to run code first? The notebooks open in Google Colab and need nothing but a browser.
Highlights¶
- End-to-end JAX implementations of GFlowNet building blocks (environments, reward modules, networks, and metrics) — the full training pipeline JIT-compiles and runs on accelerator with no CPU↔GPU bouncing.
- A decoupled environment / reward API: environments expose only dynamics; reward modules are constructed and parameterised separately so they can be swapped or trained jointly with the policy.
- Single-state primitives (
env.step,env.reset,forward_rollout) plus a uniformTrue = validmask convention —jax.vmapprovides batching and seed parallelism for free. - Ready-to-run baseline agents inspired by the CleanRL style of concise single-file experiments, including vmap-over-seeds variants.
- Utilities for logging, checkpointing, and evaluation that make it easy to compare runs and extend the library with new research code.
Installation¶
Requirements¶
- Python 3.12, 3.13 or 3.14.
- A working JAX installation. CPU works out of the box; for GPU/TPU accelerators follow the official JAX installation guide.
Install the latest version¶
pip install git+https://github.com/d-tiapkin/gfnx.git
This installs the current main branch, which this documentation describes.
The gfnx package on PyPI (pip install gfnx, version 0.0.1) predates the
decoupled environment / reward API and does not match these docs.
For NVIDIA GPUs, add the CUDA 12 extra:
pip install "gfnx[cuda12] @ git+https://github.com/d-tiapkin/gfnx.git"
Verify the install with:
python -c "import gfnx; print('gfnx import OK')"
Develop locally and run baselines¶
git clone https://github.com/d-tiapkin/gfnx.git
cd gfnx
pip install -e ".[baselines]"
The quotes around ".[baselines]" matter in zsh (the default macOS shell).
The editable install keeps your local changes in sync with the Python package,
while the optional baselines extra pulls in the dependencies required by the
reference training scripts. In line with the CleanRL philosophy, the baselines
are not meant to be imported: they serve as reference implementations. The
TFBind-8, QM9, AMP and GFP rewards read data from proxy/, and the phylogenetic
datasets are fetched with bash download_ds.sh, so run those from the
repository root.
To build this documentation locally, see Building the docs.
Quickstart¶
Kick off a short training run of Detailed Balance in the Hypergrid environment:
python baselines/db_hypergrid.py num_train_steps=1_000 logging.tqdm_print_rate=100
The script is powered by Hydra, so you can override any configuration value on the command line (for example, picking another logging backend or playing with hyperparameters of the method). Baseline outputs, checkpoints, and Hydra logs default to tmp/<date>/<time>/; point the logging.log_dir or logging.checkpoint_dir fields to custom paths when running longer experiments.
For more context, continue with:
Support¶
- Open an issue on GitHub for bugs or feature requests.
- Start a discussion or reach out via pull requests if you would like to contribute improvements. Contributions with reproducible experiments and clear documentation get merged fastest.
License¶
gfnx is released under the MIT License. Feel free to use it in academic and commercial projects; please attribute the original authors when you publish results built on this codebase.
Influences¶
gfnx stands on the shoulders of several excellent open-source projects:
- torchgfn – PyTorch-first GFlowNet library that shaped our environment design.
- CleanRL – taught us the value of single-file baselines and reproducible experiment configs.
- purejaxrl and JaxMARL – reference points for idiomatic, accelerator-ready JAX reinforcement learning code.
Citation¶
@article{tiapkin2025gfnx,
title={gfnx: Fast and Scalable Library for Generative Flow Networks in JAX},
author={Tiapkin, Daniil and Agarkov, Artem and Morozov, Nikita and Maksimov, Ian and Tsyganov, Askar and Gritsaev, Timofei and Samsonov, Sergey},
journal={arXiv preprint arXiv:2511.16592},
year={2025}
}