scipy 1.16.2__cp314-cp314t-win_arm64.whl

scipy/optimize/_highspy/_highs_wrapper.py

@@ -0,0 +1,338 @@
+from warnings import warn
+
+import numpy as np
+import scipy.optimize._highspy._core as _h # type: ignore[import-not-found]
+from scipy.optimize._highspy import _highs_options as hopt  # type: ignore[attr-defined]
+from scipy.optimize import OptimizeWarning
+
+
+def _highs_wrapper(c, indptr, indices, data, lhs, rhs, lb, ub, integrality, options):
+    '''Solve linear programs using HiGHS [1]_.
+
+    Assume problems of the form:
+
+        MIN c.T @ x
+        s.t. lhs <= A @ x <= rhs
+             lb <= x <= ub
+
+    Parameters
+    ----------
+    c : 1-D array, (n,)
+        Array of objective value coefficients.
+    astart : 1-D array
+        CSC format index array.
+    aindex : 1-D array
+        CSC format index array.
+    avalue : 1-D array
+        Data array of the matrix.
+    lhs : 1-D array (or None), (m,)
+        Array of left hand side values of the inequality constraints.
+        If ``lhs=None``, then an array of ``-inf`` is assumed.
+    rhs : 1-D array, (m,)
+        Array of right hand side values of the inequality constraints.
+    lb : 1-D array (or None), (n,)
+        Lower bounds on solution variables x.  If ``lb=None``, then an
+        array of all `0` is assumed.
+    ub : 1-D array (or None), (n,)
+        Upper bounds on solution variables x.  If ``ub=None``, then an
+        array of ``inf`` is assumed.
+    options : dict
+        A dictionary of solver options
+
+    Returns
+    -------
+    res : dict
+
+        If model_status is one of kOptimal,
+        kObjectiveBound, kTimeLimit,
+        kIterationLimit:
+
+            - ``status`` : HighsModelStatus
+                Model status code.
+
+            - ``message`` : str
+                Message corresponding to model status code.
+
+            - ``x`` : list
+                Solution variables.
+
+            - ``slack`` : list
+                Slack variables.
+
+            - ``lambda`` : list
+                Lagrange multipliers associated with the constraints
+                Ax = b.
+
+            - ``s`` : list
+                Lagrange multipliers associated with the constraints
+                x >= 0.
+
+            - ``fun``
+                Final objective value.
+
+            - ``simplex_nit`` : int
+                Number of iterations accomplished by the simplex
+                solver.
+
+            - ``ipm_nit`` : int
+                Number of iterations accomplished by the interior-
+                point solver.
+
+        If model_status is not one of the above:
+
+            - ``status`` : HighsModelStatus
+                Model status code.
+
+            - ``message`` : str
+                Message corresponding to model status code.
+
+    Notes
+    -----
+    If ``options['write_solution_to_file']`` is ``True`` but
+    ``options['solution_file']`` is unset or ``''``, then the solution
+    will be printed to ``stdout``.
+
+    If any iteration limit is reached, no solution will be
+    available.
+
+    ``OptimizeWarning`` will be raised if any option value set by
+    the user is found to be incorrect.
+
+    References
+    ----------
+    .. [1] https://highs.dev/
+    .. [2] https://www.maths.ed.ac.uk/hall/HiGHS/HighsOptions.html
+    '''
+    numcol = c.size
+    numrow = rhs.size
+    isMip = integrality is not None and np.sum(integrality) > 0
+
+    # default "null" return values
+    res = {
+        "x": None,
+        "fun": None,
+    }
+
+    # Fill up a HighsLp object
+    lp = _h.HighsLp()
+    lp.num_col_ = numcol
+    lp.num_row_ = numrow
+    lp.a_matrix_.num_col_ = numcol
+    lp.a_matrix_.num_row_ = numrow
+    lp.a_matrix_.format_ = _h.MatrixFormat.kColwise
+    lp.col_cost_ = c
+    lp.col_lower_ = lb
+    lp.col_upper_ = ub
+    lp.row_lower_ = lhs
+    lp.row_upper_ = rhs
+    lp.a_matrix_.start_ = indptr
+    lp.a_matrix_.index_ = indices
+    lp.a_matrix_.value_ = data
+    if integrality.size > 0:
+        lp.integrality_ = [_h.HighsVarType(i) for i in integrality]
+
+    # Make a Highs object and pass it everything
+    highs = _h._Highs()
+    highs_options = _h.HighsOptions()
+    hoptmanager = hopt.HighsOptionsManager()
+    for key, val in options.items():
+        # handle filtering of unsupported and default options
+        if val is None or key in ("sense",):
+            continue
+
+        # ask for the option type
+        opt_type = hoptmanager.get_option_type(key)
+        if -1 == opt_type:
+            warn(
+                f"Unrecognized options detected: {dict({key: val})}",
+                OptimizeWarning,
+                stacklevel=2,
+            )
+            continue
+        else:
+            if key in ("presolve", "parallel"):
+                # handle fake bools (require bool -> str conversions)
+                if isinstance(val, bool):
+                    val = "on" if val else "off"
+                else:
+                    warn(
+                        f'Option f"{key}" is "{val}", but only True or False is '
+                        f"allowed. Using default.",
+                        OptimizeWarning,
+                        stacklevel=2,
+                    )
+                    continue
+            opt_type = _h.HighsOptionType(opt_type)
+            status, msg = check_option(highs, key, val)
+            if opt_type == _h.HighsOptionType.kBool:
+                if not isinstance(val, bool):
+                    warn(
+                        f'Option f"{key}" is "{val}", but only True or False is '
+                        f"allowed. Using default.",
+                        OptimizeWarning,
+                        stacklevel=2,
+                    )
+                    continue
+
+            # warn or set option
+            if status != 0:
+                warn(msg, OptimizeWarning, stacklevel=2)
+            else:
+                setattr(highs_options, key, val)
+
+    opt_status = highs.passOptions(highs_options)
+    if opt_status == _h.HighsStatus.kError:
+        res.update(
+            {
+                "status": highs.getModelStatus(),
+                "message": highs.modelStatusToString(highs.getModelStatus()),
+            }
+        )
+        return res
+
+    init_status = highs.passModel(lp)
+    if init_status == _h.HighsStatus.kError:
+        # if model fails to load, highs.getModelStatus() will be NOT_SET
+        err_model_status = _h.HighsModelStatus.kModelError
+        res.update(
+            {
+                "status": err_model_status,
+                "message": highs.modelStatusToString(err_model_status),
+            }
+        )
+        return res
+
+    # Solve the LP
+    run_status = highs.run()
+    if run_status == _h.HighsStatus.kError:
+        res.update(
+            {
+                "status": highs.getModelStatus(),
+                "message": highs.modelStatusToString(highs.getModelStatus()),
+            }
+        )
+        return res
+
+    # Extract what we need from the solution
+    model_status = highs.getModelStatus()
+
+    # it should always be safe to get the info object
+    info = highs.getInfo()
+
+    # Failure modes:
+    #     LP: if we have anything other than an Optimal status, it
+    #         is unsafe (and unhelpful) to read any results
+    #    MIP: has a non-Optimal status or has timed out/reached max iterations
+    #             1) If not Optimal/TimedOut/MaxIter status, there is no solution
+    #             2) If TimedOut/MaxIter status, there may be a feasible solution.
+    #                if the objective function value is not Infinity, then the
+    #                current solution is feasible and can be returned.  Else, there
+    #                is no solution.
+    mipFailCondition = model_status not in (
+        _h.HighsModelStatus.kOptimal,
+        _h.HighsModelStatus.kTimeLimit,
+        _h.HighsModelStatus.kIterationLimit,
+        _h.HighsModelStatus.kSolutionLimit,
+    ) or (
+        model_status
+        in {
+            _h.HighsModelStatus.kTimeLimit,
+            _h.HighsModelStatus.kIterationLimit,
+            _h.HighsModelStatus.kSolutionLimit,
+        }
+        and (info.objective_function_value == _h.kHighsInf)
+    )
+    lpFailCondition = model_status != _h.HighsModelStatus.kOptimal
+    if (isMip and mipFailCondition) or (not isMip and lpFailCondition):
+        res.update(
+            {
+                "status": model_status,
+                "message": "model_status is "
+                f"{highs.modelStatusToString(model_status)}; "
+                "primal_status is "
+                f"{highs.solutionStatusToString(info.primal_solution_status)}",
+                "simplex_nit": info.simplex_iteration_count,
+                "ipm_nit": info.ipm_iteration_count,
+                "crossover_nit": info.crossover_iteration_count,
+            }
+        )
+        return res
+
+    # Should be safe to read the solution:
+    solution = highs.getSolution()
+    basis = highs.getBasis()
+
+    # Lagrangians for bounds based on column statuses
+    marg_bnds = np.zeros((2, numcol))
+    basis_col_status = basis.col_status
+    solution_col_dual = solution.col_dual
+    for ii in range(numcol):
+        if basis_col_status[ii] == _h.HighsBasisStatus.kLower:
+            marg_bnds[0, ii] = solution_col_dual[ii]
+        elif basis_col_status[ii] == _h.HighsBasisStatus.kUpper:
+            marg_bnds[1, ii] = solution_col_dual[ii]
+
+    res.update(
+        {
+            "status": model_status,
+            "message": highs.modelStatusToString(model_status),
+            # Primal solution
+            "x": np.array(solution.col_value),
+            # Ax + s = b => Ax = b - s
+            # Note: this is for all constraints (A_ub and A_eq)
+            "slack": rhs - solution.row_value,
+            # lambda are the lagrange multipliers associated with Ax=b
+            "lambda": np.array(solution.row_dual),
+            "marg_bnds": marg_bnds,
+            "fun": info.objective_function_value,
+            "simplex_nit": info.simplex_iteration_count,
+            "ipm_nit": info.ipm_iteration_count,
+            "crossover_nit": info.crossover_iteration_count,
+        }
+    )
+
+    if isMip:
+        res.update(
+            {
+                "mip_node_count": info.mip_node_count,
+                "mip_dual_bound": info.mip_dual_bound,
+                "mip_gap": info.mip_gap,
+            }
+        )
+
+    return res
+
+
+def check_option(highs_inst, option, value):
+    status, option_type = highs_inst.getOptionType(option)
+    hoptmanager = hopt.HighsOptionsManager()
+
+    if status != _h.HighsStatus.kOk:
+        return -1, "Invalid option name."
+
+    valid_types = {
+        _h.HighsOptionType.kBool: bool,
+        _h.HighsOptionType.kInt: int,
+        _h.HighsOptionType.kDouble: float,
+        _h.HighsOptionType.kString: str,
+    }
+
+    expected_type = valid_types.get(option_type, None)
+
+    if expected_type is str:
+        if not hoptmanager.check_string_option(option, value):
+            return -1, "Invalid option value."
+    if expected_type is float:
+        if not hoptmanager.check_double_option(option, value):
+            return -1, "Invalid option value."
+    if expected_type is int:
+        if not hoptmanager.check_int_option(option, value):
+            return -1, "Invalid option value."
+
+    if expected_type is None:
+        return 3, "Unknown option type."
+
+    status, current_value = highs_inst.getOptionValue(option)
+    if status != _h.HighsStatus.kOk:
+        return 4, "Failed to validate option value."
+    return 0, "Check option succeeded."

