[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-80964":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":16,"stars7d":12,"stars30d":17,"stars90d":15,"forks30d":15,"starsTrendScore":18,"compositeScore":19,"rankGlobal":9,"rankLanguage":9,"license":20,"archived":21,"fork":21,"defaultBranch":22,"hasWiki":21,"hasPages":21,"topics":23,"createdAt":9,"pushedAt":9,"updatedAt":24,"readmeContent":25,"aiSummary":26,"trendingCount":15,"starSnapshotCount":15,"syncStatus":27,"lastSyncTime":28,"discoverSource":29},80964,"EqR","locuslab\u002FEqR","locuslab","[ICML 2026] Code for Equilibrium Reasoners: learning attractor dynamics for scalable reasoning",null,"Python",38,5,31,1,0,3,7,9,2.33,"Apache License 2.0",false,"main",[],"2026-06-12 02:04:09","\u003Ch1 align=\"center\" style=\"display: flex; align-items: center; justify-content: center; gap: 0.35em;\">\n  \u003Cimg src=\"assets\u002Ficon.png\" alt=\"Equilibrium Reasoners icon\" width=\"42\" height=\"42\" style=\"display: inline-block;\">\n  Equilibrium Reasoners\n\u003C\u002Fh1>\n\n\u003Cp align=\"center\">\n  \u003Cstrong>Learning Attractors Enables Scalable Reasoning\u003C\u002Fstrong>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fhuskydoge.github.io\u002F\">Benhao Huang\u003C\u002Fa>\n  ·\n  \u003Ca href=\"https:\u002F\u002Fgsunshine.github.io\u002F\">Zhengyang Geng\u003C\u002Fa>\n  ·\n  \u003Ca href=\"https:\u002F\u002Fzicokolter.com\u002F\">Zico Kolter\u003C\u002Fa>\n  \u003Cbr\u002F>\n  CMU\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Farxiv.org\u002Fabs\u002F2605.21488\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FarXiv-2605.21488-b31b1b.svg\" alt=\"arXiv\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fhuggingface.co\u002Flocuslab\u002FEqR-model\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FHF-Model-yellow\" alt=\"HF Model\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fhuggingface.co\u002Fdatasets\u002Flocuslab\u002FEqR-data\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FHF-Data-blue\" alt=\"HF Data\">\u003C\u002Fa>\n\u003C\u002Fp>\n\nCode for reproducing EqR experiments on Sudoku-Extreme and Maze-Unique.\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"assets\u002FRI.gif\" alt=\"EqR recurrent inference\" width=\"49%\">\n  \u003Cimg src=\"assets\u002FNI.gif\" alt=\"EqR recurrent inference\" width=\"49%\">\n\u003C\u002Fp>\n\n## Setup\n\n```bash\nuv venv\nsource .venv\u002Fbin\u002Factivate\nuv pip install -r requirements.txt\n```\n\n`adam-atan2` must install its CUDA backend (`adam_atan2_backend`); a\nPython-only install is not sufficient for training. Build it in an environment\nwhere CUDA and Python headers are available:\n\n```bash\n# If CUDA is not already configured, point CUDA_HOME at the active CUDA\n# toolkit. For example:\n# export CUDA_HOME=\"$(dirname \"$(dirname \"$(which nvcc)\")\")\"\n# export PATH=\"$CUDA_HOME\u002Fbin:$PATH\"\n\n# Optional: set this when building without visible GPUs or when cross-compiling.\n# Examples: H100=9.0, A100=8.0, RTX 4090\u002FL40=8.9.\n# export TORCH_CUDA_ARCH_LIST=9.0\n\npython -m pip install --no-build-isolation --no-cache-dir --force-reinstall \\\n  adam-atan2==0.0.3\npython - \u003C\u003C'PY'\nfrom adam_atan2 import AdamATan2\nimport adam_atan2_backend\nprint(AdamATan2, adam_atan2_backend.__file__)\nPY\n```\n\nMaze training also requires FlashAttention on CUDA.\n\n\u003Cdetails>\n\u003Csummary>FlashAttention install notes\u003C\u002Fsummary>\n\nEqR follows the HRM attention import pattern: prefer FlashAttention-3 via\n`flash_attn_interface` when available, and fall back to FlashAttention-2 via\n`flash_attn`. On NVIDIA Hopper GPUs, FlashAttention-3 is recommended. If a\nlocal wheel is available:\n\n```bash\npython -m pip install --no-deps \u003Cpath-to-flash-attn-3-wheel.whl>\npython - \u003C\u003C'PY'\nimport flash_attn_interface\nprint(flash_attn_interface.__file__)\nPY\n```\n\nIf FlashAttention-3 is unavailable, install FlashAttention-2:\n\n```bash\npython -m pip install flash-attn --no-build-isolation\npython - \u003C\u003C'PY'\nfrom flash_attn import flash_attn_func\nprint(flash_attn_func)\nPY\n```\n\n\u003C\u002Fdetails>\n\nFor W&B defaults, copy `config\u002Fsecrets.example.yaml` to `config\u002Fsecrets.yaml`\nand fill in your entity\u002Fproject. `config\u002Fsecrets.yaml` is ignored by git.\n\n## Data\n\nDefault dataset paths:\n\n| Dataset | Path |\n| --- | --- |\n| Sudoku-Extreme | `data\u002Fsudoku-extreme-1k-aug-1000` |\n| Maze-Unique | `data\u002Fmaze-30x30-unique-1k` |\n\nDownload datasets:\n\n```bash\nbash scripts\u002Fdownload_artifacts.sh\n```\n\nDownload datasets and pretrained checkpoints:\n\n```bash\nbash scripts\u002Fdownload_artifacts.sh --with-ckpts\n```\n\nThe helper downloads Hugging Face snapshots under `downloads\u002Feqr-artifacts`,\ncopies datasets into `data\u002F`, and copies checkpoints into\n`downloaded_checkpoints\u002F`.\n\nCheckpoint paths:\n\n```text\ndownloaded_checkpoints\u002Fsudoku-extreme\u002Feqr.pth\ndownloaded_checkpoints\u002Fmaze-unique\u002Feqr.pth\n```\n\n### Optional: rebuild datasets\n\n\u003Cdetails>\n\u003Csummary>Dataset rebuild commands\u003C\u002Fsummary>\n\nUse these commands only if you want to regenerate the datasets instead of\ndownloading `locuslab\u002FEqR-data`.\n\nSudoku-Extreme follows the\n[sapientinc\u002FHRM](https:\u002F\u002Fgithub.com\u002Fsapientinc\u002FHRM) setup. The builder downloads\n`train.csv` and `test.csv` from `sapientinc\u002Fsudoku-extreme`, converts them to\nHRM\u002FEqR-compatible NumPy arrays, and augments only the training split with\nSudoku-preserving digit, row, column, and transpose transformations.\n\nDefault EqR\u002FHRM small-sample dataset:\n\n```bash\npython -m dataset.build_sudoku_dataset \\\n  --output-dir data\u002Fsudoku-extreme-1k-aug-1000 \\\n  --subsample-size 1000 \\\n  --num-aug 1000 \\\n  --seed 42\n```\n\nFull Sudoku-Extreme dataset:\n\n```bash\npython -m dataset.build_sudoku_dataset \\\n  --output-dir data\u002Fsudoku-extreme-full \\\n  --seed 42\n```\n\nThe generated directory should contain `train\u002F`, `test\u002F`, and\n`identifiers.json`. Each split contains `dataset.json` plus\n`all__inputs.npy`, `all__labels.npy`, `all__puzzle_identifiers.npy`,\n`all__puzzle_indices.npy`, and `all__group_indices.npy`.\n\nAdditional Sudoku-Extreme options:\n\n```bash\npython -m dataset.build_sudoku_dataset --help\n```\n\nBuild Maze-Unique:\n\n```bash\npython dataset\u002Fbuild_maze_unique_dataset.py \\\n  --output-dir data\u002Fmaze-30x30-unique-1k \\\n  --grid-size 30 \\\n  --train-samples 1000 \\\n  --test-samples 1000 \\\n  --maze-mode perfect \\\n  --length-distribution uniform \\\n  --min-path-length 100 \\\n  --max-path-length 140 \\\n  --require-unique \\\n  --dedupe\n```\n\n\u003C\u002Fdetails>\n\n## Training\n\n`scripts\u002Ftrain.sh` launches `torchrun --standalone` with one local process by\ndefault. Override `NPROC_PER_NODE` only when you want multi-GPU training:\n\n```bash\nbash scripts\u002Ftrain.sh eqr_sudoku\nbash scripts\u002Ftrain.sh trm_sudoku\nbash scripts\u002Ftrain.sh eqr_maze_unique\nbash scripts\u002Ftrain.sh trm_maze_unique\n\nNPROC_PER_NODE=2 bash scripts\u002Ftrain.sh eqr_maze_unique\n```\n\n| Dataset | Config | Steps |\n| --- | --- | ---: |\n| Sudoku-Extreme | `config\u002Ftrain\u002Feqr_sudoku.yaml` | 50k |\n| Sudoku-Extreme TRM baseline | `config\u002Ftrain\u002Ftrm_sudoku.yaml` | 50k |\n| Maze-Unique | `config\u002Ftrain\u002Feqr_maze_unique.yaml` | 100k |\n| Maze-Unique TRM baseline | `config\u002Ftrain\u002Ftrm_maze_unique.yaml` | 100k |\n\n## Evaluation\n\n`scripts\u002Feval.sh` uses `config\u002Feval\u002Fdepth_breadth.yaml`. By default it runs\ndepth 16 with breadth 1.\n\n```bash\nbash scripts\u002Feval.sh \u002Fpath\u002Fto\u002Fcheckpoint.pth\nbash scripts\u002Feval.sh \u002Fpath\u002Fto\u002Fcheckpoint.pth halt_max_steps=64\nbash scripts\u002Feval.sh \u002Fpath\u002Fto\u002Fcheckpoint.pth \\\n  halt_max_steps=64 different_init=128 convergence_top_k=1 global_batch_size=16\n```\n\nAfter downloading checkpoints, evaluate the pretrained EqR models:\n\n```bash\nbash scripts\u002Feval.sh downloaded_checkpoints\u002Fsudoku-extreme\u002Feqr.pth\nbash scripts\u002Feval.sh downloaded_checkpoints\u002Fmaze-unique\u002Feqr.pth\n```\n\nEvaluation config:\n\n```text\nconfig\u002Feval\u002Fdepth_breadth.yaml\n```\n\n## TODO\n\n- Release XLA code for large-scale inference.\n\n## Acknowledgements\n\nThis codebase builds on the [HRM](https:\u002F\u002Fgithub.com\u002Fsapientinc\u002FHRM) and\n[TRM](https:\u002F\u002Fgithub.com\u002FSamsungSAILMontreal\u002FTinyRecursiveModels) repositories.\n\n## License\n\nThis project is released under the Apache License 2.0. See [LICENSE](LICENSE)\nfor details.\n\n## Citation\n\n```bibtex\n@article{huang2026equilibrium,\n  title={Equilibrium Reasoners: Learning Attractors Enables Scalable Reasoning},\n  author={Huang, Benhao and Geng, Zhengyang and Kolter, Zico},\n  journal={arXiv preprint arXiv:2605.21488},\n  year={2026}\n}\n```\n","Equilibrium Reasoners (EqR) 是一个用于学习吸引子以实现可扩展推理的项目。该项目通过引入一种新的学习机制，能够在极端数独和独特迷宫等复杂问题上进行高效推理。其核心功能包括使用自定义的 Adam-atan2 优化器以及 FlashAttention 加速训练过程，这使得模型在处理大规模数据集时能够保持高性能。此外，EqR 支持在 Hugging Face 平台上访问预训练模型和相关数据集，便于研究者快速复现实验结果。此工具适用于需要解决组合优化问题或需要在大规模数据集中寻找最优解的研究场景。",2,"2026-06-11 04:03:00","CREATED_QUERY"]