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.

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.

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.

Some of physicsnemo v2.0 is new functionality, but for components we have moved or relocated for installation and dependency management, we have introduced physicsnemo.compat. As a thin compatibility layer, physicsnemo.compat attaches a mapping to the sys.modules path so old import locations can still work. For example, physicsnemo.models.module was moved to physicsnemo.core in v2.0. With the compatibility layer enabled, from physicsnemo.models import module will still work correctly (even though that import doesn't actually exist anymore).

The goal of the compatibility layer is to make transistioning to physicsnemo v2.0 easier. Where possible, if it's simple to update your import paths we recommend that. If for some reason it is not as easy to update your code, the compatibility layer can help.

To use the compatibility layer, there are two options. First, you can set the environment variable PHYSICSNEMO_ENABLE_COMPAT to 1 (or similar truth-y values like true, on, etc.) and upon import the compatibility layer will be enabled. To enable it manually,

from physicsnemo.compat import install
install()

should suffice.

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.

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 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) 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.

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.

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.

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.

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.

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