From 9f0c54d5eb7efc1ad8ac2d72434860d9dae27641 Mon Sep 17 00:00:00 2001 From: Dave Woodruff Date: Thu, 7 May 2026 14:48:01 -0700 Subject: [PATCH] docs(rho_setting): document grad-rho options + flag deprecations The --grad-rho section previously documented only --grad-rho-multiplier out of six gradient-rho options. Add a bullet list covering all five previously-undocumented options (--grad-order-stat, --grad-rho-relative-bound, --eval-at-xhat, --indep-denom, plus the already-mentioned multiplier) with their defaults and a one-line operational description. Add a .. note:: deprecation notice to the --sep-rho and --reduced-costs-rho sections referencing #673 so users can plan migration; both rho setters now emit a DeprecationWarning at instantiation as part of the same issue's cleanup. grad_rho.rst stays a brief pointer; deeper algorithmic content is planned for after the academic paper lands. Add a .. _grad_rho: cross-reference label so rho_setting.rst can link to it. Co-Authored-By: Claude Opus 4.7 (1M context) --- doc/src/grad_rho.rst | 8 +++++--- doc/src/rho_setting.rst | 40 ++++++++++++++++++++++++++++++++++++---- 2 files changed, 41 insertions(+), 7 deletions(-) diff --git a/doc/src/grad_rho.rst b/doc/src/grad_rho.rst index 2e860c471..e4efac9a3 100644 --- a/doc/src/grad_rho.rst +++ b/doc/src/grad_rho.rst @@ -1,6 +1,8 @@ +.. _grad_rho: + Gradient-based Rho ================== -Gradient-based rho documentation has been consolidated into -:ref:`rho_setting`. See the "Gradient-based Rho" and "Dynamic Rho Updates" -sections there. +For the user-facing options that drive gradient-based rho, see the +"Gradient-based Rho" and "Dynamic Rho Updates" sections of +:ref:`rho_setting`. diff --git a/doc/src/rho_setting.rst b/doc/src/rho_setting.rst index 81ca479e5..a93b0ce9c 100644 --- a/doc/src/rho_setting.rst +++ b/doc/src/rho_setting.rst @@ -41,6 +41,12 @@ Uses the separation between scenario solutions to set rho. Enabled with: --sep-rho +.. note:: + ``--sep-rho`` is scheduled for deprecation; its functionality is + expected to be subsumed into ``--grad-rho``. Instantiating ``SepRho`` + now emits a ``DeprecationWarning``. See + `issue #673 `_. + Coefficient-based Rho (``--coeff-rho``) ---------------------------------------- @@ -76,19 +82,45 @@ Sets rho based on reduced costs from LP relaxations. Enabled with: Like ``--sensi-rho``, this will use existing rho values if available. +.. note:: + ``--reduced-costs-rho`` is scheduled for deprecation; reduced-cost + rho has not been demonstrated to be effective in practice. + Instantiating ``ReducedCostsRho`` now emits a ``DeprecationWarning``. + See `issue #673 `_. + Gradient-based Rho (``--grad-rho``) ------------------------------------ -Uses gradient information to set rho values. Enabled with: +Uses per-variable gradient information from the scenario subproblems +to set rho. Enabled with: .. code-block:: bash --grad-rho A detailed example is in ``examples.farmer.CI.farmer_rho_demo.py``. - -The ``--grad-rho-multiplier`` option provides a cumulative multiplier -applied when rho is set or updated. +See :ref:`grad_rho` for the algorithmic description (forthcoming). + +Options: + +- ``--grad-rho-multiplier`` (default ``1.0``): scalar multiplier + applied to every computed rho. +- ``--grad-order-stat`` (default ``0.5``): order statistic across + scenarios used to combine per-scenario rho values into one. ``0`` + selects the min, ``1`` the max, ``0.5`` the mean; values in + ``(0, 0.5)`` interpolate min-to-mean and values in ``(0.5, 1)`` + interpolate mean-to-max. +- ``--grad-rho-relative-bound`` (default ``100``): floor on the + primal-residual denominator relative to the consensus value (xbar). + Prevents tiny ``|x − xbar|`` from inflating rho when a variable is + near consensus. +- ``--eval-at-xhat`` (default off): when an xhat-producing spoke is + present (e.g. ``--xhatshuffle``), evaluate the gradient at the best + xhat seen so far instead of at the latest subproblem iterate values. + Falls back to the iterate values until the first xhat arrives. +- ``--indep-denom`` (default off): use a single + probability-weighted, MPI-Allreduced denominator across all + scenarios instead of a per-scenario denominator. Dynamic Rho Updates -------------------