result.py

Go to the documentation of this file.

#!/usr/bin/env python3
# Copyright 2010-2025 Google LLC
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
 
"""The output from solving a mathematical optimization problem from model.py."""
import dataclasses
import datetime
import enum
from typing import Dict, Iterable, List, Optional, overload
 
from ortools.math_opt import result_pb2
from ortools.math_opt.python import linear_constraints as linear_constraints_mod
from ortools.math_opt.python import model
from ortools.math_opt.python import solution
from ortools.math_opt.python import variables as variables_mod
from ortools.math_opt.solvers import osqp_pb2
from ortools.math_opt.solvers.gscip import gscip_pb2
 
_NO_DUAL_SOLUTION_ERROR = (
    "Best solution does not have an associated dual feasible solution."
)
_NO_BASIS_ERROR = "Best solution does not have an associated basis."
 
 
@enum.unique
class FeasibilityStatus(enum.Enum):
    """Problem feasibility status as claimed by the solver.
 
      (solver is not required to return a certificate for the claim.)
 
    Attributes:
      UNDETERMINED: Solver does not claim a status.
      FEASIBLE: Solver claims the problem is feasible.
      INFEASIBLE: Solver claims the problem is infeasible.
    """
 
    UNDETERMINED = result_pb2.FEASIBILITY_STATUS_UNDETERMINED
    FEASIBLE = result_pb2.FEASIBILITY_STATUS_FEASIBLE
    INFEASIBLE = result_pb2.FEASIBILITY_STATUS_INFEASIBLE
 
 
@dataclasses.dataclass(frozen=True)
class ProblemStatus:
    """Feasibility status of the primal problem and its dual (or dual relaxation).
 
    Statuses are as claimed by the solver and a dual relaxation is the dual of a
    continuous relaxation for the original problem (e.g. the LP relaxation of a
    MIP). The solver is not required to return a certificate for the feasibility
    or infeasibility claims (e.g. the solver may claim primal feasibility without
    returning a primal feasible solutuion). This combined status gives a
    comprehensive description of a solver's claims about feasibility and
    unboundedness of the solved problem. For instance,
      * a feasible status for primal and dual problems indicates the primal is
        feasible and bounded and likely has an optimal solution (guaranteed for
        problems without non-linear constraints).
      * a primal feasible and a dual infeasible status indicates the primal
        problem is unbounded (i.e. has arbitrarily good solutions).
    Note that a dual infeasible status by itself (i.e. accompanied by an
    undetermined primal status) does not imply the primal problem is unbounded as
    we could have both problems be infeasible. Also, while a primal and dual
    feasible status may imply the existence of an optimal solution, it does not
    guarantee the solver has actually found such optimal solution.
 
    Attributes:
      primal_status: Status for the primal problem.
      dual_status: Status for the dual problem (or for the dual of a continuous
        relaxation).
      primal_or_dual_infeasible: If true, the solver claims the primal or dual
        problem is infeasible, but it does not know which (or if both are
        infeasible). Can be true only when primal_problem_status =
        dual_problem_status = kUndetermined. This extra information is often
        needed when preprocessing determines there is no optimal solution to the
        problem (but can't determine if it is due to infeasibility, unboundedness,
        or both).
    """
 
    primal_status: FeasibilityStatus = FeasibilityStatus.UNDETERMINED
    dual_status: FeasibilityStatus = FeasibilityStatus.UNDETERMINED
    primal_or_dual_infeasible: bool = False
 
    def to_proto(self) -> result_pb2.ProblemStatusProto:
        """Returns an equivalent proto for a problem status."""
        return result_pb2.ProblemStatusProto(
            primal_status=self.primal_status.value,
            dual_status=self.dual_status.value,
            primal_or_dual_infeasible=self.primal_or_dual_infeasible,
        )
 
 
def parse_problem_status(proto: result_pb2.ProblemStatusProto) -> ProblemStatus:
    """Returns an equivalent ProblemStatus from the input proto."""
    primal_status_proto = proto.primal_status
    if primal_status_proto == result_pb2.FEASIBILITY_STATUS_UNSPECIFIED:
        raise ValueError("Primal feasibility status should not be UNSPECIFIED")
    dual_status_proto = proto.dual_status
    if dual_status_proto == result_pb2.FEASIBILITY_STATUS_UNSPECIFIED:
        raise ValueError("Dual feasibility status should not be UNSPECIFIED")
    return ProblemStatus(
        primal_status=FeasibilityStatus(primal_status_proto),
        dual_status=FeasibilityStatus(dual_status_proto),
        primal_or_dual_infeasible=proto.primal_or_dual_infeasible,
    )
 
 
