mergeron 2024.738953.1__py3-none-any.whl → 2025.739265.0__py3-none-any.whl

mergeron/core/guidelines_boundaries.py

@@ -1,35 +1,40 @@
 """
-Routines for defining and analyzing boundaries for Guidelines standards,
+Methods for defining and analyzing boundaries for Guidelines standards,
 with a canvas on which to draw boundaries for Guidelines standards.
 
 """
 
+from __future__ import annotations
+
 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
 
 import numpy as np
-from attrs import define, field
+from attrs import Attribute, field, frozen, validators
 from mpmath import mp, mpf  # type: ignore
-from numpy.typing import NDArray
 
-from .. import _PKG_NAME, UPPAggrSelector  # noqa: TID252
-from . import UPPBoundarySpec
+from .. import (  # noqa: TID252
+    DEFAULT_REC_RATIO,
+    VERSION,
+    ArrayDouble,
+    HMGPubYear,
+    RECForm,
+    UPPAggrSelector,
+)
+from . import guidelines_boundary_functions as gbfn
 
-__version__ = version(_PKG_NAME)
+__version__ = VERSION
 
 
-mp.prec = 80
+mp.dps = 32
 mp.trap_complex = True
 
-HMGPubYear: TypeAlias = Literal[1992, 2010, 2023]
-
 
-@dataclass(slots=True, frozen=True)
+@dataclass(frozen=True)
 class HMGThresholds:
     delta: float
+    fc: float
     rec: float
     guppi: float
     divr: float
@@ -37,67 +42,62 @@ 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.
+    ΔHHI, Recapture Ratio, GUPPI, Diversion ratio, CMCR, and IPR thresholds
+    constructed from concentration standards in Guidelines published in
+    1982, 1984, 1992, 2010, and 2023.
+
     """
 
-    pub_year: HMGPubYear
+    pub_year: HMGPubYear = field(
+        kw_only=False,
+        default=2023,
+        validator=validators.in_([1982, 1984, 1992, 2010, 2023]),
+    )
     """
-    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)
     """
     Negative presumption quantified on various measures
 
-    ΔHHI safeharbor bound, default recapture rate, GUPPI bound,
+    ΔHHI safeharbor bound, default recapture ratio, GUPPI bound,
     diversion ratio limit, CMCR, and IPR
     """
 
-    imputed_presumption: HMGThresholds = field(kw_only=True, default=None)
+    presumption: HMGThresholds = field(kw_only=True, default=None)
     """
-    Presumption of harm imputed from guidelines
+    Presumption of harm defined in HMG
 
-    ΔHHI bound inferred from strict numbers-equivalent
-    of (post-merger) HHI presumption, and corresponding default recapture rate,
-    GUPPI bound, diversion ratio limit, CMCR, and IPR
+    ΔHHI bound and corresponding default recapture ratio, GUPPI bound,
+    diversion ratio limit, CMCR, and IPR
     """
 
-    presumption: HMGThresholds = field(kw_only=True, default=None)
+    imputed_presumption: HMGThresholds = field(kw_only=True, default=None)
     """
-    Presumption of harm defined in HMG
+    Presumption of harm imputed from guidelines
 
-    ΔHHI bound and corresponding default recapture rate, GUPPI bound,
-    diversion ratio limit, CMCR, and IPR
+    ΔHHI bound inferred from strict numbers-equivalent
+    of (post-merger) HHI presumption, and corresponding default recapture ratio,
+    GUPPI bound, diversion ratio limit, CMCR, and IPR
     """
 
     def __attrs_post_init__(self, /) -> None:
-        # In the 2023 Guidlines, the agencies do not define a
+        # In the 2023 Guidelines, the agencies do not define a
         # negative presumption, or safeharbor. Practically speaking,
         # given resource constraints and loss aversion, it is likely
         # that staff only investigates mergers that meet the presumption;
         # thus, here, the tentative delta safeharbor under
         # the 2023 Guidelines is 100 points
         _hhi_p, _dh_s, _dh_p = {
-            1992: (0.18, 0.005, 0.01),
+            1982: (_s1982 := (0.18, 0.005, 0.01)),
+            1984: _s1982,
+            1992: _s1982,
             2010: (0.25, 0.01, 0.02),
             2023: (0.18, 0.01, 0.01),
         }[self.pub_year]
