Skip to content

v2.0-MIGRATION-GUIDE.md

Latest commit

 

History

History
283 lines (234 loc) · 14.2 KB

v2.0-MIGRATION-GUIDE.md

File metadata and controls

283 lines (234 loc) · 14.2 KB
Raw

PhysicsNeMo v2.0 Migration Guide

PhysicsNeMo v2.0, for release in March 2026, includes a significant code base refactor to improve many areas of physicsnemo. In addition to new functionality, we've upgraded our python infrastructure and dependency management. This guide highlights some new functionality, changes, should be used as a starting point to transition your applications to physicsnemo v2.0.

Installation

You can now install and run physicsnemo with uv, and we've made some trimming of the core dependencies and install requirements. pip install is still available and functional, too. uv sync and pip install of physicsnemo is now tested, nightly, and successful on linux, macOS, and Windows platforms.

We have also isolated some of the optional dependencies of physicsnemo to ensure missing optional packages are not an install or runtime issue for users and developers, unless you are actively using that dependency. For example, pyvista and vtk are a common dependencies in some of the CAE and mesh-centric workloads or models. But if you are using physicsnemo for something else, you should not be required to have those installed!

In general, the PhysicsNeMo team recommends uv for installation and development. However, in some cases (such as running or developing in a container) pip install is still useful.

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.

Compatibility Layer

PhysicsNeMo v2.0 through v2.2 shipped an opt-in physicsnemo.compat module that aliased pre-v2.0 import paths onto their new locations. That layer was removed in v2.3, and the PHYSICSNEMO_ENABLE_COMPAT environment variable no longer has any effect. The tables below list every alias it provided; update imports accordingly.

Moved Modules

Any name previously imported from the module on the left is now imported from the module on the right.

Before (pre-v2.0) After
physicsnemo.distributed.shard_tensor physicsnemo.domain_parallel.shard_tensor
physicsnemo.launch.logging physicsnemo.utils.logging
physicsnemo.launch.utils.checkpoint physicsnemo.utils.checkpoint
physicsnemo.metrics.diffusion physicsnemo.diffusion.metrics
physicsnemo.models.diffusion.corrdiff_utils physicsnemo.diffusion.samplers
physicsnemo.models.layers physicsnemo.nn
physicsnemo.models.layers.activations physicsnemo.nn.module.activations
physicsnemo.models.layers.attention_layers physicsnemo.nn.module.attention_layers
physicsnemo.models.layers.ball_query physicsnemo.nn.module.ball_query
physicsnemo.models.layers.conv_layers physicsnemo.nn.module.conv_layers
physicsnemo.models.layers.dgm_layers physicsnemo.nn.module.dgm_layers
physicsnemo.models.layers.drop physicsnemo.nn.module.drop
physicsnemo.models.layers.fft physicsnemo.nn.module.fft
physicsnemo.models.layers.fourier_layers physicsnemo.nn.module.fourier_layers
physicsnemo.models.layers.fully_connected_layers physicsnemo.nn.module.fully_connected_layers
physicsnemo.models.layers.fused_silu physicsnemo.nn.module.fused_silu
physicsnemo.models.layers.interpolation physicsnemo.nn.functional.interpolation
physicsnemo.models.layers.kan_layers physicsnemo.nn.module.kan_layers
physicsnemo.models.layers.mlp_layers physicsnemo.nn.module.mlp_layers
physicsnemo.models.layers.resample_layers physicsnemo.nn.module.resample_layers
physicsnemo.models.layers.siren_layers physicsnemo.nn.module.siren_layers
physicsnemo.models.layers.spectral_layers physicsnemo.nn.module.spectral_layers
physicsnemo.models.layers.transformer_decoder physicsnemo.nn.module.transformer_decoder
physicsnemo.models.layers.transformer_layers physicsnemo.nn.module.transformer_layers
physicsnemo.models.layers.weight_fact physicsnemo.nn.module.weight_fact
physicsnemo.models.layers.weight_norm physicsnemo.nn.module.weight_norm
physicsnemo.models.meta physicsnemo.core.meta
physicsnemo.models.module physicsnemo.core.module
physicsnemo.utils.diffusion physicsnemo.diffusion.utils
physicsnemo.utils.domino physicsnemo.models.domino.utils
physicsnemo.utils.filesystem physicsnemo.core.filesystem
physicsnemo.utils.graphcast physicsnemo.models.graphcast.utils
physicsnemo.utils.neighbors physicsnemo.nn.functional
physicsnemo.utils.patching physicsnemo.diffusion.multi_diffusion.patching
physicsnemo.utils.sdf physicsnemo.nn.functional.geometry.sdf
physicsnemo.utils.version_check physicsnemo.core.version_check

Moved Classes and Functions

