Sym upstream pr1

[ktangsali]

PhysicsNeMo Pull Request

Description

First PR of Sym upstream efforts. Examples would be ported in a separate PR.

This PR depends on #1545

Summary

Adds physicsnemo.sym — a symbolic PDE residual computation module that enables
physics-informed training by automatically computing spatial derivatives and
evaluating PDE residuals. This is the upstreamed and modernized version of the
PhysicsInformer from physicsnemo-sym, rewired to use the PhysicsNeMo derivative
functionals (nn.functional.derivatives) as its computational backend.

What it does

PhysicsInformer takes a user-defined PDE (expressed symbolically via SymPy) and a
gradient method, then automatically:

1. Parses the SymPy equations to identify required spatial derivatives
2. Builds a computational graph that wires derivative computations to equation evaluation
3. Computes PDE residuals in the forward pass
   Users define their PDEs inline using standard SymPy:

from sympy import Symbol, Function
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)),
        }
ns = NavierStokes(nu=0.01, dim=2)
phy_inf = PhysicsInformer(
    required_outputs=["continuity", "momentum_x"],
    equations=ns,
    grad_method="autodiff",
)
residuals = phy_inf.forward({"coordinates": coords, "u": u, "v": v, "p": p})

Key design decisions

1. No Key / Node abstractions — replaced with plain strings and a lightweight Computation class
2. No TorchScript / JitManager / GraphManager — all removed
3. No pre-built PDE library — users define equations symbolically in their training code (common PDEs can be provided as documentation recipes)
4. Uses PhysicsNeMo derivative functionals — instead of porting the legacy eq/fd/, eq/ls/, eq/mfd/ implementations, the gradient modules wrap the FunctionSpec-based functionals from nn.functional.derivatives

Tests

Ported the exact same test methodology from physicsnemo-sym:

test_gradients.py — validates all 5 gradient methods against analytical derivatives of u = sin(x)*sin(8y)*sin(4z), threshold < 0.2
test_phy_informer.py — validates end-to-end Navier-Stokes residuals (continuity + momentum_x) across all 5 methods, threshold < 0.5

Checklist

• I am familiar with the Contributing Guidelines.
• New or existing tests cover these changes.
• The documentation is up to date with these changes.
• The CHANGELOG.md is up to date with these changes.
• An issue is linked to this pull request.
• If I am implementing a new model or modifying any existing model, I have followed the Models Implementation Coding Standards.

Dependencies

Review Process

All PRs are reviewed by the PhysicsNeMo team before merging.

Depending on which files are changed, GitHub may automatically assign a maintainer for review.

We are also testing AI-based code review tools (e.g., Greptile), which may add automated comments with a confidence score.
This score reflects the AI’s assessment of merge readiness and is not a qualitative judgment of your work, nor is
it an indication that the PR will be accepted / rejected.

AI-generated feedback should be reviewed critically for usefulness.
You are not required to respond to every AI comment, but they are intended to help both authors and reviewers.
Please react to Greptile comments with 👍 or 👎 to provide feedback on their accuracy.

[greptile-apps]

Greptile Summary

This PR upstreams physicsnemo.sym — a symbolic PDE residual computation module built on SymPy and the new nn.functional.derivatives backend. It adds the PhysicsInformer, five gradient methods, a lightweight Computation/Graph scheduler, and a SymPy-to-PyTorch compiler, along with the full suite of derivative functionals (uniform_grid_gradient, spectral_grid_gradient, mesh_lsq_gradient, etc.).

• P1: PhysicsInformer.forward mutates the caller's inputs dict by inserting "connectivity_tensor" in-place — use inputs = dict(inputs) before modifying.
• P2: The constant-lambda branch in torch_lambdify is defined with **kwargs but invoked positionally in SympyToTorch.forward, causing TypeError for pure-constant PDE expressions or freeze_terms paths containing constant additive terms.
• P2: GradientsAutoDiff reads input_dict["coordinates"] at runtime but the wrapping Computation only declares [var] as its inputs, leaving the dependency implicit and unvalidated at graph-construction time.

Important Files Changed