@@ -107,1143 +107,355 @@ 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),
-                _dr := round_cust(1 / (_fc + 1)),
+                _fc := int(np.ceil(1 / _hhi_p)),
+                _r := float(_r_s := gbfn.round_cust(_fc / (_fc + 1), frac=0.05)),
+                _g := float(guppi_from_delta(_dh_s, m_star=1.0, r_bar=_r)),
+                _dr := float(1 - _r_s),
                 _cmcr := 0.03,  # Not strictly a Guidelines standard
-                _ipr := _g_s,  # Not strictly a Guidelines standard
+                _ipr := _g,  # Not strictly a Guidelines standard
             ),
         )
 
-        # imputed_presumption is relevant for 2010 Guidelines
+        object.__setattr__(
+            self, "presumption", HMGThresholds(_dh_p, _fc, _r, _g, _dr, _cmcr, _ipr)
+        )
+
+        # imputed_presumption is relevant for presumptions implicating
+        # mergers *to* symmetry in numbers-equivalent of post-merger HHI
+        # as in 2010 U.S.Guidelines
         object.__setattr__(
             self,
             "imputed_presumption",
             (
                 HMGThresholds(
-                    _dh_i := 2 * (0.5 / _fc) ** 2,
-                    _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)),
+                    2 * (0.5 / _fc) ** 2,
+                    _fc,
+                    float(
+                        _r_i := gbfn.round_cust(
+                            (_fc - 1 / 2) / (_fc + 1 / 2), frac=0.05
+                        )
+                    ),
+                    _g,
+                    float((1 - _r_i) / 2),
                     _cmcr,
-                    _g_i,
+                    _ipr := _g,
                 )
                 if self.pub_year == 2010
                 else HMGThresholds(
-                    _dh_i := 2 * (1 / (_fc + 1)) ** 2,
-                    _r,
-                    _g_i := gbd_from_dsf(_dh_i, m_star=1.0, r_bar=_r),
-                    _dr,
-                    _cmcr,
-                    _g_i,
+                    2 * (1 / (_fc + 1)) ** 2, _fc, _r, _g, _dr, _cmcr, _ipr
                 )
             ),
         )
 
-        object.__setattr__(
-            self,
-            "presumption",
-            HMGThresholds(
-                _dh_p,
-                _r,
-                _g_p := gbd_from_dsf(_dh_p, m_star=1.0, r_bar=_r),
-                _dr,
-                _cmcr,
-                _ipr := _g_p,
-            ),
-        )
 
+@frozen
+class ConcentrationBoundary:
+    """Concentration parameters, boundary coordinates, and area under concentration boundary."""
 
-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.
+    measure_name: Literal[
+        "ΔHHI", "Combined share", "Pre-merger HHI", "Post-merger HHI"
+    ] = field(kw_only=False, default="ΔHHI")
 
-    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
-    ----------
+    @measure_name.validator  # pyright: ignore
+    def __mnv(
+        _instance: ConcentrationBoundary, _attribute: Attribute[str], _value: str, /
+    ) -> None:
+        if _value not in (
+            "ΔHHI",
+            "Combined share",
+            "Pre-merger HHI",
+            "Post-merger HHI",
+        ):
+            raise ValueError(f"Invalid name for a concentration measure, {_value!r}.")
 
-    .. [2] C++ Reference, https://en.cppreference.com/w/cpp/numeric/lerp
+    threshold: float = field(kw_only=False, default=0.01)
 
