HalluDesign_NA

June 15, 2026 · View on GitHub

HalluDesign_NA is an independent HalluDesign interface for nucleic-acid sequence optimization. It uses NA-MPNN to propose DNA/RNA sequences and AF3 or Protenix as the structure oracle for self-consistency evaluation. An optional joint-design mode can also redesign protein chains with ProteinMPNN/LigandMPNN after NA-MPNN proposes the DNA/RNA sequence.

This directory is intentionally separated from the original HalluDesign runner: all NA-design code lives under HalluDesign_NA/, while the original HalluDesign files are left unchanged.

Scope

  • By default, protein chains are kept fixed.
  • DNA/RNA chains are redesigned by NA-MPNN.
  • With --joint_design, DNA/RNA chains are redesigned first by NA-MPNN and protein chains are then redesigned by ProteinMPNN/LigandMPNN using the NA-updated structure as context.
  • AF3 or Protenix evaluates NA-MPNN candidates after --design_epoch_begin.
  • The selected NA-MPNN packed structure is then passed into AF3/Protenix as ref-guided coordinates for an optimization prediction.
  • The optimized structure is converted to PDB and recycled into the next cycle.
  • --symmetry_chains supports identity tying, for example B,C means B1,C1|B2,C2|.... This is not Watson-Crick reverse-complement tying.
  • --symmetry_residues can pass an explicit NA-MPNN tying string.
  • --symmetry_segments N ties repeated identity segments within one NA chain, following the same modulo idea as HalluDesign protein segment symmetry.

The self-consistency evaluation stage uses sequence-only structure prediction to rank candidate NA sequences. The optimization stage is ref-guided: it uses the selected candidate PDB coordinates as the starting structure and continues denoising for --ref_time_steps, matching the original HalluDesign pattern.

Environment

The computational environment for HalluDesign-NA follows the requirements of the original HalluDesign framework. Please refer to the installation instructions and environment setup provided at:

https://github.com/MinchaoFang/HalluDesign

Although HalluDesign-NA is maintained as a separate repository, it is intended to be cloned inside the original HalluDesign directory for execution:

HalluDesign/
  HalluDesign_NA/

The runner reuses HalluDesign's AF3 wrapper, Protenix wrapper, coordinate preprocessing utilities, and evaluation helpers from the parent HalluDesign repository. Running HalluDesign-NA outside the HalluDesign directory is not the recommended layout.

NA-MPNN Dependency

By default the runner expects NA-MPNN at:

HalluDesign_NA/NA-MPNN

You can also pass another clone:

--na_mpnn_dir /path/to/NA-MPNN

The wrapper imports NA-MPNN in-process and loads the checkpoint once.

Design Logic

Each cycle copies the current best structure and runs NA-MPNN on the DNA/RNA chains. Before --design_epoch_begin, one NA-MPNN sequence is generated and sent directly to the coordinate-guided optimization stage. From --design_epoch_begin onward, --num_seqs NA-MPNN candidates are first evaluated by AF3 or Protenix, the highest-ranked candidate is selected, and then that selected candidate's packed PDB coordinates are used as the ref-guided optimization input.

When --joint_design is enabled, each candidate is generated in two proposal steps by default: NA-MPNN first updates the DNA/RNA chains, then ProteinMPNN/LigandMPNN updates the selected protein chains using that NA-updated PDB as context. The merged protein and NA sequences are written to the AF3/Protenix template and ranked by the same self-consistency evaluation. This mode keeps the total candidate count controlled by --num_seqs; it does not create all pairwise protein-by-NA combinations.

The default joint proposal order is --joint_order na_then_protein. For ablation or legacy behavior, --joint_order protein_then_na runs the protein proposal before NA-MPNN.