Before (pre-v2.0) After
physicsnemo.models.diffusion.AttentionOp physicsnemo.nn.AttentionOp
physicsnemo.models.diffusion.Conv2D physicsnemo.nn.Conv2d
physicsnemo.models.diffusion.DhariwalUNet physicsnemo.models.diffusion_unets.DhariwalUNet
physicsnemo.models.diffusion.EDMPrecond physicsnemo.diffusion.preconditioners.EDMPrecond
physicsnemo.models.diffusion.EDMPrecondSR physicsnemo.diffusion.preconditioners.EDMPrecondSR
physicsnemo.models.diffusion.EDMPrecondSuperResolution physicsnemo.diffusion.preconditioners.EDMPrecondSuperResolution
physicsnemo.models.diffusion.FourierEmbedding physicsnemo.nn.FourierEmbedding
physicsnemo.models.diffusion.GroupNorm physicsnemo.nn.GroupNorm
physicsnemo.models.diffusion.Linear physicsnemo.nn.Linear
physicsnemo.models.diffusion.PositionalEmbedding physicsnemo.nn.PositionalEmbedding
physicsnemo.models.diffusion.SongUNet physicsnemo.models.diffusion_unets.SongUNet
physicsnemo.models.diffusion.SongUNetPosEmbd physicsnemo.models.diffusion_unets.SongUNetPosEmbd
physicsnemo.models.diffusion.SongUNetPosLtEmbd physicsnemo.models.diffusion_unets.SongUNetPosLtEmbd
physicsnemo.models.diffusion.StormCastUNet physicsnemo.models.diffusion_unets.StormCastUNet
physicsnemo.models.diffusion.UNet physicsnemo.models.diffusion_unets.UNet
physicsnemo.models.diffusion.UNetBlock physicsnemo.nn.UNetBlock
physicsnemo.models.diffusion.VEPrecond physicsnemo.diffusion.preconditioners.VEPrecond
physicsnemo.models.diffusion.VEPrecond_dfsr physicsnemo.diffusion.preconditioners.VEPrecond_dfsr
physicsnemo.models.diffusion.VEPrecond_dfsr_cond physicsnemo.diffusion.preconditioners.VEPrecond_dfsr_cond
physicsnemo.models.diffusion.VPPrecond physicsnemo.diffusion.preconditioners.VPPrecond
physicsnemo.models.diffusion.get_group_norm physicsnemo.nn.get_group_norm
physicsnemo.models.diffusion.iDDPMPrecond physicsnemo.diffusion.preconditioners.iDDPMPrecond
physicsnemo.models.diffusion.layers.Attention physicsnemo.nn.UNetAttention

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. physicsnemo.diffusion contains the diffusion framework for training diffusion models and sampling from them. It includes noise schedules, samplers, diffusion losses, plug-and-play guidance, multi-diffusion, and other related utilities.
  4. physicsnemo.mesh contains a GPU-accelerated mesh processing library for simplicial meshes of any dimension, including discrete calculus, curvature analysis, subdivision, repair, and visualization.
  5. physicsnemo.datapipes brings reusable and generic utilities to standardize GPU-centric data pipelines for SciML.

Model Standardization

During the v2.0 refactor, all production models and layers were aligned with the standards in CODING_STANDARDS/MODELS_IMPLEMENTATION.md. In short:

  • Layout: Reusable building blocks live in physicsnemo.nn; full models live in physicsnemo.models. New model code starts in physicsnemo.experimental.
  • Docs: Model code was standardized to Numpy-style docstrings for a consistent API reference.
  • Types and validation: Public methods use jaxtyping shape annotations (e.g. Float[Tensor, "b c h w"]).
  • Self-contained modules: Model-specific helpers live with the model (single file or model_name/ subpackage), not in a flat mix of shared utility files.

Other changes below the surface also were implemented, feel free to browse the (extensive) list of standards for models for more information.

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 GPU-accelerated mesh processing library for 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.

PhysicsNeMo Sym → physicsnemo.sym

The PhysicsNeMo-Sym repository is being archived. Its core functionality — symbolic PDE definition, automatic spatial derivative computation, and physics-informed residual evaluation — has been upstreamed into PhysicsNeMo as the physicsnemo.sym module.

What changed

Before (physicsnemo-sym) After (physicsnemo)
pip install nvidia-physicsnemo.sym pip install "nvidia-physicsnemo[sym]"
from physicsnemo.sym.eq.pdes.navier_stokes import NavierStokes Define your PDE inline using SymPy (see example below)
from physicsnemo.sym.key import Key Use plain strings
from physicsnemo.sym.models.arch import Arch Use torch.nn.Module
from physicsnemo.sym.geometry.* import ... Use physicsnemo.mesh primitives + PyVista
from physicsnemo.sym.eq.spatial_grads.spatial_grads import compute_connectivity_tensor from physicsnemo.sym.eq.gradients import compute_connectivity_tensor

Defining PDEs

Pre-built PDE classes (NavierStokes, Diffusion, etc.) are no longer shipped. Instead, define your equations inline using SymPy:

from sympy import Symbol, Function, Number
from physicsnemo.sym.eq.pde import PDE
from physicsnemo.sym.eq.phy_informer import PhysicsInformer


class NavierStokes(PDE):
    def __init__(self, nu=0.01, dim=2):
        self.dim = dim
        x, y = Symbol("x"), Symbol("y")
        u = Function("u")(x, y)
        v = Function("v")(x, y)
        p = Function("p")(x, y)
        self.equations = {
            "continuity": u.diff(x) + v.diff(y),
            "momentum_x": (
                u * u.diff(x)
                + v * u.diff(y)
                + p.diff(x)
                - nu * (u.diff(x, 2) + u.diff(y, 2))
            ),
            "momentum_y": (
                u * v.diff(x)
                + v * v.diff(y)
                + p.diff(y)
                - nu * (v.diff(x, 2) + v.diff(y, 2))
            ),
        }


ns = NavierStokes(nu=0.01, dim=2)
pi = PhysicsInformer(
    ["continuity", "momentum_x", "momentum_y"], ns, grad_method="autodiff"
)

See the LDC PINNs example for a complete working training script. For an inverse problem (recovering unknown PDE coefficients from data), see the Inverse PINN example, which also includes a side-by-side mapping of the old Solver / Domain / PointwiseConstraint workflow to the new explicit PyTorch loop.

Getting help

If you have a workflow that depends on PhysicsNeMo-Sym functionality not yet available in the upstreamed module, please reach out to physicsnemo-team@nvidia.com or open a GitHub issue.

Reporting questions, concerns, or comments

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