-    """
+    @threshold.validator  # pyright: ignore
+    def __tv(
+        _instance: ConcentrationBoundary, _attribute: Attribute[float], _value: float, /
+    ) -> None:
+        if not 0 <= _value <= 1:
+            raise ValueError("Concentration threshold must lie between 0 and 1.")
 
-    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
-) -> float:
-    """
-    Translate ∆HHI bound to GUPPI bound.
-
-    Parameters
-    ----------
-    _deltasf
-        Specified ∆HHI bound.
-    m_star
-        Parametric price-cost margin.
-    r_bar
-        Default recapture rate.
-
-    Returns
-    -------
-        GUPPI bound corresponding to ∆HHI bound, at given margin and recapture rate.
-
-    """
-    return round_cust(
-        m_star * r_bar * (_s_m := np.sqrt(_deltasf / 2)) / (1 - _s_m),
-        frac=0.005,
-        rounding_mode="ROUND_HALF_DOWN",
+    precision: int = field(
+        kw_only=False, default=5, validator=validators.instance_of(int)
     )
 
+    coordinates: ArrayDouble = field(init=False, kw_only=True)
+    """Market-share pairs as Cartesian coordinates of points on the concentration boundary."""
 
-def critical_shrratio(
-    _gbd: float = 0.06,
-    /,
-    *,
-    m_star: float = 1.00,
-    r_bar: float = 0.80,
-    frac: float = 1e-16,
-) -> mpf:
-    """
-    Corollary to GUPPI bound.
+    area: float = field(init=False, kw_only=True)
+    """Area under the concentration boundary."""
 
-    Parameters
-    ----------
-    _gbd
-        Specified GUPPI bound.
-    m_star
-        Parametric price-cost margin.
-    r_bar
-        Default recapture rate.
-
-    Returns
-    -------
-        Critical share ratio (share ratio bound) corresponding to the GUPPI bound
-        for given margin and recapture rate.
+    def __attrs_post_init__(self, /) -> None:
+        match self.measure_name:
+            case "ΔHHI":
+                _conc_fn = gbfn.hhi_delta_boundary
+            case "Combined share":
+                _conc_fn = gbfn.combined_share_boundary
+            case "Pre-merger HHI":
+                _conc_fn = gbfn.hhi_pre_contrib_boundary
+            case "Post-merger HHI":
+                _conc_fn = gbfn.hhi_post_contrib_boundary
 
-    """
-    return round_cust(mpf(f"{_gbd}") / mp.fmul(f"{m_star}", f"{r_bar}"), frac=frac)
+        _boundary = _conc_fn(self.threshold, dps=self.precision)
+        object.__setattr__(self, "coordinates", _boundary.coordinates)
+        object.__setattr__(self, "area", _boundary.area)
 
 
-def shr_from_gbd(
-    _gbd: float = 0.06, /, *, m_star: float = 1.00, r_bar: float = 0.80
-) -> float:
+@frozen
+class DiversionRatioBoundary:
     """
-    Symmetric-firm share for given GUPPI, margin, and recapture rate.
+    Diversion ratio specification, boundary coordinates, and area under boundary.
 
-    Parameters
-    ----------
-    _gbd
-        GUPPI bound.
-    m_star
-        Parametric price-cost margin.
-    r_bar
-        Default recapture rate.
-
-    Returns
-    -------
-    float
-        Symmetric firm market share on GUPPI boundary, for given margin and
-        recapture rate.
+    Along with the default diversion ratio and recapture ratio,
+    a diversion ratio boundary specification includes the recapture form --
+    whether fixed for both merging firms' products ("proportional") or
+    consistent with share-proportionality, i.e., "inside-out";
+    the method of aggregating diversion ratios for the two products, and
+    the precision for the estimate of area under the divertion ratio boundary
+    (also defines the number of points on the boundary).
 
     """
 
-    return round_cust(
-        (_d0 := critical_shrratio(_gbd, 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.
+    diversion_ratio: float = field(kw_only=False, default=0.065)
 
-    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,
+    @diversion_ratio.validator
+    def __dvv(
+        _instance: DiversionRatioBoundary,
+        _attribute: Attribute[float],
+        _value: float,
         /,
-        *,
-        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
+    ) -> None:
+        if not (isinstance(_value, float) and 0 <= _value <= 1):
+            raise ValueError(
+                "Margin-adjusted benchmark share ratio must lie between 0 and 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, /, *, dh_dps: 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.
-    dh_dps
-        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))),
-        dh_dps,
+    recapture_ratio: float = field(
+        kw_only=False,
+        default=DEFAULT_REC_RATIO,
+        validator=validators.instance_of(float),
     )
 
-
-def dh_area_quad(_dh_val: float = 0.01, /, *, dh_dps: int = 9) -> float:
+    recapture_form: RECForm | None = field(kw_only=True, default=RECForm.INOUT)
     """