@dataclasses.dataclass(frozen=True)
class ObjectiveBounds:
    """Bounds on the optimal objective value.
 
  MOE:begin_intracomment_strip
  See go/mathopt-objective-bounds for more details.
  MOE:end_intracomment_strip
 
  Attributes:
    primal_bound: Solver claims there exists a primal solution that is
      numerically feasible (i.e. feasible up to the solvers tolerance), and
      whose objective value is primal_bound.
 
      The optimal value is equal or better (smaller for min objectives and
      larger for max objectives) than primal_bound, but only up to
      solver-tolerances.
 
      MOE:begin_intracomment_strip
      See go/mathopt-objective-bounds for more details.
      MOE:end_intracomment_strip
    dual_bound: Solver claims there exists a dual solution that is numerically
      feasible (i.e. feasible up to the solvers tolerance), and whose objective
      value is dual_bound.
 
      For MIP solvers, the associated dual problem may be some continuous
      relaxation (e.g. LP relaxation), but it is often an implicitly defined
      problem that is a complex consequence of the solvers execution. For both
      continuous and MIP solvers, the optimal value is equal or worse (larger
      for min objective and smaller for max objectives) than dual_bound, but
      only up to solver-tolerances. Some continuous solvers provide a
      numerically safer dual bound through solver's specific output (e.g. for
      PDLP, pdlp_output.convergence_information.corrected_dual_objective).
 
      MOE:begin_intracomment_strip
      See go/mathopt-objective-bounds for more details.
      MOE:end_intracomment_strip
  """  # fmt: skip
 
    primal_bound: float = 0.0
    dual_bound: float = 0.0
 
    def to_proto(self) -> result_pb2.ObjectiveBoundsProto:
        """Returns an equivalent proto for objective bounds."""
        return result_pb2.ObjectiveBoundsProto(
            primal_bound=self.primal_bound, dual_bound=self.dual_bound
        )
 
 
def parse_objective_bounds(
    proto: result_pb2.ObjectiveBoundsProto,
) -> ObjectiveBounds:
    """Returns an equivalent ObjectiveBounds from the input proto."""
    return ObjectiveBounds(primal_bound=proto.primal_bound, dual_bound=proto.dual_bound)
 
 
@dataclasses.dataclass
class SolveStats:
    """Problem statuses and solve statistics returned by the solver.
 
    Attributes:
      solve_time: Elapsed wall clock time as measured by math_opt, roughly the
        time inside solve(). Note: this does not include work done building the
        model.
      simplex_iterations: Simplex iterations.
      barrier_iterations: Barrier iterations.
      first_order_iterations: First order iterations.
      node_count: Node count.
    """
 
    solve_time: datetime.timedelta = datetime.timedelta()
    simplex_iterations: int = 0
    barrier_iterations: int = 0
    first_order_iterations: int = 0
    node_count: int = 0
 
    def to_proto(self) -> result_pb2.SolveStatsProto:
        """Returns an equivalent proto for a solve stats."""
        result = result_pb2.SolveStatsProto(
            simplex_iterations=self.simplex_iterations,
            barrier_iterations=self.barrier_iterations,
            first_order_iterations=self.first_order_iterations,
            node_count=self.node_count,
        )
        result.solve_time.FromTimedelta(self.solve_time)
        return result
 
 
def parse_solve_stats(proto: result_pb2.SolveStatsProto) -> SolveStats:
    """Returns an equivalent SolveStats from the input proto."""
    result = SolveStats()
    result.solve_time = proto.solve_time.ToTimedelta()
    result.simplex_iterations = proto.simplex_iterations
    result.barrier_iterations = proto.barrier_iterations
    result.first_order_iterations = proto.first_order_iterations
    result.node_count = proto.node_count
    return result
 
 
@enum.unique
class TerminationReason(enum.Enum):
    """The reason a solve of a model terminated.
 
    These reasons are typically as reported by the underlying solver, e.g. we do
    not attempt to verify the precision of the solution returned.
 
    The values are:
       * OPTIMAL: A provably optimal solution (up to numerical tolerances) has
           been found.
       * INFEASIBLE: The primal problem has no feasible solutions.
       * UNBOUNDED: The primal problem is feasible and arbitrarily good solutions
           can be found along a primal ray.
       * INFEASIBLE_OR_UNBOUNDED: The primal problem is either infeasible or
           unbounded. More details on the problem status may be available in
           solve_stats.problem_status. Note that Gurobi's unbounded status may be
           mapped here as explained in
           go/mathopt-solver-specific#gurobi-inf-or-unb.
       * IMPRECISE: The problem was solved to one of the criteria above (Optimal,
           Infeasible, Unbounded, or InfeasibleOrUnbounded), but one or more
           tolerances was not met. Some primal/dual solutions/rays may be present,
           but either they will be slightly infeasible, or (if the problem was
           nearly optimal) their may be a gap between the best solution objective
           and best objective bound.
 
           Users can still query primal/dual solutions/rays and solution stats,
           but they are responsible for dealing with the numerical imprecision.
       * FEASIBLE: The optimizer reached some kind of limit and a primal feasible
           solution is returned. See SolveResultProto.limit_detail for detailed
           description of the kind of limit that was reached.
       * NO_SOLUTION_FOUND: The optimizer reached some kind of limit and it did
           not find a primal feasible solution. See SolveResultProto.limit_detail
           for detailed description of the kind of limit that was reached.
       * NUMERICAL_ERROR: The algorithm stopped because it encountered
           unrecoverable numerical error. No solution information is present.
       * OTHER_ERROR: The algorithm stopped because of an error not covered by one
           of the statuses defined above. No solution information is present.
    """
 
    OPTIMAL = result_pb2.TERMINATION_REASON_OPTIMAL
    INFEASIBLE = result_pb2.TERMINATION_REASON_INFEASIBLE
    UNBOUNDED = result_pb2.TERMINATION_REASON_UNBOUNDED
    INFEASIBLE_OR_UNBOUNDED = result_pb2.TERMINATION_REASON_INFEASIBLE_OR_UNBOUNDED
    IMPRECISE = result_pb2.TERMINATION_REASON_IMPRECISE
    FEASIBLE = result_pb2.TERMINATION_REASON_FEASIBLE
    NO_SOLUTION_FOUND = result_pb2.TERMINATION_REASON_NO_SOLUTION_FOUND
    NUMERICAL_ERROR = result_pb2.TERMINATION_REASON_NUMERICAL_ERROR
    OTHER_ERROR = result_pb2.TERMINATION_REASON_OTHER_ERROR
 
 
