mergeron 2024.738963.0__py3-none-any.whl → 2024.738973.0__py3-none-any.whl

mergeron/core/guidelines_boundaries.py

@@ -4,19 +4,24 @@ with a canvas on which to draw boundaries for Guidelines standards.
 
 """
 
-import decimal
-from collections.abc import Callable
 from dataclasses import dataclass
 from importlib.metadata import version
-from typing import Any, Literal, TypeAlias
+from typing import Literal, TypeAlias
 
 import numpy as np
-from attrs import define, field
+from attrs import field, frozen
 from mpmath import mp, mpf  # type: ignore
-from numpy.typing import NDArray
 
 from .. import _PKG_NAME, UPPAggrSelector  # noqa: TID252
-from . import UPPBoundarySpec
+from . import GuidelinesBoundary, UPPBoundarySpec
+from .guidelines_boundary_functions import (
+    dh_area,
+    round_cust,
+    shrratio_boundary_max,
+    shrratio_boundary_min,
+    shrratio_boundary_wtd_avg,
+    shrratio_boundary_xact_avg,
+)
 
 __version__ = version(_PKG_NAME)
 
@@ -24,12 +29,13 @@ __version__ = version(_PKG_NAME)
 mp.prec = 80
 mp.trap_complex = True
 
-HMGPubYear: TypeAlias = Literal[1992, 2010, 2023]
+HMGPubYear: TypeAlias = Literal[1992, 2004, 2010, 2023]
 
 
-@dataclass(slots=True, frozen=True)
+@dataclass(frozen=True)
 class HMGThresholds:
     delta: float
+    fc: float
     rec: float
     guppi: float
     divr: float
@@ -37,31 +43,28 @@ class HMGThresholds:
     ipr: float
 
 
-@dataclass(slots=True, frozen=True)
-class GuidelinesBoundary:
-    coordinates: NDArray[np.float64]
-    area: float
-
-
-@dataclass(slots=True, frozen=True)
-class GuidelinesBoundaryCallable:
-    boundary_function: Callable[[NDArray[np.float64]], NDArray[np.float64]]
-    area: float
-    s_naught: float = 0
-
-
-@define(slots=True, frozen=True)
+@frozen
 class GuidelinesThresholds:
     """
     Guidelines threholds by Guidelines publication year
 
     ΔHHI, Recapture Rate, GUPPI, Diversion ratio, CMCR, and IPR thresholds
-    constructed from concentration standards.
+    constructed from concentration standards in Guidelines published in
+    1992, 2004, 2010, and 2023.
+
+    The 2004 Guidelines refernced here are the EU Commission
+    guidelines on assessment of horizontal mergers. These
+    guidelines also define a presumption for mergers with
+    post-merger HHI in [1000, 2000) and ΔHHI >= 250 points,
+    whi is not modeled here.
+
+    All other Guidelines modeled here are U.S. merger guidelines.
+
     """
 
     pub_year: HMGPubYear
     """