-    Area under the ΔHHI boundary.
+    The form of the recapture ratio.
 
-    When the given ΔHHI bound matches a Guidelines safeharbor,
-    the area under the boundary is half the intrinsic clearance rate
-    for the ΔHHI safeharbor.
+    When :attr:`mergeron.RECForm.INOUT`, the recapture ratio for
+    he product having the smaller market-share is assumed to equal the default,
+    and the recapture ratio for the product with the larger market-share is
+    computed assuming MNL demand. Fixed recapture ratios are specified as
+    :attr:`mergeron.RECForm.FIXED`. (To specify that recapture ratios be
+    constructed from the generated purchase-probabilities for products in
+    the market and for the outside good, specify :attr:`mergeron.RECForm.OUTIN`.)
 
-    Parameters
-    ----------
-    _dh_val
-        Merging-firms' ΔHHI bound.
-    dh_dps
-        Specified precision in decimal places.
-
-    Returns
-    -------
-        Area under ΔHHI boundary.
+    The GUPPI boundary is a continuum of diversion ratio boundaries conditional on
+    price-cost margins, :math:`d_{ij} = g_i * p_i / (m_j * p_j)`,
+    with :math:`d_{ij}` the diverion ratio from product :math:`i` to product :math:`j`;
+    :math:`g_i` the GUPPI for product :math:`i`;
+    :math:`m_j` the margin for product :math:`j`; and
+    :math:`p_i, p_j` the prices of goods :math:`i, j`, respectively.
 
     """
 
-    _dh_val = mpf(f"{_dh_val}")
-    _s_naught = (1 - mp.sqrt(1 - 2 * _dh_val)) / 2
+    @recapture_form.validator
+    def __rsv(
+        _instance: DiversionRatioBoundary,
+        _attribute: Attribute[RECForm],
+        _value: RECForm,
+        /,
+    ) -> None:
+        if _value and not (isinstance(_value, RECForm)):
+            raise ValueError(f"Invalid recapture specification, {_value!r}.")
+        if _value == RECForm.OUTIN and _instance.recapture_ratio:
+            raise ValueError(
+                f"Invalid recapture specification, {_value!r}. "
+                "You may consider specifying `mergeron.RECForm.INOUT` here, and "
+                'assigning the default recapture ratio as attribute, "recapture_ratio" of '
+                "this `DiversionRatioBoundarySpec` object."
+            )
+        if _value is None and _instance.agg_method != UPPAggrSelector.MAX:
+            raise ValueError(
+                f"Specified aggregation method, {_instance.agg_method} requires a recapture specification."
+            )
 
-    return round(
-        float(
-            _s_naught + mp.quad(lambda x: _dh_val / (2 * x), [_s_naught, 1 - _s_naught])
-        ),
-        dh_dps,
+    agg_method: UPPAggrSelector = field(
+        kw_only=True,
+        default=UPPAggrSelector.MAX,
+        validator=validators.instance_of(UPPAggrSelector),
     )
-
-
-def delta_hhi_boundary(
-    _dh_val: float = 0.01, /, *, prec: int = 5
-) -> GuidelinesBoundary:
     """
-    Generate the list of share combination on the ΔHHI boundary.
+    Method for aggregating the distinct diversion ratio measures for the two products.
 
