pygeodesy 24.11.11__py2.py3-none-any.whl → 25.1.5__py2.py3-none-any.whl

pygeodesy/utily.py

@@ -3,45 +3,52 @@
 
 u'''Various utility functions.
 
-After I{(C) Chris Veness 2011-2024} published under the same MIT Licence**, see
-U{Latitude/Longitude<https://www.Movable-Type.co.UK/scripts/latlong.html>} and
-U{Vector-based geodesy<https://www.Movable-Type.co.UK/scripts/latlong-vectors.html>}.
+After I{Karney}'s C++ U{Math<https://GeographicLib.SourceForge.io/C++/doc/classGeographicLib_1_1Math.html>}
+class and I{Veness}' U{Latitude/Longitude<https://www.Movable-Type.co.UK/scripts/latlong.html>}
+and U{Vector-based geodesy<https://www.Movable-Type.co.UK/scripts/latlong-vectors.html>}
+and published under the same MIT Licence**.
 '''
 # make sure int/int division yields float quotient, see .basics
 from __future__ import division as _; del _  # PYCHOK semicolon
 
-from pygeodesy.basics import _copysign, isinstanceof, isint, isstr, neg
+from pygeodesy.basics import _copysign, isinstanceof, isint, isstr
 from pygeodesy.constants import EPS, EPS0, INF, NAN, PI, PI2, PI_2, R_M, \
-                               _M_KM, _M_NM, _M_SM, _0_0, _1__90, _0_5, _1_0, \
-                               _N_1_0, _2__PI, _10_0, _90_0, _N_90_0, _180_0, \
-                               _N_180_0, _360_0, _400_0, _copysign_0_0, \
-                               _float as _F, _isfinite, isnan, isnear0, \
+                               _M_KM, _M_NM, _M_SM, _0_0, _1__90, _0_5, _2__PI, \
+                               _1_0, _N_1_0, _10_0, _90_0, _180_0, _360_0, \
+                               _copysign_0_0, _float, _isfinite, isnan, isnear0, \
                                _over, _umod_360, _umod_PI2
-from pygeodesy.errors import _ValueError, _xkwds, _xkwds_get1,  _ALL_LAZY, _MODS
-from pygeodesy.internals import _passargs  # , _MODS?
+from pygeodesy.errors import _ValueError, _xkwds,  _ALL_LAZY, _MODS
+from pygeodesy.internals import _passargs
 from pygeodesy.interns import _edge_, _radians_, _semi_circular_, _SPACE_
 # from pygeodesy.lazily import _ALL_LAZY, _ALL_MODS as _MODS  # from .errors
 from pygeodesy.units import Degrees, Degrees_, Feet, Float, Lam, Lamd, \
-                            Meter, Meter2, Radians, Radians_
+                            Meter, Meter2, Radians  # Radians_
 
-from math import acos, asin, atan2, cos, degrees, fabs, radians, sin, tan  # pow
+from math import acos, asin, atan2 as _atan2, cos, degrees, fabs, radians, \
+                 sin, tan as _tan  # pow
 
 __all__ = _ALL_LAZY.utily
-__version__ = '24.10.12'
-
-# read constant name "_M_Unit" as "meter per Unit"
-_M_CHAIN     = _F(  20.1168)     # yard2m(1) * 22
-_M_FATHOM    = _F(   1.8288)     # yard2m(1) * 2 or _M_NM * 1e-3
-_M_FOOT      = _F(   0.3048)     # Int'l (1 / 3.2808398950131 = 10_000 / (254 * 12))
-_M_FOOT_GE   = _F(   0.31608)    # German Fuss (1 / 3.1637560111364)
-_M_FOOT_FR   = _F(   0.3248406)  # French Pied-du-Roi or pied (1 / 3.0784329298739)
-_M_FOOT_USVY = _F(   0.3048006096012192)  # US Survey (1200 / 3937)
-_M_FURLONG   = _F( 201.168)      # 220 * yard2m(1) == 10 * m2chain(1)
-# _M_KM      = _F(1000.0)        # kilo meter
-# _M_NM      = _F(1852.0)        # nautical mile
-# _M_SM      = _F(1609.344)      # statute mile
-_M_TOISE     = _F(   1.9490436)  # French toise, 6 pieds (6 / 3.0784329298739)
-_M_YARD_UK   = _F(   0.9144)     # 254 * 12 * 3 / 10_000 == 3 * ft2m(1) Int'l
+__version__ = '25.01.05'
+
+_G_DEG     = _float(  400.0 / _360_0)  # grades per degree
+_G_RAD     = _float(  400.0 /  PI2)    # grades per radian
+_M_ACRE    = _float( 4046.8564224)     # square meter per acre, chain2m(1) * furlong2m(1)
+_M_CHAIN   = _float(   20.1168)        # meter per yard2m(1) * 22
+_M_FATHOM  = _float(    1.8288)        # meter per yard2m(1) * 2 or _M_NM * 1e-3
+_M_FOOT    = _float(    0.3048)        # meter per Int'l foot, 1 / 3.280_839_895_0131 = 10_000 / (254 * 12)
+_M_FOOT_GE = _float(    0.31608)       # meter per German Fuss, 1 / 3.163_756_011_1364
+_M_FOOT_FR = _float(    0.3248406)     # meter per French Pied-du-Roi or pied, 1 / 3.078_432_929_8739
+_M_FOOT_US = _float(    0.3048006096012192)  # meter per US Survey foot, 1_200 / 3_937
+_M_FURLONG = _float(  201.168)         # meter per furlong, 220 * yard2m(1) = 10 * m2chain(1)
+_M_HA      = _float(10000.0)           # square meter per hectare, 100 * 100
+# _M_KM    = _float( 1000.0)           # meter per kilo meter
+# _M_NM    = _float( 1852.0)           # meter per nautical mile
+# _M_SM    = _float( 1609.344)         # meter per statute mile
+_M_TOISE   = _float(    1.9490436)     # meter per French toise, 6 pieds = 6 / 3.078_432_929_8739
+_M_YARD_UK = _float(    0.9144)        # meter per yard, 254 * 12 * 3 / 10_000 = 3 * _M_FOOT
+# sqrt(3) <https://WikiPedia.org/wiki/Square_root_of_3>
+_COS_30,  _SIN_30 = 0.86602540378443864676, _0_5  # sqrt(3) / 2
+_COS_45 = _SIN_45 = 0.70710678118654752440  # sqrt(2) / 2
 
 
 def _abs1nan(x):
