Face area documentation is confusing / wrong #1567

Version

v2026.6.0

How did you install UXarray?

Source

What happened?

Face area calculations currently do not depend on kwargs as promised in the docstring of Grid.calculate_total_face_area(). Also, are face areas returned in meters^2 or in steradians? On the unit sphere these are the same, but I haven't yet checked what happens when the grid.sphere_radius is not 1. Either way, it would help to clarify in the docstring, and maybe add a test for this unless one is already present.

The kwargs issue shows up also on the Face Area Calculations docs page (https://uxarray.readthedocs.io/en/latest/user-guide/area_calc.html), where section 2 claims to use a different method for computing areas, and that "For the result above, notice that the area is slightly different than the first calculation we made." However, the result above is not different than the first calculation at all.

Inspecting the code itself reveals:

# --- in grid.py --- #
class Grid:
    def calculate_total_face_area(
        self,
        quadrature_rule: str | None = "triangular",
        order: int | None = 4,
        latitude_adjusted_area: bool | None = False,
    ) -> float:
        """Function to calculate the total surface area of all the faces in a
        mesh.

        Parameters
        ----------
        quadrature_rule : str, optional
            Quadrature rule to use. Defaults to "triangular".
        order : int, optional
            Order of quadrature rule. Defaults to 4.
        latitude_adjusted_area : bool, optional
            If True, corrects the area of the faces accounting for lines of constant lattitude. Defaults to False.

        Returns
        -------
        Sum of area of all the faces in the mesh : float
        """

        return np.sum(self.face_areas.values)

This does not appear to incorporate the kwargs as promised.

What did you expect to happen?

I expected calculate_total_face_area() to respect the quadrature_rule and order kwargs as promised, probably giving different results with different values of those kwargs. However, the code does not appear to utilize those kwargs at all in any way, and I got the same results when I varied them in a small test case.

Can you provide a MCVE to repoduce the bug?