Access and Startup#

The BioNeMo Framework is free to use and easily accessible. Users can pull the BioNeMo Framework Docker container to develop and execute code. Below, we outline the steps to access the latest version.

An open-source version of the BioNeMo Framework is coming soon and will be available on GitHub.

Access the BioNeMo Framework#

NGC Account and API Key Configuration#

NVIDIA GPU Cloud (NGC) is a portal of enterprise services, software, and support for AI and HPC workloads. The NGC Catalog is a collection of GPU-accelerated software, models and containers that speed up end-to-end AI workflows. The BioNeMo Framework container is available on NGC.

Create a free account on NGC and log in.
At the top right, click on the User > Setup > Generate API Key, then click + Generate API Key and Confirm. Copy and store your API Key in a secure location.

You can now view the BioNeMo Framework container here or by searching the NGC Catalog for “BioNeMo Framework”. Feel free to explore the resources available to you in the Catalog.

Startup Instructions#

Now that you can access the BioNeMo Framework container, it is time to get up and running. BioNeMo is compatible across a variety of computing environments, keeping in mind users with local workstations and data centers, users of major CSPs (e.g., AWS, Azure, GCP, and OCI), and users of NVIDIA’s DGX Cloud infrastructure.

Running the Container on a Local Machine#

Pull Docker Container from NGC#

Within the NGC Catalog, navigate to BioNeMo Framework > Tags > Get Container, and copy the image path for the latest tag.

Open a command prompt on your machine and enter the following:

docker login nvcr.io

    Username: $oauthtoken
    Password: <YOUR_API_KEY>

You can now pull the container:

docker pull <IMAGE_PATH>

Run Docker Container#

First, create a local workspace directory (to be mounted to the home directory of the Docker container to persist data). You can then launch the container. We recommend running the container in a JupyterLab environment, as per the below command:

docker run --rm -d --gpus all -p 8888:8888 \
  -v <YOUR_WORKSPACE>:/workspace/bionemo/<YOUR_WORKSPACE> <IMAGE_PATH> \
  "jupyter lab --allow-root --ip=* --port=8888 --no-browser \
  --NotebookApp.token='' --NotebookApp.allow_origin='*' \
  --ContentsManager.allow_hidden=True --notebook-dir=/workspace/bionemo"

Explanation:

Docker: The first line runs a Docker container in detached mode (-d), uses all available GPUs for the container (--gpus all), and maps it to port 8888.
Volume Mapping: Maps host directory into the home directory of the container.
JupyterLab Command: Customizable command line which allows root access (--allow-root), binding to all IP addresses on the specified port (--ip=* --port=8888), disables browser launch (--no-browser) and token authentication requirements (--NotebookApp.token), shows hidden files by setting (.allow_hidden=True), and sets the starting working directory to /workspace/bionemo.

Running the Container in the Cloud through Major CSPs#

Launch Instance Through NVIDIA VMI#

The BioNeMo Framework container is supported on cloud-based GPU instances through the NVIDIA GPU-Optimized Virtual Machine Image (VMI), available for AWS, GCP, Azure, and OCI. NVIDIA VMIs are built on Ubuntu and provide a standardized operating system environment across clouds for running NVIDIA GPU-accelerated software. They are pre-configured with software dependencies such as NVIDIA GPU drivers, Docker, and the NVIDIA Container Toolkit. More details about NVIDIA VMIs can be found here.

The general steps below should be adapted according to the CSP:

Launch a GPU instance running the NVIDIA GPU-Optimized VMI (e.g. AWS EC2).
Connect to the running instance, and then pull and run the BioNeMo Framework container exactly as outlined in the Running the Container on a Local Machine section above.

Integration with Cloud Services#

BioNeMo is compatible with various cloud services. Check out blogs about BioNeMo on SageMaker (example code repository), ParallelCluster (example code repository), and EKS (example code repository).

Running the Container on DGX Cloud#

For DGX Cloud users, NVIDIA Base Command Platform (BCP) includes a central user interface with managed compute resources. It can be used to manage datasets, workspaces, jobs, and users within an organization and team. This creates a convenient hub for monitoring job execution, viewing metrics and logs, and monitoring resource utilization. NVIDIA DGX Cloud is powered by Base Command Platform. More information can be found on the BCP website.

NGC CLI Configuration#

NVIDIA NGC Command Line Interface (CLI) is a command-line tool for managing Docker containers in NGC. You can download it on your local machine as per the instructions here.

Once installed, run ngc config set to establish NGC credentials:

API key: Enter your API Key
CLI output: Accept the default (ascii format) by pressing Enter
org: Choose from the list which org you have access to
team: Choose the team you are assigned to
ace: Choose an ACE, otherwise press Enter to continue

Note that the org and team are only relevant when pulling private containers/datasets from NGC created by you or your team. For BioNeMo Framework, use the default value.

You can learn more about NGC CLI installation here. Note that the NGC documentation also discusses how to mount your own datasets and workspaces.

Running the BioNeMo Framework Container#

On your local machine, run the following command to launch your job, ensuring to replace the relevant fields with your settings:

ngc batch run \
	--name <YOUR_JOB_NAME> \
	--team <YOUR_TEAM> \
	--ace <YOUR_ACE> \
	--instance dgxa100.80g.1.norm \
	--image <IMAGE_PATH> \
	--port 8888 \
	--workspace <YOUR_WORKSPACE>:/workspace/bionemo/<YOUR_WORKSPACE>:RW \
	--datasetid <YOUR_DATASET> \
	--result /result \
	--total-runtime 1D \
	--order 1 \
	--label <YOUR_LABEL> \
	--commandline "jupyter lab --allow-root --ip=* --port=8888 --allow-root --no-browser --NotebookApp.token='' --NotebookApp.allow_origin='*' --ContentsManager.allow_hidden=True --notebook-dir=/workspace/bionemo & sleep infinity"