@@ -65,8 +72,7 @@ def acre2ha(acres):
 
        @raise ValueError: Invalid B{C{acres}}.
     '''
-    # 0.40468564224 == acre2m2(1) / 10_000
-    return Float(ha=Float(acres) * 0.40468564224)
+    return m2ha(acre2m2(acres))
 
 
 def acre2m2(acres):
@@ -78,8 +84,7 @@ def acre2m2(acres):
 
        @raise ValueError: Invalid B{C{acres}}.
     '''
-    # 4046.8564224 == chain2m(1) * furlong2m(1)
-    return Meter2(Float(acres) * 4046.8564224)
+    return Meter2(Float(acres=acres) * _M_ACRE)
 
 
 def asin1(x):
@@ -92,7 +97,7 @@ def atan1(y, x=_1_0):
     '''Return C{atan(B{y} / B{x})} angle in C{radians} M{[-PI/2..+PI/2]}
        using C{atan2} for consistency and to avoid C{ZeroDivisionError}.
     '''
-    return atan2(-y, -x) if x < 0 else atan2(y, x or _0_0)  # -0. to 0.
+    return _atan1u(y, x, atan2)
 
 
 def atan1d(y, x=_1_0):
@@ -101,18 +106,35 @@ def atan1d(y, x=_1_0):
 
        @see: Function L{pygeodesy.atan2d}.
     '''
-    return atan2d(-y, -x) if x < 0 else atan2d(y, x or _0_0)  # -0. to 0.
+    return _atan1u(y, x, atan2d)
+
+
+def _atan1u(y, x, _2u):
+    '''(INTERNAL) Helper for functions C{atan1} and C{atan1d}.
+    '''
+    if x < 0:
+        x = -x
+        y = -y
+    return _2u(y, x or _0_0)
+
+
+atan2 = _atan2
+'''Return C{atan2(B{y}, B{x})} in radians M{[-PI..+PI]}.
+
+   @see: I{Karney}'s C++ function U{Math.atan2d
+         <https://GeographicLib.SourceForge.io/C++/doc/classGeographicLib_1_1Math.html>}.
+'''
 
 
 def atan2b(y, x):
-    '''Return C{atan2(B{y}, B{x})} in degrees M{[0..+360]}.
+    '''Return C{atan2(B{y}, B{x})} in degrees M{[0..+360], counter-clockwise}.
 
        @see: Function L{pygeodesy.atan2d}.
     '''
     b = atan2d(y, x)
     if b < 0:
         b += _360_0
-    return b
+    return b or _0_0  # unsigned-0
 
 
 def atan2d(y, x, reverse=False):
@@ -122,29 +144,14 @@ def atan2d(y, x, reverse=False):
        @see: I{Karney}'s C++ function U{Math.atan2d
              <https://GeographicLib.SourceForge.io/C++/doc/classGeographicLib_1_1Math.html>}.
     '''
-    if fabs(y) > fabs(x) > 0:
-        if y < 0:  # q = 3
-            d = degrees(atan2(x, -y)) - _90_0
-        else:  # q = 2
-            d = _90_0 - degrees(atan2(x, y))
-    elif isnan(x) or isnan(y):
-        return NAN
-    elif y:
-        if x > 0:  # q = 0
-            d =  degrees(atan2(y, x))
-        elif x < 0:  # q = 1
-            d = _copysign(_180_0, y) - degrees(atan2(y, -x))
-        else:  # x == 0
-            d = _copysign(_90_0, y)
-    else:
-        d = _180_0 if x < 0 else _0_0
+    d = degrees(_atan2(y, x))  # preserves signed-0
     return _azireversed(d) if reverse else d
 
 
-def _azireversed(azimuth):  # in .rhumbBase
-    '''(INTERNAL) Return the I{reverse} B{C{azimuth}} in degrees M{[-180..+180]}.
+def _azireversed(azi):  # in .rhumbBase
+    '''(INTERNAL) Return the I{reverse} B{C{azi}} in degrees M{[-180..+180]}.
     '''
-    return azimuth + (_N_180_0 if azimuth > 0 else _180_0)
+    return azi - _copysign(_180_0, azi)
 
 
 def chain2m(chains):
