Inference Instructions

Concise reference for installing OpenDDE, preparing runtime data, and running opendde commands.

Install

OpenDDE supports CPython 3.11, 3.12, and 3.13. We recommend uv for Python installations. Choose one of the following methods.

Install from PyPI

uv venv --python 3.11

CPU:

uv pip install --python .venv --torch-backend cpu opendde

NVIDIA GPU (Linux x86_64, CUDA 12.6):

uv pip install --python .venv --torch-backend cu126 "opendde[gpu]"

Install from source

git clone https://github.com/aurekaresearch/OpenDDE.git
cd OpenDDE
uv venv --python 3.11

CPU:

uv pip install --python .venv --torch-backend cpu -e .

NVIDIA GPU (Linux x86_64, CUDA 12.6):

uv pip install --python .venv --torch-backend cu126 -e ".[gpu]"

After a PyPI or source installation, verify the environment with:

uv run --no-project --python .venv opendde doctor

Use Docker

The prebuilt image targets NVIDIA GPU inference:

docker pull aurekaresearch/opendde:v1

See the Docker guide for GPU setup, runtime-data mounts, and a complete docker run example.

Runtime data

Set OPENDDE_ROOT_DIR to the directory that stores checkpoints and runtime data:

$OPENDDE_ROOT_DIR/
├── checkpoint/opendde.pt
├── common/
└── search_database/        # needed for local template/RNA-MSA search

The default checkpoint and managed common files come from a release-pinned asset revision and are verified against their published size and SHA-256. Checkpoints passed explicitly with --load_checkpoint_path are left untouched.

Prepare data from a source checkout:

export OPENDDE_ROOT_DIR=/path/to/opendde_data
bash scripts/download_opendde_data.sh

For a protein-only prediction that disables MSA, template, and RNA-MSA features, search databases are not needed:

bash scripts/download_opendde_data.sh --skip-search-database

If you already have a custom checkpoint, keep a descriptive filename and pass it directly. Use --skip-model when preparing only the remaining runtime data:

mkdir -p "$OPENDDE_ROOT_DIR/checkpoint"
cp /path/to/my_checkpoint.pt \
  "$OPENDDE_ROOT_DIR/checkpoint/my_checkpoint.pt"
bash scripts/download_opendde_data.sh --skip-model
opendde pred \
  --load_checkpoint_path "$OPENDDE_ROOT_DIR/checkpoint/my_checkpoint.pt" \
  -i examples/input.json \
  -o ./output

The names opendde.pt and opendde_abag.pt are reserved for released assets. Their authoritative links, sizes, and digests are in supported_models.md.

Use opendde.pt with -n opendde_v1 as the default general-purpose checkpoint. To use the ABAG-optimized checkpoint, keep it as opendde_abag.pt and pass it with --load_checkpoint_path, for example opendde pred --load_checkpoint_path "$OPENDDE_ROOT_DIR/checkpoint/opendde_abag.pt".

Install and verify the ABAG checkpoint from the same manifest-backed helper:

export OPENDDE_ROOT_DIR=/path/to/opendde_data
bash scripts/download_opendde_data.sh \
  --checkpoint opendde_abag.pt \
  --skip-common \
  --skip-search-database

Then run general-purpose inference without an explicit checkpoint path. For ABAG inference, add:

--load_checkpoint_path "$OPENDDE_ROOT_DIR/checkpoint/opendde_abag.pt"

Useful environment variables:

Variable	Purpose
OPENDDE_ROOT_DIR	Checkpoints, common files, search databases. Defaults to ~/.cache/opendde.
OPENDDE_DEPENDENCY_URL	Override checkpoint download root.
OPENDDE_COMMON_URL	Override common runtime file download root. Falls back to OPENDDE_DEPENDENCY_URL when set.
OPENDDE_SEARCH_DATABASE_URL	Override template/RNA-MSA database download root.
LAYERNORM_TYPE	LayerNorm backend; defaults to torch. Set to fast_layernorm to opt into the fused kernel.

Template/RNA-MSA preprocessing also needs HMMER. Template inference may need kalign:

apt-get update && apt-get install -y hmmer kalign

Input JSON

OpenDDE input is a top-level list of jobs:

[
  {
    "name": "tiny",
    "modelSeeds": [101],
    "sequences": [
      {
        "proteinChain": {
          "sequence": "ACDEFGHIK",
          "count": 1
        }
      }
    ]
  }
]

covalent_bonds is optional and may be omitted from a job; include it only to declare explicit covalent links between entities.

Full schema: infer_json_format.md.

Convert a structure file to JSON:

opendde json -i examples/7pzb.pdb -o ./output --altloc first
opendde json -i examples/2lwu.cif -o ./output --altloc first --assembly_id 1

Preprocess optional features

# Protein MSA
opendde msa -i examples/input.json -o ./output

# Protein MSA + template search
opendde mt -i examples/input.json -o ./output

# Protein MSA + template search + RNA MSA when RNA is present
opendde prep -i examples/input.json -o ./output

Notes:

