[codex] Add rectilinear vector calculus functionals

[loliverhennigh]

Summary

Adds rectilinear-grid vector calculus functionals for periodic nonuniform grids:

• rectilinear_grid_divergence
• rectilinear_grid_curl
• rectilinear_grid_laplacian

Each functional follows the existing rectilinear gradient structure with its own package, FunctionSpec, Torch implementation, fused Warp custom op, custom backward kernels, exports, benchmark registry entries, tests, and docs figures.

Details

The Torch paths reuse the low-level rectilinear coordinate validation and finite-difference weight utilities, but implement the vector calculus operators directly. The Warp paths use fused operator-specific kernels and explicit adjoints for nonuniform rectilinear spacing rather than relying on uniform-grid transpose identities.

Curl is scoped to 2D/3D inputs, divergence supports 1D/2D/3D channel-first vector fields, and Laplacian supports 1D/2D/3D scalar fields.

Validation

Local:

• uv run --frozen pre-commit run --all-files
• uv run --frozen ruff format --check benchmarks/physicsnemo/nn/functional/registry.py physicsnemo/nn/functional/__init__.py physicsnemo/nn/functional/derivatives/__init__.py physicsnemo/nn/functional/derivatives/rectilinear_grid_divergence physicsnemo/nn/functional/derivatives/rectilinear_grid_curl physicsnemo/nn/functional/derivatives/rectilinear_grid_laplacian test/nn/functional/derivatives/test_rectilinear_grid_divergence.py test/nn/functional/derivatives/test_rectilinear_grid_curl.py test/nn/functional/derivatives/test_rectilinear_grid_laplacian.py
• uv run --frozen ruff check benchmarks/physicsnemo/nn/functional/registry.py physicsnemo/nn/functional/__init__.py physicsnemo/nn/functional/derivatives/__init__.py physicsnemo/nn/functional/derivatives/rectilinear_grid_divergence physicsnemo/nn/functional/derivatives/rectilinear_grid_curl physicsnemo/nn/functional/derivatives/rectilinear_grid_laplacian test/nn/functional/derivatives/test_rectilinear_grid_divergence.py test/nn/functional/derivatives/test_rectilinear_grid_curl.py test/nn/functional/derivatives/test_rectilinear_grid_laplacian.py
• uv run --frozen pytest -q test/nn/functional/derivatives
• Checked benchmark registry import/discovery for the new FunctionSpec classes.

RTX 4090 (torch 2.11.0+cu130, Warp available):

• /home/oliver/physicsnemo-maxwell-rtx4090/.venv/bin/python -m pytest -q test/nn/functional/derivatives/test_rectilinear_grid_divergence.py test/nn/functional/derivatives/test_rectilinear_grid_curl.py test/nn/functional/derivatives/test_rectilinear_grid_laplacian.py — 62 passed across CPU and CUDA.
• /home/oliver/physicsnemo-maxwell-rtx4090/.venv/bin/python -m pytest -q test/nn/functional/derivatives — 302 passed across CPU and CUDA.

Forward timing sanity check on RTX 4090:

Functional	Case	Torch	Warp	Speedup
RectilinearGridDivergence	1d-n8192	0.1847 ms	0.1669 ms	1.11x
RectilinearGridDivergence	2d-384x384	0.3394 ms	0.2412 ms	1.41x
RectilinearGridDivergence	3d-96x96x96	0.5001 ms	0.3154 ms	1.59x
RectilinearGridCurl	2d-384x384	0.3324 ms	0.2369 ms	1.40x
RectilinearGridCurl	3d-96x96x96	0.9213 ms	0.3032 ms	3.04x
RectilinearGridLaplacian	1d-n512	0.1807 ms	0.1570 ms	1.15x
RectilinearGridLaplacian	2d-256x256	0.3452 ms	0.2457 ms	1.40x
RectilinearGridLaplacian	3d-64x64x64	0.5166 ms	0.2911 ms	1.78x

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[greptile-apps]

Greptile Summary

This PR adds three new periodic vector-calculus functionals — rectilinear_grid_divergence, rectilinear_grid_curl, and rectilinear_grid_laplacian — for nonuniform rectilinear grids, each with its own FunctionSpec, Torch eager implementation, fused Warp custom op with explicit adjoint kernels, tests, benchmark registry entries, and docs figures.