@enum.unique
class Limit(enum.Enum):
    """The optimizer reached a limit, partial solution information may be present.
 
    Values are:
       * UNDETERMINED: The underlying solver does not expose which limit was
           reached.
       * ITERATION: An iterative algorithm stopped after conducting the
           maximum number of iterations (e.g. simplex or barrier iterations).
       * TIME: The algorithm stopped after a user-specified amount of
           computation time.
       * NODE: A branch-and-bound algorithm stopped because it explored a
           maximum number of nodes in the branch-and-bound tree.
       * SOLUTION: The algorithm stopped because it found the required
           number of solutions. This is often used in MIPs to get the solver to
           return the first feasible solution it encounters.
       * MEMORY: The algorithm stopped because it ran out of memory.
       * OBJECTIVE: The algorithm stopped because it found a solution better
           than a minimum limit set by the user.
       * NORM: The algorithm stopped because the norm of an iterate became
           too large.
       * INTERRUPTED: The algorithm stopped because of an interrupt signal or a
           user interrupt request.
       * SLOW_PROGRESS: The algorithm stopped because it was unable to continue
           making progress towards the solution.
       * OTHER: The algorithm stopped due to a limit not covered by one of the
           above. Note that UNDETERMINED is used when the reason cannot be
           determined, and OTHER is used when the reason is known but does not fit
           into any of the above alternatives.
    """
 
    UNDETERMINED = result_pb2.LIMIT_UNDETERMINED
    ITERATION = result_pb2.LIMIT_ITERATION
    TIME = result_pb2.LIMIT_TIME
    NODE = result_pb2.LIMIT_NODE
    SOLUTION = result_pb2.LIMIT_SOLUTION
    MEMORY = result_pb2.LIMIT_MEMORY
    OBJECTIVE = result_pb2.LIMIT_OBJECTIVE
    NORM = result_pb2.LIMIT_NORM
    INTERRUPTED = result_pb2.LIMIT_INTERRUPTED
    SLOW_PROGRESS = result_pb2.LIMIT_SLOW_PROGRESS
    OTHER = result_pb2.LIMIT_OTHER
 
 
@dataclasses.dataclass
class Termination:
    """An explanation of why the solver stopped.
 
    Attributes:
      reason: Why the solver stopped, e.g. it found a provably optimal solution.
        Additional information in `limit` when value is FEASIBLE or
        NO_SOLUTION_FOUND, see `limit` for details.
      limit: If the solver stopped early, what caused it to stop. Have value
        UNSPECIFIED when reason is not NO_SOLUTION_FOUND or FEASIBLE. May still be
        UNSPECIFIED when reason is NO_SOLUTION_FOUND or FEASIBLE, some solvers
        cannot fill this in.
      detail: Additional, information beyond reason about why the solver stopped,
        typically solver specific.
      problem_status: Feasibility statuses for primal and dual problems.
      objective_bounds: Bounds on the optimal objective value.
    """
 
    reason: TerminationReason = TerminationReason.OPTIMAL
    limit: Optional[Limit] = None
    detail: str = ""
    problem_status: ProblemStatus = ProblemStatus()
    objective_bounds: ObjectiveBounds = ObjectiveBounds()
 
    def to_proto(self) -> result_pb2.TerminationProto:
        """Returns an equivalent protocol buffer to this Termination."""
        return result_pb2.TerminationProto(
            reason=self.reason.value,
            limit=(
                result_pb2.LIMIT_UNSPECIFIED if self.limit is None else self.limit.value
            ),
            detail=self.detail,
            problem_status=self.problem_status.to_proto(),
            objective_bounds=self.objective_bounds.to_proto(),
        )
 
 
