Skip to content

v2.0-MIGRATION-GUIDE.md

Latest commit

 

History

History
101 lines (76 loc) · 4.42 KB

v2.0-MIGRATION-GUIDE.md

File metadata and controls

101 lines (76 loc) · 4.42 KB

PhysicsNeMo v2.0 Migration Guide

This document is meant to inform users of physicsnemo of high level changes to the repository, provide a little background on why they were necessary, and give you some guidance on updating your code.

This guide is a work in progress. Please come back later for more information.

Core Reorganization

The core packages of physicsnemo have been reorganized to prevent circular imports. For most uses, the key changes are:

  1. physicsnemo.models.Module and physicsnemo.models.Meta are now in physicsnemo.core.
  2. physicsnemo.launch is completely deprecated and removed. Logging functionality is now in physicsnemo.utils.logging, while checkpoint functionality is now in physicsnemo.utils.checkpoint
  3. Many layer-like components have been migrated to physicsnemo.nn, from both physicsnemo.models and from physicsnemo.utils
  4. Model-specific utility functions have been relocated to adjacent to their corresponding model. For example, physicsnemo.utils.domino now is located at physicsnemo.models.domino.utils.
  5. Domain Parallelism has been separated from distributed utilities to provide better isolation for users of just the distributed utilities. ShardTensor is now located in physicsnemo.domain_parallelism.

New Packages

Several new packages have been introduced for PhysicsNeMo v2.0. At a high level:

  1. physicsnemo.nn contains reusable, pytorch-like modules for building blocks of layers. physicsnemo.nn.functional contains a functional interface to these layers, where appropriate.
  2. physicsnemo.domain_parallel contains the ShardTensor object and utilities.
  3. [TBD] physicsnemo.diffusion
  4. physicsnemo.mesh contains GPU-accelerated mesh processing utilities for training dataset analysis, subdivision, and repair. It can handle simplicial meshes of any dimension, including discrete calculus, curvature.
  5. physicsnemo.datapipes brings reusable and generic utilities to standardize GPU-centric data pipelines for SciML.

Packaging, Installation, and Dependencies

The core dependencies of physicsnemo have been identified and consolidated. Optional dependencies are now aggressively protected throughout the code base. Circular imports inside the code base have been fixed, and external imports have additional requirements to be met before introducing them.

uv is now the preferred way to install and develop with physicsnemo. pip is still a viable installation method.

Model Standardization

[TBD]

PhysicsNeMo Datapipes

PhysicsNeMo DataPipes is a GPU-first, high-performance data loading infrastructure for scientific machine learning that uses threading and asynchronous execution to maximize throughput on large, high-resolution datasets. It provides a modular architecture of readers, transforms, datasets, and a dataloader that can be configured via Hydra YAML files for reproducibility, while maintaining familiar PyTorch-like interfaces and easy extensibility for custom data formats and preprocessing operations. Check out examples/minimal/datapipes to learn more.

PhysicsNeMo Mesh

PhysicsNeMo Mesh (physicsnemo.mesh) is a set of GPU-accelerated mesh utilities for pre-processing meshes of any dimension - the same API handles 2D planar triangulations, 3D surface meshes, tetrahedral volume meshes, curve meshes, undirected graphs, and point clouds. The central object is a PyTorch tensorclass:

from physicsnemo.mesh import Mesh

mesh = Mesh(
    points=...,      # float (n_points, n_spatial_dims) - vertex coordinates
    cells=...,       # int   (n_cells, n_manifold_dims + 1) - cell connectivity
    point_data=...,  # TensorDict: per-vertex field data
    cell_data=...,   # TensorDict: per-cell field data
    global_data=..., # TensorDict: mesh-level data
)

points is a float tensor of vertex coordinates; cells is an integer tensor of indices into points that define each simplex. All geometry and field data moves together under .to("cuda") / .to("cpu"), and most operations are differentiable through PyTorch autograd. See physicsnemo/mesh/README.md for the full feature matrix.

Updating your code

To update your code for physicsnemo v2.0, you will need to adjust several key import paths (like logging, see above) and potentially update datapipes and model checkpoints.

Reporting questions, concerns, or comments

Please contact the development team via github issues on the physicsnemo repository.