-    Parameters
-    ----------
-    _dh_val:
-        Merging-firms' ΔHHI bound.
-    dh_dps
-        Number of decimal places for rounding reported shares.
-
-    Returns
-    -------
-        Array of share-pairs, area under boundary.
+    Distinct diversion ratio or GUPPI measures for the two merging-firms' products are
+    aggregated using the method specified by the `agg_method` attribute, which is specified
+    using the enum :class:`mergeron.UPPAggrSelector`.
 
     """
 
-    _dh_val = mpf(f"{_dh_val}")
-    _s_naught = 1 / 2 * (1 - mp.sqrt(1 - 2 * _dh_val))
-    _s_mid = mp.sqrt(_dh_val / 2)
-
-    _dh_step_sz = mp.power(10, -6)
-    _s_1 = np.array(mp.arange(_s_mid, _s_naught - mp.eps, -_dh_step_sz))
-    _s_2 = _dh_val / (2 * _s_1)
-
-    # Boundary points
-    _dh_half = np.row_stack((
-        np.column_stack((_s_1, _s_2)),
-        np.array([(mpf("0.0"), mpf("1.0"))]),
-    ))
-    _dh_bdry_pts = np.row_stack((np.flip(_dh_half, 0), np.flip(_dh_half[1:], 1)))
-
-    _s_1_pts, _s_2_pts = np.split(_dh_bdry_pts, 2, axis=1)
-    return GuidelinesBoundary(
-        np.column_stack((
-            np.array(_s_1_pts, np.float64),
-            np.array(_s_2_pts, np.float64),
-        )),
-        dh_area(_dh_val, dh_dps=prec),
+    precision: int = field(
+        kw_only=False, default=5, validator=validators.instance_of(int)
     )
-
-
-def combined_share_boundary(
-    _s_intcpt: float = 0.0625, /, *, bdry_dps: int = 10
-) -> GuidelinesBoundary:
-    """
-    Share combinations on the merging-firms' combined share boundary.
-
-    Assumes symmetric merging-firm margins. The combined-share is
-    congruent to the post-merger HHI contribution boundary, as the
-    post-merger HHI bound is the square of the combined-share bound.
-
-    Parameters
-    ----------
-    _s_intcpt:
-        Merging-firms' combined share.
-    bdry_dps
-        Number of decimal places for rounding reported shares.
-
-    Returns
-    -------
-        Array of share-pairs, area under boundary.
-
     """
-    _s_intcpt = mpf(f"{_s_intcpt}")
-    _s_mid = _s_intcpt / 2
-
-    _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), bdry_dps),
-    )
+    The number of decimal places of precision for the estimated area under the UPP boundary.
 
+    Leaving this attribute unspecified will result in the default precision,
+    which varies based on the `agg_method` attribute, reflecting
+    the limit of precision available from the underlying functions. The number of
+    boundary points generated is also defined based on this attribute.
 
-def hhi_pre_contrib_boundary(
-    _hhi_contrib: float = 0.03125, /, *, bdry_dps: int = 5
-) -> GuidelinesBoundary:
     """
-    Share combinations on the premerger HHI contribution boundary.
 
-    Parameters
-    ----------
-    _hhi_contrib:
-        Merging-firms' pre-merger HHI contribution bound.
-    bdry_dps
-        Number of decimal places for rounding reported shares.
+    coordinates: ArrayDouble = field(init=False, kw_only=True)
+    """Market-share pairs as Cartesian coordinates of points on the diversion ratio boundary."""
 
-    Returns
-    -------
-        Array of share-pairs, area under boundary.
+    area: float = field(init=False, kw_only=True)
+    """Area under the diversion ratio boundary."""
 