• Divergence (1D/2D/3D): accumulates per-axis central-difference first derivatives; forward and backward Warp kernels verified correct.
• Curl (2D scalar, 3D vector): 2D path returns (n0, n1), 3D path returns (3, n0, n1, n2); mathematical correctness of all six Warp backward contributions confirmed.
• Laplacian (1D/2D/3D): sums per-axis second-derivative stencils; backward kernel correctly leverages the self-adjoint structure of the operator.

Important Files Changed

Filename	Overview
test/nn/functional/derivatives/test_rectilinear_grid_curl.py	Curl tests include correctness and parity checks; test_rectilinear_grid_curl_make_inputs_forward has an incorrect shape assertion that passes only because next(iter(...)) always yields the 2D case.
physicsnemo/nn/functional/derivatives/rectilinear_grid_curl/utils.py	Utility helpers for curl; validate_and_normalize_coordinates and normalize_periods are duplicated verbatim from the divergence and gradient packages.
physicsnemo/nn/functional/derivatives/rectilinear_grid_divergence/_warp_impl.py	Fused Warp kernels for 1D/2D/3D divergence; backward adjoints are mathematically correct, but coordinates are validated three times per forward call on the Warp path.
physicsnemo/nn/functional/derivatives/rectilinear_grid_curl/_warp_impl.py	Fused Warp kernels for 2D/3D curl; forward and backward kernels verified correct, launch dimensions use shape[-grid_ndim:] correctly for the 3D vector output.
physicsnemo/nn/functional/derivatives/rectilinear_grid_laplacian/_warp_impl.py	Fused Warp kernels for 1D/2D/3D Laplacian; forward and backward kernels accumulate contributions from all axes correctly.
physicsnemo/nn/functional/derivatives/rectilinear_grid_curl/_torch_impl.py	Torch curl implementation; 2D scalar and 3D vector curl computed correctly using periodic central-difference weights.
physicsnemo/nn/functional/derivatives/rectilinear_grid_divergence/_torch_impl.py	Torch divergence implementation; accumulates per-axis first derivatives correctly for 1D/2D/3D channel-first vector fields.
physicsnemo/nn/functional/derivatives/rectilinear_grid_laplacian/_torch_impl.py	Torch Laplacian implementation; accumulates second-derivative contributions per axis correctly for 1D/2D/3D scalar fields.
test/nn/functional/derivatives/test_rectilinear_grid_divergence.py	Divergence tests cover 1D/2D/3D accuracy, Warp/Torch parity, error handling, and make_inputs utilities.
test/nn/functional/derivatives/test_rectilinear_grid_laplacian.py	Laplacian tests cover 1D/2D/3D accuracy, Warp/Torch parity, error handling, and make_inputs utilities.
physicsnemo/nn/functional/derivatives/init.py	Exports three new functional classes and callables; sorted and consistent with existing pattern.
physicsnemo/nn/functional/init.py	Adds curl, divergence, and Laplacian to the top-level functional namespace and all; alphabetically ordered correctly.

_{Reviews (1): Last reviewed commit: "Add rectilinear vector calculus function..." | Re-trigger Greptile}

[loliverhennigh]

/blossom-ci

[loliverhennigh]

/blossom-ci

[megnvidia]

lgtm

[ktangsali]

A few notes:

1. We should update the Changelog for this.
2. Are we documenting somewhere the cast to float32 in Warp implementation path ? (This PR and the already existing functionals). I feel like we should raise a warning for this / document it if not done already
3. In the API docs, we should explicitly state that only periodic boundaries are supported
4. The flow of the modules introduced in this PR does not match with the earlier functionals. For example, the uniform_grid_gradient has below structure. Is it possible to make them consistent, whichever way you prefer?

uniform_grid_gradient/_warp_impl/
├── __init__.py
├── op.py
├── utils.py
├── launch_forward.py
├── launch_backward.py
└── _kernels/
    ├── __init__.py
    ├── forward.py
    └── backward.py

[loliverhennigh]

/ok to test e59f78f

[loliverhennigh]

/ok to test c93dc09

[copy-pr-bot]

/ok to test 08c186a

@loliverhennigh, there was an error processing your request: E2

See the following link for more information: https://docs.gha-runners.nvidia.com/cpr/e/2/

[loliverhennigh]

/ok to test 08c186a