{"id":13869705,"url":"https://github.com/CUAI/Equivariant-Manifold-Flows","last_synced_at":"2025-07-15T18:31:47.752Z","repository":{"id":112298581,"uuid":"418326446","full_name":"CUAI/Equivariant-Manifold-Flows","owner":"CUAI","description":"[NeurIPS 2021] Equivariant Manifold Flows (https://arxiv.org/abs/2107.08596)","archived":false,"fork":false,"pushed_at":"2021-12-08T22:06:03.000Z","size":25,"stargazers_count":9,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-11-23T15:35:35.530Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CUAI.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2021-10-18T03:10:23.000Z","updated_at":"2024-01-18T22:41:58.000Z","dependencies_parsed_at":"2023-05-12T15:00:29.401Z","dependency_job_id":null,"html_url":"https://github.com/CUAI/Equivariant-Manifold-Flows","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/CUAI/Equivariant-Manifold-Flows","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CUAI%2FEquivariant-Manifold-Flows","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CUAI%2FEquivariant-Manifold-Flows/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CUAI%2FEquivariant-Manifold-Flows/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CUAI%2FEquivariant-Manifold-Flows/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CUAI","download_url":"https://codeload.github.com/CUAI/Equivariant-Manifold-Flows/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CUAI%2FEquivariant-Manifold-Flows/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265451443,"owners_count":23767768,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-05T20:01:12.812Z","updated_at":"2025-07-15T18:31:47.492Z","avatar_url":"https://github.com/CUAI.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# Equivariant Manifold Flows\n\nWe provide the code for [Equivariant Manifold Flows](https://arxiv.org/abs/2107.08596) in this repository.\n\nSummary: We lay the theoretical foundations for learning symmetry-invariant distributions on arbitrary manifolds via our introduced equivariant manifold flows. We demonstrate the utility of our approach by using it to learn gauge invariant densities over SU(n), useful for lattice quantum field theory.\n\nExample learned densities, together with baselines, are given below.\n\nSU(2)             |  SU(3)\n:-------------------------:|:-------------------------:\n![SU(2)](https://i.imgur.com/FrDmsBG.png)| ![SU(3)](https://i.imgur.com/h2LJWDd.png)\n\nSphere            |\n:-------------------------:\n![Sphere S^2](https://i.imgur.com/gd3IeGF.png)|\n\nBelow we have visualized how our equivariant manifold flows learn the `boyda1` and `boyda2` densities on SU(3) (first and second rows in the SU(3) figure above).\n\nSU(3) Boyda1             |  SU(3) Boyda2 \n:-------------------------:|:-------------------------:\n![SU(3) Boyda1](https://media3.giphy.com/media/NbWVIBxjLsd16sxn58/giphy.gif)| ![SU(3) Boyda2](https://media.giphy.com/media/7p3PBzoD5XYdfwCFfK/giphy.gif)\n\n## Software Requirements\nThis codebase requires Python 3 and PyTorch 1.8+.\n\n## Usage\n\n### Demo\n\nThe following command learns a equivariant manifold flow model for the `boyda2` density on SU(3). The density learned will be symmetric with respect to conjugation by SU(3), which we prove is an isometry in Appendix A.5 of our paper.\n\n```\npython main.py --M SU3 --batch_size 1024 --dev cpu --save_viz --contsave --save_freq 1 --lr 4e-3 --epochs 200 --example_density boyda2\n```\n\nNote that 1024 samples are used per epoch. 200 epochs were used for the results in the paper. The learned density is given below, in comparison with the ground truth density:\n\nGround Truth             |  Ours (50 epochs)         |    Ours (200 epochs)\n:-------------------------:|:-------------------------:|:---------------------:\n![SU(3) GT](https://i.imgur.com/eJOVxV3.png)| ![SU(3) 50 epochs](https://i.imgur.com/RDSe1O7.png) | ![SU(3) 200 epochs](https://i.imgur.com/oVNKrxo.png)\n\nObserve that even after 50 epochs (only approximately 50,000 samples), our model approaches the ground truth.\n\n### Full Usage\n\nAll options are given below:\n\n```\nusage: main.py [-h] [--example_density EXAMPLE_DENSITY] [--num_drops NUM_DROPS] [--save_viz] [--save_model] [--dev DEV]\n               [--M {SU3}] [--contsave] [--save_freq SAVE_FREQ] [--epochs EPOCHS] [--batch_size BATCH_SIZE] [--lr LR]\n               [--weight_decay WEIGHT_DECAY]\n\noptional arguments:\n  -h, --help            show this help message and exit\n  --example_density EXAMPLE_DENSITY\n                        example density to learn. Options are: boyda1 | boyda2 | boyda3 (different densities defined on\n                        SU(3))\n  --num_drops NUM_DROPS\n                        number of times to drop the learning rate\n  --save_viz            Save a visualization of the learned density once training is completed\n  --save_model          Save a visualization of the learned sampler\n  --dev DEV             Default device; cpu preferred due to poor support of complex tensor differentiation on cuda\n  --M {SU3}             Manifold over which to learn\n  --contsave            Continuously save intermediate flow visualization in contsave/\n  --save_freq SAVE_FREQ\n                        frequency of continuous saving of intermediate flows\n  --epochs EPOCHS\n  --batch_size BATCH_SIZE\n  --lr LR\n  --weight_decay WEIGHT_DECAY\n```\n\n## Attribution\n\nIf you use this code or our results in your research, please cite:\n\n```\n@article{Katsman2021EquivariantMF,\n  title={Equivariant Manifold Flows},\n  author={Isay Katsman and Aaron Lou and Derek Lim and Qingxuan Jiang and Ser-Nam Lim and Christopher De Sa},\n  journal={ArXiv},\n  year={2021},\n  volume={abs/2107.08596}\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCUAI%2FEquivariant-Manifold-Flows","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FCUAI%2FEquivariant-Manifold-Flows","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCUAI%2FEquivariant-Manifold-Flows/lists"}