def parse_termination(
    termination_proto: result_pb2.TerminationProto,
) -> Termination:
    """Returns a Termination that is equivalent to termination_proto."""
    reason_proto = termination_proto.reason
    limit_proto = termination_proto.limit
    if reason_proto == result_pb2.TERMINATION_REASON_UNSPECIFIED:
        raise ValueError("Termination reason should not be UNSPECIFIED")
    reason_is_limit = (
        reason_proto == result_pb2.TERMINATION_REASON_NO_SOLUTION_FOUND
    ) or (reason_proto == result_pb2.TERMINATION_REASON_FEASIBLE)
    limit_set = limit_proto != result_pb2.LIMIT_UNSPECIFIED
    if reason_is_limit != limit_set:
        raise ValueError(
            f"Termination limit (={limit_proto})) should take value other than "
            f"UNSPECIFIED if and only if termination reason (={reason_proto}) is "
            "FEASIBLE or NO_SOLUTION_FOUND"
        )
    termination = Termination()
    termination.reason = TerminationReason(reason_proto)
    termination.limit = Limit(limit_proto) if limit_set else None
    termination.detail = termination_proto.detail
    termination.problem_status = parse_problem_status(termination_proto.problem_status)
    termination.objective_bounds = parse_objective_bounds(
        termination_proto.objective_bounds
    )
    return termination
 
 