• Protein MSA uses the public ColabFold MMseqs2 API unless A3M paths are already present in the JSON.
• Template and RNA-MSA search use local databases under $OPENDDE_ROOT_DIR/search_database/.
• Generated JSON files are written under <out_dir>/.opendde_preprocessed/<input-hash>/ rather than next to the input JSON, so read-only input directories work.

Details: msa_template_pipeline.md.

Run prediction

Standard run:

opendde pred -i examples/input.json -o ./output -n opendde_v1

Compatibility run with the standard step/cycle counts:

opendde pred \
  -i examples/input.json \
  -o ./output \
  -n opendde_v1 \
  --use_msa false \
  --use_template false \
  --use_rna_msa false \
  --sample 1 \
  --step 200 \
  --cycle 10

Inference defaults to --device auto, fp32, and auto triangle kernels. Device auto-selection uses NVIDIA CUDA when available, then the Apple Metal (MPS) backend on Apple Silicon, and otherwise CPU. cuEquivariance is selected only when its Linux CUDA packages import successfully; otherwise the model uses PyTorch triangle kernels. MPS always uses PyTorch triangle kernels and defaults to FP32. --dtype bf16 also works there and follows the same dynamic policy as CUDA: the trunk uses BF16; by default, diffusion and the confidence head stay FP32 through 2560 tokens, confidence uses BF16 above 2560, and diffusion uses BF16 above 3840 to reduce memory. BF16 performance varies by Apple GPU and workload, so compare it with FP32 for your inputs. BF16 autocast needs macOS 14 or newer and is downgraded to FP32 below that.

Multi-GPU Fold-CP inference

Fold-CP distributes token-pair-heavy inference work over a 1 x P mesh, where P can be any available GPU count greater than one. Launch it with torchrun and expose exactly the GPUs you want to use. For example, four GPUs use:

CUDA_VISIBLE_DEVICES=0,1,2,3 torchrun --standalone --nproc_per_node 4 \
  -m runner.batch_inference pred \
  -i examples/protein_200.json \
  -o ./output_foldcp \
  -n opendde_v1 \
  --use_msa false \
  --use_template false \
  --use_rna_msa false \
  --sample 1 \
  --step 200 \
  --cycle 10 \
  --trimul_kernel torch \
  --triatt_kernel torch \
  --foldcp_mode distributed \
  --foldcp_size_dp 1 \
  --foldcp_size_cp 4

Runtime notes:

• --nproc_per_node P must match --foldcp_size_dp 1 times --foldcp_size_cp P.
• --foldcp_size_cp P creates a 1 x P context-parallel mesh. The example uses P=4; other GPU counts require changing both 4 values.
• Keep the input, model, dtype, cycle, step, sample, MSA, and template settings identical when comparing single-GPU and Fold-CP outputs. Select --triatt_kernel torch --trimul_kernel torch for both runs; the distributed CUDA BF16 path additionally uses Triton for attention-bias fusion.
• Outputs are written under the requested -o/--out_dir just like normal inference.
• Optional --foldcp_metrics_jsonl path/to/metrics.jsonl records Fold-CP timing and memory metrics.

For single-GPU inference, omit the Fold-CP flags or set --foldcp_mode single --foldcp_size_cp 1.

Use prepared features:

opendde pred -i examples/examples_with_template/example_9fm7.json \
  -o ./output -n opendde_v1 \
  --use_msa true --use_template true

opendde pred -i examples/examples_with_rna_msa/example_9gmw_2.json \
  -o ./output -n opendde_v1 \
  --use_rna_msa true

Optional TFG Guidance

OpenDDE includes default-off Training-Free Guidance (TFG) for protein-ligand runs. TFG refines each sampled trajectory with geometry potentials while keeping the requested --sample count unchanged.

opendde pred -i examples/input.json -o ./output -n opendde_v1 \
  --use_tfg_guidance true

Outputs are written to:

<out_dir>/<job_name>/seed_<seed>/predictions/

Common flags

Flag	Meaning
-n, --model_name	Model name. Currently opendde_v1.
--load_checkpoint_path	Explicit checkpoint path.
--seeds	Comma-separated seeds, e.g. 101,102. Overrides the job's modelSeeds; if unset, modelSeeds are used, or a random seed when both are absent.
--use_msa	Use/generate protein MSA features.
--use_template	Use/generate template features.
--use_rna_msa	Use/generate RNA MSA features; requires --use_msa true.
--use_tfg_guidance	Enable Training-Free Guidance.
--foldcp_mode	single or distributed; use distributed with torchrun for multi-GPU Fold-CP inference.
--foldcp_size_dp	Compatibility option; only 1 is supported. Runtime 2 x 2 topology is not maintained.
--foldcp_size_cp	Context-parallel degree P in the maintained 1 x P mesh; must match the launched process count.
--foldcp_devices	Optional visible-device list recorded in Fold-CP metrics; actual GPU visibility is controlled by CUDA_VISIBLE_DEVICES.
--foldcp_metrics_jsonl	Optional JSONL path for Fold-CP timing and memory metrics.
--dtype	bf16 or fp32.
--device	auto, cpu, cuda, or mps; auto uses CUDA when available, then Apple MPS, and otherwise CPU.
--trimul_kernel, --triatt_kernel	auto, cuequivariance, or torch.

Run opendde <command> --help for the full option list.