In joint mode, ProteinMPNN/LigandMPNN is used as a protein sequence proposal model, while NA-MPNN remains the DNA/RNA proposal model. The selected protein and NA sequences are passed to AF3/Protenix through the JSON template. The coordinate-refinement input follows the existing HalluDesign-NA packed-PDB path, so side-chain geometry should be interpreted as structure-model-refined rather than as a final ProteinMPNN side-chain packing result.

The final cycle follows the original HalluDesign convention: it records the NA-MPNN/self-consistency result but does not launch another expensive optimization prediction.

For no-PDB random initialization, omit --input_file/--pdb_list and provide --random_init_chain_spec, for example A:20, A:20-40, or A:100,B:20-40,C:18. The chain IDs must already exist as protein, DNA, or RNA chains in the template JSON; this option sets the initial random sequence length but does not add new chains to the template. Protein chains are only randomly initialized when explicitly listed in --random_init_chain_spec. Unlisted protein targets keep the sequence from the template JSON, which is the recommended mode for fixed-target aptamer-like design. Cycle 1 is run as pure AF3/Protenix prediction, and later cycles recycle the predicted PDB into the normal NA-MPNN/ref-guided loop.

Use --num_designs to launch multiple independent no-PDB random-init design trajectories in one command. This is different from --num_seqs: --num_seqs controls the number of NA-MPNN candidates evaluated within each cycle, while --num_designs controls the number of independent final design trajectories.

Useful controls:

--fix_res_index "B1 B2"
--redesign_res_index "B10 B11 B12"
--symmetry_residues "B1,C1|B2,C2"
--symmetry_chains B,C
--symmetry_segments 3 --symmetry_segment_chain B
--ref_time_steps 150
--random_init_chain_spec "A:100-120,B:20-40"
--num_designs 20
--joint_design --protein_design_chains A
--joint_order na_then_protein
--protein_fix_res_index "A10 A11"
--protein_redesign_res_index "A30 A31"

--fix_res_index and --redesign_res_index use PDB-style chain+residue labels as parsed by NA-MPNN. If --redesign_res_index is provided, only those residues are sampled and all other residues are fixed.

--protein_fix_res_index and --protein_redesign_res_index are the analogous controls for the optional protein-design proposal step. If --protein_design_chains is omitted in --joint_design, all protein chains in the template are redesigned. The protein proposal model is selected with --mpnn; the default is ligand_mpnn.

Examples

All example commands below are intended to be run from the HalluDesign_NA directory after cloning it inside the original HalluDesign repository:

cd /path/to/HalluDesign/HalluDesign_NA

Protenix:

python ./HalluDesign_NA_run.py \
  --optimizer protenix \
  --template_path examples/RNA_Protenix.json \
  --output_dir examples/HalluDesign_NA_random \
  --random_init_chain_spec "B:20-40" \
  --num_designs 5 \
  --ref_time_steps 150 \
  --num_seqs 8 \
  --num_recycles 10

AF3:

python ./HalluDesign_NA_run.py \
  --optimizer af3 \
  --template_path examples/DNA_af3.json \
  --output_dir examples/HalluDesign_NA_DNA_af3_random \
  --random_init_chain_spec "B:20" \
  --ref_time_steps 150 \
  --num_seqs 8 \
  --num_recycles 10

No-PDB protein-NA random initialization:

python ./HalluDesign_NA_run.py \
  --optimizer protenix \
  --template_path examples/DNA_Protenix.json \
  --output_dir examples/HalluDesign_NA_protein_dna_random \
  --random_init_chain_spec "A:100-120,B:50-80" \
  --joint_design \
  --protein_design_chains A \
  --ref_time_steps 150 \
  --num_seqs 8 \
  --num_recycles 10

Joint protein-NA design:

python ./HalluDesign_NA_run.py \
  --optimizer protenix \
  --input_file examples/protein_dna_complex.pdb \
  --template_path examples/DNA_Protenix.json \
  --output_dir examples/HalluDesign_NA_joint \
  --joint_design \
  --protein_design_chains A \
  --ref_time_steps 150 \
  --num_seqs 8 \
  --num_recycles 10

