{"id":50917943,"url":"https://github.com/aqlaboratory/confornets","last_synced_at":"2026-06-16T17:02:46.162Z","repository":{"id":364434026,"uuid":"1210701227","full_name":"aqlaboratory/confornets","owner":"aqlaboratory","description":"Latents-based conformational control in OpenFold3.","archived":false,"fork":false,"pushed_at":"2026-05-25T19:45:57.000Z","size":14048,"stargazers_count":68,"open_issues_count":2,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-06-13T03:00:04.502Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","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/aqlaboratory.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,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-14T17:11:41.000Z","updated_at":"2026-06-11T12:49:25.000Z","dependencies_parsed_at":null,"dependency_job_id":"d2448c27-8aa4-4dab-9505-270b3e348b1c","html_url":"https://github.com/aqlaboratory/confornets","commit_stats":null,"previous_names":["aqlaboratory/confornets"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/aqlaboratory/confornets","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aqlaboratory%2Fconfornets","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aqlaboratory%2Fconfornets/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aqlaboratory%2Fconfornets/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aqlaboratory%2Fconfornets/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aqlaboratory","download_url":"https://codeload.github.com/aqlaboratory/confornets/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aqlaboratory%2Fconfornets/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34415248,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-16T02:00:06.860Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":"2026-06-16T17:02:45.487Z","updated_at":"2026-06-16T17:02:46.150Z","avatar_url":"https://github.com/aqlaboratory.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ConforNets\n\nLatents-based conformational control in OpenFold3.\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://arxiv.org/abs/2604.18559\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/arXiv-Paper-b31b1b\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://x.com/m1nj12/status/2046615914179916059\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/X-Thread-111111\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"repo/pipeline.gif\" alt=\"ConforNets teaser\" width=\"80%\"\u003e\n\u003c/p\u003e\n\n## Setup\n\n### Environment\n\nConfornet depends on OpenFold3-preview (\u003e= 0.4.0, a.k.a. OF3p2).\n\n```bash\nconda create -n confornet python=3.12\nconda activate confornet\n\n# 1. Install confornet (pulls OpenFold3 \u003e= 0.4.0 and other deps)\npip install -e .\n\n# 2. Reinstall OpenFold3 from GitHub main.\n#    The current PyPI release may error on ColabFold MSA server queries\n#    when a hit points to an obsolete PDB entry (e.g. 6rm0).\n#    The fix is already on `main` but has not yet been released.\npip install --no-deps --force-reinstall \\\n    \"openfold3 @ git+https://github.com/aqlaboratory/openfold-3.git@main\"\n\n# 3. Download OF3p2 checkpoint (~2.3 GB)\n#    setup_openfold uses $OPENFOLD_CACHE as the destination; set it first if you\n#    want the checkpoint somewhere other than the default (~/.cache/openfold).\nexport OPENFOLD_CACHE=/path/to/checkpoint/dir\nsetup_openfold\n```\n\nEvaluation uses the USalign binary at `packages/USalign`. See [packages/README.md](packages/README.md).\n\n\u003e [!IMPORTANT]\n\u003e The paper reports results with **OF3p1** (`of3_ft3_v1.pt`, OpenFold3 0.3.x). This checkpoint is **not compatible** with `openfold3 \u003e= 0.4.0` and will fail to load. We are standardizing on **OF3p2** (`of3-p2-155k.pt`) going forward and will re-run the benchmarks; updated results will be posted.\n\u003e To reproduce the exact paper numbers, use **OF3p1** with `openfold3==0.3.1`.\n\n\n## Demo \n\nA tiny benchmark under `repo/toy_assets/toy_benchmark/` (`mdfA` from `membrane` + `fs-4zrb_C-4zrb_H` from `foldswitching`) along with a pretrained `ConforNet` trained to fold membrane transporters toward the outward-facing conformation. Peak GPU memory usage \u003c 24GB. \n\n```bash\nBENCH=toy_benchmark\nASSETS=repo/toy_assets\nCKPT=/path/to/of3-p2-155k.pt\n\n# 1. Preprocessing — writes MSA + OF3p batches under $ASSETS/$BENCH/{msa,batch}.\npython preprocess.py --benchmark $BENCH --assets-dir $ASSETS\n\n# 2. k-ConforNet diversity training on both test cases.\npython scripts/run_diversity.py \\\n    --benchmark $BENCH --assets-dir $ASSETS \\\n    --checkpoint $CKPT \\\n    --output-dir ./output/demo/diversity \\\n    --k-confornets 2 --num-runs 2 --num-samples 5\n#   This will generate 2 * 2 * 4 * 5 = 80 samples per test case\n#   May take ~30 GPU minutes. If you have multiple GPUs, launch with torchrun --nproc_per_node=4 \n\n# 3. Conformation transfer — use the provided ConforNet\n#    to fold the mdfA sequence. Demonstrates transfer.\npython scripts/run_transfer.py \\\n    --benchmark $BENCH --assets-dir $ASSETS \\\n    --confornet-path $ASSETS/$BENCH/confornet/TM_0287v2_6QV1_B.pt \\\n    --test-case mdfA \\\n    --checkpoint $CKPT \\\n    --output-dir ./output/demo/transfer \\\n    --num-samples 10\n#  10 samples generation, quick\n```\n\nSee [`repo/demo.ipynb`](repo/demo.ipynb) for evaluation + py3Dmol overlay visualization of the outputs (`pip install py3Dmol`).\n\n## Benchmarking\n\nAll benchmarks reported in the paper are provided under `assets/`. Follow the benchmark scaffolding in `assets/` (references, residue ranges, and test-case mappings); see [assets/README.md](assets/README.md) for details. Once you have defined your benchmark, or if you want to reproduce the paper results, see [scripts/README.md](scripts/README.md) for the benchmark entry points: `run_diversity`, `run_mse_training`, `run_transfer`, `run_baseline`, `evaluate`, and `summarize`.\n\n\u003e [!WARNING]\n\u003e ConforNets backpropagate through the Pairformer and therefore require more GPU memory than standard inference. Roughly speaking, a 40GB GPU can fit a ~300aa, while an 80GB GPU can fit ~600 aa. The `dist_cdf_mse` objective is currently less memory-efficient. We are actively working on memory optimizations.\n\n### Preprocessing\n\n`assets/` contains benchmark definitions and reference PDBs. Preprocessing computes MSAs and saves OF3p batches as `.pt` files.\n\n```bash\n# Default ./assets directory\npython preprocess.py --benchmark domainmotion\n\n# Custom assets directory (copies ./assets there first if needed)\npython preprocess.py --benchmark domainmotion --assets-dir /scratch/assets\n\n# Skip MSA step (not recommended unless you know what you're doing)\npython preprocess.py --benchmark domainmotion --skip-msa\n```\n\nOF3p batches may take 10+ GB per benchmark.\n\n### Parallelism\n\nTwo independent axes, both embarrassingly parallel (no cross-rank communication):\n\n- **Intra-node, multi-GPU** — `torchrun --nproc_per_node=N`. Each script partitions its work by `job_idx % WORLD_SIZE == LOCAL_RANK`. Reads `LOCAL_RANK` / `WORLD_SIZE` (torchrun) or `FLUX_TASK_RANK` / `NRANKS_PER_NODE` (Flux); see `confornet/utils/dist.py`.\n- **Inter-node, test-case sharding** — benchmark scripts accept `--num-nodes N --node-idx i`. Each invocation keeps only the test cases where `tc_idx % num_nodes == node_idx`. Launch one `torchrun` per node (SLURM array, multiple `srun`s, etc.).\n\nCombine: `torchrun --nproc_per_node=4 -m scripts.run_diversity ... --num-nodes 8 --node-idx $NODE_IDX` = 4 GPUs × 8 nodes, disjoint.\n\n## Changelog\n\n- **OF3p2 switch**: default checkpoint is `of3-p2-155k.pt`; the paper's OF3p1 checkpoint will not load against `openfold3 \u003e= 0.4.0`.\n- **USAlign**: dropped the `mdtraj` / `bioemu_benchmarks` dependencies in favor of the USAlign binary. Introduces a 0.1–3 Å difference in global RMSD (~1–2% in reported success rates). Some OOD60 local test cases can show larger differences because the alignment method itself has changed.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faqlaboratory%2Fconfornets","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faqlaboratory%2Fconfornets","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faqlaboratory%2Fconfornets/lists"}