@@ -162,13 +169,11 @@ def chain2m(chains):
 def circle4(earth, lat):
     '''Get the equatorial or a parallel I{circle of latitude}.
 
-       @arg earth: The earth radius, ellipsoid or datum
-                   (C{meter}, L{Ellipsoid}, L{Ellipsoid2},
-                   L{Datum} or L{a_f2Tuple}).
+       @arg earth: The earth radius (C{meter}), ellipsoid or datum
+                   (L{Ellipsoid}, L{Ellipsoid2}, L{Datum} or L{a_f2Tuple}).
        @arg lat: Geodetic latitude (C{degrees90}, C{str}).
 
-       @return: A L{Circle4Tuple}C{(radius, height, lat, beta)}
-                instance.
+       @return: A L{Circle4Tuple}C{(radius, height, lat, beta)}.
 
        @raise RangeError: Latitude B{C{lat}} outside valid range and
                           L{rangerrors<pygeodesy.rangerrors>} is C{True}.
@@ -181,76 +186,78 @@ def circle4(earth, lat):
     return E.circle4(lat)
 
 
-def cot(rad, **error_kwds):
+def cot(rad, **raiser_kwds):
     '''Return the C{cotangent} of an angle in C{radians}.
 
        @arg rad: Angle (C{radians}).
-       @kwarg error_kwds: Error to raise (C{ValueError}).
+       @kwarg raiser_kwds: Use C{B{raiser}=False} to avoid
+                     ValueErrors or optionally, additional
+                     ValueError keyword argments.
 
        @return: C{cot(B{rad})}.
 