-    """
-    _hhi_contrib = mpf(f"{_hhi_contrib}")
-    _s_mid = mp.sqrt(_hhi_contrib / 2)
-
-    _bdry_step_sz = mp.power(10, -bdry_dps)
-    # Range-limit is 0 less a step, which is -1 * step-size
-    _s_1 = np.array(mp.arange(_s_mid, -_bdry_step_sz, -_bdry_step_sz), np.float64)
-    _s_2 = np.sqrt(_hhi_contrib - _s_1**2).astype(np.float64)
-    _bdry_pts_mid = np.column_stack((_s_1, _s_2))
-    return GuidelinesBoundary(
-        np.row_stack((np.flip(_bdry_pts_mid, 0), np.flip(_bdry_pts_mid[1:], 1))),
-        round(float(mp.pi * _hhi_contrib / 4), bdry_dps),
-    )
-
-
-def shrratio_boundary(_bdry_spec: UPPBoundarySpec) -> GuidelinesBoundary:
-    match _bdry_spec.agg_method:
-        case UPPAggrSelector.AVG:
-            return shrratio_boundary_xact_avg(
-                _bdry_spec.share_ratio,
-                _bdry_spec.rec,
-                recapture_spec=_bdry_spec.recapture_spec.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
-            )
-        case UPPAggrSelector.MIN:
-            return shrratio_boundary_min(
-                _bdry_spec.share_ratio,
-                _bdry_spec.rec,
-                recapture_spec=_bdry_spec.recapture_spec.value,  # type: ignore
-                prec=_bdry_spec.precision,
-            )
-        case UPPAggrSelector.DIS:
-            return shrratio_boundary_wtd_avg(
-                _bdry_spec.share_ratio,
-                _bdry_spec.rec,
-                agg_method="distance",
-                weighting=None,
-                recapture_spec=_bdry_spec.recapture_spec.value,  # type: ignore
-                prec=_bdry_spec.precision,
-            )
-        case _:
-            _weighting = (
-                "cross-product-share"
-                if _bdry_spec.agg_method.value.startswith("cross-product-share")
-                else "own-share"
-            )
-
-            _agg_method = (
-                "arithmetic"
-                if _bdry_spec.agg_method.value.endswith("average")
-                else "distance"
-            )
-
-            return shrratio_boundary_wtd_avg(
-                _bdry_spec.share_ratio,
-                _bdry_spec.rec,
-                agg_method=_agg_method,  # type: ignore
-                weighting=_weighting,  # type: ignore
-                recapture_spec=_bdry_spec.recapture_spec.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,
+    def __attrs_post_init__(self, /) -> None:
+        _share_ratio = critical_share_ratio(
+            self.diversion_ratio, r_bar=self.recapture_ratio
+        )
+        _upp_agg_kwargs: gbfn.ShareRatioBoundaryKeywords = {
+            "recapture_form": getattr(self.recapture_form, "value", "inside-out"),
+            "dps": self.precision,
+        }
+
+        match self.agg_method:
+            case UPPAggrSelector.DIS:
+                _upp_agg_fn = gbfn.shrratio_boundary_wtd_avg
+                _upp_agg_kwargs |= {"agg_method": "distance", "weighting": None}
+            case UPPAggrSelector.AVG:
+                _upp_agg_fn = gbfn.shrratio_boundary_xact_avg  # type: ignore
+            case UPPAggrSelector.MAX:
+                _upp_agg_fn = gbfn.shrratio_boundary_max  # type: ignore
+                _upp_agg_kwargs = {"dps": 10}  # replace here
+            case UPPAggrSelector.MIN:
+                _upp_agg_fn = gbfn.shrratio_boundary_min  # type: ignore
+                _upp_agg_kwargs |= {"dps": 10}  # update here
+            case _:
+                _upp_agg_fn = gbfn.shrratio_boundary_wtd_avg
+
+                _aggregator: Literal["arithmetic mean", "geometric mean", "distance"]
+                if self.agg_method.value.endswith("average"):
+                    _aggregator = "arithmetic mean"
+                elif self.agg_method.value.endswith("geometric mean"):
+                    _aggregator = "geometric mean"
+                else:
+                    _aggregator = "distance"
+
+                _wgt_type: Literal["cross-product-share", "own-share", None]
+                if self.agg_method.value.startswith("cross-product-share"):
+                    _wgt_type = "cross-product-share"
+                elif self.agg_method.value.startswith("own-share"):
+                    _wgt_type = "own-share"
+                else:
+                    _wgt_type = None
+
+                _upp_agg_kwargs |= {"agg_method": _aggregator, "weighting": _wgt_type}
+
+        _boundary = _upp_agg_fn(_share_ratio, self.recapture_ratio, **_upp_agg_kwargs)
+        object.__setattr__(self, "coordinates", _boundary.coordinates)
+        object.__setattr__(self, "area", _boundary.area)
+
+
+def guppi_from_delta(
+    _delta_bound: float = 0.01,
     /,
     *,
-    recapture_spec: str = "inside-out",
-    prec: int = 10,
-) -> GuidelinesBoundary:
+    m_star: float = 1.00,
+    r_bar: float = DEFAULT_REC_RATIO,
+) -> decimal.Decimal:
     """
-    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.
+    Translate ∆HHI bound to GUPPI bound.
 
     Parameters
     ----------
