Getting Started | NVIDIA BioNeMo NIM Documentation

Prerequisites

For detailed hardware requirements, supported GPU configurations, and system setup instructions (Docker, NVIDIA Drivers, Container Toolkit), refer to the Support Matrix.

NGC Account

Create an account on NGC
Generate an API Key
Log in to Docker with your NGC API key using docker login nvcr.io --username='$oauthtoken' --password=<your personal NGC key>

NGC CLI Tool

Download the NGC CLI tool for your OS.

Use NGC CLI version 3.41.1 or newer. Here is the command to install this on AMD64 Linux in your home directory:

wget --content-disposition https://api.ngc.nvidia.com/v2/resources/nvidia/ngc-apps/ngc_cli/versions/3.41.3/files/ngccli_linux.zip -O ~/ngccli_linux.zip && \
unzip ~/ngccli_linux.zip -d ~/ngc && \
chmod u+x ~/ngc/ngc-cli/ngc && \
echo "export PATH=\"\$PATH:~/ngc/ngc-cli\"" >> ~/.bash_profile && source ~/.bash_profile

Set up your NGC CLI tool locally. You will need your API key for this.

ngc config set

After you enter your API key, you might see multiple options for the org and team. Select as desired or press Enter to accept the default.

Launch the DiffDock NIM

Pull the NIM container.

docker pull nvcr.io/nim/mit/diffdock:2.3.0

Run the container.

The environment variable NGC_API_KEY must be defined and valid in your local environment for the following command to proceed. For information about personal API key setup, refer to the NGC User Guide.

export NGC_API_KEY=<your personal NGC key>

docker run --rm -it --name diffdock-nim \
  --runtime=nvidia -e NVIDIA_VISIBLE_DEVICES=0 \
  --shm-size=2G \
  --ulimit memlock=-1 \
  --ulimit stack=67108864 \
  -e NGC_API_KEY=$NGC_API_KEY \
  -p 8000:8000 \
  nvcr.io/nim/mit/diffdock:2.3.0

Open a new terminal and use the following command to check the API status until it returns true. This can take a couple of minutes.

curl localhost:8000/v1/health/ready

Example output:

true

Run Inference

Open a new terminal, leaving the current terminal open with the launched service.
Prepare the JSON request body. Run this step in bash. Check the shell with echo $0. If it is not bash, run /bin/bash first.

sed converts the multi-line file into one line for JSON encoding.

protein_bytes=`curl https://files.rcsb.org/download/8G43.pdb | grep -E '^ATOM' | sed -z 's/\n/\\\n/g'`; \
ligand_bytes=`curl https://files.rcsb.org/ligands/download/ZU6_ideal.sdf | sed -z 's/\n/\\\n/g'`; \
echo "{
    \"ligand\": \"${ligand_bytes}\",
    \"ligand_file_type\": \"sdf\",
    \"protein\": \"${protein_bytes}\",
    \"num_poses\": 1,
    \"time_divisions\": 20,
    \"steps\": 18,
    \"save_trajectory\": false,
    \"is_staged\": false
}" > diffdock.json

Run inference and save the response to output.json.

curl --header "Content-Type: application/json" \
    --request POST \
    --data @diffdock.json \
    --output output.json \
    http://localhost:8000/molecular-docking/diffdock/generate

The output file output.json is JSON with the predicted docking poses. The fields are:

Field	Type	Description
status	str	report ‘success’ or ‘fail’ for this request
details	str	detailed information for success or failure
protein	str	protein PDB text from the input
ligand	str	ligand molecule description from the input
ligand_positions	list of str	list of SDF formatted text as the generated poses
position_confidence	list of float	list of confidence scores for the generated poses
trajectory	list of str	list of PDB formatted text as the diffusion trajectories for the generated poses (optional)

Dump Generated Poses

Use the Python script in this section to write the docked ligand poses into a folder named output. Create a file named dump_output.py and copy the content below into it.

import json
import os
import shutil
def dump_one(folder, ligand_positions, position_confidence):
    os.makedirs(folder, exist_ok=True)
    for i, c in enumerate(position_confidence):
        with open('%s/rank%02d_confidence_%0.2f.sdf' % (folder, i+1, c), 'w') as f:
            f.write(ligand_positions[i])
shutil.rmtree('output', ignore_errors=True)
os.makedirs('output', exist_ok=True)
with open('output.json') as f:
    data = json.load(f)
if type(data['status']) == str:
    dump_one('output', data['ligand_positions'], data['position_confidence'])
else:
    for i in range(len(data['status'])):
        dump_one('output/ligand%d' % (i+1), data['ligand_positions'][i], data['position_confidence'][i])

Run the command below to launch the Python script.

python3 dump_output.py

List the content in the output folder.

$ ls output
rank01_confidence_-0.98.sdf

Stop the Container

When you are done testing the endpoint, stop the container by running docker stop diffdock-nim in a new terminal.