@dataclasses.dataclass
class SolveResult:
    """The result of solving an optimization problem defined by a Model.
 
    We attempt to return as much solution information (primal_solutions,
    primal_rays, dual_solutions, dual_rays) as each underlying solver will provide
    given its return status. Differences in the underlying solvers result in a
    weak contract on what fields will be populated for a given termination
    reason. This is discussed in detail in termination_reasons.md, and the most
    important points are summarized below:
      * When the termination reason is optimal, there will be at least one primal
        solution provided that will be feasible up to the underlying solver's
        tolerances.
      * Dual solutions are only given for convex optimization problems (e.g.
        linear programs, not integer programs).
      * A basis is only given for linear programs when solved by the simplex
        method (e.g., not with PDLP).
      * Solvers have widely varying support for returning primal and dual rays.
        E.g. a termination_reason of unbounded does not ensure that a feasible
        solution or a primal ray is returned, check termination_reasons.md for
        solver specific guarantees if this is needed. Further, many solvers will
        provide the ray but not the feasible solution when returning an unbounded
        status.
      * When the termination reason is that a limit was reached or that the result
        is imprecise, a solution may or may not be present. Further, for some
        solvers (generally, convex optimization solvers, not MIP solvers), the
        primal or dual solution may not be feasible.
 
    Solver specific output is also returned for some solvers (and only information
    for the solver used will be populated).
 
    Attributes:
      termination: The reason the solver stopped.
      solve_stats: Statistics on the solve process, e.g. running time, iterations.
      solutions: Lexicographically by primal feasibility status, dual feasibility
        status, (basic dual feasibility for simplex solvers), primal objective
        value and dual objective value.
      primal_rays: Directions of unbounded primal improvement, or equivalently,
        dual infeasibility certificates. Typically provided for terminal reasons
        UNBOUNDED and DUAL_INFEASIBLE.
      dual_rays: Directions of unbounded dual improvement, or equivalently, primal
        infeasibility certificates. Typically provided for termination reason
        INFEASIBLE.
      gscip_specific_output: statistics returned by the gSCIP solver, if used.
      osqp_specific_output: statistics returned by the OSQP solver, if used.
      pdlp_specific_output: statistics returned by the PDLP solver, if used.
    """
 
    termination: Termination = dataclasses.field(default_factory=Termination)
    solve_stats: SolveStats = dataclasses.field(default_factory=SolveStats)
    solutions: List[solution.Solution] = dataclasses.field(default_factory=list)
    primal_rays: List[solution.PrimalRay] = dataclasses.field(default_factory=list)
    dual_rays: List[solution.DualRay] = dataclasses.field(default_factory=list)
    # At most one of the below will be set
    gscip_specific_output: Optional[gscip_pb2.GScipOutput] = None
    osqp_specific_output: Optional[osqp_pb2.OsqpOutput] = None
    pdlp_specific_output: Optional[result_pb2.SolveResultProto.PdlpOutput] = None
 
    def solve_time(self) -> datetime.timedelta:
        """Shortcut for SolveResult.solve_stats.solve_time."""
        return self.solve_stats.solve_time
 
    def primal_bound(self) -> float:
        """Returns a primal bound on the optimal objective value as described in ObjectiveBounds.
 
        Will return a valid (possibly infinite) bound even if no primal feasible
        solutions are available.
        """
        return self.termination.objective_bounds.primal_bound
 
    def dual_bound(self) -> float:
        """Returns a dual bound on the optimal objective value as described in ObjectiveBounds.
 
        Will return a valid (possibly infinite) bound even if no dual feasible
        solutions are available.
        """
        return self.termination.objective_bounds.dual_bound
 
    def has_primal_feasible_solution(self) -> bool:
        """Indicates if at least one primal feasible solution is available.
 
        When termination.reason is TerminationReason.OPTIMAL or
        TerminationReason.FEASIBLE, this is guaranteed to be true and need not be
        checked.
 
        Returns:
          True if there is at least one primal feasible solution is available,
          False, otherwise.
        """
        if not self.solutions:
            return False
        sol = self.solutions[0]
        return (
            sol.primal_solution is not None
            and sol.primal_solution.feasibility_status
            == solution.SolutionStatus.FEASIBLE
        )
 
    def objective_value(self) -> float:
        """Returns the objective value of the best primal feasible solution.
 
        An error will be raised if there are no primal feasible solutions.
        primal_bound() above is guaranteed to be at least as good (larger or equal
        for max problems and smaller or equal for min problems) as objective_value()
        and will never raise an error, so it may be preferable in some cases. Note
        that primal_bound() could be better than objective_value() even for optimal
        terminations, but on such optimal termination, both should satisfy the
        optimality tolerances.
 
         Returns:
           The objective value of the best primal feasible solution.
 
         Raises:
           ValueError: There are no primal feasible solutions.
        """
        if not self.has_primal_feasible_solution():
            raise ValueError("No primal feasible solution available.")
        sol = self.solutions[0]
        assert sol.primal_solution is not None
        return sol.primal_solution.objective_value
 
    def best_objective_bound(self) -> float:
        """Returns a bound on the best possible objective value.
 
        best_objective_bound() is always equal to dual_bound(), so they can be
        used interchangeably.
        """
        return self.termination.objective_bounds.dual_bound
 
    @overload
    def variable_values(
        self, variables: None = ...
    ) -> Dict[variables_mod.Variable, float]: ...
 
    @overload
    def variable_values(self, variables: variables_mod.Variable) -> float: ...
 
    @overload
    def variable_values(
        self, variables: Iterable[variables_mod.Variable]
    ) -> List[float]: ...
 
    def variable_values(self, variables=None):
        """The variable values from the best primal feasible solution.
 
        An error will be raised if there are no primal feasible solutions.
 
        Args:
          variables: an optional Variable or iterator of Variables indicating what
            variable values to return. If not provided, variable_values returns a
            dictionary with all the variable values for all variables.
 
        Returns:
          The variable values from the best primal feasible solution.
 
        Raises:
          ValueError: There are no primal feasible solutions.
          TypeError: Argument is not None, a Variable or an iterable of Variables.
          KeyError: Variable values requested for an invalid variable (e.g. is not a
            Variable or is a variable for another model).
        """
        if not self.has_primal_feasible_solution():
            raise ValueError("No primal feasible solution available.")
        sol = self.solutions[0]
        assert sol.primal_solution is not None
        if variables is None:
            return sol.primal_solution.variable_values
        if isinstance(variables, variables_mod.Variable):
            return sol.primal_solution.variable_values[variables]
        if isinstance(variables, Iterable):
            return [sol.primal_solution.variable_values[v] for v in variables]
        raise TypeError(
            "unsupported type in argument for "
            f"variable_values: {type(variables).__name__!r}"
        )
 
    def bounded(self) -> bool:
        """Returns true only if the problem has been shown to be feasible and bounded."""
        return (
            self.termination.problem_status.primal_status == FeasibilityStatus.FEASIBLE
            and self.termination.problem_status.dual_status
            == FeasibilityStatus.FEASIBLE
        )
 
    def has_ray(self) -> bool:
        """Indicates if at least one primal ray is available.
 
        This is NOT guaranteed to be true when termination.reason is
        TerminationReason.kUnbounded or TerminationReason.kInfeasibleOrUnbounded.
 
        Returns:
          True if at least one primal ray is available.
        """
        return bool(self.primal_rays)
 
    @overload
    def ray_variable_values(
        self, variables: None = ...
    ) -> Dict[variables_mod.Variable, float]: ...
 
    @overload
    def ray_variable_values(self, variables: variables_mod.Variable) -> float: ...
 
    @overload
    def ray_variable_values(
        self, variables: Iterable[variables_mod.Variable]
    ) -> List[float]: ...
 
    def ray_variable_values(self, variables=None):
        """The variable values from the first primal ray.
 
        An error will be raised if there are no primal rays.
 
        Args:
          variables: an optional Variable or iterator of Variables indicating what
            variable values to return. If not provided, variable_values() returns a
            dictionary with the variable values for all variables.
 
        Returns:
          The variable values from the first primal ray.
 
        Raises:
          ValueError: There are no primal rays.
          TypeError: Argument is not None, a Variable or an iterable of Variables.
          KeyError: Variable values requested for an invalid variable (e.g. is not a
            Variable or is a variable for another model).
        """
        if not self.has_ray():
            raise ValueError("No primal ray available.")
        if variables is None:
            return self.primal_rays[0].variable_values
        if isinstance(variables, variables_mod.Variable):
            return self.primal_rays[0].variable_values[variables]
        if isinstance(variables, Iterable):
            return [self.primal_rays[0].variable_values[v] for v in variables]
        raise TypeError(
            "unsupported type in argument for "
            f"ray_variable_values: {type(variables).__name__!r}"
        )
 
    def has_dual_feasible_solution(self) -> bool:
        """Indicates if the best solution has an associated dual feasible solution.
 
        This is NOT guaranteed to be true when termination.reason is
        TerminationReason.Optimal. It also may be true even when the best solution
        does not have an associated primal feasible solution.
 
        Returns:
          True if the best solution has an associated dual feasible solution.
        """
        if not self.solutions:
            return False
        sol = self.solutions[0]
        return (
            sol.dual_solution is not None
            and sol.dual_solution.feasibility_status == solution.SolutionStatus.FEASIBLE
        )
 
    @overload
    def dual_values(
        self, linear_constraints: None = ...
    ) -> Dict[linear_constraints_mod.LinearConstraint, float]: ...
 
    @overload
    def dual_values(
        self, linear_constraints: linear_constraints_mod.LinearConstraint
    ) -> float: ...
 
    @overload
    def dual_values(
        self,
        linear_constraints: Iterable[linear_constraints_mod.LinearConstraint],
    ) -> List[float]: ...
 
    def dual_values(self, linear_constraints=None):
        """The dual values associated to the best solution.
 
        If there is at least one primal feasible solution, this corresponds to the
        dual values associated to the best primal feasible solution. An error will
        be raised if the best solution does not have an associated dual feasible
        solution.
 
        Args:
          linear_constraints: an optional LinearConstraint or iterator of
            LinearConstraint indicating what dual values to return. If not provided,
            dual_values() returns a dictionary with the dual values for all linear
            constraints.
 
        Returns:
          The dual values associated to the best solution.
 
        Raises:
          ValueError: The best solution does not have an associated dual feasible
            solution.
          TypeError: Argument is not None, a LinearConstraint or an iterable of
            LinearConstraint.
          KeyError: LinearConstraint values requested for an invalid
            linear constraint (e.g. is not a LinearConstraint or is a linear
            constraint for another model).
        """
        if not self.has_dual_feasible_solution():
            raise ValueError(_NO_DUAL_SOLUTION_ERROR)
        sol = self.solutions[0]
        assert sol.dual_solution is not None
        if linear_constraints is None:
            return sol.dual_solution.dual_values
        if isinstance(linear_constraints, linear_constraints_mod.LinearConstraint):
            return sol.dual_solution.dual_values[linear_constraints]
        if isinstance(linear_constraints, Iterable):
            return [sol.dual_solution.dual_values[c] for c in linear_constraints]
        raise TypeError(
            "unsupported type in argument for "
            f"dual_values: {type(linear_constraints).__name__!r}"
        )
 
    @overload
    def reduced_costs(
        self, variables: None = ...
    ) -> Dict[variables_mod.Variable, float]: ...
 
    @overload
    def reduced_costs(self, variables: variables_mod.Variable) -> float: ...
 
    @overload
    def reduced_costs(
        self, variables: Iterable[variables_mod.Variable]
    ) -> List[float]: ...
 
    def reduced_costs(self, variables=None):
        """The reduced costs associated to the best solution.
 
        If there is at least one primal feasible solution, this corresponds to the
        reduced costs associated to the best primal feasible solution. An error will
        be raised if the best solution does not have an associated dual feasible
        solution.
 
        Args:
          variables: an optional Variable or iterator of Variables indicating what
            reduced costs to return. If not provided, reduced_costs() returns a
            dictionary with the reduced costs for all variables.
 
        Returns:
          The reduced costs associated to the best solution.
 
        Raises:
          ValueError: The best solution does not have an associated dual feasible
            solution.
          TypeError: Argument is not None, a Variable or an iterable of Variables.
          KeyError: Variable values requested for an invalid variable (e.g. is not a
            Variable or is a variable for another model).
        """
        if not self.has_dual_feasible_solution():
            raise ValueError(_NO_DUAL_SOLUTION_ERROR)
        sol = self.solutions[0]
        assert sol.dual_solution is not None
        if variables is None:
            return sol.dual_solution.reduced_costs
        if isinstance(variables, variables_mod.Variable):
            return sol.dual_solution.reduced_costs[variables]
        if isinstance(variables, Iterable):
            return [sol.dual_solution.reduced_costs[v] for v in variables]
        raise TypeError(
            "unsupported type in argument for "
            f"reduced_costs: {type(variables).__name__!r}"
        )
 
    def has_dual_ray(self) -> bool:
        """Indicates if at least one dual ray is available.
 
        This is NOT guaranteed to be true when termination.reason is
        TerminationReason.Infeasible.
 
        Returns:
          True if at least one dual ray is available.
        """
        return bool(self.dual_rays)
 
    @overload
    def ray_dual_values(
        self, linear_constraints: None = ...
    ) -> Dict[linear_constraints_mod.LinearConstraint, float]: ...
 
    @overload
    def ray_dual_values(
        self, linear_constraints: linear_constraints_mod.LinearConstraint
    ) -> float: ...
 
    @overload
    def ray_dual_values(
        self,
        linear_constraints: Iterable[linear_constraints_mod.LinearConstraint],
    ) -> List[float]: ...
 
    def ray_dual_values(self, linear_constraints=None):
        """The dual values from the first dual ray.
 
        An error will be raised if there are no dual rays.
 
        Args:
          linear_constraints: an optional LinearConstraint or iterator of
            LinearConstraint indicating what dual values to return. If not provided,
            ray_dual_values() returns a dictionary with the dual values for all
            linear constraints.
 
        Returns:
          The dual values from the first dual ray.
 
        Raises:
          ValueError: There are no dual rays.
          TypeError: Argument is not None, a LinearConstraint or an iterable of
            LinearConstraint.
          KeyError: LinearConstraint values requested for an invalid
            linear constraint (e.g. is not a LinearConstraint or is a linear
            constraint for another model).
        """
        if not self.has_dual_ray():
            raise ValueError("No dual ray available.")
        ray = self.dual_rays[0]
        if linear_constraints is None:
            return ray.dual_values
        if isinstance(linear_constraints, linear_constraints_mod.LinearConstraint):
            return ray.dual_values[linear_constraints]
        if isinstance(linear_constraints, Iterable):
            return [ray.dual_values[v] for v in linear_constraints]
        raise TypeError(
            "unsupported type in argument for "
            f"ray_dual_values: {type(linear_constraints).__name__!r}"
        )
 
    @overload
    def ray_reduced_costs(
        self, variables: None = ...
    ) -> Dict[variables_mod.Variable, float]: ...
 
    @overload
    def ray_reduced_costs(self, variables: variables_mod.Variable) -> float: ...
 
    @overload
    def ray_reduced_costs(
        self, variables: Iterable[variables_mod.Variable]
    ) -> List[float]: ...
 
    def ray_reduced_costs(self, variables=None):
        """The reduced costs from the first dual ray.
 
        An error will be raised if there are no dual rays.
 
        Args:
          variables: an optional Variable or iterator of Variables indicating what
            reduced costs to return. If not provided, ray_reduced_costs() returns a
            dictionary with the reduced costs for all variables.
 
        Returns:
          The reduced costs from the first dual ray.
 
        Raises:
          ValueError: There are no dual rays.
          TypeError: Argument is not None, a Variable or an iterable of Variables.
          KeyError: Variable values requested for an invalid variable (e.g. is not a
            Variable or is a variable for another model).
        """
        if not self.has_dual_ray():
            raise ValueError("No dual ray available.")
        ray = self.dual_rays[0]
        if variables is None:
            return ray.reduced_costs
        if isinstance(variables, variables_mod.Variable):
            return ray.reduced_costs[variables]
        if isinstance(variables, Iterable):
            return [ray.reduced_costs[v] for v in variables]
        raise TypeError(
            "unsupported type in argument for "
            f"ray_reduced_costs: {type(variables).__name__!r}"
        )
 
    def has_basis(self) -> bool:
        """Indicates if the best solution has an associated basis.
 
        This is NOT guaranteed to be true when termination.reason is
        TerminationReason.Optimal. It also may be true even when the best solution
        does not have an associated primal feasible solution.
 
        Returns:
          True if the best solution has an associated basis.
        """
        if not self.solutions:
            return False
        return self.solutions[0].basis is not None
 
    @overload
    def constraint_status(
        self, linear_constraints: None = ...
    ) -> Dict[linear_constraints_mod.LinearConstraint, solution.BasisStatus]: ...
 
    @overload
    def constraint_status(
        self, linear_constraints: linear_constraints_mod.LinearConstraint
    ) -> solution.BasisStatus: ...
 
    @overload
    def constraint_status(
        self,
        linear_constraints: Iterable[linear_constraints_mod.LinearConstraint],
    ) -> List[solution.BasisStatus]: ...
 
    def constraint_status(self, linear_constraints=None):
        """The constraint basis status associated to the best solution.
 
        If there is at least one primal feasible solution, this corresponds to the
        basis associated to the best primal feasible solution. An error will
        be raised if the best solution does not have an associated basis.
 
 
        Args:
          linear_constraints: an optional LinearConstraint or iterator of
            LinearConstraint indicating what constraint statuses to return. If not
            provided, returns a dictionary with the constraint statuses for all
            linear constraints.
 
        Returns:
          The constraint basis status associated to the best solution.
 
        Raises:
          ValueError: The best solution does not have an associated basis.
          TypeError: Argument is not None, a LinearConstraint or an iterable of
            LinearConstraint.
          KeyError: LinearConstraint values requested for an invalid
            linear constraint (e.g. is not a LinearConstraint or is a linear
            constraint for another model).
        """
        if not self.has_basis():
            raise ValueError(_NO_BASIS_ERROR)
        basis = self.solutions[0].basis
        assert basis is not None
        if linear_constraints is None:
            return basis.constraint_status
        if isinstance(linear_constraints, linear_constraints_mod.LinearConstraint):
            return basis.constraint_status[linear_constraints]
        if isinstance(linear_constraints, Iterable):
            return [basis.constraint_status[c] for c in linear_constraints]
        raise TypeError(
            "unsupported type in argument for "
            f"constraint_status: {type(linear_constraints).__name__!r}"
        )
 
    @overload
    def variable_status(
        self, variables: None = ...
    ) -> Dict[variables_mod.Variable, solution.BasisStatus]: ...
 
    @overload
    def variable_status(
        self, variables: variables_mod.Variable
    ) -> solution.BasisStatus: ...
 
    @overload
    def variable_status(
        self, variables: Iterable[variables_mod.Variable]
    ) -> List[solution.BasisStatus]: ...
 
    def variable_status(self, variables=None):
        """The variable basis status associated to the best solution.
 
        If there is at least one primal feasible solution, this corresponds to the
        basis associated to the best primal feasible solution. An error will
        be raised if the best solution does not have an associated basis.
 
        Args:
          variables: an optional Variable or iterator of Variables indicating what
            reduced costs to return. If not provided, variable_status() returns a
            dictionary with the reduced costs for all variables.
 
        Returns:
          The variable basis status associated to the best solution.
 
        Raises:
          ValueError: The best solution does not have an associated basis.
          TypeError: Argument is not None, a Variable or an iterable of Variables.
          KeyError: Variable values requested for an invalid variable (e.g. is not a
            Variable or is a variable for another model).
        """
        if not self.has_basis():
            raise ValueError(_NO_BASIS_ERROR)
        basis = self.solutions[0].basis
        assert basis is not None
        if variables is None:
            return basis.variable_status
        if isinstance(variables, variables_mod.Variable):
            return basis.variable_status[variables]
        if isinstance(variables, Iterable):
            return [basis.variable_status[v] for v in variables]
        raise TypeError(
            "unsupported type in argument for "
            f"variable_status: {type(variables).__name__!r}"
        )
 
    def to_proto(self) -> result_pb2.SolveResultProto:
        """Returns an equivalent protocol buffer for a SolveResult."""
        proto = result_pb2.SolveResultProto(
            termination=self.termination.to_proto(),
            solutions=[s.to_proto() for s in self.solutions],
            primal_rays=[r.to_proto() for r in self.primal_rays],
            dual_rays=[r.to_proto() for r in self.dual_rays],
            solve_stats=self.solve_stats.to_proto(),
        )
 
        # Ensure that at most solver has solver specific output.
        existing_solver_specific_output = None
 
        def has_solver_specific_output(solver_name: str) -> None:
            nonlocal existing_solver_specific_output
            if existing_solver_specific_output is not None:
                raise ValueError(
                    "found solver specific output for both"
                    f" {existing_solver_specific_output} and {solver_name}"
                )
            existing_solver_specific_output = solver_name
 
        if self.gscip_specific_output is not None:
            has_solver_specific_output("gscip")
            proto.gscip_output.CopyFrom(self.gscip_specific_output)
        if self.osqp_specific_output is not None:
            has_solver_specific_output("osqp")
            proto.osqp_output.CopyFrom(self.osqp_specific_output)
        if self.pdlp_specific_output is not None:
            has_solver_specific_output("pdlp")
            proto.pdlp_output.CopyFrom(self.pdlp_specific_output)
        return proto
 
 