Filename	Overview
physicsnemo/sym/eq/phy_informer.py	Core PhysicsInformer class; P1 issue: forward mutates the caller's input dict when grad_method="least_squares" and compute_connectivity=True.
physicsnemo/sym/eq/gradients.py	Gradient modules for all five methods; implicit undeclared "coordinates" dependency in autodiff Computation, _heaviside_torch ignores values parameter, and numba JIT warm-up at import time.
physicsnemo/sym/utils/sympy/torch_printer.py	SymPy-to-PyTorch compiler; constant lambda uses **kwargs calling convention but is invoked with a positional argument, causing TypeError for pure-constant or freeze_terms PDE expressions.
physicsnemo/sym/graph.py	Two-phase graph scheduler with stall detection; previous infinite-loop issue addressed. Clean implementation.
physicsnemo/sym/computation.py	Lightweight Computation wrapper replacing the legacy Node abstraction; straightforward and correct.
physicsnemo/sym/eq/pde.py	PDE base class with make_computations and pprint helpers; clean implementation.
physicsnemo/mesh/calculus/_lsq_reconstruction.py	Refactored to delegate to the new functional LSQ API; removed duplicate solver logic, layout conversion handled by _to_mesh_gradient_layout.
physicsnemo/nn/functional/derivatives/init.py	New derivatives sub-package init; exports all six gradient functionals cleanly.
test/sym/test_phy_informer.py	End-to-end Navier-Stokes residual tests across all five gradient methods; all CUDA-only, comprehensive coverage.
test/sym/test_gradients.py	Per-method gradient validation against analytical derivatives of sin(x)*sin(8y)*sin(4z); good coverage.

_{Reviews (2): Last reviewed commit: "address all greptile comments" | Re-trigger Greptile}

[ktangsali]

/blossom-ci

[ktangsali]

Updated the branch after pulling in the changes from the latest main (after #1545 was merged). Ready for review

[coreyjadams]

I have mostly left comments about the overall structure, but a few things can be cleaned up too

[NickGeneva]

I approved for the code owner edit, but man I dont understand why this is getting added tbh.
I feel like this is just kinda worse outside of the sym package 🤷

[ktangsali]

I approved for the code owner edit, but man I dont understand why this is getting added tbh. I feel like this is just kinda worse outside of the sym package 🤷

Think of it as an abstraction on top of Functionals. Why do you think it is worse? Any design changes needed?

[NickGeneva]

I think its the fact that psn.sym was a framework centered around all these symbolic representations. So the symbolic description of PDEs worked well there and had create synergy with the entirety of the package (since it was build around symbolic PDEs)

While here symbolic representations are now just kinda this stripped down version which has a lot less synergy with the rest of the package. I not saying any of the implementation here is better or worse. I'm talking higher level, but this is not my judgement call to make... Seeing the graph representations getting added seemed out of place.

I do like the general idea of building on top of the functionals

[ktangsali]

I think its the fact that psn.sym was a framework centered around all these symbolic representations. So the symbolic description of PDEs worked well there and had create synergy with the entirety of the package (since it was build around symbolic PDEs)

While here symbolic representations are now just kinda this stripped down version which has a lot less synergy with the rest of the package. I not saying any of the implementation here is better or worse. I'm talking higher level, but this is not my judgement call to make... Seeing the graph representations getting added seemed out of place.

I do like the general idea of building on top of the functionals

I think its the fact that psn.sym was a framework centered around all these symbolic representations. So the symbolic description of PDEs worked well there and had create synergy with the entirety of the package (since it was build around symbolic PDEs)

While here symbolic representations are now just kinda this stripped down version which has a lot less synergy with the rest of the package. I not saying any of the implementation here is better or worse. I'm talking higher level, but this is not my judgement call to make... Seeing the graph representations getting added seemed out of place.

I do like the general idea of building on top of the functionals

Thanks for the context @NickGeneva ! Discussed this offline but will also share here for completeness. Yes, the motivation of this PR is hence to only bring in the base PDE class and not all the PDEs. The abstracted way of adding losses is valuable as it can let folks try out - say different numerical gradient techniques on the same model with minimal friction. The API is also valuable for someone working on a very high level and not wanting to dig deep into the functionals and their requirements. The requirements of PhysicsInformer are relatively straightforward. Finally, down the line as we continue to add more functionals and APIs for other numerical techniques, having a unified interface like this one will be useful

[coreyjadams]

@ktangsali what do you think of @peterdsharpe 's suggestion to use mesh for the adjacency computation instead of numba? I really like keeping the pyproject.toml free of unneeded deps. If we really, truly need numba, ok, let's do it. If we can do it without it, and it's not expected to be a critical path feature, can we avoid it?

[ktangsali]

@ktangsali what do you think of @peterdsharpe 's suggestion to use mesh for the adjacency computation instead of numba? I really like keeping the pyproject.toml free of unneeded deps. If we really, truly need numba, ok, let's do it. If we can do it without it, and it's not expected to be a critical path feature, can we avoid it?

I have updated the implementation to use Mesh now. Removed numba imports :)

[ktangsali]

/blossom-ci

[coreyjadams]

Thanks @ktangsali for taking the time to work on the numba dependency!