scipy/optimize/_isotonic.py

@@ -0,0 +1,157 @@
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from ._optimize import OptimizeResult
+from ._pava_pybind import pava
+
+if TYPE_CHECKING:
+    import numpy.typing as npt
+
+
+__all__ = ["isotonic_regression"]
+
+
+def isotonic_regression(
+    y: "npt.ArrayLike",
+    *,
+    weights: "npt.ArrayLike | None" = None,
+    increasing: bool = True,
+) -> OptimizeResult:
+    r"""Nonparametric isotonic regression.
+
+    A (not strictly) monotonically increasing array `x` with the same length
+    as `y` is calculated by the pool adjacent violators algorithm (PAVA), see
+    [1]_. See the Notes section for more details.
+
+    Parameters
+    ----------
+    y : (N,) array_like
+        Response variable.
+    weights : (N,) array_like or None
+        Case weights.
+    increasing : bool
+        If True, fit monotonic increasing, i.e. isotonic, regression.
+        If False, fit a monotonic decreasing, i.e. antitonic, regression.
+        Default is True.
+
+    Returns
+    -------
+    res : OptimizeResult
+        The optimization result represented as a ``OptimizeResult`` object.
+        Important attributes are:
+
+        - ``x``: The isotonic regression solution, i.e. an increasing (or
+          decreasing) array of the same length than y, with elements in the
+          range from min(y) to max(y).
+        - ``weights`` : Array with the sum of case weights for each block
+          (or pool) B.
+        - ``blocks``: Array of length B+1 with the indices of the start
+          positions of each block (or pool) B. The j-th block is given by
+          ``x[blocks[j]:blocks[j+1]]`` for which all values are the same.
+
+    Notes
+    -----
+    Given data :math:`y` and case weights :math:`w`, the isotonic regression
+    solves the following optimization problem:
+
+    .. math::
+
+        \operatorname{argmin}_{x_i} \sum_i w_i (y_i - x_i)^2 \quad
+        \text{subject to } x_i \leq x_j \text{ whenever } i \leq j \,.
+
+    For every input value :math:`y_i`, it generates a value :math:`x_i` such
+    that :math:`x` is increasing (but not strictly), i.e.
+    :math:`x_i \leq x_{i+1}`. This is accomplished by the PAVA.
+    The solution consists of pools or blocks, i.e. neighboring elements of
+    :math:`x`, e.g. :math:`x_i` and :math:`x_{i+1}`, that all have the same
+    value.
+
+    Most interestingly, the solution stays the same if the squared loss is
+    replaced by the wide class of Bregman functions which are the unique
+    class of strictly consistent scoring functions for the mean, see [2]_
+    and references therein.
+
+    The implemented version of PAVA according to [1]_ has a computational
+    complexity of O(N) with input size N.
+
+    References
+    ----------
+    .. [1] Busing, F. M. T. A. (2022).
+           Monotone Regression: A Simple and Fast O(n) PAVA Implementation.
+           Journal of Statistical Software, Code Snippets, 102(1), 1-25.
+           :doi:`10.18637/jss.v102.c01`
+    .. [2] Jordan, A.I., Mühlemann, A. & Ziegel, J.F.
+           Characterizing the optimal solutions to the isotonic regression
+           problem for identifiable functionals.
+           Ann Inst Stat Math 74, 489-514 (2022).
+           :doi:`10.1007/s10463-021-00808-0`
+
+    Examples
+    --------
+    This example demonstrates that ``isotonic_regression`` really solves a
+    constrained optimization problem.
+
+    >>> import numpy as np
+    >>> from scipy.optimize import isotonic_regression, minimize
+    >>> y = [1.5, 1.0, 4.0, 6.0, 5.7, 5.0, 7.8, 9.0, 7.5, 9.5, 9.0]
+    >>> def objective(yhat, y):
+    ...     return np.sum((yhat - y)**2)
+    >>> def constraint(yhat, y):
+    ...     # This is for a monotonically increasing regression.
+    ...     return np.diff(yhat)
+    >>> result = minimize(objective, x0=y, args=(y,),
+    ...                   constraints=[{'type': 'ineq',
+    ...                                 'fun': lambda x: constraint(x, y)}])
+    >>> result.x
+    array([1.25      , 1.25      , 4.        , 5.56666667, 5.56666667,
+           5.56666667, 7.8       , 8.25      , 8.25      , 9.25      ,
+           9.25      ])
+    >>> result = isotonic_regression(y)
+    >>> result.x
+    array([1.25      , 1.25      , 4.        , 5.56666667, 5.56666667,
+           5.56666667, 7.8       , 8.25      , 8.25      , 9.25      ,
+           9.25      ])
+
+    The big advantage of ``isotonic_regression`` compared to calling
+    ``minimize`` is that it is more user friendly, i.e. one does not need to
+    define objective and constraint functions, and that it is orders of
+    magnitudes faster. On commodity hardware (in 2023), for normal distributed
+    input y of length 1000, the minimizer takes about 4 seconds, while
+    ``isotonic_regression`` takes about 200 microseconds.
+    """
+    yarr = np.atleast_1d(y)  # Check yarr.ndim == 1 is implicit (pybind11) in pava.
+    order = slice(None) if increasing else slice(None, None, -1)
+    x = np.array(yarr[order], order="C", dtype=np.float64, copy=True)
+    if weights is None:
+        wx = np.ones_like(yarr, dtype=np.float64)
+    else:
+        warr = np.atleast_1d(weights)
+
+        if not (yarr.ndim == warr.ndim == 1 and yarr.shape[0] == warr.shape[0]):
+            raise ValueError(
+                "Input arrays y and w must have one dimension of equal length."
+            )
+        if np.any(warr <= 0):
+            raise ValueError("Weights w must be strictly positive.")
+
+        wx = np.array(warr[order], order="C", dtype=np.float64, copy=True)
+    n = x.shape[0]
+    r = np.full(shape=n + 1, fill_value=-1, dtype=np.intp)
+    x, wx, r, b = pava(x, wx, r)
+    # Now that we know the number of blocks b, we only keep the relevant part
+    # of r and wx.
+    # As information: Due to the pava implementation, after the last block
+    # index, there might be smaller numbers appended to r, e.g.
+    # r = [0, 10, 8, 7] which in the end should be r = [0, 10].
+    r = r[:b + 1]  # type: ignore[assignment]
+    wx = wx[:b]
+    if not increasing:
+        x = x[::-1]
+        wx = wx[::-1]
+        r = r[-1] - r[::-1]
+    return OptimizeResult(
+        x=x,
+        weights=wx,
+        blocks=r,
+    )