-    Year of publication of the U.S. Horizontal Merger Guidelines (HMG)
+    Year of publication of the Guidelines
     """
 
     safeharbor: HMGThresholds = field(kw_only=True, default=None)
@@ -99,6 +102,7 @@ class GuidelinesThresholds:
         _hhi_p, _dh_s, _dh_p = {
             1992: (0.18, 0.005, 0.01),
             2010: (0.25, 0.01, 0.02),
+            2004: (0.20, 0.015, 0.015),
             2023: (0.18, 0.01, 0.01),
         }[self.pub_year]
 
@@ -107,8 +111,9 @@ class GuidelinesThresholds:
             "safeharbor",
             HMGThresholds(
                 _dh_s,
-                _r := round_cust((_fc := int(np.ceil(1 / _hhi_p))) / (_fc + 1)),
-                _g_s := gbd_from_dsf(_dh_s, m_star=1.0, r_bar=_r),
+                _fc := int(np.ceil(1 / _hhi_p)),
+                _r := round_cust(_fc / (_fc + 1)),
+                _g_s := guppi_from_delta(_dh_s, m_star=1.0, r_bar=_r),
                 _dr := round_cust(1 / (_fc + 1)),
                 _cmcr := 0.03,  # Not strictly a Guidelines standard
                 _ipr := _g_s,  # Not strictly a Guidelines standard
@@ -122,17 +127,19 @@ class GuidelinesThresholds:
             (
                 HMGThresholds(
                     _dh_i := 2 * (0.5 / _fc) ** 2,
+                    _fc,
                     _r_i := round_cust((_fc - 1 / 2) / (_fc + 1 / 2)),
-                    _g_i := gbd_from_dsf(_dh_i, m_star=1.0, r_bar=_r_i),
-                    round_cust((1 / 2) / (_fc - 1 / 2)),
+                    _g_i := guppi_from_delta(_dh_i, m_star=1.0, r_bar=_r_i),
+                    round_cust((1 / 2) / (_fc + 1 / 2)),
                     _cmcr,
                     _g_i,
                 )
                 if self.pub_year == 2010
                 else HMGThresholds(
                     _dh_i := 2 * (1 / (_fc + 1)) ** 2,
+                    _fc,
                     _r,
-                    _g_i := gbd_from_dsf(_dh_i, m_star=1.0, r_bar=_r),
+                    _g_i := guppi_from_delta(_dh_i, m_star=1.0, r_bar=_r),
                     _dr,
                     _cmcr,
                     _g_i,
@@ -145,8 +152,9 @@ class GuidelinesThresholds:
             "presumption",
             HMGThresholds(
                 _dh_p,
+                _fc,
                 _r,
-                _g_p := gbd_from_dsf(_dh_p, m_star=1.0, r_bar=_r),
+                _g_p := guppi_from_delta(_dh_p, m_star=1.0, r_bar=_r),
                 _dr,
                 _cmcr,
                 _ipr := _g_p,
@@ -154,112 +162,8 @@ class GuidelinesThresholds:
         )
 
 
-def round_cust(
-    _num: float = 0.060215,
-    /,
-    *,
-    frac: float = 0.005,
-    rounding_mode: str = "ROUND_HALF_UP",
-) -> float:
-    """
-    Custom rounding, to the nearest 0.5% by default.
-
-    Parameters
-    ----------
-    _num
-        Number to be rounded.
-    frac
-        Fraction to be rounded to.
-    rounding_mode
-        Rounding mode, as defined in the :code:`decimal` package.
-
-    Returns
-    -------
-        The given number, rounded as specified.
-
-    Raises
-    ------
-    ValueError
-        If rounding mode is not defined in the :code:`decimal` package.
-
-    Notes
-    -----
-    Integer-round the quotient, :code:`(_num / frac)` using the specified
-    rounding mode. Return the product of the rounded quotient times
-    the specified precision, :code:`frac`.
-
-    """
-
-    if rounding_mode not in (
-        decimal.ROUND_05UP,
-        decimal.ROUND_CEILING,
-        decimal.ROUND_DOWN,
-        decimal.ROUND_FLOOR,
-        decimal.ROUND_HALF_DOWN,
-        decimal.ROUND_HALF_EVEN,
-        decimal.ROUND_HALF_UP,
-        decimal.ROUND_UP,
-    ):
-        raise ValueError(
-            f"Value, {f'"{rounding_mode}"'} is invalid for rounding_mode."
-            "Documentation for the, \"decimal\" built-in lists valid rounding modes."
-        )
-
-    _n, _f, _e = (decimal.Decimal(f"{_g}") for _g in [_num, frac, 1])
-
-    return float(_f * (_n / _f).quantize(_e, rounding=rounding_mode))
-
-
-def lerp(
-    _x1: int | float | mpf | NDArray[np.float64 | np.int64] = 3,
-    _x2: int | float | mpf | NDArray[np.float64 | np.int64] = 1,
-    _r: float | mpf = 0.25,
-    /,
-) -> float | mpf | NDArray[np.float64]:
-    """
-    From the function of the same name in the C++ standard [2]_
-
-    Constructs the weighted average, :math:`w_1 x_1 + w_2 x_2`, where
-    :math:`w_1 = 1 - r` and :math:`w_2 = r`.
-
-    Parameters
-    ----------
-    _x1, _x2
-        bounds :math:`x_1, x_2` to interpolate between.
-    _r
-        interpolation weight :math:`r` assigned to :math:`x_2`
-
-    Returns
-    -------
-        The linear interpolation, or weighted average,
-        :math:`x_1 + r \\cdot (x_1 - x_2) \\equiv (1 - r) \\cdot x_1 + r \\cdot x_2`.
-
-    Raises
-    ------
-    ValueError
-        If the interpolation weight is not in the interval, :math:`[0, 1]`.
-
-    References
-    ----------
-
-    .. [2] C++ Reference, https://en.cppreference.com/w/cpp/numeric/lerp
-
-    """
-
-    if not 0 <= _r <= 1:
-        raise ValueError("Specified interpolation weight must lie in [0, 1].")
-    elif _r == 0:
-        return _x1
-    elif _r == 1:
-        return _x2
-    elif _r == 0.5:
-        return 1 / 2 * (_x1 + _x2)
-    else:
-        return _r * _x2 + (1 - _r) * _x1
-
-
-def gbd_from_dsf(
-    _deltasf: float = 0.01, /, *, m_star: float = 1.00, r_bar: float = 0.80
+def guppi_from_delta(
+    _delta_bound: float = 0.01, /, *, m_star: float = 1.00, r_bar: float = 0.855
 ) -> float:
     """
     Translate ∆HHI bound to GUPPI bound.
