Add area and area_equivalent_radius to all three ellipsoid classes

.github/workflows/test.yml

@@ -38,11 +38,11 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu, macos, windows]
-        python: ["3.7", "3.11"]
+        python: ["3.8", "3.12"]
         include:
-          - python: "3.7"
+          - python: "3.8"
             dependencies: oldest
-          - python: "3.11"
+          - python: "3.12"
             dependencies: latest
     env:
       REQUIREMENTS: env/requirements-build.txt env/requirements-test.txt

AUTHORS.md

@@ -10,3 +10,4 @@ order by last name) and are considered "The Boule Developers":
 * [Agustina Pesce](https://github.com/aguspesce) - Unaffiliated (ORCID: [0000-0002-5538-8845](https://orcid.org//0000-0002-5538-8845))
 * [Santiago Soler](https://github.com/santisoler) - CONICET, Argentina; Instituto Geofísico Sismológico Volponi, Universidad Nacional de San Juan, Argentina (ORCID: [0000-0001-9202-5317](https://www.orcid.org/0000-0001-9202-5317))
 * [Leonardo Uieda](https://github.com/leouieda) - Universidade de São Paulo, Brazil (ORCID: 0000-0001-6123-9515)
+* [Mark Wieczorek](https://github.com/MarkWieczorek) - Institut de physique du globe de Paris, France (ORCID: [0000-0001-7007-4222](https://orcid.org/0000-0001-7007-4222))

boule/_ellipsoid.py

@@ -111,6 +111,10 @@ class Ellipsoid:
     5513 kg/m³
     >>> print(f"{ellipsoid.volume * 1e-9:.5e} km³")
     1.08321e+12 km³
+    >>> print(f"{ellipsoid.area:.10e} m²")
+    5.1006562172e+14 m²
+    >>> print(f"{ellipsoid.area_equivalent_radius:0.4f} m")
+    6371007.1809 m
     >>> print(f"{ellipsoid.gravity_equator:.10f} m/s²")
     9.7803253359 m/s²
     >>> print(f"{ellipsoid.gravity_pole:.10f} m/s²")
@@ -227,6 +231,27 @@ def mean_radius(self):
         """
         return 1 / 3 * (2 * self.semimajor_axis + self.semiminor_axis)
 
+    @property
+    def area(self):
+        r"""
+        The area of the ellipsoid.
+        Definition: :math:`A = 2 \pi a^2 \left(1 + \dfrac{b^2}{e a^2}
+        \arctanh{e} \right)`.
+        Units: :math:`m^2`.
+        """
+        # see https://en.wikipedia.org/wiki/Ellipsoid#Surface_area
+        return (
+            2
+            * np.pi
+            * self.semimajor_axis**2
+            * (
+                1
+                + (self.semiminor_axis / self.semimajor_axis) ** 2
+                / self.first_eccentricity
+                * np.arctanh(self.first_eccentricity)
+            )
+        )
+
     @property
     def volume(self):
         r"""
@@ -236,6 +261,15 @@ def volume(self):
         """
         return (4 / 3 * np.pi) * self.semimajor_axis**2 * self.semiminor_axis
 
+    @property
+    def area_equivalent_radius(self):
+        r"""
+        The area equivalent radius of the ellipsoid.
+        Definition: :math:`R_2 = \sqrt{A / (4 \pi)}`.
+        Units: :math:`m`.
+        """
+        return np.sqrt(self.area / (4 * np.pi))
+
     @property
     def mass(self):
         r"""
@@ -261,7 +295,7 @@ def volume_equivalent_radius(self):
         Definition: :math:`R_3 = \left(\dfrac{3}{4 \pi} V \right)^{1/3}`.
         Units: :math:`m`.
         """
-        return (self.volume * 3 / 4 / np.pi) ** (1 / 3)
+        return (self.volume * 3 / (4 * np.pi)) ** (1 / 3)
 
     @property
     def _emm(self):

boule/_sphere.py

@@ -103,6 +103,10 @@ class Sphere:
     1.0 m
     >>> print(f"{sphere.volume:.10f} m³")
     4.1887902048 m³
+    >>> print(f"{sphere.area:.10f} m²")
+    12.5663706144 m²
+    >>> print(sphere.area_equivalent_radius)
+    1
     >>> print(f"{sphere.mass:.12e} kg")
     2.996568928577e+10 kg
     >>> print(f"{sphere.mean_density:.0f} kg/m³")
@@ -184,6 +188,15 @@ def first_eccentricity(self):
         """
         return 0
 
+    @property
+    def area(self):
+        r"""
+        The area of the sphere.
+        Definition: :math:`A = 4 \pi r^2`.
+        Units: :math:`m^2`.
+        """
+        return 4 * np.pi * self.radius**2
+
     @property
     def volume(self):
         r"""
@@ -193,6 +206,15 @@ def volume(self):
         """
         return (4 / 3 * np.pi) * self.radius**3
 
+    @property
+    def area_equivalent_radius(self):
+        """
+        The area equivalent radius of the sphere is equal to its radius.
+        Definition: :math:`R_2 = R`.
+        Units: :math:`m`.
+        """
+        return self.radius
+
     @property
     def mass(self):
         r"""

boule/_triaxialellipsoid.py

@@ -11,6 +11,7 @@
 
 import attr
 import numpy as np
+from scipy.special import elliprd, elliprf
 
 from ._constants import G
 
@@ -100,6 +101,10 @@ class TriaxialEllipsoid:
 
     >>> print(f"{ellipsoid.mean_radius:.0f} m")
     262700 m
+    >>> print(f"{ellipsoid.area:.10e} m²")
+    8.6562393883e+11 m²
+    >>> print(f"{ellipsoid.area_equivalent_radius:0.0f} m")
+    262458 m
     >>> print(f"{ellipsoid.volume_equivalent_radius:.0f} m")
     261115 m
     >>> print(f"{ellipsoid.mass:.10e} kg")
@@ -179,6 +184,25 @@ def mean_radius(self):
         """
         return (self.semimajor_axis + self.semimedium_axis + self.semiminor_axis) / 3
 
+    @property
+    def area(self):
+        r"""
+        The area of the ellipsoid.
+        Definition: :math:`A`.
+        Units: :math:`m^2`.
+        """
+        # see https://en.wikipedia.org/wiki/Ellipsoid#Surface_area
+        a = self.semimajor_axis
+        b = self.semimedium_axis
+        c = self.semiminor_axis
+        return 2 * np.pi * c**2 + 2 * np.pi * a * b * (
+            elliprf((c / a) ** 2, (c / b) ** 2, 1)
+            - (1 / 3)
+            * (1 - (c / a) ** 2)
+            * (1 - (c / b) ** 2)
+            * elliprd((c / a) ** 2, (c / b) ** 2, 1)
+        )
+
     @property
     def volume(self):
         r"""
@@ -193,6 +217,15 @@ def volume(self):
             * self.semiminor_axis
         )
 
+    @property
+    def area_equivalent_radius(self):
+        r"""
+        The area equivalent radius of the ellipsoid.
+        Definition: :math:`R_2 = \sqrt{A / (4 \pi)}`.
+        Units: :math:`m`.
+        """
+        return np.sqrt(self.area / (4 * np.pi))
+
     @property
     def mass(self):
         r"""
@@ -218,7 +251,7 @@ def volume_equivalent_radius(self):
         Definition: :math:`R_3 = \left(\dfrac{3}{4 \pi} V \right)^{1/3}`.
         Units: :math:`m`.
         """
-        return (self.volume * 3 / 4 / np.pi) ** (1 / 3)
+        return (self.volume * 3 / (4 * np.pi)) ** (1 / 3)
 
     @property
     def equatorial_flattening(self):

env/requirements-test.txt

@@ -3,3 +3,4 @@ pytest
 pytest-cov
 coverage
 pymap3d>=2.9.0
+scipy

environment.yml

@@ -9,6 +9,7 @@ dependencies:
   # Run
   - numpy
   - attrs
+  - scipy
   # Build
   - build
   - twine