Fix stale per-radian magnitude assumptions after sphere-radius scaling

[rajeeja]

Overview

After #1517 made scale_by_radius=True the default for gradient() and curl(), several places still assumed unit-sphere (per-radian) magnitudes. This surfaced in the docs as a confusing curl(grad(f)) example (see #1522, where the documented O(1–10) residual is now ~1e-13).

Closes #1534. Refs #1522, #1516, #1517.

Changes

Code (uxarray/core/dataarray.py)

• divergence(): add a scale_by_radius parameter (previously missing, unlike gradient/curl) and forward it to the underlying gradient() calls. Infer units from the input field and scaling instead of hardcoding "1/s".
• Document output units and the default radius scaling in the gradient(), curl(), and divergence() docstrings.

Docs (docs/user-guide/vector_calculus.ipynb)

• Correct the curl(grad(f)) residual wording: ~O(1e-13) with the default radius scaling (the curl stencil applies a 1/radius² factor) vs ~O(1–10) on the unit sphere.
• Update the vortex/radial examples to scientific notation (the old :.2f printed 0.00) and reword the "≈ 2" annotations.
• Drop hardcoded clim=(-1e-10, 1e-10) on the curl/divergence plots, which rendered flat at the new ~1e-13 scale.

Tests (test/core/test_vector_calculus.py)

• Tighten the now-vacuous curl(grad) (< 10.0) and antisymmetry (< 200.0) thresholds to the actual scaled magnitudes (< 1e-9 and < 1e-3).
• Add test_divergence_scales_by_radius covering the new parameter and units.

Verification

• Re-executed the full notebook end-to-end with no errored cells; curl(grad) ~1.1e-13, vortex curl/radial divergence ~5.4e-5 (positive). Outputs stripped per repo convention.
• pytest test/core/test_vector_calculus.py → 28 passed.
• pre-commit run --all-files → all hooks pass.

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[Copilot]

Pull request overview

Updates UXarray’s vector-calculus operators and documentation to be consistent with the post-#1517 default behavior (scale_by_radius=True), eliminating stale “unit-sphere magnitude” assumptions and making the docs/tests reflect physically scaled magnitudes.

Changes:

• Add scale_by_radius to UxDataArray.divergence() and forward it through the underlying gradient computations; infer divergence output units instead of hardcoding.
• Expand gradient()/curl()/divergence() docstrings to describe default radius scaling and resulting units.
• Update the vector calculus user-guide notebook and tighten related test tolerances; add a divergence radius-scaling test.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
uxarray/core/dataarray.py	Adds scale_by_radius to divergence() and updates units/scaling documentation for vector calculus APIs.
test/core/test_vector_calculus.py	Tightens curl-related tolerances and adds a divergence scaling test to match scaled magnitudes.
docs/user-guide/vector_calculus.ipynb	Updates narrative/formatting and plot scaling to reflect default radius scaling and new residual magnitudes.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.