Mixins for private Grid helpers (coordinates, connectivity, validation, …)

[Sevans711]

Proposed new feature or change:

Proposing to lean in further to object oriented programming for the private API, as I noticed many helper methods like def _helper(grid): ... throughout various files in the grid subpackage. I am working on #1305 which will require more methods with that pattern, and I'm wondering if it makes sense to switch to this pattern first?

Before:

# --- in grid.py --- #
from uxarray.grid.coordinates import (
    _populate_edge_centroids,
    _populate_face_centerpoints,
    _populate_face_centroids,
    _populate_node_latlon,
    _populate_node_xyz,
    _set_desired_longitude_range,
    points_atleast_2d_xyz,
    prepare_points,
)
from uxarray.grid.validation import (
    _check_area,
    _check_connectivity,
    _check_duplicate_nodes,
    _check_duplicate_nodes_indices,
    _check_normalization,
)

class Grid:
    # example method that will be affected by this change:
    def validate(self, check_duplicates=True):
        checkDN = _check_duplicate_nodes(self) if check_duplicates else True
        check_C = _check_connectivity(self)
        check_A = _check_area(self)

        if checkDN and check_C and check_A:
            return True
        else:
            raise RuntimeError("Mesh validation failed.")

# --- in validation.py --- #
def _check_connectivity(grid): ...
def _check_duplicate_nodes(grid): ...
def _check_duplicate_nodes_indices(grid): ...
def _check_area(grid): ...
def _find_duplicate_nodes(grid): ...
def _check_normalization(grid): ...

# --- in coordinates.py --- #
def _populate_edge_centroids(grid, repopulate=False): ...
def _populate_face_centerpoints(grid, repopulate=False): ...
def _populate_face_centroids(grid, repopulate=False): ...
def _populate_node_latlon(grid): ...
def _populate_node_xyz(grid): ...
def _set_desired_longitude_range(grid): ...
def points_atleast_2d_xyz(points, normalize): ...
def prepare_points(points): ...

After:

# --- in grid.py --- #
from uxarray.grid.coordinates import (
    GridCoordinatesMixin,  # private methods got grouped
    points_atleast_2d_xyz,  # public methods remain the same
    prepare_points,
)
from uxarray.grid.validation import GridValidationMixin

class Grid(GridCoordinatesMixin, GridValidationMixin):
    # example method that will be affected by this change:
    def validate(self, check_duplicates=True):
        checkDN = self._check_duplicate_nodes() if check_duplicates else True
        check_C = self._check_connectivity()
        check_A = self._check_area()

        if checkDN and check_C and check_A:
            return True
        else:
            raise RuntimeError("Mesh validation failed.")

# --- in validation.py --- #
class GridValidationMixin:
    def _check_connectivity(self): ...
    def _check_duplicate_nodes(self): ...
    def _check_duplicate_nodes_indices(self): ...
    def _check_area(self): ...
    def _find_duplicate_nodes(self): ...
    def _check_normalization(self): ...

# --- in coordinates.py --- #
class GridCoordinatesMixin:   # private methods get grouped
    def _populate_edge_centroids(self, repopulate=False): ...
    def _populate_face_centerpoints(self, repopulate=False): ...
    def _populate_face_centroids(self, repopulate=False): ...
    def _populate_node_latlon(self): ...
    def _populate_node_xyz(self): ...
    def _set_desired_longitude_range(self): ...
# public methods remain the same
def points_atleast_2d_xyz(points, normalize): ...
def prepare_points(points): ...

Note that this is just a mechanical rename of grouping, not a broader reorganization or refactor. There will be no behavioral changes, no new files, and no new conceptual groupings to review. The only change to public API will be that Grid now inherits from mixins, instead of having no inheritance at all.

What are the main benefits? This is mostly cosmetic/ergonomic. May improve discoverability of private methods for super users. May help slightly with debugging, e.g., can call mygrid._check_area() instead of the more verbose: from uxarray.grid.validation import _check_area; _check_area(mygrid). May help slightly with maintainability as uxarray expands to include more methods, as private helper methods can be accessed directly from self instead of needing to import at top of file.