@@ -279,18 +183,18 @@ def gbd_from_dsf(
 
     """
     return round_cust(
-        m_star * r_bar * (_s_m := np.sqrt(_deltasf / 2)) / (1 - _s_m),
+        m_star * r_bar * (_s_m := np.sqrt(_delta_bound / 2)) / (1 - _s_m),
         frac=0.005,
         rounding_mode="ROUND_HALF_DOWN",
     )
 
 
-def critical_shrratio(
-    _gbd: float = 0.06,
+def critical_share_ratio(
+    _guppi_bound: float = 0.075,
     /,
     *,
     m_star: float = 1.00,
-    r_bar: float = 0.80,
+    r_bar: float = 1.00,
     frac: float = 1e-16,
 ) -> mpf:
     """
@@ -298,7 +202,7 @@ def critical_shrratio(
 
     Parameters
     ----------
-    _gbd
+    _guppi_bound
         Specified GUPPI bound.
     m_star
         Parametric price-cost margin.
@@ -311,18 +215,20 @@ def critical_shrratio(
         for given margin and recapture rate.
 
     """
-    return round_cust(mpf(f"{_gbd}") / mp.fmul(f"{m_star}", f"{r_bar}"), frac=frac)
+    return round_cust(
+        mpf(f"{_guppi_bound}") / mp.fmul(f"{m_star}", f"{r_bar}"), frac=frac
+    )
 
 
-def shr_from_gbd(
-    _gbd: float = 0.06, /, *, m_star: float = 1.00, r_bar: float = 0.80
+def share_from_guppi(
+    _guppi_bound: float = 0.065, /, *, m_star: float = 1.00, r_bar: float = 0.855
 ) -> float:
     """
     Symmetric-firm share for given GUPPI, margin, and recapture rate.
 
     Parameters
     ----------
-    _gbd
+    _guppi_bound
         GUPPI bound.
     m_star
         Parametric price-cost margin.
@@ -338,249 +244,12 @@ def shr_from_gbd(
     """
 
     return round_cust(
-        (_d0 := critical_shrratio(_gbd, m_star=m_star, r_bar=r_bar)) / (1 + _d0)
+        (_d0 := critical_share_ratio(_guppi_bound, m_star=m_star, r_bar=r_bar))
+        / (1 + _d0)
     )
 
 
-def boundary_plot(*, mktshares_plot_flag: bool = True) -> tuple[Any, ...]:
-    """Setup basic figure and axes for plots of safe harbor boundaries.
-
-    See, https://matplotlib.org/stable/tutorials/text/pgf.html
-    """
-
-    import matplotlib as mpl
-    import matplotlib.axes as mpa
-    import matplotlib.patches as mpp
-    import matplotlib.ticker as mpt
-
-    mpl.use("pgf")
-    import matplotlib.pyplot as plt
-    # from matplotlib.backends.backend_pgf import FigureCanvasPgf
-
-    # from matplotlib.backends.backend_pgf import FigureCanvasPgf
-    # mpl.backend_bases.register_backend("pdf", FigureCanvasPgf)
-    # import matplotlib.pyplot as plt
-
-    plt.rcParams.update({
-        "pgf.rcfonts": False,
-        "pgf.texsystem": "lualatex",
-        "pgf.preamble": "\n".join([
-            R"\pdfvariable minorversion=7",
-            R"\usepackage{fontspec}",
-            R"\usepackage{luacode}",
-            R"\begin{luacode}",
-            R"local function embedfull(tfmdata)",
-            R'    tfmdata.embedding = "full"',
-            R"end",
-            R"",
-            R"luatexbase.add_to_callback("
-            R'  "luaotfload.patch_font", embedfull, "embedfull"'
-            R")",
-            R"\end{luacode}",
-            R"\usepackage{mathtools}",
-            R"\usepackage{unicode-math}",
-            R"\setmathfont[math-style=ISO]{STIX Two Math}",
-            R"\setmainfont{STIX Two Text}",
-            r"\setsansfont{Fira Sans Light}",
-            R"\setmonofont[Scale=MatchLowercase,]{Fira Mono}",
-            R"\defaultfontfeatures[\rmfamily]{",
-            R"  Ligatures={TeX, Common},",
-            R"  Numbers={Proportional, Lining},",
-            R"  }",
-            R"\defaultfontfeatures[\sffamily]{",
-            R"  Ligatures={TeX, Common},",
-            R"  Numbers={Monospaced, Lining},",
-            R"  LetterSpace=0.50,",
-            R"  }",
-            R"\usepackage[",
-            R"  activate={true, nocompatibility},",
-            R"  tracking=true,",
-            R"  ]{microtype}",
-        ]),
-    })
-
-    # Initialize a canvas with a single figure (set of axes)
-    _fig = plt.figure(figsize=(5, 5), dpi=600)
-    _ax_out = _fig.add_subplot()
-
-    def _set_axis_def(
-        _ax1: mpa.Axes,
-        /,
-        *,
-        mktshares_plot_flag: bool = False,
-        mktshares_axlbls_flag: bool = False,
-    ) -> mpa.Axes:
-        # Set the width of axis gridlines, and tick marks:
-        # both axes, both major and minor ticks
-        # Frame, grid, and facecolor
-        for _spos0 in "left", "bottom":
-            _ax1.spines[_spos0].set_linewidth(0.5)
-            _ax1.spines[_spos0].set_zorder(5)
-        for _spos1 in "top", "right":
-            _ax1.spines[_spos1].set_linewidth(0.0)
-            _ax1.spines[_spos1].set_zorder(0)
-            _ax1.spines[_spos1].set_visible(False)
-        _ax1.set_facecolor("#E6E6E6")
-
-        _ax1.grid(linewidth=0.5, linestyle=":", color="grey", zorder=1)
-        _ax1.tick_params(axis="x", which="both", width=0.5)
-        _ax1.tick_params(axis="y", which="both", width=0.5)
-
-        # Tick marks skip, size, and rotation
-        # x-axis
-        plt.setp(
-            _ax1.xaxis.get_majorticklabels(),
-            horizontalalignment="right",
-            fontsize=6,
-            rotation=45,
-        )
-        # y-axis
-        plt.setp(
-            _ax1.yaxis.get_majorticklabels(), horizontalalignment="right", fontsize=6
-        )
-
-        if mktshares_plot_flag:
-            # Axis labels
-            if mktshares_axlbls_flag:
-                # x-axis
-                _ax1.set_xlabel("Firm 1 Market Share, $s_1$", fontsize=10)
-                _ax1.xaxis.set_label_coords(0.75, -0.1)
-                # y-axis
-                _ax1.set_ylabel("Firm 2 Market Share, $s_2$", fontsize=10)
-                _ax1.yaxis.set_label_coords(-0.1, 0.75)
-
-            # Plot the ray of symmetry
-            _ax1.plot(
-                [0, 1], [0, 1], linewidth=0.5, linestyle=":", color="grey", zorder=1
-            )
-
-            # Axis scale
-            _ax1.set_xlim(0, 1)
-            _ax1.set_ylim(0, 1)
-            _ax1.set_aspect(1.0)
-
-            # Truncate the axis frame to a triangle:
-            _ax1.add_patch(
-                mpp.Rectangle(
-                    xy=(1.0025, 0.00),
-                    width=1.1 * mp.sqrt(2),
-                    height=1.1 * mp.sqrt(2),
-                    angle=45,
-                    color="white",
-                    edgecolor=None,
-                    fill=True,
-                    clip_on=True,
-                    zorder=5,
-                )
-            )
-            # Feasible space is bounded by the other diagonal:
-            _ax1.plot(
-                [0, 1], [1, 0], linestyle="-", linewidth=0.5, color="black", zorder=1
-            )
-
-            # Axis Tick-mark locations
-            # One can supply an argument to mpt.AutoMinorLocator to
-            # specify a fixed number of minor intervals per major interval, e.g.:
-            # minorLocator = mpt.AutoMinorLocator(2)
-            # would lead to a single minor tick between major ticks.
-            _minorLocator = mpt.AutoMinorLocator(5)
-            _majorLocator = mpt.MultipleLocator(0.05)
-            for _axs in _ax1.xaxis, _ax1.yaxis:
-                if _axs == _ax1.xaxis:
-                    _majorticklabels_rot = 45
-                elif _axs == _ax1.yaxis:
-                    _majorticklabels_rot = 0
-                # x-axis
-                _axs.set_major_locator(_majorLocator)
-                _axs.set_minor_locator(_minorLocator)
-                # It"s always x when specifying the format
-                _axs.set_major_formatter(mpt.StrMethodFormatter("{x:>3.0%}"))
-
-            # Hide every other tick-label
-            for _axl in _ax1.get_xticklabels(), _ax1.get_yticklabels():
-                plt.setp(_axl[::2], visible=False)
-
-        return _ax1
-
-    _ax_out = _set_axis_def(_ax_out, mktshares_plot_flag=mktshares_plot_flag)
-
-    return plt, _fig, _ax_out, _set_axis_def
-
-
-def dh_area(_dh_val: float = 0.01, /, *, prec: int = 9) -> float:
-    R"""
-    Area under the ΔHHI boundary.
-
-    When the given ΔHHI bound matches a Guidelines standard,
-    the area under the boundary is half the intrinsic clearance rate
-    for the ΔHHI safeharbor.
-
-    Notes
-    -----
-    To derive the knots, :math:`(s^0_1, s^1_1), (s^1_1, s^0_1)`
-    of the ΔHHI boundary, i.e., the points where it intersects
-    the merger-to-monopoly boundary, solve
-
-    .. math::
-
-        2 s1 s_2 &= ΔHHI\\
-        s_1 + s_2 &= 1
-
-    Parameters
-    ----------
-    _dh_val
-        Change in concentration.
-    prec
-        Specified precision in decimal places.
-
-    Returns
-    -------
-        Area under ΔHHI boundary.
-
-    """
-
-    _dh_val = mpf(f"{_dh_val}")
-    _s_naught = (1 - mp.sqrt(1 - 2 * _dh_val)) / 2
-
-    return round(
-        float(_s_naught + (_dh_val / 2) * (mp.ln(1 - _s_naught) - mp.ln(_s_naught))),
-        prec,
-    )
-
-
-def dh_area_quad(_dh_val: float = 0.01, /, *, prec: int = 9) -> float:
-    """
-    Area under the ΔHHI boundary.
-
-    When the given ΔHHI bound matches a Guidelines safeharbor,
-    the area under the boundary is half the intrinsic clearance rate
-    for the ΔHHI safeharbor.
-
-    Parameters
-    ----------
-    _dh_val
-        Merging-firms' ΔHHI bound.
-    prec
-        Specified precision in decimal places.
-
-    Returns
-    -------
-        Area under ΔHHI boundary.
-
-    """
-
-    _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])
-        ),
-        prec,
-    )
-
-
-def delta_hhi_boundary(
+def hhi_delta_boundary(
     _dh_val: float = 0.01, /, *, prec: int = 5
 ) -> GuidelinesBoundary:
     """
@@ -691,29 +360,56 @@ def hhi_pre_contrib_boundary(
     )
 
 
-def shrratio_boundary(_bdry_spec: UPPBoundarySpec) -> GuidelinesBoundary:
+def hhi_post_contrib_boundary(
+    _hhi_contrib: float = 0.800, /, *, bdry_dps: int = 10
+) -> GuidelinesBoundary:
+    """
+    Share combinations on the postmerger HHI contribution boundary.
+
+    The post-merger HHI contribution boundary is identical to the
+    combined-share boundary.
+
+    Parameters
+    ----------
+    _hhi_contrib:
+        Merging-firms' pre-merger HHI contribution bound.
+    bdry_dps
+        Number of decimal places for rounding reported shares.
+
+    Returns
+    -------
+        Array of share-pairs, area under boundary.
+
+    """
+    return combined_share_boundary(np.sqrt(_hhi_contrib), bdry_dps=bdry_dps)
+
+
+def diversion_ratio_boundary(_bdry_spec: UPPBoundarySpec) -> GuidelinesBoundary:
+    _share_ratio = critical_share_ratio(
+        _bdry_spec.diversion_ratio, r_bar=_bdry_spec.rec
+    )
     match _bdry_spec.agg_method:
         case UPPAggrSelector.AVG:
             return shrratio_boundary_xact_avg(
-                _bdry_spec.share_ratio,
+                _share_ratio,
                 _bdry_spec.rec,
                 recapture_form=_bdry_spec.recapture_form.value,  # type: ignore
                 prec=_bdry_spec.precision,
             )
         case UPPAggrSelector.MAX:
             return shrratio_boundary_max(
-                _bdry_spec.share_ratio, _bdry_spec.rec, prec=_bdry_spec.precision
+                _share_ratio, _bdry_spec.rec, prec=_bdry_spec.precision
             )
         case UPPAggrSelector.MIN:
             return shrratio_boundary_min(
-                _bdry_spec.share_ratio,
+                _share_ratio,
                 _bdry_spec.rec,
                 recapture_form=_bdry_spec.recapture_form.value,  # type: ignore
                 prec=_bdry_spec.precision,
             )
         case UPPAggrSelector.DIS:
             return shrratio_boundary_wtd_avg(
-                _bdry_spec.share_ratio,
+                _share_ratio,
                 _bdry_spec.rec,
                 agg_method="distance",
                 weighting=None,
@@ -734,516 +430,10 @@ def shrratio_boundary(_bdry_spec: UPPBoundarySpec) -> GuidelinesBoundary:
             )
 
             return shrratio_boundary_wtd_avg(
-                _bdry_spec.share_ratio,
+                _share_ratio,
                 _bdry_spec.rec,
                 agg_method=_agg_method,  # type: ignore
                 weighting=_weighting,  # type: ignore
                 recapture_form=_bdry_spec.recapture_form.value,  # type: ignore
                 prec=_bdry_spec.precision,
             )
-
-
-def shrratio_boundary_max(
-    _delta_star: float = 0.075, _r_val: float = 0.80, /, *, prec: int = 10
-) -> GuidelinesBoundary:
-    """
-    Share combinations on the minimum GUPPI boundary with symmetric
-    merging-firm margins.
-
-    Parameters
-    ----------
-    _delta_star
-        Margin-adjusted benchmark share ratio.
-    _r_val
-        Recapture ratio.
-    prec
-        Number of decimal places for rounding returned shares.
-
-    Returns
-    -------
-        Array of share-pairs, area under boundary.
-
-    """
-
-    # _r_val is not needed for max boundary, but is specified for consistency
-    # of function call with other shrratio_mgnsym_boundary functions
-    del _r_val
-    _delta_star = mpf(f"{_delta_star}")
-    _s_intcpt = _delta_star
-    _s_mid = _delta_star / (1 + _delta_star)
-
-    _s1_pts = (0, _s_mid, _s_intcpt)
-
-    return GuidelinesBoundary(
-        np.column_stack((
-            np.array(_s1_pts, np.float64),
-            np.array(_s1_pts[::-1], np.float64),
-        )),
-        round(float(_s_intcpt * _s_mid), prec),  # simplified calculation
-    )
-
-
-def shrratio_boundary_min(
-    _delta_star: float = 0.075,
-    _r_val: float = 0.80,
-    /,
-    *,
-    recapture_form: str = "inside-out",
-    prec: int = 10,
-) -> GuidelinesBoundary:
-    """
-    Share combinations on the minimum GUPPI boundary, with symmetric
-    merging-firm margins.
-
-    Notes
-    -----
-    With symmetric merging-firm margins, the maximum GUPPI boundary is
-    defined by the diversion ratio from the smaller merging-firm to the
-    larger one, and is hence unaffected by the method of estimating the
-    diversion ratio for the larger firm.
-
-    Parameters
-    ----------
-    _delta_star
-        Margin-adjusted benchmark share ratio.
-    _r_val
-        Recapture ratio.
-    recapture_form
-        Whether recapture-ratio is MNL-consistent ("inside-out") or has fixed
-        value for both merging firms ("proportional").
-    prec
-        Number of decimal places for rounding returned shares.
-
-    Returns
-    -------
-        Array of share-pairs, area under boundary.
-
-    """
-
-    _delta_star = mpf(f"{_delta_star}")
-    _s_intcpt = mpf("1.00")
-    _s_mid = _delta_star / (1 + _delta_star)
-
-    if recapture_form == "inside-out":
-        # ## Plot envelope of GUPPI boundaries with r_k = r_bar if s_k = min(_s_1, _s_2)
-        # ## See (s_i, s_j) in equation~(44), or thereabouts, in paper
-        _smin_nr = _delta_star * (1 - _r_val)
-        _smax_nr = 1 - _delta_star * _r_val
-        _guppi_bdry_env_dr = _smin_nr + _smax_nr
-        _s1_pts = np.array(
-            (
-                0,
-                _smin_nr / _guppi_bdry_env_dr,
-                _s_mid,
-                _smax_nr / _guppi_bdry_env_dr,
-                _s_intcpt,
-            ),
-            np.float64,
-        )
-
-        _gbd_area = _s_mid + _s1_pts[1] * (1 - 2 * _s_mid)
-    else:
-        _s1_pts, _gbd_area = np.array((0, _s_mid, _s_intcpt), np.float64), _s_mid
-
-    return GuidelinesBoundary(
-        np.column_stack((_s1_pts, _s1_pts[::-1])), round(float(_gbd_area), prec)
-    )
-
-
-def shrratio_boundary_wtd_avg(
-    _delta_star: float = 0.075,
-    _r_val: float = 0.80,
-    /,
-    *,
-    agg_method: Literal["arithmetic", "geometric", "distance"] = "arithmetic",
-    weighting: Literal["own-share", "cross-product-share"] | None = "own-share",
-    recapture_form: Literal["inside-out", "proportional"] = "inside-out",
-    prec: int = 5,
-) -> GuidelinesBoundary:
-    """
-    Share combinations for the share-weighted average GUPPI boundary with symmetric
-    merging-firm margins.
-
-    Parameters
-    ----------
-    _delta_star
-        corollary to GUPPI bound (:math:`\\overline{g} / (m^* \\cdot \\overline{r})`)
-    _r_val
-        recapture ratio
-    agg_method
-        Whether "arithmetic", "geometric", or "distance".
-    weighting
-        Whether "own-share" or "cross-product-share"  (or None for simple, unweighted average).
-    recapture_form
-        Whether recapture-ratio is MNL-consistent ("inside-out") or has fixed
-        value for both merging firms ("proportional").
-    prec
-        Number of decimal places for rounding returned shares and area.
-
-    Returns
-    -------
-        Array of share-pairs, area under boundary.
-
-    Notes
-    -----
-    An analytical expression for the share-weighted arithmetic mean boundary
-    is derived and plotted from y-intercept to the ray of symmetry as follows::
-
-        from sympy import plot as symplot, solve, symbols
-        s_1, s_2 = symbols("s_1 s_2", positive=True)
-
-        g_val, r_val, m_val = 0.06, 0.80, 0.30
-        delta_star = g_val / (r_val * m_val)
-
-        # recapture_form == "inside-out"
-        oswag = solve(
-            s_1 * s_2 / (1 - s_1)
-            + s_2 * s_1 / (1 - (r_val * s_2 + (1 - r_val) * s_1))
-            - (s_1 + s_2) * delta_star,
-            s_2
-        )[0]
-        symplot(
-            oswag,
-            (s_1, 0., d_hat / (1 + d_hat)),
-            ylabel=s_2
-        )
-
-        cpswag = solve(
-            s_2 * s_2 / (1 - s_1)
-            + s_1 * s_1 / (1 - (r_val * s_2 + (1 - r_val) * s_1))
-            - (s_1 + s_2) * delta_star,
-            s_2
-        )[1]
-        symplot(
-            cpwag,
-            (s_1, 0., d_hat / (1 + d_hat)),
-            ylabel=s_2
-        )
-
-        # recapture_form == "proportional"
-        oswag = solve(
-            s_1 * s_2 / (1 - s_1)
-            + s_2 * s_1 / (1 - s_2)
-            - (s_1 + s_2) * delta_star,
-             s_2
-        )[0]
-        symplot(
-            oswag,
-            (s_1, 0., d_hat / (1 + d_hat)),
-            ylabel=s_2
-        )
-
-        cpswag = solve(
-            s_2 * s_2 / (1 - s_1)
-            + s_1 * s_1 / (1 - s_2)
-            - (s_1 + s_2) * delta_star,
-             s_2
-        )[1]
-        symplot(
-            cpswag,
-            (s_1, 0.0, d_hat / (1 + d_hat)),
-            ylabel=s_2
-        )
-
-
-    """
-
-    _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
-
-    # parameters for iteration
-    _gbd_step_sz = mp.power(10, -prec)
-    _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):
-        # The wtd. avg. GUPPI is not always convex to the origin, so we
-        #   increment _s_2 after each iteration in which our algorithm
-        #   finds (s1, s2) on the boundary
-        _s_2 = _s_2_pre * (1 + _theta)
-
-        if (_s_1 + _s_2) > mpf("0.99875"):
-            # Loss of accuracy at 3-9s and up
-            break
-
-        while True:
-            _de_1 = _s_2 / (1 - _s_1)
-            _de_2 = (
-                _s_1 / (1 - lerp(_s_1, _s_2, _r_val))
-                if recapture_form == "inside-out"
-                else _s_1 / (1 - _s_2)
-            )
-
-            _r = (
-                mp.fdiv(
-                    _s_1 if weighting == "cross-product-share" else _s_2, _s_1 + _s_2
-                )
-                if weighting
-                else 0.5
-            )
-
-            match agg_method:
-                case "geometric":
-                    _delta_test = mp.expm1(lerp(mp.log1p(_de_1), mp.log1p(_de_2), _r))
-                case "distance":
-                    _delta_test = mp.sqrt(lerp(_de_1**2, _de_2**2, _r))
-                case _:
-                    _delta_test = lerp(_de_1, _de_2, _r)
-
-            _test_flag, _incr_decr = (
-                (_delta_test > _delta_star, -1)
-                if weighting == "cross-product-share"
-                else (_delta_test < _delta_star, 1)
-            )
-
-            if _test_flag:
-                _s_2 += _incr_decr * _gbd_step_sz
-            else:
-                break
-
-        # Build-up boundary points
-        _gbdry_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
-
-        # Hold share points
-        _s_2_pre = _s_2
-        _s_1_pre = _s_1
-
-    if _s_2_oddval:
-        _s_2_evnsum -= _s_2_pre
-    else:
-        _s_2_oddsum -= _s_1_pre
-
-    _s_intcpt = _shrratio_boundary_intcpt(
-        _s_1_pre,
-        _delta_star,
-        _r_val,
-        recapture_form=recapture_form,
-        agg_method=agg_method,
-        weighting=weighting,
-    )
-
-    if weighting == "own-share":
-        _gbd_prtlarea = (
-            _gbd_step_sz * (4 * _s_2_oddsum + 2 * _s_2_evnsum + _s_mid + _s_2_pre) / 3
-        )
-        # Area under boundary
-        _gbdry_area_total = float(
-            2 * (_s_1_pre + _gbd_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
-        )
-        # Area under boundary
-        _gbdry_area_total = float(2 * _gbd_prtlarea - mp.power(_s_mid, "2"))
-
-    _gbdry_points = np.row_stack((_gbdry_points, (mpf("0.0"), _s_intcpt))).astype(
-        np.float64
-    )
-
-    # Points defining boundary to point-of-symmetry
-    return GuidelinesBoundary(
-        np.row_stack((np.flip(_gbdry_points, 0), np.flip(_gbdry_points[1:], 1))),
-        round(float(_gbdry_area_total), prec),
-    )
-
-
-def shrratio_boundary_xact_avg(
-    _delta_star: float = 0.075,
-    _r_val: float = 0.80,
-    /,
-    *,
-    recapture_form: Literal["inside-out", "proportional"] = "inside-out",
-    prec: int = 5,
-) -> GuidelinesBoundary:
-    """
-    Share combinations for the simple average GUPPI boundary with symmetric
-    merging-firm margins.
-
-    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
-        Margin-adjusted benchmark share ratio.
-    _r_val
-        Recapture ratio
-    recapture_form
-        Whether recapture-ratio is MNL-consistent ("inside-out") or has fixed
-        value for both merging firms ("proportional").
-    prec
-        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)
-    _gbd_step_sz = mp.power(10, -prec)
-
-    _gbdry_points_start = np.array([(_s_mid, _s_mid)])
-    _s_1 = np.array(mp.arange(_s_mid - _gbd_step_sz, 0, -_gbd_step_sz), np.float64)
-    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(np.float64)),
-            np.einsum("i->", _nr_t2_s1.astype(np.float64)),
-            rtol=0,
-            atol=0.5 * prec,
-        ):
-            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)
-            )
-        )
-
-    _gbdry_points_inner = np.column_stack((_s_1, _s_2))
-    _gbdry_points_end = np.array([(mpf("0.0"), _s_intcpt)], np.float64)
-
-    _gbdry_points = np.row_stack((
-        _gbdry_points_end,
-        np.flip(_gbdry_points_inner, 0),
-        _gbdry_points_start,
-        np.flip(_gbdry_points_inner, 1),
-        np.flip(_gbdry_points_end, 1),
-    )).astype(np.float64)
-    _s_2 = np.concatenate((np.array([_s_mid], np.float64), _s_2))
-
-    _gbdry_ends = [0, -1]
-    _gbdry_odds = np.array(range(1, len(_s_2), 2), np.int64)
-    _gbdry_evns = np.array(range(2, len(_s_2), 2), np.int64)
-
-    # Double the are under the curve, and subtract the double counted bit.
-    _gbdry_area_simpson = 2 * _gbd_step_sz * (
-        (4 / 3) * np.sum(_s_2.take(_gbdry_odds))
-        + (2 / 3) * np.sum(_s_2.take(_gbdry_evns))
-        + (1 / 3) * np.sum(_s_2.take(_gbdry_ends))
-    ) - np.power(_s_mid, 2)
-
-    _s_1_pts, _s_2_pts = np.split(_gbdry_points, 2, axis=1)
-    return GuidelinesBoundary(
-        np.column_stack((np.array(_s_1_pts), np.array(_s_2_pts))),
-        round(float(_gbdry_area_simpson), prec),
-    )
-
-
-def _shrratio_boundary_intcpt(
-    _s_2_pre: float,
-    _delta_star: mpf,
-    _r_val: mpf,
-    /,
-    *,
-    recapture_form: Literal["inside-out", "proportional"],
-    agg_method: Literal["arithmetic", "geometric", "distance"],
-    weighting: Literal["cross-product-share", "own-share"] | None,
-) -> float:
-    match weighting:
-        case "cross-product-share":
-            _s_intcpt: float = _delta_star
-        case "own-share":
-            _s_intcpt = mpf("1.0")
-        case None if agg_method == "distance":
-            _s_intcpt = _delta_star * mp.sqrt("2")
-        case None if agg_method == "arithmetic" and 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}"),
-            )
-        case None if agg_method == "arithmetic":
-            _s_intcpt = mp.fsub(_delta_star + 1 / 2, mp.fabs(_delta_star - 1 / 2))
-        case _:
-            _s_intcpt = _s_2_pre
-
-    return _s_intcpt