-       @raise ValueError: L{pygeodesy.isnear0}C{(sin(B{rad})}.
+       @raise Error: If L{pygeodesy.isnear0}C{(sin(B{rad})}.
     '''
-    s, c = sincos2(rad)
-    if c:
-        if isnear0(s):
-            raise _valueError(cot, rad, **error_kwds)
-        c = c / s  # /= chokes PyChecker
-    return c
+    try:
+        return _cotu(*sincos2(rad), **raiser_kwds)
+    except ZeroDivisionError:
+        raise _valueError(cot, rad, **raiser_kwds)
 
 
-def cot_(*rads, **error_kwds):
-    '''Return the C{cotangent} of angle(s) in C{radiansresection}.
+def cot_(*rads, **raiser_kwds):
+    '''Yield the C{cotangent} of angle(s) in C{radians}.
 
-       @arg rads: One or more angles (C{radians}).
-       @kwarg error_kwds: Error to raise (C{ValueError}).
+       @arg rads: One or more angles (each in C{radians}).
 
-       @return: Yield the C{cot(B{rad})} for each angle.
+       @return: Yield C{cot(B{rad})} for each angle.
 
-       @raise ValueError: See L{pygeodesy.cot}.
+       @see: Function L{pygeodesy.cot} for further details.
     '''
     try:
         for r in rads:
-            yield cot(r)
-    except ValueError:
-        raise _valueError(cot_, r, **error_kwds)
+            yield _cotu(*sincos2(r), **raiser_kwds)
+    except ZeroDivisionError:
+        raise _valueError(cot_, r, **raiser_kwds)
 
 
-def cotd(deg, **error_kwds):
+def cotd(deg, **raiser_kwds):
     '''Return the C{cotangent} of an angle in C{degrees}.
 
        @arg deg: Angle (C{degrees}).
-       @kwarg error_kwds: Error to raise (C{ValueError}).
+       @kwarg raiser_kwds: Use C{B{raiser}=False} to avoid
+                     ValueErrors or optionally, additional
+                     ValueError keyword argments.
 
        @return: C{cot(B{deg})}.
 
-       @raise ValueError: L{pygeodesy.isnear0}C{(sin(B{deg})}.
+       @raise Error: If L{pygeodesy.isnear0}C{(sin(B{deg})}.
     '''
-    s, c = sincos2d(deg)
-    if c:
-        if isnear0(s):
-            raise _valueError(cotd, deg, **error_kwds)
-        c = c / s  # /= chokes PyChecker
-    elif s < 0:
-        c = -c  # negate-0
-    return c
+    try:
+        return _cotu(*sincos2d(deg), **raiser_kwds)
+    except ZeroDivisionError:
+        raise _valueError(cotd, deg, **raiser_kwds)
 
 
-def cotd_(*degs, **error_kwds):
-    '''Return the C{cotangent} of angle(s) in C{degrees}.
+def cotd_(*degs, **raiser_kwds):
+    '''Yield the C{cotangent} of angle(s) in C{degrees}.
 
-       @arg degs: One or more angles (C{degrees}).
-       @kwarg error_kwds: Error to raise (C{ValueError}).
+       @arg degs: One or more angles (each in C{degrees}).
 
-       @return: Yield the C{cot(B{deg})} for each angle.
+       @return: Yield C{cotd(B{deg})} for each angle.
 
-       @raise ValueError: See L{pygeodesy.cotd}.
+       @see: Function L{pygeodesy.cotd} for further details.
     '''
     try:
         for d in degs:
-            yield cotd(d)
-    except ValueError:
-        raise _valueError(cotd_, d, **error_kwds)
+            yield _cotu(*sincos2d(d), **raiser_kwds)
+    except ZeroDivisionError:
+        raise _valueError(cotd_, d, **raiser_kwds)
+
+
+def _cotu(s, c, **raiser_kwds):
+    '''(INTERNAL) Helper for functions C{cot}, C{cotd}, C{cot_} and C{cotd_}.
+    '''
+    return _tanu(c, s, **raiser_kwds)
 
 
 def degrees90(rad):
@@ -290,30 +297,27 @@ def degrees2grades(deg):
 
        @return: Angle (C{grades}).
     '''
-    return Degrees(deg) * _400_0 / _360_0
+    return Float(grades=Degrees(deg) * _G_DEG)
 
 
 def degrees2m(deg, radius=R_M, lat=0):
-    '''Convert an angle to a distance along the equator or
-       along the parallel at an other (geodetic) latitude.
+    '''Convert an angle to a distance along the equator or along a parallel
+       at (geodetic) latitude.
 
        @arg deg: The angle (C{degrees}).
-       @kwarg radius: Mean earth radius, ellipsoid or datum
-                      (C{meter}, L{Ellipsoid}, L{Ellipsoid2},
-                      L{Datum} or L{a_f2Tuple}).
+       @kwarg radius: Mean earth radius (C{meter}), an ellipsoid or datum
+                      (L{Ellipsoid}, L{Ellipsoid2}, L{Datum} or L{a_f2Tuple}).
        @kwarg lat: Parallel latitude (C{degrees90}, C{str}).
 
-       @return: Distance (C{meter}, same units as B{C{radius}}
-                or equatorial and polar radii) or C{0.0} for
-                near-polar B{C{lat}}.
+       @return: Distance (C{meter}, same units as B{C{radius}} or polar and
+                equatorial radii) or C{0.0} for near-polar B{C{lat}}.
 
        @raise RangeError: Latitude B{C{lat}} outside valid range and
                           L{rangerrors<pygeodesy.rangerrors>} is C{True}.
 
        @raise TypeError: Invalid B{C{radius}}.
 
-       @raise ValueError: Invalid B{C{deg}}, B{C{radius}} or
-                          B{C{lat}}.
+       @raise ValueError: Invalid B{C{deg}}, B{C{radius}} or B{C{lat}}.
 
        @see: Function L{radians2m} and L{m2degrees}.
     '''
@@ -349,9 +353,9 @@ def ft2m(feet, usurvey=False, pied=False, fuss=False):
 
        @raise ValueError: Invalid B{C{feet}}.
     '''
-    return Meter(Feet(feet) * (_M_FOOT_USVY if usurvey else
-                              (_M_FOOT_FR   if pied    else
-                              (_M_FOOT_GE   if fuss    else _M_FOOT))))
+    return Meter(Feet(feet) * (_M_FOOT_US if usurvey else
+                              (_M_FOOT_FR if pied    else
+                              (_M_FOOT_GE if fuss    else _M_FOOT))))
 
 
 def furlong2m(furlongs):
@@ -373,7 +377,7 @@ def grades(rad):
 
        @return: Angle (C{grades}).
     '''
-    return Float(grades=Float(rad=rad) * _400_0 / PI2)
+    return Float(grades=Radians(rad) * _G_RAD)
 
 
 def grades400(rad):
@@ -383,7 +387,7 @@ def grades400(rad):
 
        @return: Angle, wrapped (C{grades}).
     '''
-    return Float(grades400=(grades(rad) % _400_0) or _0_0)  # _umod_400
+    return Float(grades400=wrapPI2(rad) * _G_RAD)
 
 
 def grades2degrees(gon):
@@ -393,7 +397,7 @@ def grades2degrees(gon):
 
        @return: Angle (C{degrees}).
     '''
-    return Degrees(Float(gon=gon) * _360_0 / _400_0)
+    return Degrees(Float(gon=gon) / _G_DEG)
 
 
 def grades2radians(gon):
@@ -403,7 +407,41 @@ def grades2radians(gon):
 
        @return: Angle (C{radians}).
     '''
-    return Radians(Float(gon=gon) * PI2 / _400_0)
+    return Radians(Float(gon=gon) / _G_RAD)
+
+
+def ha2acre(ha):
+    '''Convert hectare to acre.
+
+       @arg ha: Value in hectare (C{scalar}).
+
+       @return: Value in acres (C{float}).
+
+       @raise ValueError: Invalid B{C{ha}}.
+    '''
+    return m2acre(ha2m2(ha))
+
+
+def ha2m2(ha):
+    '''Convert hectare to I{square} meter.
+
+       @arg ha: Value in hectare (C{scalar}).
+
+       @return: Value in C{meter^2} (C{float}).
+
+       @raise ValueError: Invalid B{C{ha}}.
+    '''
+    return Meter2(Float(ha=ha) * _M_HA)
+
+
+def hav(rad):
+    '''Return the U{haversine<https://WikiPedia.org/wiki/Haversine_formula>} of an angle.
+
+       @arg rad: Angle (C{radians}).
+
+       @return: C{sin(B{rad} / 2)**2}.
+    '''
+    return sin(rad * _0_5)**2
 
 
 def km2m(km):
@@ -424,6 +462,18 @@ def _loneg(lon):
     return _180_0 - lon
 
 
+def m2acre(meter2):
+    '''Convert I{square} meter to acres.
+
+       @arg meter2: Value in C{meter^2} (C{scalar}).
+
+       @return: Value in acres (C{float}).
+
+       @raise ValueError: Invalid B{C{meter2}}.
+    '''
+    return Float(acre=Meter2(meter2) / _M_ACRE)
+
+
 def m2chain(meter):
     '''Convert meter to I{UK} chains.
 
@@ -433,17 +483,16 @@ def m2chain(meter):
 
        @raise ValueError: Invalid B{C{meter}}.
     '''
-    return Float(chain=Meter(meter) / _M_CHAIN)  # * 0.049709695378986715
+    return Float(chain=Meter(meter) / _M_CHAIN)  # * 0.049_709_695_378_986_715
 
 
 def m2degrees(distance, radius=R_M, lat=0):
-    '''Convert a distance to an angle along the equator or
-       along the parallel at an other (geodetic) latitude.
+    '''Convert a distance to an angle along the equator or along a parallel
+       at (geodetic) latitude.
 
        @arg distance: Distance (C{meter}, same units as B{C{radius}}).
-       @kwarg radius: Mean earth radius, ellipsoid or datum (C{meter},
-                      an L{Ellipsoid}, L{Ellipsoid2}, L{Datum} or
-                      L{a_f2Tuple}).
+       @kwarg radius: Mean earth radius (C{meter}), an ellipsoid or datum
+                      (L{Ellipsoid}, L{Ellipsoid2}, L{Datum} or L{a_f2Tuple}).
        @kwarg lat: Parallel latitude (C{degrees90}, C{str}).
 
        @return: Angle (C{degrees}) or C{INF} for near-polar B{C{lat}}.
@@ -453,8 +502,7 @@ def m2degrees(distance, radius=R_M, lat=0):
 
        @raise TypeError: Invalid B{C{radius}}.
 
-       @raise ValueError: Invalid B{C{distance}}, B{C{radius}}
-                          or B{C{lat}}.
+       @raise ValueError: Invalid B{C{distance}}, B{C{radius}} or B{C{lat}}.
 
        @see: Function L{m2radians} and L{degrees2m}.
     '''
@@ -473,7 +521,7 @@ def m2fathom(meter):
        @see: Function L{m2toise}, U{Fathom<https://WikiPedia.org/wiki/Fathom>}
              and U{Klafter<https://WikiPedia.org/wiki/Klafter>}.
     '''
-    return Float(fathom=Meter(meter) / _M_FATHOM)  # * 0.546806649
+    return Float(fathom=Meter(meter) / _M_FATHOM)  # * 0.546_806_649
 
 
 def m2ft(meter, usurvey=False, pied=False, fuss=False):
@@ -490,11 +538,11 @@ def m2ft(meter, usurvey=False, pied=False, fuss=False):
 
        @raise ValueError: Invalid B{C{meter}}.
     '''
-    # * 3.2808333333333333, US Survey 3937 / 1200
-    # * 3.2808398950131235, Int'l 10_000 / (254 * 12)
-    return Float(feet=Meter(meter) / (_M_FOOT_USVY if usurvey else
-                                     (_M_FOOT_FR   if pied    else
-                                     (_M_FOOT_GE   if fuss    else _M_FOOT))))
+    # * 3.280_833_333_333_3333, US Survey 3_937 / 1_200
+    # * 3.280_839_895_013_1235, Int'l 10_000 / (254 * 12)
+    return Float(feet=Meter(meter) / (_M_FOOT_US if usurvey else
+                                     (_M_FOOT_FR if pied    else
+                                     (_M_FOOT_GE if fuss    else _M_FOOT))))
 
 
 def m2furlong(meter):
@@ -506,7 +554,19 @@ def m2furlong(meter):
 
        @raise ValueError: Invalid B{C{meter}}.
     '''
-    return Float(furlong=Meter(meter) / _M_FURLONG)  # * 0.00497096954
+    return Float(furlong=Meter(meter) / _M_FURLONG)  # * 0.004_970_969_54
+
+
+def m2ha(meter2):
+    '''Convert I{square} meter to hectare.
+
+       @arg meter2: Value in C{meter^2} (C{scalar}).
+
+       @return: Value in hectare (C{float}).
+
+       @raise ValueError: Invalid B{C{meter2}}.
+    '''
+    return Float(ha=Meter2(meter2) / _M_HA)
 
 
 def m2km(meter):
@@ -530,17 +590,16 @@ def m2NM(meter):
 
        @raise ValueError: Invalid B{C{meter}}.
     '''
-    return Float(NM=Meter(meter) / _M_NM)  # * 5.39956804e-4
+    return Float(NM=Meter(meter) / _M_NM)  # * 5.399_568_04e-4
 
 
 def m2radians(distance, radius=R_M, lat=0):
-    '''Convert a distance to an angle along the equator or along the
-       parallel at an other (geodetic) latitude.
+    '''Convert a distance to an angle along the equator or along a parallel
+       at (geodetic) latitude.
 
        @arg distance: Distance (C{meter}, same units as B{C{radius}}).
-       @kwarg radius: Mean earth radius, ellipsoid or datum (C{meter},
-                      an L{Ellipsoid}, L{Ellipsoid2}, L{Datum} or
-                      L{a_f2Tuple}).
+       @kwarg radius: Mean earth radius (C{meter}, an ellipsoid or datum
+                      (L{Ellipsoid}, L{Ellipsoid2}, L{Datum} or L{a_f2Tuple}).
        @kwarg lat: Parallel latitude (C{degrees90}, C{str}).
 
        @return: Angle (C{radians}) or C{INF} for near-polar B{C{lat}}.
@@ -550,8 +609,7 @@ def m2radians(distance, radius=R_M, lat=0):
 
        @raise TypeError: Invalid B{C{radius}}.
 
-       @raise ValueError: Invalid B{C{distance}}, B{C{radius}}
-                          or B{C{lat}}.
+       @raise ValueError: Invalid B{C{distance}}, B{C{radius}} or B{C{lat}}.
 
        @see: Function L{m2degrees} and L{radians2m}.
     '''
@@ -568,7 +626,7 @@ def m2SM(meter):
 
        @raise ValueError: Invalid B{C{meter}}.
     '''
-    return Float(SM=Meter(meter) / _M_SM)  # * 6.21369949e-4 == 1 / 1609.344
+    return Float(SM=Meter(meter) / _M_SM)  # * 6.213_699_49e-4 == 1 / 1_609.344
 
 
 def m2toise(meter):
@@ -582,7 +640,7 @@ def m2toise(meter):
 
        @see: Function L{m2fathom}.
     '''
-    return Float(toise=Meter(meter) / _M_TOISE)  # * 0.513083632632119
+    return Float(toise=Meter(meter) / _M_TOISE)  # * 0.513_083_632_632_119
 
 
 def m2yard(meter):
@@ -594,7 +652,7 @@ def m2yard(meter):
 
        @raise ValueError: Invalid B{C{meter}}.
     '''
-    return Float(yard=Meter(meter) / _M_YARD_UK)  # * 1.0936132983377078
+    return Float(yard=Meter(meter) / _M_YARD_UK)  # * 1.093_613_298_337_707_8
 
 
 def NM2m(nm):
@@ -610,26 +668,23 @@ def NM2m(nm):
 
 
 def radians2m(rad, radius=R_M, lat=0):
-    '''Convert an angle to a distance along the equator or
-       along the parallel at an other (geodetic) latitude.
+    '''Convert an angle to a distance along the equator or along a parallel
+       at (geodetic) latitude.
 
        @arg rad: The angle (C{radians}).
-       @kwarg radius: Mean earth radius, ellipsoid or datum
-                      (C{meter}, L{Ellipsoid}, L{Ellipsoid2},
-                      L{Datum} or L{a_f2Tuple}).
+       @kwarg radius: Mean earth radius (C{meter}) or an ellipsoid or datum
+                      (L{Ellipsoid}, L{Ellipsoid2}, L{Datum} or L{a_f2Tuple}).
        @kwarg lat: Parallel latitude (C{degrees90}, C{str}).
 
-       @return: Distance (C{meter}, same units as B{C{radius}}
-                or equatorial and polar radii) or C{0.0} for
-                near-polar B{C{lat}}.
+       @return: Distance (C{meter}, same units as B{C{radius}} or polar and
+                equatorial radii) or C{0.0} for near-polar B{C{lat}}.
 
        @raise RangeError: Latitude B{C{lat}} outside valid range and
                           L{rangerrors<pygeodesy.rangerrors>} is C{True}.
 
        @raise TypeError: Invalid B{C{radius}}.
 
-       @raise ValueError: Invalid B{C{rad}}, B{C{radius}} or
-                          B{C{lat}}.
+       @raise ValueError: Invalid B{C{rad}}, B{C{radius}} or B{C{lat}}.
 
        @see: Function L{degrees2m} and L{m2radians}.
     '''
@@ -673,20 +728,25 @@ def radiansPI_2(deg):
     return wrapPI_2(radians(deg))
 
 
-def _sin0cos2(q, r, sign):
-    '''(INTERNAL) 2-tuple (C{sin(r), cos(r)}) in quadrant C{0 <= B{q} <= 3}
-       and C{sin} zero I{signed} with B{C{sign}}.
+def _sin0cos2(q, r, sign, a, Q):  # Quarter turn
+    '''(INTERNAL) 2-tuple (C{sin(r), cos(r)}) in quadrant C{0 <= B{q} <= 3} and
+       C{sin} zero I{signed} with B{C{sign}}, like Karney's U{Math.sind and .cosd
+       <https://GeographicLib.SourceForge.io/C++/doc/classGeographicLib_1_1Math.html>}
     '''
     if r < PI_2:
-        s, c = sin(r), cos(r)
-        t = s, c, -s, -c, s
-    else:  # r == PI_2
-        t = _1_0, _0_0, _N_1_0, _0_0, _1_0
-#   else:  # r == 0, testUtility failures
-#       t = _0_0, _1_0, _0_0, _N_1_0, _0_0
+        s = sin(r)
+        if (a * 2) == Q:
+            s, c = _copysign(_SIN_45, s), _COS_45
+        elif (a * 3) == Q:
+            s, c = _copysign(_SIN_30, s), _COS_30
+        else:
+            c = cos(r)
+    else:
+        s, c = _1_0, _0_0
+    t  = s, c, -s, -c, s
 #   q &= 3
-    s = t[q]     or _copysign_0_0(sign)
-    c = t[q + 1] or _0_0
+    s  = t[q]     or _copysign_0_0(sign)
+    c  = t[q + 1] or _0_0
     return s, c
 
 
@@ -698,8 +758,8 @@ def SinCos2(x):
        @return: 2-Tuple (C{sin(B{x})}, C{cos(B{x})}).
     '''
     return sincos2d(x) if isinstanceof(x, Degrees, Degrees_) else (
-           sincos2(x)  if isinstanceof(x, Radians, Radians_) else
-           sincos2(float(x)))  # assume C{radians}
+#          sincos2(x)  if isinstanceof(x, Radians, Radians_) else
+           sincos2(Radians(x)))  # assume C{radians}
 
 
 def sincos2(rad):
@@ -720,20 +780,21 @@ def sincos2(rad):
         q = int(rad * _2__PI)  # int(math.floor)
         if q < 0:
             q -= 1
-        t = _sin0cos2(q & 3, rad - q * PI_2, rad)
+        r =  rad - q * PI_2
+        t = _sin0cos2(q & 3, r, rad, fabs(r), PI_2)
     else:
         t =  NAN, NAN
     return t
 
 
 def sincos2_(*rads):
-    '''Return the C{sine} and C{cosine} of angle(s) in C{radians}.
+    '''Yield the C{sine} and C{cosine} of angle(s) in C{radians}.
 
        @arg rads: One or more angles (C{radians}).
 
-       @return: Yield the C{sin(B{rad})} and C{cos(B{rad})} for each angle.
+       @return: Yield C{sin(B{rad})} and C{cos(B{rad})} for each angle.
 
-       @see: function L{sincos2}.
+       @see: Function L{sincos2}.
     '''
     for r in rads:
         s, c = sincos2(r)
@@ -741,7 +802,7 @@ def sincos2_(*rads):
         yield c
 
 
-def sincos2d(deg, **adeg):
+def sincos2d(deg, adeg=_0_0):
     '''Return the C{sine} and C{cosine} of an angle in C{degrees}.
 
        @arg deg: Angle (C{degrees}).
@@ -763,20 +824,19 @@ def sincos2d(deg, **adeg):
             q -= 1
         d = deg - q * _90_0
         if adeg:
-            t = _xkwds_get1(adeg, adeg=_0_0)
-            d = _MODS.karney._around(d + t)
-        t = _sin0cos2(q & 3, radians(d), deg)
+            d = _MODS.karney._around(d + adeg)
+        t = _sin0cos2(q & 3, radians(d), deg, fabs(d), _90_0)
     else:
         t =  NAN, NAN
     return t
 
 
 def sincos2d_(*degs):
-    '''Return the C{sine} and C{cosine} of angle(s) in C{degrees}.
+    '''Yield the C{sine} and C{cosine} of angle(s) in C{degrees}.
 
        @arg degs: One or more angles (C{degrees}).
 
-       @return: Yield the C{sin(B{deg})} and C{cos(B{deg})} for each angle.
+       @return: Yield C{sind(B{deg})} and C{cosd(B{deg})} for each angle.
 
        @see: Function L{sincos2d}.
     '''
@@ -795,9 +855,25 @@ def sincostan3(rad):
 
        @see: Function L{sincos2}.
     '''
-    s, c = sincos2(float(rad))
-    t = NAN if s is NAN else (_over(s, c) if s else neg(s, neg0=c < 0))
-    return s, c, t
+    return _sincostan3(*sincos2(float(rad)))
+
+
+def _sincostan3(s, c):
+    '''(INTERNAL) Helper for C{sincostan3} and C{sincostan3d}.
+    '''
+    return s, c, _tanu(s, c, raiser=False)
+
+
+def sincostan3d(deg):
+    '''Return the C{sine}, C{cosine} and C{tangent} of an angle in C{degrees}.
+
+       @arg deg: Angle (C{degrees}).
+
+       @return: 3-Tuple (C{sind(B{deg})}, C{cosd(B{deg})}, C{tand(B{deg})}).
+
+       @see: Function L{sincos2d}.
+    '''
+    return _sincostan3(*sincos2d(float(deg)))
 
 
 def SM2m(sm):
@@ -832,41 +908,75 @@ def tan_2(rad, **semi):  # edge=1
             _SPACE_(_MODS.streprs.Fmt.SQUARE(**semi), _edge_)
         raise _ValueError(n, rad, txt=_semi_circular_)
 
-    return tan(rad * _0_5) if _isfinite(rad) else NAN
+    return _tan(rad * _0_5) if _isfinite(rad) else NAN
+
+
+def tan(rad, **raiser_kwds):
+    '''Return the C{tangent} of an angle in C{radians}.
+
+       @arg rad: Angle (C{radians}).
+       @kwarg raiser_kwds: Use C{B{raiser}=False} to avoid
+                     ValueErrors or optionally, additional
+                     ValueError keyword argments.
+
+       @return: C{tan(B{rad})}.
+
+       @raise Error: If L{pygeodesy.isnear0}C{(cos(B{rad})}.
+    '''
+    try:
+        return _tanu(*sincos2(rad), **raiser_kwds)
+    except ZeroDivisionError:
+        raise _valueError(tan, rad, **raiser_kwds)
+
+
+def tan_(*rads, **raiser_kwds):
+    '''Yield the C{tangent} of angle(s) in C{radians}.
 
+       @arg rads: One or more angles (each in C{radians}).
 
-def tand(deg, **error_kwds):
+       @return: Yield C{tan(B{rad})} for each angle.
+
+       @see: Function L{pygeodesy.tan} for futher details.
+    '''
+    try:
+        for r in rads:
+            yield _tanu(*sincos2(r), **raiser_kwds)
+    except ZeroDivisionError:
+        raise _valueError(tan_, r, **raiser_kwds)
+
+
+def tand(deg, **raiser_kwds):
     '''Return the C{tangent} of an angle in C{degrees}.
 
        @arg deg: Angle (C{degrees}).
-       @kwarg error_kwds: Error to raise (C{ValueError}).
+       @kwarg raiser_kwds: Use C{B{raiser}=False} to avoid
+                     ValueErrors or optionally, additional
+                     ValueError keyword argments.
 
        @return: C{tan(B{deg})}.
 
-       @raise ValueError: If L{pygeodesy.isnear0}C{(cos(B{deg})}.
+       @raise Error: If L{pygeodesy.isnear0}C{(cos(B{deg})}.
     '''
-    s, c = sincos2d(deg)
-    if s:
-        if isnear0(c):
-            raise _valueError(tand, deg, **error_kwds)
-        s = s / c  # /= chokes PyChecker
-    elif c < 0:
-        s = -s  # negate-0
-    return s
+    try:
+        return _tanu(*sincos2d(deg), **raiser_kwds)
+    except ZeroDivisionError:
+        raise _valueError(tand, deg, **raiser_kwds)
 
 
-def tand_(*degs, **error_kwds):
-    '''Return the C{tangent} of angle(s) in C{degrees}.
+def tand_(*degs, **raiser_kwds):
+    '''Yield the C{tangent} of angle(s) in C{degrees}.
 
-       @arg degs: One or more angles (C{degrees}).
-       @kwarg error_kwds: Error to raise (C{ValueError}).
+       @arg degs: One or more angles (each in C{degrees}).
 
-       @return: Yield the C{tan(B{deg})} for each angle.
+       @return: Yield C{tand(B{deg})} for each angle.
 
-       @raise ValueError: See L{pygeodesy.tand}.
+       @see: Function L{pygeodesy.tand} for futher details.
     '''
-    for d in degs:
-        yield tand(d, **error_kwds)
+    try:
+        for d in degs:
+            yield _tanu(*sincos2d(d), **raiser_kwds)
+    except ZeroDivisionError:
+        raise _valueError(tand_, d, **raiser_kwds)
 
 
 def tanPI_2_2(rad):
@@ -876,8 +986,24 @@ def tanPI_2_2(rad):
 
        @return: M{tan((rad + PI/2) / 2)} (C{float}).
     '''
-    return tan((rad + PI_2) * _0_5) if _isfinite(rad) else (
-           NAN if isnan(rad) else (_N_90_0 if rad < 0 else _90_0))
+    return _tan((rad + PI_2) * _0_5) if _isfinite(rad) else (
+            NAN if isnan(rad) else _copysign(_90_0, rad))
+
+
+def _tanu(s, c, raiser=True, **unused):
+    '''(INTERNAL) Helper for functions C{_cotu}, C{sincostan3},
+       C{sincostan3d}, C{tan}, C{tan_}, C{tand} and C{tand_}.
+    '''
+    if s is NAN or isnan(s):
+        s = NAN
+    elif s:
+        if raiser and isnear0(c):
+            raise ZeroDivisionError()
+        s = _over(s, c) if fabs(s) != fabs(c) else \
+            _copysign(_1_0, (-s) if c < 0 else s)
+    elif c < 0:
+        s = -s  # negate-0
+    return s
 
 
 def toise2m(toises):
@@ -980,11 +1106,11 @@ def unrollPI(rad1, rad2, wrap=True):
     return r, rad2
 
 
-def _valueError(where, x, **kwds):
-    '''(INTERNAL) Return a C{_ValueError}.
+def _valueError(where, x, raiser=True, **kwds):
+    '''(INTERNAL) Return a C{_ValueError} or C{None}.
     '''
     t = _MODS.streprs.Fmt.PAREN(where.__name__, x)
-    return _ValueError(t, **kwds)
+    return _ValueError(t, **kwds) if raiser else None
 
 
 class _Wrap(object):
@@ -1065,7 +1191,7 @@ class _Wrap(object):
         '''
         if wrap and self._normal is not None:
             lat, lon = ll.latlon
-            if fabs(lon) > 180 or fabs(lat) > 90:
+            if fabs(lon) > _180_0 or fabs(lat) > _90_0:
                 _n = self.latlon
                 ll = ll.copy(name=_n.__name__)
                 ll.latlon = _n(lat, lon)
@@ -1100,8 +1226,7 @@ def wrap90(deg):
 
        @return: Degrees, wrapped (C{degrees90}).
     '''
-    w = wrap180(deg)
-    return (w - _180_0) if w > 90 else ((w + _180_0) if w < -90 else w)
+    return _wrapu(wrap180(deg), _180_0, _90_0)
 
 
 def wrap180(deg):
@@ -1113,9 +1238,9 @@ def wrap180(deg):
     '''
     d =  float(deg)
     w = _umod_360(d)
-    if w > 180:
+    if w > _180_0:
         w -= _360_0
-    elif d < 0 and w == 180:
+    elif d < 0 and w == _180_0:
         w = -w
     return w
 
@@ -1163,8 +1288,7 @@ def wrapPI_2(rad):
 
        @return: Radians, wrapped (C{radiansPI_2}).
     '''
-    w = wrapPI(rad)
-    return (w - PI) if w > PI_2 else ((w + PI) if w < (-PI_2) else w)
+    return _wrapu(wrapPI(rad), PI, PI_2)
 
 
 # def wraplatlon(lat, lon):
@@ -1183,7 +1307,7 @@ def wrap_normal(*normal):
                     lat- and longitude individually by L{wrap90} or
                     L{wrapPI_2} respectively L{wrap180}, L{wrapPI} or
                     if C{None}, leave lat- and longitude I{unchanged}.
-                    Do not supply any value to get the current setting.
+                    To get the current setting, do not specify.
 
        @return: The previous L{wrap_normal} setting (C{bool} or C{None}).
     '''
@@ -1199,6 +1323,12 @@ def wrap_normal(*normal):
 #     return wrapPI_2(phi), wrapPI(lam)
 
 
+def _wrapu(w, H, Q):
+    '''(INTERNAL) Helper for functions C{wrap180} and C{wrapPI}.
+    '''
+    return (w - H) if w > Q else ((w + H) if w < (-Q) else w)
+
+
 def yard2m(yards):
     '''Convert I{UK} yards to meter.
 
@@ -1212,7 +1342,7 @@ def yard2m(yards):
 
 # **) MIT License
 #
-# Copyright (C) 2016-2024 -- mrJean1 at Gmail -- All Rights Reserved.
+# Copyright (C) 2016-2025 -- mrJean1 at Gmail -- All Rights Reserved.
 #
 # Permission is hereby granted, free of charge, to any person obtaining a
 # copy of this software and associated documentation files (the "Software"),