{"id":19482508,"url":"https://github.com/aqlaboratory/genie2","last_synced_at":"2025-04-12T02:25:48.380Z","repository":{"id":242104107,"uuid":"804806254","full_name":"aqlaboratory/genie2","owner":"aqlaboratory","description":"Protein structure diffusion model for unconditional protein generation and motif scaffolding","archived":false,"fork":false,"pushed_at":"2024-06-24T21:34:55.000Z","size":16814,"stargazers_count":152,"open_issues_count":7,"forks_count":25,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-04-12T02:25:43.179Z","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":"apache-2.0","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":"LICENSE","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}},"created_at":"2024-05-23T09:59:03.000Z","updated_at":"2025-04-11T06:37:06.000Z","dependencies_parsed_at":"2024-05-31T17:47:20.557Z","dependency_job_id":"7ccba735-f7f6-4972-aa72-b367df15c95d","html_url":"https://github.com/aqlaboratory/genie2","commit_stats":null,"previous_names":["aqlaboratory/genie2"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aqlaboratory%2Fgenie2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aqlaboratory%2Fgenie2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aqlaboratory%2Fgenie2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aqlaboratory%2Fgenie2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aqlaboratory","download_url":"https://codeload.github.com/aqlaboratory/genie2/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248506435,"owners_count":21115429,"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-11-10T20:10:50.588Z","updated_at":"2025-04-12T02:25:48.318Z","avatar_url":"https://github.com/aqlaboratory.png","language":"Python","funding_links":[],"categories":["🔬 Domain-Specific Applications"],"sub_categories":["🧬 Biology \u0026 Medicine"],"readme":"# Genie 2: Designing and Scaffing Proteins at the Scale of the Structural Universe\n\nThis repository provides the implementation code for our [preprint](https://arxiv.org/abs/2405.15489), including training and inference code, as well as model weights. For the in-silico evaluation pipeline, which is used to assess the designability, diversity and novelty of our generated structures, we provide them in a seperate [repository](https://github.com/aqlaboratory/insilico_design_pipeline) since it is independent of Genie 2 and could be applicable for evaluating other protein structure diffusion models. Below provides an illustration of the Genie 2 sampling process for both unconditional generation and motif scaffolding.\n\n![](https://github.com/aqlaboratory/genie2/blob/main/sampling.gif)\n\n## Setup\n\nSet up Genie 2 by running\n```bash\ngit clone https://github.com/aqlaboratory/genie2.git\ncd genie2\npip install -e .\n```\nThis would clone the repository, install dependencies and set up Genie 2 as a packge.\n\n### Docker\n\nAlternatively, you can run Genie 2 in a Docker container. The included `Dockerfile` contains the required dependencies to run Genie 2 using the `pytorch/pytorch:2.3.0-cuda12.1-cudnn8-runtime` default base image.\n\n```bash\n## Build Docker Container\ndocker build -t genie2 .\n```\n\nAlso, you can use the `PYTORCH_TAG` build argument to rebuild with a different base image, thus using different PyTorch, CUDA, and/or cuDNN versions.\n\nFor example:\n```bash\n## Use build argument to change versions\ndocker build --build-arg \"PYTORCH_TAG=2.2.1-cuda12.1-cudnn8-devel\"  -t genie2 .\n```\n\nThen, run the container with GPUs and mount a local volume using the following command:\n\n```bash\n## Run Container\ndocker run -v .:/data --gpus all -it genie2\n```\n\nThis will open a bash terminal inside the container where you can run the following training and generation commands as needed.\n\n## Training\n\n### Dataset\n\nIn `data/afdbreps_l-256_plddt_80`, we provide an index file named `index.txt`. It contains a list of 588,571 AFDB filenames, each of which correponds to a structure in the [AlphaFold Protein Structure Database](https://alphafold.ebi.ac.uk/), specifically in the format `https://alphafold.ebi.ac.uk/files/[FILENAME].pdb`. These structures are representative structures from the [FoldSeek-clustered AFDB](https://cluster.foldseek.com/) dataset (filtered with a maximum sequence length of 256 and a minimum pLDDT of 80) and are used for the training of Genie 2. To set up for this dataset, create a subdirectory named `pdbs` under `data/afdbreps_l-256_plddt_80` and download this set of structures from AFDB into this `pdbs` subdirectory. Our default training data directory is set to `data/afdbreps_l-256_plddt_80/pdbs` and this could be changed by using the `dataDirectory` key in the configuration file.\n\n### Training\n\nTo train a model, create a directory `runs/[RUN_NAME]` and create a configuration file with name `configuration` under this directory. An example is provided in `runs/example` and a complete list of configurable parameters could be found in `genie/config.py`. Note that in the configuration file, name should match with RUN_NAME in order to log into the correct directory. To start training, run\n```bash\npython genie/train.py --devices [NUM_DEVICES] --num_nodes [NUM_NODES] --config runs/[RUN_NAME]/configuration\n```\n\n## Sampling\n\n### Directory Setup\n\nTo sample using a model, create a directory `results/[MODEL_NAME]`, which consists of\n-\tthe model configuration file named `configuration`\n-\ta subdirectory named `checkpoints`, where each file is named `epoch=[EPOCH].ckpt` and contains the model weight checkpointed at the specified epoch.\n\nAn example is provided under `results/base`, which contains the configuration and checkpoints for our trained model. **The checkpoints are available in [v1.0.0 release](https://github.com/aqlaboratory/genie2/releases/tag/v1.0.0)**. For results reported in our manuscript, we used the 40-epoch checkpoint for unconditional generation and 30-epoch checkpoint for motif scaffolding.\n\n### Unconditional Generation\n\nPerform unconditional sampling by running\n\n```bash\npython genie/sample_unconditional.py --name [NAME] --epoch [EPOCH] --scale [SCALE] --outdir [OUTDIR]\n``` \n\nThe list of parameters are summarized in the following table.\n\n| Parameter | Type   | Description | Required | Default |\n| :-------: | :----: | ---------- | :------: | :-----: |\n| `name` | string | Model name | :heavy_check_mark: | |\n| `epoch` | int | Model epoch | :heavy_check_mark: | |\n| `scale` | float | Sampling noise scale (between 0 and 1, inclusive) | :heavy_check_mark: | |\n| `outdir` | string | Output directory |:heavy_check_mark: | |\n| `rootdir` | string | Model root directory | | results |\n| `num_samples` | int | Number of samples per length |  | 5 |\n| `batch_size` | int | Batch size |  | 4 |\n| `min_length` | int | Minimum sequence length |  | 50 |\n| `max_length` | int | Maximum sequence length |  | 256 |\n| `length_step` | int | Sequence length step | | 1 |\n| `num_devices` | int | Number of GPUs | | 1 |\n\nTo balance the sampling time across GPUs, we shuffle the generation tasks. To avoid this behavior and sample in increasing order of length, add the flag `--sequential_order`.\n\nTo reproduce our unconditional generation, run the command below. \n\n```bash\npython genie/sample_unconditional.py --name base --epoch 40 --scale 0.6 --outdir results/base/outputs\n```\n\n### Motif Scaffolding\n\nWe provide the benchmark datasets for single-motif and multi-motif scaffolding under `data/design25` and `data/multimotifs`, respectively. The format of a motif scaffolding problem definition file is described [here](https://github.com/aqlaboratory/genie2?tab=readme-ov-file#format-of-motif-scaffolding-problem-definition-file).\n\nPerform motif scaffolding by running\n\n```bash\npython genie/sample_scaffold.py --name [NAME] --epoch [EPOCH] --scale [SCALE] --outdir [OUTDIR]\n```\n\nThe list of parameters are summarized in the following table.\n\n| Parameter | Type   | Description | Required | Default |\n| :-------: | :----: | ---------- | :------: | :-----: |\n| `name` | string | Model name | :heavy_check_mark: | |\n| `epoch` | int | Model epoch | :heavy_check_mark: | |\n| `scale` | float | Sampling noise scale (between 0 and 1, inclusive) | :heavy_check_mark: | |\n| `outdir` | string | Output directory | :heavy_check_mark: | |\n| `rootdir` | string | Model root directory | | results |\n| `num_samples` | int | Number of samples per length | | 100 |\n| `batch_size` | int | Batch size | | 4 |\n| `motif_name` | string | Name of motif-scaffolding problem (Automatically \u003cbr\u003eevaluate all problems in `datadir` if unspecified) | | |\n| `datadir` | string | Directory of motif-scaffolding problems | | data/design25 |\n| `num_devices` | int | Number of GPUs | | 1 |\n\nTo reproduce our single-motif scaffolding, run\n\n```bash\npython genie/sample_scaffold.py --name base --epoch 30 --scale 0.4 --outdir results/base/design25 --num_samples 1000\n``` \n\nTo reproduce our multi-motif scaffolding, run\n\n```bash\npython genie/sample_scaffold.py --name base --epoch 30 --scale 0.4 --outdir results/base/multimotifs --datadir data/multimotifs --num_samples 1000\n```\n\n## Format of Motif Scaffolding Problem Definition File\n\nA motif scaffolding problem definition file consists of two parts: the first part defines motif scaffolding specifications, including arrangements of motif segments, minimum/maximum length of each scaffold segment and minimum/maximum sequence length; the second part defines motif structure in a PDB format. The table below details the format for defining motif scaffolding specifications.\n\n| Specification | Column | Data | Justification | Data Type |\n| :-------: | ------ | ---------- | :------: | :-----: |\n| Motif segment | 1-16 | \"REMARK 999 INPUT\" | | string \u003ctr\u003e\u003c/tr\u003e|\n|               | 19 | Chain index of motif segment in the PDB file | | string \u003ctr\u003e\u003c/tr\u003e|\n|               | 20-23 | Starting residue index of motif segment in the PDB file | right | int \u003ctr\u003e\u003c/tr\u003e|\n|               | 24-27 | Ending residue index of motif segment in the PDB file | right | int \u003ctr\u003e\u003c/tr\u003e|\n|               | 29 | Motif group that the segment belongs to (default to 'A' if unspecified) | | string |\n| Scaffold segment | 1-16 | \"REMARK 999 INPUT\" | | string \u003ctr\u003e\u003c/tr\u003e|\n|                  | 20-23 | Minimum length of scaffold segment | right | int \u003ctr\u003e\u003c/tr\u003e|\n|                  | 24-27 | Maximum length of scaffold segment | right | int |\n| Minimum \u003cbr\u003esequence length | 1-31 | \"REMARK 999 MINIMUM TOTAL LENGTH\" | | string \u003ctr\u003e\u003c/tr\u003e|\n|                             | 38-40 | Minimum sequence length | left | int |\n| Maximum \u003cbr\u003esequence length | 1-31 | \"REMARK 999 MAXIMUM TOTAL LENGTH\" | | string \u003ctr\u003e\u003c/tr\u003e|\n|                             | 38-40 | Maximum sequence length | left | int |\n\nOne example of motif scaffolding specifications is provided below.\n\n```\nREMARK 999 NAME   1PRW_two\nREMARK 999 PDB    1PRW\nREMARK 999 INPUT      5  20\nREMARK 999 INPUT  A  16  35 A\nREMARK 999 INPUT     10  25\nREMARK 999 INPUT  A  52  71 A\nREMARK 999 INPUT     10  30\nREMARK 999 INPUT  A  89 108 B\nREMARK 999 INPUT     10  25\nREMARK 999 INPUT  A 125 144 B\nREMARK 999 INPUT      5  20\nREMARK 999 MINIMUM TOTAL LENGTH      120\nREMARK 999 MAXIMUM TOTAL LENGTH      200\n```\n\nThere are two limitations with our current format:\n- When defining motif structures in a PDB format, the residue order should match with the order in motif scaffolding specification.\n- PDB name is not specified when defining motif segment in motif scaffolding specification.\n\nWe intend to optimize our code to address these two limitations in the future.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faqlaboratory%2Fgenie2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faqlaboratory%2Fgenie2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faqlaboratory%2Fgenie2/lists"}