mergeron 2025.739290.3__py3-none-any.whl → 2025.739290.5__py3-none-any.whl

mergeron/core/guidelines_boundary_functions_extra.py

@@ -8,16 +8,16 @@ poor performance
 """
 
 from collections.abc import Callable
-from dataclasses import dataclass
 from typing import Literal
 
 import numpy as np
+from attrs import frozen
 from mpmath import mp, mpf  # type: ignore
 from scipy.spatial.distance import minkowski as distance_function  # type: ignore
 from sympy import lambdify, simplify, solve, symbols  # type: ignore
 
 from .. import DEFAULT_REC_RATIO, VERSION, ArrayDouble  # noqa: TID252
-from . import guidelines_boundary_functions as gbfn
+from . import guidelines_boundary_functions as gbf
 
 __version__ = VERSION
 
@@ -26,14 +26,14 @@ mp.dps = 32
 mp.trap_complex = True
 
 
-@dataclass(slots=True, frozen=True)
+@frozen
 class GuidelinesBoundaryCallable:
     boundary_function: Callable[[ArrayDouble], ArrayDouble]
     area: float
     s_naught: float = 0
 
 
-def dh_area_quad(_dh_val: float = 0.01, /, *, dps: int = 9) -> float:
+def dh_area_quad(_dh_val: float = 0.01, /) -> float:
     """
     Area under the ΔHHI boundary.
 
@@ -45,8 +45,6 @@ def dh_area_quad(_dh_val: float = 0.01, /, *, dps: int = 9) -> float:
     ----------
     _dh_val
         Merging-firms' ΔHHI bound.
-    dps
-        Specified precision in decimal places.
 
     Returns
     -------
@@ -57,11 +55,12 @@ def dh_area_quad(_dh_val: float = 0.01, /, *, dps: int = 9) -> float:
     _dh_val = mpf(f"{_dh_val}")
     _s_naught = (1 - mp.sqrt(1 - 2 * _dh_val)) / 2
 
