Install Guide#

Source Code or Container Installation?#

Both options provide lots of flexibility.

Installing using the container is, typically, sufficient for most users. Installing from source comes with the responsibility of managing your environment.

The following are a few installation scenarios:

  • I’m an AI researcher and want to train a model in PhysicsNeMo.

    We recommend that you use the container image. You can create any model architecture from scratch. Refer to the Simple Training Tutorial for more details.

  • I’m a domain expert and want to use an existing model with some modifications.

    We recommend that you use the container image. We also recommend that you download the examples from the GitHub source to use as a starting point for your work.

  • I’m an AI researcher and want to contribute to PhysicsNeMo.

    We recommend that you clone the source code from GitHub. If you want to contribute to the repo, use a fork for your development.

PhysicsNeMo with Docker Image#

NVIDIA PhysicsNeMo NGC Container is the easiest way to start using PhysicsNeMo. This comes will all PhysicsNeMo software and its dependencies pre-installed allowing you to get started with PhysicsNeMo examples with ease. The PhysicsNeMo container is built on top of NVIDIA PyTorch NGC Container which is optimized for GPU acceleration.

Install the Docker Engine#

To start working with PhysicsNeMo repos, ensure that you have Docker Engine installed.

You will also need to install the NVIDIA Container Toolkit. This should work on most debian based systems:

 curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg \
&& curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
 sudo apt-get update
 sudo apt-get install -y nvidia-container-toolkit

To verify this install, you can run a sample workload

Running PhysicsNeMo in the Docker image while using SDF library requires an NVIDIA container toolkit version greater or equal to 1.0.4.

To run the Docker commands without sudo, add yourself to the Docker group by following the steps 1-4 found in Manage Docker as a non-root user

Get PhysicsNeMo Container#

Download the PhysicsNeMo Docker container from NGC using:

docker pull nvcr.io/nvidia/physicsnemo/physicsnemo:<tag>

All the available tags can be found on PhysicsNeMo NGC Container.

A shell session can be launched in the container using:

docker run --shm-size=1g --ulimit memlock=-1 --ulimit stack=67108864 \
           --runtime nvidia -it --rm nvcr.io/nvidia/physicsnemo/physicsnemo:<tag> bash

The current directory can be mounted inside the Docker container using:

docker run --shm-size=1g --ulimit memlock=-1 --ulimit stack=67108864 \
           --runtime nvidia -v ${PWD}:/workspace \
           -it --rm nvcr.io/nvidia/physicsnemo/physicsnemo:<tag> bash

To verify the installation, refer to Running Examples or run the following:

python
>>> import torch
>>> from physicsnemo.models.mlp.fully_connected import FullyConnected
>>> model = FullyConnected(in_features=32, out_features=64)
>>> input = torch.randn(128, 32)
>>> output = model(input)
>>> output.shape
torch.Size([128, 64])

PhysicsNeMo with Docker Image - Singularity#

After you have installed Singularity, to build and run the PhysicsNeMo Docker image with Singularity, use:

singularity build PhysicsNeMo.sif docker://nvcr.io/nvidia/physicsnemo/physicsnemo:<tag>
singularity run --writable --nv PhysicsNeMo.sif

PhysicsNeMo with pip Install#

Typically, it is recommended that you install Python packages inside a virtual environment. Depending on your preference, you can choose to create either a conda environment or a python virtual environment.

After you have the appropriate Python environment set up, install PyTorch for your environment by following the PyTorch Install Guide . Then, PhysicsNeMo can be pip installed using:

pip install nvidia-physicsnemo
# Below steps are required for PhysicsNeMo-Sym's installation
pip install Cython
pip install nvidia-physicsnemo-sym --no-build-isolation

To verify the installation, refer to Running Examples or run the following:

python
>>> import torch
>>> from physicsnemo.models.mlp.fully_connected import FullyConnected
>>> model = FullyConnected(in_features=32, out_features=64)
>>> input = torch.randn(128, 32)
>>> output = model(input)
>>> output.shape
torch.Size([128, 64])

Optional Dependencies#

  1. Additional packages are required for PhysicsNeMo examples. Refer to the README.md of each example for instructions on adding required dependencies. Typically, you will have to install dgl library, nvFuser library, and then do a full installation of PhysicsNeMo core (in addition to the above pip install steps). This can be done using pip install nvidia-physicsnemo[all].

  2. Add packages for quadpy, orthopy, ndim, and gdown if you intend to use the quadrature functionality of PhysicsNeMo Sym or want to download the example data for the Neural Operator training. This can be done using pip install quadpy orthopy ndim gdown.

Running Examples#

For tutorials and user guide, refer to: User Guide

A summary of case studies and example using PhysicsNeMo can be found on the GitHub:

PhysicsNeMo Examples#

Clone the PhysicsNeMo repository in your working directory using:

git clone https://github.com/NVIDIA/physicsnemo.git

Note

It is highly recommended to read the README.md file from each individual example to learn about the problem description and any other run instructions specific to each example. Most examples also provide a separate requirements.txt or instructions to install example specific dependencies.

To verify the examples run correctly, run these commands:

cd ./physicsnemo/examples/cfd/darcy_fno/
pip install -r requirements.txt
python train_fno_darcy.py

If you see the outputs/ directory created after the execution of the command (about five minutes), the installation is successful.

PhysicsNeMo Sym Examples#

Clone the PhysicsNeMo Sym repository in your working directory using:

git clone https://github.com/NVIDIA/physicsnemo-sym.git

Note

The physicsnemo-sym repository has Git LFS enabled. You must have Git LFS installed for the clone to work correctly. For more information, refer to Git LFS .

To verify that the examples run correctly, run these commands:

cd ./physicsnemo-sym/examples/helmholtz/
python helmholtz.py

If you see the outputs/ directory created after the execution of the command (about five minutes), the installation is successful.

PhysicsNeMo on Public Cloud Instances#

PhysicsNeMo can be used on public cloud instances like AWS and GCP. To install and run PhysicsNeMo:

  1. Get your GPU instance on AWS or GCP. See System Requirements for recommended hardware platform.

  2. Use the NVIDIA GPU-Optimized VMI on the cloud instance. For detailed instructions on setting up VMI, refer to NGC Certified Public Clouds.

  3. After the instance spins up, follow the NVIDIA PhysicsNeMo Getting Started to load the PhysicsNeMo Docker container and the examples.