-    _delta_star
-        Margin-adjusted benchmark share ratio.
-    _r_val
-        Recapture ratio.
-    recapture_spec
-        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.
+    _delta_bound
+        Specified ∆HHI bound.
+    m_star
+        Parametric price-cost margin.
+    r_bar
+        Default recapture ratio.
 
     Returns
     -------
-        Array of share-pairs, area under boundary.
+        GUPPI bound corresponding to ∆HHI bound, at given margin and recapture ratio.
 
     """
-
-    _delta_star = mpf(f"{_delta_star}")
-    _s_intcpt = mpf("1.00")
-    _s_mid = _delta_star / (1 + _delta_star)
-
-    if recapture_spec == "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)
+    return gbfn.round_cust(
+        m_star * r_bar * (_s_m := np.sqrt(_delta_bound / 2)) / (1 - _s_m),
+        frac=0.005,
+        rounding_mode="ROUND_HALF_DOWN",
     )
 
 
-def shrratio_boundary_wtd_avg(
-    _delta_star: float = 0.075,
-    _r_val: float = 0.80,
+def critical_share_ratio(
+    _guppi_bound: float | decimal.Decimal = 0.075,
     /,
     *,
-    agg_method: Literal["arithmetic", "geometric", "distance"] = "arithmetic",
-    weighting: Literal["own-share", "cross-product-share"] | None = "own-share",
-    recapture_spec: Literal["inside-out", "proportional"] = "inside-out",
-    prec: int = 5,
-) -> GuidelinesBoundary:
+    m_star: float = 1.00,
+    r_bar: float = 1.00,
+    frac: float = 1e-16,
+) -> decimal.Decimal:
     """
-    Share combinations for the share-weighted average GUPPI boundary with symmetric
-    merging-firm margins.
+    Corollary to GUPPI bound.
 
     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_spec
-        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.
+    _guppi_bound
+        Specified GUPPI bound.
+    m_star
+        Parametric price-cost margin.
+    r_bar
+        Default recapture ratio.
 
     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_spec == "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_spec == "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
-        )
-
+        Critical share ratio (share ratio bound) corresponding to the GUPPI bound
+        for given margin and recapture ratio.
 
     """
-
-    _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_spec == "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_spec=recapture_spec,
-        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),
+    return gbfn.round_cust(
+        mpf(f"{_guppi_bound}") / mp.fmul(f"{m_star}", f"{r_bar}"), frac=frac
     )
 
 
-def shrratio_boundary_xact_avg(
-    _delta_star: float = 0.075,
-    _r_val: float = 0.80,
+def share_from_guppi(
+    _guppi_bound: float | decimal.Decimal = 0.065,
     /,
     *,
-    recapture_spec: Literal["inside-out", "proportional"] = "inside-out",
-    prec: int = 5,
-) -> GuidelinesBoundary:
+    m_star: float = 1.00,
+    r_bar: float = DEFAULT_REC_RATIO,
+) -> decimal.Decimal:
     """
-    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_spec = "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_spec = "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
-        )
+    Symmetric-firm share for given GUPPI, margin, and recapture ratio.
 
     Parameters
     ----------
-    _delta_star
-        Margin-adjusted benchmark share ratio.
-    _r_val
-        Recapture ratio
-    recapture_spec
-        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.
+    _guppi_bound
+        GUPPI bound.
+    m_star
+        Parametric price-cost margin.
+    r_bar
+        Default recapture ratio.
 
     Returns
     -------
-        Array of share-pairs, area under boundary, area under boundary.
+    float
+        Symmetric firm market share on GUPPI boundary, for given margin and
+        recapture ratio.
 
     """
 
-    _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_spec == "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)  # type: ignore
-
-        _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(  # type: ignore
-            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_spec}"'} 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),
+    return gbfn.round_cust(
+        (_d0 := critical_share_ratio(_guppi_bound, m_star=m_star, r_bar=r_bar))
+        / (1 + _d0)
     )
 
 
-def _shrratio_boundary_intcpt(
-    _s_2_pre: float,
-    _delta_star: mpf,
-    _r_val: mpf,
-    /,
-    *,
-    recapture_spec: 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_spec == "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
+if __name__ == "__main__":
+    print(
+        "This module defines classes with methods for generating boundaries for concentration and diversion-ratio screens."
+    )