Reorganize math module into meaningful submodules

model/common/src/icon4py/model/common/grid/geometry.py

@@ -29,7 +29,11 @@
     horizontal as h_grid,
     icon,
 )
-from icon4py.model.common.math import helpers as math_helpers, xp_utils
+from icon4py.model.common.math import (
+    coordinate_transformations as coord_trans,
+    math_utils,
+    vector_operations as vector_ops,
+)
 from icon4py.model.common.states import factory, model, utils as state_utils
 from icon4py.model.common.utils import data_allocation as data_alloc, device_utils
 
@@ -187,7 +191,7 @@ def _inverse_field_provider(self, field_name: str) -> factory.FieldProvider:
         name = meta["standard_name"]
         self._attrs.update({name: meta})
         provider = factory.ProgramFieldProvider(
-            func=math_helpers.compute_inverse_on_edges,
+            func=vector_ops.compute_inverse_on_edges,
             deps={"f": field_name},
             fields={"f_inverse": name},
             domain={
@@ -367,7 +371,7 @@ def _register_computed_fields(self) -> None:
         self.register_provider(mean_dual_cell_area_np)
 
         characteristic_length_np = factory.NumpyDataProvider(
-            func=xp_utils.compute_sqrt,
+            func=math_utils.compute_sqrt,
             domain=(),
             deps={
                 "input_val": attrs.MEAN_DUAL_AREA,
@@ -408,7 +412,7 @@ def _register_normals_and_tangents_icosahedron(self) -> None:
 
         # 2. primal_normals: gridfile%zonal_normal_primal_edge - edges%primal_normal%v1, gridfile%meridional_normal_primal_edge - edges%primal_normal%v2,
         normal_uv = factory.ProgramFieldProvider(
-            func=math_helpers.compute_zonal_and_meridional_components_on_edges,
+            func=coord_trans.compute_zonal_and_meridional_components_on_edges,
             deps={
                 "lat": attrs.EDGE_LAT,
                 "lon": attrs.EDGE_LON,
@@ -431,7 +435,7 @@ def _register_normals_and_tangents_icosahedron(self) -> None:
         self.register_provider(normal_uv)
 
         dual_uv = factory.ProgramFieldProvider(
-            func=math_helpers.compute_zonal_and_meridional_components_on_edges,
+            func=coord_trans.compute_zonal_and_meridional_components_on_edges,
             deps={
                 "lat": attrs.EDGE_LAT,
                 "lon": attrs.EDGE_LON,
@@ -708,7 +712,7 @@ def _register_normals_and_tangents_torus(self) -> None:
     def _register_cartesian_coordinates_icosahedron(self) -> None:
         """Register Cartesian coordinate conversions for icosahedron geometry."""
         cartesian_vertices = factory.EmbeddedFieldOperatorProvider(
-            func=math_helpers.geographical_to_cartesian_on_vertices.with_backend(self.backend),
+            func=coord_trans.geographical_to_cartesian_on_vertices.with_backend(self.backend),
             domain={
                 dims.VertexDim: (
                     h_grid.vertex_domain(h_grid.Zone.LOCAL),
@@ -728,7 +732,7 @@ def _register_cartesian_coordinates_icosahedron(self) -> None:
         )
         self.register_provider(cartesian_vertices)
         cartesian_edge_centers = factory.EmbeddedFieldOperatorProvider(
-            func=math_helpers.geographical_to_cartesian_on_edges.with_backend(self.backend),
+            func=coord_trans.geographical_to_cartesian_on_edges.with_backend(self.backend),
             domain={
                 dims.EdgeDim: (
                     h_grid.edge_domain(h_grid.Zone.LOCAL),
@@ -748,7 +752,7 @@ def _register_cartesian_coordinates_icosahedron(self) -> None:
         )
         self.register_provider(cartesian_edge_centers)
         cartesian_cell_centers = factory.EmbeddedFieldOperatorProvider(
-            func=math_helpers.geographical_to_cartesian_on_cells.with_backend(self.backend),
+            func=coord_trans.geographical_to_cartesian_on_cells.with_backend(self.backend),
             domain={
                 dims.CellDim: (
                     h_grid.cell_domain(h_grid.Zone.LOCAL),

model/common/src/icon4py/model/common/grid/geometry_stencils.py

@@ -15,15 +15,19 @@
 
 from icon4py.model.common import dimension as dims, field_type_aliases as fa, type_alias as ta
 from icon4py.model.common.dimension import E2C, E2C2V, E2V, EdgeDim
-from icon4py.model.common.math.helpers import (
+from icon4py.model.common.math.coordinate_transformations import (
+    geographical_to_cartesian_on_edges,
+    geographical_to_cartesian_on_vertices,
+    zonal_and_meridional_components_on_edges,
+)
+from icon4py.model.common.math.distance import (
     arc_length_on_edges,
-    cross_product_on_edges,
     diff_on_edges_torus,
     distance_on_edges_torus,
-    geographical_to_cartesian_on_edges,
-    geographical_to_cartesian_on_vertices,
+)
+from icon4py.model.common.math.vector_operations import (
+    cross_product_on_edges,
     normalize_cartesian_vector_on_edges,
-    zonal_and_meridional_components_on_edges,
 )
 from icon4py.model.common.utils import data_allocation as data_alloc
 

model/common/src/icon4py/model/common/interpolation/interpolation_fields.py

@@ -17,14 +17,13 @@
 from gt4py.next import where
 
 import icon4py.model.common.field_type_aliases as fa
-import icon4py.model.common.math.projection as proj
 import icon4py.model.common.type_alias as ta
 from icon4py.model.common import dimension as dims
 from icon4py.model.common.decomposition import definitions as decomposition
 from icon4py.model.common.dimension import C2E, V2E
 from icon4py.model.common.grid import base as base_grid, gridfile
 from icon4py.model.common.grid.geometry_stencils import compute_primal_cart_normal
-from icon4py.model.common.math.projection import diff_on_edges_torus_numpy, gnomonic_proj
+from icon4py.model.common.math import projection
 from icon4py.model.common.utils import data_allocation as data_alloc
 
 
@@ -1057,10 +1056,10 @@ def compute_pos_on_tplane_e_x_y(
     pos_on_tplane_e_y = array_ns.zeros(e2c.shape)
     xyloc_plane_n1 = array_ns.zeros([2, e2c.shape[0]])
     xyloc_plane_n2 = array_ns.zeros([2, e2c.shape[0]])
-    xyloc_plane_n1[0, llb:], xyloc_plane_n1[1, llb:] = proj.gnomonic_proj(
+    xyloc_plane_n1[0, llb:], xyloc_plane_n1[1, llb:] = projection.gnomonic_proj(
         edges_lon[llb:], edges_lat[llb:], cells_lon[e2c[llb:, 0]], cells_lat[e2c[llb:, 0]]
     )
-    xyloc_plane_n2[0, llb:], xyloc_plane_n2[1, llb:] = proj.gnomonic_proj(
+    xyloc_plane_n2[0, llb:], xyloc_plane_n2[1, llb:] = projection.gnomonic_proj(
         edges_lon[llb:], edges_lat[llb:], cells_lon[e2c[llb:, 1]], cells_lat[e2c[llb:, 1]]
     )
 
@@ -1236,7 +1235,7 @@ def compute_lsq_coeffs(
         case base_grid.GeometryType.ICOSAHEDRON:
             for js in range(lsq_dim_stencil):
                 z_dist_g[:, js, :] = array_ns.asarray(
-                    gnomonic_proj(
+                    projection.gnomonic_proj(
                         cell_lon,
                         cell_lat,
                         cell_lon[c2e2c[:, js]],
@@ -1259,7 +1258,7 @@ def compute_lsq_coeffs(
                 cc_cv = array_ns.asarray((cell_center_x[jc], cell_center_y[jc]))
                 for js in range(lsq_dim_stencil):
                     cc_cell[js, :] = array_ns.asarray(
-                        diff_on_edges_torus_numpy(
+                        projection.diff_on_edges_torus_numpy(
                             cell_center_x[jc],
                             cell_center_y[jc],
                             cell_center_x[ilc_s][js],

model/common/src/icon4py/model/common/math/__init__.py

@@ -5,3 +5,23 @@
 #
 # Please, refer to the LICENSE file in the root directory.
 # SPDX-License-Identifier: BSD-3-Clause
+
+"""
+Mathematical operations for ICON grid computations.
+
+This package provides mathematical operations organized into the following submodules:
+
+- ``coordinate_transformations``: Conversions between geographical (lat/lon) and cartesian
+  coordinates, and between zonal/meridional and cartesian vector components.
+- ``derivative``: Vertical derivative computations at cell centers.
+- ``distance``: Arc length on spheres and distance/difference operations on torus geometries.
+- ``gradient``: Finite difference gradient operators (normal and tangential).
+- ``math_utils``: General-purpose mathematical utility functions (typed sqrt, etc.).
+- ``operators``: Laplacian (nabla²) and difference operators on cell fields.
+- ``projection``: Gnomonic projection and NumPy-based torus operations.
+- ``smagorinsky``: Smagorinsky diffusion enhancement factor computation.
+- ``vector_operations``: Dot product, cross product, norms, normalization and inversion
+  of vectors on cell, edge and vertex fields.
+- ``vertical_operations``: Averaging and differencing of adjacent vertical levels.
+- ``stencils``: GT4Py program wrappers for operators with domain control.
+"""