-    return round(
-        float(
-            _s_naught + mp.quad(lambda x: _dh_val / (2 * x), [_s_naught, 1 - _s_naught])
-        ),
-        dps,
+    return float(
+        mp.nstr(
+            _s_naught
+            + mp.quad(lambda x: _dh_val / (2 * x), [_s_naught, 1 - _s_naught]),
+            mp.prec,
+        )
     )
 
 
@@ -84,18 +83,24 @@ def hhi_delta_boundary_qdtr(_dh_val: float = 0.01, /) -> GuidelinesBoundaryCalla
 
     _s_1, _s_2 = symbols("s_1, s_2", positive=True)
 
-    _hhi_eqn = _s_2 - 0.01 / (2 * _s_1)
+    _hhi_eqn = _s_2 - _dh_val / (2 * _s_1)
 
-    _hhi_bdry = solve(_hhi_eqn, _s_2)[0]
-    _s_nought = float(solve(_hhi_eqn.subs({_s_2: 1 - _s_1}), _s_1)[0])
+    hhi_bdry = solve(_hhi_eqn, _s_2)[0]
+    s_nought = float(solve(_hhi_eqn.subs({_s_2: 1 - _s_1}), _s_1)[0])
 
-    _hhi_bdry_area = 2 * (
-        _s_nought
-        + mp.quad(lambdify(_s_1, _hhi_bdry, "mpmath"), (_s_nought, 1 - _s_nought))
+    hhi_bdry_area = float(
+        mp.nstr(
+            2
+            * (
+                s_nought
+                + mp.quad(lambdify(_s_1, hhi_bdry, "mpmath"), (s_nought, 1 - s_nought))
+            ),
+            mp.prec,
+        )
     )
 
     return GuidelinesBoundaryCallable(
-        lambdify(_s_1, _hhi_bdry, "numpy"), _hhi_bdry_area, _s_nought
+        lambdify(_s_1, hhi_bdry, "numpy"), hhi_bdry_area, s_nought
     )
 
 
@@ -131,62 +136,60 @@ def shrratio_boundary_qdtr_wtd_avg(
 
     _delta_star = mpf(f"{_delta_star}")
     _s_mid = _delta_star / (1 + _delta_star)
-    _s_naught = 0
+    s_naught = 0
 
-    _s_1, _s_2 = symbols("s_1:3", positive=True)
+    s_1, s_2 = symbols("s_1:3", positive=True)
 
     match weighting:
         case "own-share":
             _bdry_eqn = (
-                _s_1 * _s_2 / (1 - _s_1)
-                + _s_2
-                * _s_1
+                s_1 * s_2 / (1 - s_1)
+                + s_2
+                * s_1
                 / (
-                    (1 - (_r_val * _s_2 + (1 - _r_val) * _s_1))
+                    (1 - (_r_val * s_2 + (1 - _r_val) * s_1))
                     if recapture_form == "inside-out"
-                    else (1 - _s_2)
+                    else (1 - s_2)
                 )
-                - (_s_1 + _s_2) * _delta_star
+                - (s_1 + s_2) * _delta_star
             )
 
-            _bdry_func = solve(_bdry_eqn, _s_2)[0]
-            _s_naught = (
-                float(solve(simplify(_bdry_eqn.subs({_s_2: 1 - _s_1})), _s_1)[0])  # type: ignore
+            _bdry_func = solve(_bdry_eqn, s_2)[0]
+            s_naught = (
+                float(solve(simplify(_bdry_eqn.subs({s_2: 1 - s_1})), s_1)[0])  # type: ignore
                 if recapture_form == "inside-out"
                 else 0
             )
-            _bdry_area = float(
+            bdry_area = float(
                 2
                 * (
-                    _s_naught
-                    + mp.quad(lambdify(_s_1, _bdry_func, "mpmath"), (_s_naught, _s_mid))
+                    s_naught
+                    + mp.quad(lambdify(s_1, _bdry_func, "mpmath"), (s_naught, _s_mid))
                 )
-                - (_s_mid**2 + _s_naught**2)
+                - (_s_mid**2 + s_naught**2)
             )
 
         case "cross-product-share":
             mp.trap_complex = False
-            _d_star = symbols("d", positive=True)
+            d_star = symbols("d", positive=True)
             _bdry_eqn = (
-                _s_2 * _s_2 / (1 - _s_1)
-                + _s_1
-                * _s_1
+                s_2 * s_2 / (1 - s_1)
+                + s_1
+                * s_1
                 / (
-                    (1 - (_r_val * _s_2 + (1 - _r_val) * _s_1))
+                    (1 - (_r_val * s_2 + (1 - _r_val) * s_1))
                     if recapture_form == "inside-out"
-                    else (1 - _s_2)
+                    else (1 - s_2)
                 )
-                - (_s_1 + _s_2) * _d_star
+                - (s_1 + s_2) * d_star
             )
 
-            _bdry_func = solve(_bdry_eqn, _s_2)[1]
-            _bdry_area = float(
+            _bdry_func = solve(_bdry_eqn, s_2)[1]
+            bdry_area = float(
                 2
                 * (
                     mp.quad(
-                        lambdify(
-                            _s_1, _bdry_func.subs({_d_star: _delta_star}), "mpmath"
-                        ),
+                        lambdify(s_1, _bdry_func.subs({d_star: _delta_star}), "mpmath"),
                         (0, _s_mid),
                     )
                 ).real
@@ -195,30 +198,30 @@ def shrratio_boundary_qdtr_wtd_avg(
 
         case _:
             _bdry_eqn = (
-                1 / 2 * _s_2 / (1 - _s_1)
+                1 / 2 * s_2 / (1 - s_1)
                 + 1
                 / 2
-                * _s_1
+                * s_1
                 / (
-                    (1 - (_r_val * _s_2 + (1 - _r_val) * _s_1))
+                    (1 - (_r_val * s_2 + (1 - _r_val) * s_1))
                     if recapture_form == "inside-out"
-                    else (1 - _s_2)
+                    else (1 - s_2)
                 )
                 - _delta_star
             )
 
-            _bdry_func = solve(_bdry_eqn, _s_2)[0]
-            _bdry_area = float(
-                2 * (mp.quad(lambdify(_s_1, _bdry_func, "mpmath"), (0, _s_mid)))
+            _bdry_func = solve(_bdry_eqn, s_2)[0]
+            bdry_area = float(
+                2 * (mp.quad(lambdify(s_1, _bdry_func, "mpmath"), (0, _s_mid)))
                 - _s_mid**2
             )
 
     return GuidelinesBoundaryCallable(
-        lambdify(_s_1, _bdry_func, "numpy"), _bdry_area, _s_naught
+        lambdify(s_1, _bdry_func, "numpy"), bdry_area, s_naught
     )
 
 
-def shrratio_boundary_distance(
+def shrratio_boundary_distance(  # noqa: PLR0914
     _delta_star: float = 0.075,
     _r_val: float = DEFAULT_REC_RATIO,
     /,
@@ -227,7 +230,7 @@ def shrratio_boundary_distance(
     weighting: Literal["own-share", "cross-product-share"] | None = "own-share",
     recapture_form: Literal["inside-out", "proportional"] = "inside-out",
     dps: int = 5,
-) -> gbfn.GuidelinesBoundary:
+) -> gbf.GuidelinesBoundary:
     """
     Share combinations for the GUPPI boundaries using various aggregators with
     symmetric merging-firm margins.
@@ -261,42 +264,41 @@ def shrratio_boundary_distance(
     """
 
     _delta_star = mpf(f"{_delta_star}")
-    _s_mid = _delta_star / (1 + _delta_star)
-
-    # initial conditions
-    _gbdry_points = [(_s_mid, _s_mid)]
-    _s_1_pre, _s_2_pre = _s_mid, _s_mid
-    _s_2_oddval, _s_2_oddsum, _s_2_evnsum = True, 0.0, 0.0
 
     # parameters for iteration
+    _s_mid = mp.fdiv(_delta_star, 1 + _delta_star)
     _weights_base = (mpf("0.5"),) * 2
-    _gbd_step_sz = mp.power(10, -dps)
-    _theta = _gbd_step_sz * (10 if weighting == "cross-product-share" else 1)
-    for _s_1 in mp.arange(_s_mid - _gbd_step_sz, 0, -_gbd_step_sz):
+    _bdry_step_sz = mp.power(10, -dps)
+    _theta = _bdry_step_sz * (10 if weighting == "cross-product-share" else 1)
+
+    # initial conditions
+    bdry_points = [(_s_mid, _s_mid)]
+    s_1_pre, s_2_pre = _s_mid, _s_mid
+    s_2_oddval, s_2_oddsum, s_2_evnsum = True, 0.0, 0.0
+    for s_1 in mp.arange(_s_mid - _bdry_step_sz, 0, -_bdry_step_sz):
         # The wtd. avg. GUPPI is not always convex to the origin, so we
-        #   increment _s_2 after each iteration in which our algorithm
+        #   increment s_2 after each iteration in which our algorithm
         #   finds (s1, s2) on the boundary
-        _s_2 = _s_2_pre * (1 + _theta)
+        s_2 = s_2_pre * (1 + _theta)
 
-        if (_s_1 + _s_2) > mpf("0.99875"):
-            # 1: # We lose accuracy at 3-9s and up
+        if (s_1 + s_2) > mpf("0.99875"):
+            # 1: # inaccuracy at 3-9s and up
             break
 
         while True:
-            _de_1 = _s_2 / (1 - _s_1)
-            _de_2 = (
-                _s_1 / (1 - gbfn.lerp(_s_1, _s_2, _r_val))
+            de_1 = s_2 / (1 - s_1)
+            de_2 = (
+                s_1 / (1 - gbf.lerp(s_1, s_2, _r_val))
                 if recapture_form == "inside-out"
-                else _s_1 / (1 - _s_2)
+                else s_1 / (1 - s_2)
             )
 
-            _weights_i = (
+            weights_i = (
                 (
-                    _w1 := mp.fdiv(
-                        _s_2 if weighting == "cross-product-share" else _s_1,
-                        _s_1 + _s_2,
+                    _w := mp.fdiv(
+                        s_2 if weighting == "cross-product-share" else s_1, s_1 + s_2
                     ),
-                    1 - _w1,
+                    1 - _w,
                 )
                 if weighting
                 else _weights_base
@@ -304,70 +306,226 @@ def shrratio_boundary_distance(
 
             match agg_method:
                 case "arithmetic mean":
-                    _delta_test = distance_function(
-                        (_de_1, _de_2), (0.0, 0.0), p=1, w=_weights_i
+                    delta_test = distance_function(
+                        (de_1, de_2), (0.0, 0.0), p=1, w=weights_i
                     )
                 case "distance":
-                    _delta_test = distance_function(
-                        (_de_1, _de_2), (0.0, 0.0), p=2, w=_weights_i
+                    delta_test = distance_function(
+                        (de_1, de_2), (0.0, 0.0), p=2, w=weights_i
                     )
 
             _test_flag, _incr_decr = (
-                (_delta_test > _delta_star, -1)
+                (delta_test > _delta_star, -1)
                 if weighting == "cross-product-share"
-                else (_delta_test < _delta_star, 1)
+                else (delta_test < _delta_star, 1)
             )
 
             if _test_flag:
-                _s_2 += _incr_decr * _gbd_step_sz
+                s_2 += _incr_decr * _bdry_step_sz
             else:
                 break
 
         # Build-up boundary points
-        _gbdry_points.append((_s_1, _s_2))
+        bdry_points.append((s_1, s_2))
 
         # Build up area terms
-        _s_2_oddsum += _s_2 if _s_2_oddval else 0
-        _s_2_evnsum += _s_2 if not _s_2_oddval else 0
-        _s_2_oddval = not _s_2_oddval
+        s_2_oddsum += s_2 if s_2_oddval else 0
+        s_2_evnsum += s_2 if not s_2_oddval else 0
+        s_2_oddval = not s_2_oddval
 
         # Hold share points
-        _s_2_pre = _s_2
-        _s_1_pre = _s_1
+        s_2_pre = s_2
+        s_1_pre = s_1
 
-    if _s_2_oddval:
-        _s_2_evnsum -= _s_2_pre
+    if s_2_oddval:
+        s_2_evnsum -= s_2_pre
     else:
-        _s_2_oddsum -= _s_1_pre
+        s_2_oddsum -= s_1_pre
 
-    _s_intcpt = gbfn._shrratio_boundary_intcpt(
-        _s_1_pre,
+    s_intcpt = gbf._shrratio_boundary_intcpt(
+        s_1_pre,
         _delta_star,
         _r_val,
         recapture_form=recapture_form,
         agg_method=agg_method,
         weighting=weighting,
     )
+    print(s_1_pre, _delta_star, _r_val, s_intcpt)
+    print(type(s_intcpt))
 
     if weighting == "own-share":
-        _gbd_prtlarea = (
-            _gbd_step_sz * (4 * _s_2_oddsum + 2 * _s_2_evnsum + _s_mid + _s_2_pre) / 3
+        bdry_prtlarea = (
+            _bdry_step_sz * (4 * s_2_oddsum + 2 * s_2_evnsum + _s_mid + s_2_pre) / 3
         )
         # Area under boundary
-        _gbdry_area_total = 2 * (_s_1_pre + _gbd_prtlarea) - (
-            mp.power(_s_mid, "2") + mp.power(_s_1_pre, "2")
+        bdry_area_total = 2 * (s_1_pre + bdry_prtlarea) - (
+            mp.power(_s_mid, "2") + mp.power(s_1_pre, "2")
         )
 
     else:
-        _gbd_prtlarea = (
-            _gbd_step_sz * (4 * _s_2_oddsum + 2 * _s_2_evnsum + _s_mid + _s_intcpt) / 3
+        print([type(_f) for _f in (_s_mid, s_2_oddsum, s_2_evnsum, s_intcpt)])
+        bdry_prtlarea = (
+            _bdry_step_sz * (4 * s_2_oddsum + 2 * s_2_evnsum + _s_mid + s_intcpt) / 3
         )
         # Area under boundary
-        _gbdry_area_total = 2 * _gbd_prtlarea - mp.power(_s_mid, "2")
+        bdry_area_total = 2 * bdry_prtlarea - mp.power(_s_mid, "2")
 
-    _gbdry_points.append((mpf("0.0"), _s_intcpt))
+    bdry_points.append((mpf("0.0"), s_intcpt))
     # Points defining boundary to point-of-symmetry
-    return gbfn.GuidelinesBoundary(
-        np.vstack((_gbdry_points[::-1], np.flip(_gbdry_points[1:], 1))),
-        round(float(_gbdry_area_total), dps),
+    return gbf.GuidelinesBoundary(
+        np.vstack((bdry_points[::-1], np.flip(bdry_points[1:], 1))),
+        round(float(bdry_area_total), dps),
     )
+
+
+def shrratio_boundary_xact_avg_mp(  # noqa: PLR0914
+    _delta_star: float = 0.075,
+    _r_val: float = DEFAULT_REC_RATIO,
+    /,
+    *,
+    recapture_form: Literal["inside-out", "proportional"] = "inside-out",
+    dps: int = 5,
+) -> gbf.GuidelinesBoundary:
+    """
+    Share combinations along the simple average diversion-ratio boundary.
+
+    Notes
+    -----
+    An analytical expression for the exact average boundary is derived
+    and plotted from the y-intercept to the ray of symmetry as follows::
+
+        from sympy import latex, plot as symplot, solve, symbols
+
+        s_1, s_2 = symbols("s_1 s_2")
+
+        g_val, r_val, m_val = 0.06, 0.80, 0.30
+        d_hat = g_val / (r_val * m_val)
+
+        # recapture_form = "inside-out"
+        sag = solve(
+            (s_2 / (1 - s_1))
+            + (s_1 / (1 - (r_val * s_2 + (1 - r_val) * s_1)))
+            - 2 * d_hat,
+            s_2
+        )[0]
+        symplot(
+            sag,
+            (s_1, 0., d_hat / (1 + d_hat)),
+            ylabel=s_2
+        )
+
+        # recapture_form = "proportional"
+        sag = solve((s_2/(1 - s_1)) + (s_1/(1 - s_2)) - 2 * d_hat, s_2)[0]
+        symplot(
+            sag,
+            (s_1, 0., d_hat / (1 + d_hat)),
+            ylabel=s_2
+        )
+
+    Parameters
+    ----------
+    _delta_star
+        Share ratio (:math:`\\overline{d} / \\overline{r}`).
+    _r_val
+        Recapture ratio
+    recapture_form
+        Whether recapture-ratio is MNL-consistent ("inside-out") or has fixed
+        value for both merging firms ("proportional").
+    dps
+        Number of decimal places for rounding returned shares.
+
+    Returns
+    -------
+        Array of share-pairs, area under boundary, area under boundary.
+
+    """
+
+    _delta_star = mpf(f"{_delta_star}")
+    _s_mid = _delta_star / (1 + _delta_star)
+    _bdry_step_sz = 10**-dps
+    _bdry_start = np.array([(_s_mid, _s_mid)])
+    _s_1 = np.array(mp.arange(_s_mid - _bdry_step_sz, 0, -_bdry_step_sz))
+    if recapture_form == "inside-out":
+        s_intcpt = mp.fdiv(
+            mp.fsub(
+                2 * _delta_star * _r_val + 1, mp.fabs(2 * _delta_star * _r_val - 1)
+            ),
+            2 * mpf(f"{_r_val}"),
+        )
+        nr_t1 = 1 + 2 * _delta_star * _r_val * (1 - _s_1) - _s_1 * (1 - _r_val)
+
+        nr_sqrt_mdr = 4 * _delta_star * _r_val
+        nr_sqrt_mdr2 = nr_sqrt_mdr * _r_val
+        nr_sqrt_md2r2 = nr_sqrt_mdr2 * _delta_star
+
+        nr_sqrt_t1 = nr_sqrt_md2r2 * (_s_1**2 - 2 * _s_1 + 1)
+        nr_sqrt_t2 = nr_sqrt_mdr2 * _s_1 * (_s_1 - 1)
+        nr_sqrt_t3 = nr_sqrt_mdr * (2 * _s_1 - _s_1**2 - 1)
+        nr_sqrt_t4 = (_s_1**2) * (_r_val**2 - 6 * _r_val + 1)
+        nr_sqrt_t5 = _s_1 * (6 * _r_val - 2) + 1
+
+        nr_t2_mdr = nr_sqrt_t1 + nr_sqrt_t2 + nr_sqrt_t3 + nr_sqrt_t4 + nr_sqrt_t5
+
+        # Alternative grouping of terms in np.sqrt
+        nr_sqrt_s1sq = (_s_1**2) * (
+            nr_sqrt_md2r2 + nr_sqrt_mdr2 - nr_sqrt_mdr + _r_val**2 - 6 * _r_val + 1
+        )
+        nr_sqrt_s1 = _s_1 * (
+            -2 * nr_sqrt_md2r2 - nr_sqrt_mdr2 + 2 * nr_sqrt_mdr + 6 * _r_val - 2
+        )
+        nr_sqrt_nos1 = nr_sqrt_md2r2 - nr_sqrt_mdr + 1
+
+        nr_t2_s1 = nr_sqrt_s1sq + nr_sqrt_s1 + nr_sqrt_nos1
+
+        if not np.isclose(
+            np.einsum("i->", nr_t2_mdr.astype(float)),
+            np.einsum("i->", nr_t2_s1.astype(float)),
+            rtol=0,
+            atol=0.5 * dps,
+        ):
+            raise RuntimeError(
+                "Calculation of sq. root term in exact average GUPPI"
+                f"with recapture spec, {f'"{recapture_form}"'} is incorrect."
+            )
+
+        s_2 = (nr_t1 - np.sqrt(nr_t2_s1)) / (2 * _r_val)
+
+    else:
+        s_intcpt = mp.fsub(_delta_star + 1 / 2, mp.fabs(_delta_star - 1 / 2))
+        s_2 = (
+            (1 / 2)
+            + _delta_star
+            - _delta_star * _s_1
+            - np.sqrt(
+                ((_delta_star**2) - 1) * (_s_1**2)
+                + (-2 * (_delta_star**2) + _delta_star + 1) * _s_1
+                + (_delta_star**2)
+                - _delta_star
+                + (1 / 4)
+            )
+        )
+
+    bdry_inner = np.column_stack((_s_1, s_2))
+    bdry_end = np.array([(mpf("0.0"), s_intcpt)])
+
+    bdry = np.vstack((
+        bdry_end,
+        bdry_inner[::-1],
+        _bdry_start,
+        np.flip(bdry_inner, 1),
+        np.flip(bdry_end, 1),
+    ))
+    s_2 = np.concatenate((np.array([_s_mid]), s_2))
+
+    bdry_ends = [0, -1]
+    bdry_odds = np.array(range(1, len(s_2), 2), int)
+    bdry_evns = np.array(range(2, len(s_2), 2), int)
+
+    # Double the area under the half-curve, and subtract the double-counted bit.
+    bdry_area_simpson = 2 * _bdry_step_sz * (
+        (4 / 3) * np.sum(s_2.take(bdry_odds))
+        + (2 / 3) * np.sum(s_2.take(bdry_evns))
+        + (1 / 3) * np.sum(s_2.take(bdry_ends))
+    ) - mp.power(_s_mid, 2)
+
+    return gbf.GuidelinesBoundary(bdry, float(mp.nstr(bdry_area_simpson, dps)))