Small-molecule SMILES ligand random-init example:

python /storage/caolab/fangmc/for_pub/HalluDesign/HalluDesign_NA/HalluDesign_NA_run.py \
  --optimizer protenix \
  --template_path /storage/caolab/fangmc/for_pub/HalluDesign/HalluDesign_NA/examples/RNA_ligand_smiles_Protenix.json \
  --output_dir /storage/caolab/fangmc/tmp/HalluDesign_NA_smiles_ligand \
  --random_init_chain_spec "A:50-80" \
  --num_designs 20 \
  --num_seqs 8 \
  --num_recycles 20 \
  --ref_time_steps 150

Selection

When self-consistency evaluation is enabled, candidates are selected by the structure model's ranking score. This matches the default AF3/Protenix behavior and avoids adding an extra selection interface for routine use.

Citation

@article {Fang2025.11.08.686881,
	author = {Fang, Minchao and Wang, Chentong and Shi, Jungang and Lian, Fangbai and Jin, Qihan and Wang, Zhe and Zhang, Yanzhe and Cui, Zhanyuan and Wang, YanJun and Ke, Yitao and Han, Qingzheng and Cao, Longxing},
	title = {HalluDesign: Protein Optimization and de novo Design via Iterative Structure Hallucination and Sequence design},
	elocation-id = {2025.11.08.686881},
	year = {2025},
	doi = {10.1101/2025.11.08.686881},
	publisher = {Cold Spring Harbor Laboratory},
	URL = {https://www.biorxiv.org/content/early/2025/11/09/2025.11.08.686881},
	eprint = {https://www.biorxiv.org/content/early/2025/11/09/2025.11.08.686881.full.pdf},
	journal = {bioRxiv}
}

@article{Abramson2024,
  author  = {Abramson, Josh and Adler, Jonas and Dunger, Jack and Evans, Richard and Green, Tim and Pritzel, Alexander and Ronneberger, Olaf and Willmore, Lindsay and Ballard, Andrew J. and Bambrick, Joshua and Bodenstein, Sebastian W. and Evans, David A. and Hung, Chia-Chun and O’Neill, Michael and Reiman, David and Tunyasuvunakool, Kathryn and Wu, Zachary and Žemgulytė, Akvilė and Arvaniti, Eirini and Beattie, Charles and Bertolli, Ottavia and Bridgland, Alex and Cherepanov, Alexey and Congreve, Miles and Cowen-Rivers, Alexander I. and Cowie, Andrew and Figurnov, Michael and Fuchs, Fabian B. and Gladman, Hannah and Jain, Rishub and Khan, Yousuf A. and Low, Caroline M. R. and Perlin, Kuba and Potapenko, Anna and Savy, Pascal and Singh, Sukhdeep and Stecula, Adrian and Thillaisundaram, Ashok and Tong, Catherine and Yakneen, Sergei and Zhong, Ellen D. and Zielinski, Michal and Žídek, Augustin and Bapst, Victor and Kohli, Pushmeet and Jaderberg, Max and Hassabis, Demis and Jumper, John M.},
  journal = {Nature},
  title   = {Accurate structure prediction of biomolecular interactions with AlphaFold 3},
  year    = {2024},
  volume  = {630},
  number  = {8016},
  pages   = {493–-500},
  doi     = {10.1038/s41586-024-07487-w}
}

@article{bytedance2025protenix,
  title={Protenix - Advancing Structure Prediction Through a Comprehensive AlphaFold3 Reproduction},
  author={ByteDance AML AI4Science Team and Chen, Xinshi and Zhang, Yuxuan and Lu, Chan and Ma, Wenzhi and Guan, Jiaqi and Gong, Chengyue and Yang, Jincai and Zhang, Hanyu and Zhang, Ke and Wu, Shenghao and Zhou, Kuangqi and Yang, Yanping and Liu, Zhenyu and Wang, Lan and Shi, Bo and Shi, Shaochen and Xiao, Wenzhi},
  year={2025},
  journal={bioRxiv},
  publisher={Cold Spring Harbor Laboratory},
  doi={10.1101/2025.01.08.631967},
  URL={https://www.biorxiv.org/content/early/2025/01/11/2025.01.08.631967},
  elocation-id={2025.01.08.631967},
  eprint={https://www.biorxiv.org/content/early/2025/01/11/2025.01.08.631967.full.pdf},
}

@article{kubaney2025nammpnn,
  title={RNA sequence design and protein--DNA specificity prediction with NA-MPNN},
  author={Kubaney, Andrew and Favor, Andrew and McHugh, Lilian and Mitra, Raktim and Pecoraro, Robert and Dauparas, Justas and Glasscock, Cameron and Baker, David},
  year={2025},
  journal={bioRxiv},
  publisher={Cold Spring Harbor Laboratory},
  doi={10.1101/2025.10.03.679414},
  URL={https://www.biorxiv.org/content/early/2025/10/07/2025.10.03.679414},
  elocation-id={2025.10.03.679414},
  eprint={https://www.biorxiv.org/content/early/2025/10/07/2025.10.03.679414.full.pdf},
}

@article {Fang2026.06.10.730767,
	author = {Fang, Minchao and Wang, Zhe and Cao, Longxing},
	title = {HalluDesign-NA: Extending HalluDesign for De Novo Nucleic Acid Design},
	elocation-id = {2026.06.10.730767},
	year = {2026},
	doi = {10.64898/2026.06.10.730767},
	publisher = {Cold Spring Harbor Laboratory},
	abstract = {AlphaFold3 has revolutionized the prediction of biomolecular structures and interactions, including atomic-level modeling of nucleic acids. However, the de novo design of structured and functional nucleic acids remains a significant challenge. Here, we extend our HalluDesign framework to nucleic acid design by integrating NA-MPNN for nucleic acid sequence optimization and design. This new framework, HalluDesign-NA, enables iterative sequence-structure co-optimization, facilitating the de novo design of nucleic acids. Computational benchmarking across ssDNA, ssRNA, and aptamer design tasks demonstrates consistent improvements in confidence scores (pLDDT, ipTM), supporting the feasibility of de novo nucleic acid design under various constraints, such as sequence length, symmetry, and protein structure context. We anticipate that HalluDesign-NA will accelerate the de novo design of functional nucleic acids for applications in biotechnology and medicine. The source code for HalluDesign-NA is available at https://github.com/MinchaoFang/HalluDesign_NA.Competing Interest StatementThe authors have declared no competing interest.},
	URL = {https://www.biorxiv.org/content/early/2026/06/11/2026.06.10.730767},
	eprint = {https://www.biorxiv.org/content/early/2026/06/11/2026.06.10.730767.full.pdf},
	journal = {bioRxiv}
}

Licence and Disclaimer

HalluDesign

HalluDesign all code are under MIT license

AlphaFold 3 Source Code and Model Parameters

alphafold3 is not an officially supported Google product.

Copyright 2024 DeepMind Technologies Limited.

The AlphaFold 3 source code is licensed under the Creative Commons Attribution-Non-Commercial ShareAlike International License, Version 4.0 (CC-BY-NC-SA 4.0) (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at https://github.com/google-deepmind/alphafold3/blob/main/LICENSE.

The AlphaFold 3 model parameters are made available under the AlphaFold 3 Model Parameters Terms of Use (the "Terms"); you may not use these except in compliance with the Terms. You may obtain a copy of the Terms at https://github.com/google-deepmind/alphafold3/blob/main/WEIGHTS_TERMS_OF_USE.md.

Protenix

The Protenix project including both code and model parameters is released under the Apache 2.0 License. It is free for both academic research and commercial use.

NA-MPNN

NA-MPNN are under MIT license