def _get_problem_status(
    result_proto: result_pb2.SolveResultProto,
) -> result_pb2.ProblemStatusProto:
    if result_proto.termination.HasField("problem_status"):
        return result_proto.termination.problem_status
    return result_proto.solve_stats.problem_status
 
 
def _get_objective_bounds(
    result_proto: result_pb2.SolveResultProto,
) -> result_pb2.ObjectiveBoundsProto:
    if result_proto.termination.HasField("objective_bounds"):
        return result_proto.termination.objective_bounds
    return result_pb2.ObjectiveBoundsProto(
        primal_bound=result_proto.solve_stats.best_primal_bound,
        dual_bound=result_proto.solve_stats.best_dual_bound,
    )
 
 
def _upgrade_termination(
    result_proto: result_pb2.SolveResultProto,
) -> result_pb2.TerminationProto:
    return result_pb2.TerminationProto(
        reason=result_proto.termination.reason,
        limit=result_proto.termination.limit,
        detail=result_proto.termination.detail,
        problem_status=_get_problem_status(result_proto),
        objective_bounds=_get_objective_bounds(result_proto),
    )
 
 
def parse_solve_result(
    proto: result_pb2.SolveResultProto,
    mod: model.Model,
    *,
    validate: bool = True,
) -> SolveResult:
    """Returns a SolveResult equivalent to the input proto."""
    result = SolveResult()
    # TODO(b/290091715): change to parse_termination(proto.termination)
    # once solve_stats proto no longer has best_primal/dual_bound/problem_status
    # and problem_status/objective_bounds are guaranteed to be present in
    # termination proto.
    result.termination = parse_termination(_upgrade_termination(proto))
    result.solve_stats = parse_solve_stats(proto.solve_stats)
    for solution_proto in proto.solutions:
        result.solutions.append(
            solution.parse_solution(solution_proto, mod, validate=validate)
        )
    for primal_ray_proto in proto.primal_rays:
        result.primal_rays.append(
            solution.parse_primal_ray(primal_ray_proto, mod, validate=validate)
        )
    for dual_ray_proto in proto.dual_rays:
        result.dual_rays.append(
            solution.parse_dual_ray(dual_ray_proto, mod, validate=validate)
        )
    if proto.HasField("gscip_output"):
        result.gscip_specific_output = proto.gscip_output
    elif proto.HasField("osqp_output"):
        result.osqp_specific_output = proto.osqp_output
    elif proto.HasField("pdlp_output"):
        result.pdlp_specific_output = proto.pdlp_output
    return result