Reorganize math module into meaningful submodules

[Copilot]

helpers.py was a 662-line catch-all with 32 functions spanning unrelated concerns (vector ops, coordinate transforms, vertical averaging, gradients, distances). xp_utils.py had an opaque name for a single function.

New module structure

• vector_operations.py — dot/cross product, norms, normalization, inversion (10 functions)
• coordinate_transformations.py — geographical ↔ cartesian, zonal/meridional conversions (10 functions)
• vertical_operations.py — vertical level averaging and differences (5 functions)
• gradient.py — finite difference gradient operators (2 functions)
• distance.py — arc length on spheres, torus geometry (3 functions)
• math_utils.py — typed sqrt wrapper, renamed from xp_utils.py (1 function)

Import conventions

Two import patterns are used depending on context:

Regular Python files use module-level imports with aliases:

from icon4py.model.common.math import (
    coordinate_transformations as coord_trans,
    distance,
    vector_operations as vector_ops,
)

Standard aliases: coord_trans, vector_ops, vertical_ops.

GT4Py files (containing @gtx.field_operator / @gtx.program) use direct imports, since GT4Py's DSL parser does not support module.func() syntax:

from icon4py.model.common.math.coordinate_transformations import (
    geographical_to_cartesian_on_edges,
    geographical_to_cartesian_on_vertices,
)

No backward-compat re-exports — helpers.py and xp_utils.py are emptied. All consumers are updated.

Other

• __init__.py now documents the submodule layout
• Fixed pre-existing spelling typos in docstrings (meridonal → meridional)
• Unchanged modules: operators.py, derivative.py, projection.py, smagorinsky.py, stencils/

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[jenkins-apn]

Hi there, this is jenkins continuous integration...
Do you want me to verify this patch?

[jenkins-apn]

Hi there, this is jenkins continuous integration...
Do you want me to verify this patch?

[jcanton]

@copilot remove the backwards compatibility: always import the new structure and change any consumer that needs changing.
also, for all files that use maths: import the modules, not the methods directly, e.g.:
instead of from icon4py.model.common.math.coordinate_transformations import something
do:
from icon4py.model.common.math import coordinate_transformations

if useful for long names come up with aliases (e.g. coord_trans)

only change the imports for maths, leave the rest unchanged

[Copilot]

@copilot remove the backwards compatibility: always import the new structure and change any consumer that needs changing.
also, for all files that use maths: import the modules, not the methods direc...

Done in 65a5451. Removed all backward-compat re-exports from helpers.py and xp_utils.py. All math imports now use the module-level pattern with aliases for long names (coord_trans, vector_ops, vertical_ops).

One caveat: GT4Py's DSL parser doesn't support module.func() syntax inside @gtx.field_operator / @gtx.program bodies (raises "Functions can only be called directly"). For those files, I added module-level bindings like func_name = module.func_name so the import is still from icon4py.model.common.math import module, but the GT4Py operator body uses the direct name.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• releases.astral.sh
  • Triggering command: /home/REDACTED/.local/bin/uv uv sync --extra testing --group test --no-install-package dace (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[jcanton]

@copilot please revert the edits in modules that only use imports for gt4py programs/field operators: the direct imports were cleaner in those files.

[Copilot]

@copilot please revert the edits in modules that only use imports for gt4py programs/field operators: the direct imports were cleaner in those files.

Done in 912fad7. Reverted all GT4Py-only files to direct imports (from icon4py.model.common.math.module import func). This affects 10 files: diffusion_utils.py, compute_cell_diagnostics_for_dycore.py, compute_horizontal_advection_of_rho_and_theta.py, geometry_stencils.py, metric_fields.py, coordinate_transformations.py, distance.py, and the 3 stencil files. Files with regular Python usage keep the module-level import pattern.