API Reference

class Constraint:
    """A linear (or quadratic) constraint of the form `Ax [<=|=|>=] b`."""

    def __init__(self) -> None:
        """Create an empty `<= 0` constraint with no coefficients."""
        self._coefs: dict[int, float] = {}
        self._quad_coefs: dict[tuple[int, int], float] = {}
        self._relation: Relation = Relation.LessEqual
        self._value: float = 0.0

    def set_coefficient(self, i: SupportsIndex, value: float) -> None:
        """Set the linear coefficient of variable `i`."""
        if value == 0:
            self._coefs.pop(int(i), None)
        else:
            self._coefs[int(i)] = value

    def get_coefficients(self) -> Mapping[int, float]:
        """Return the linear coefficients as a mapping from variable index to value."""
        return MappingProxyType(self._coefs)

    def set_quadratic_coefficient(
        self, i: SupportsIndex, j: SupportsIndex, value: float
    ) -> None:
        """Set the quadratic coefficient for the term `x_i * x_j`."""
        key = (int(i), int(j))
        if value == 0:
            self._quad_coefs.pop(key, None)
        else:
            self._quad_coefs[key] = value

    def get_quadratic_coefficients(self) -> Mapping[tuple[int, int], float]:
        """Return the quadratic coefficients, keyed by variable-index pairs."""
        return MappingProxyType(self._quad_coefs)

    def set_relation(self, relation: Relation) -> None:
        """Set the relation (`<=`, `=`, `>=`) used by this constraint."""
        self._relation = relation

    def get_relation(self) -> Relation:
        """Return the relation of this constraint."""
        return self._relation

    def set_value(self, value: float) -> None:
        """Set the right-hand-side value of this constraint."""
        self._value = value

    def get_value(self) -> float:
        """Return the right-hand-side value of this constraint."""
        return self._value

    def is_violated(self, solution: Solution) -> bool:
        """Return True if `solution` violates this constraint."""
        total = sum(coef * solution[var] for var, coef in self._coefs.items())
        if self._relation == Relation.LessEqual:
            return total > self._value
        elif self._relation == Relation.GreaterEqual:
            return total < self._value
        elif self._relation == Relation.Equal:
            return total != self._value
        return False

    @classmethod
    def from_coefficients(
        cls,
        coefficients: LinearCoeffs = (),
        quadratic_coefficients: QCoeffs = (),
        relation: Relation = Relation.LessEqual,
        value: float = 0,
    ) -> Constraint:
        """Build a `Constraint` from coefficients, a relation, and a value."""
        constraint = cls()
        iter_coeffs = (
            coefficients.items()
            if isinstance(coefficients, Mapping)
            else enumerate(coefficients)
        )
        for i, coeff in iter_coeffs:
            constraint.set_coefficient(i, coeff)
        iter_quadratic_coeffs = (
            quadratic_coefficients.items()
            if isinstance(quadratic_coefficients, Mapping)
            else quadratic_coefficients
        )
        for (i, j), coeff in iter_quadratic_coeffs:
            constraint.set_quadratic_coefficient(i, j, coeff)

        constraint.set_relation(relation)
        constraint.set_value(value)
        return constraint

class Constraints:
    """An ordered collection of `Constraint` objects."""

    def __init__(self) -> None:
        """Create an empty collection of constraints."""
        self._constraints: list[Constraint] = []

    def clear(self) -> None:
        """Remove all constraints from this collection."""
        self._constraints.clear()

    def add(self, constraint: Constraint | Expression) -> None:
        """Append a `Constraint` (or an `Expression` convertible to one)."""
        if isinstance(constraint, Expression):
            self._constraints.append(constraint.as_constraint())
        else:
            self._constraints.append(constraint)

    def add_all(self, constraints: Constraints) -> None:
        """Append every constraint from another `Constraints` instance."""
        self._constraints.extend(constraints._constraints)

    def __len__(self) -> int:
        return len(self._constraints)

    def __iter__(self) -> Iterator[Constraint]:
        return iter(self._constraints)

class Expression(ast.expr):
    """Base class for all expression nodes.

    Expressions allow ilpy to represent mathematical expressions in an
    intuitive syntax, and then convert to a native Constraint object.

    This class provides all of the operators and methods needed to build
    expressions. For example, to create the expression `2 * x - y >= 0`, you can
    write `2 * Variable('x') - Variable('y') >= 0`.

    !!! tip

        you can use `ast.dump` to see the AST representation of an expression.
        Or, use `print(expr)` to see the string representation of an expression.
    """

    def as_constraint(self) -> Constraint:
        """Create an [ilpy.Constraint][] object from this expression."""
        from ._components import Constraint

        l_coeffs, q_coeffs, value = _get_coeff_indices(self)
        return Constraint.from_coefficients(
            coefficients=l_coeffs,
            quadratic_coefficients=q_coeffs,
            relation=_get_relation(self) or Relation.LessEqual,
            value=-value,  # negate value to convert to RHS form
        )

    def as_objective(self, sense: Sense = Sense.Minimize) -> Objective:
        """Create a linear objective from this expression."""
        if _get_relation(self) is not None:  # pragma: no cover
            # TODO: may be supported in the future, eg. for piecewise objectives?
            raise ValueError(f"Objective function cannot have comparisons: {self}")
        from ._components import Objective

        l_coeffs, q_coeffs, value = _get_coeff_indices(self)
        return Objective.from_coefficients(
            coefficients=l_coeffs,
            quadratic_coefficients=q_coeffs,
            constant=value,
            sense=sense,
        )

    @staticmethod
    def _cast(obj: Any) -> Expression:
        """Cast object into an Expression."""
        return obj if isinstance(obj, Expression) else Constant(obj)

    def __str__(self) -> str:
        """Serialize this expression to string form."""
        return str(_ExprSerializer(self))

    # comparisons

    def __lt__(self, other: Expression | float) -> Compare:
        return Compare(self, [ast.Lt()], [other])

    def __le__(self, other: Expression | float) -> Compare:
        return Compare(self, [ast.LtE()], [other])

    def __eq__(self, other: Expression | float) -> Compare:  # type: ignore
        return Compare(self, [ast.Eq()], [other])

    def __ne__(self, other: Expression | float) -> Compare:  # type: ignore
        return Compare(self, [ast.NotEq()], [other])

    def __gt__(self, other: Expression | float) -> Compare:
        return Compare(self, [ast.Gt()], [other])

    def __ge__(self, other: Expression | float) -> Compare:
        return Compare(self, [ast.GtE()], [other])

    # binary operators
    # (note that __and__ and __or__ are reserved for boolean operators.)

    def __add__(self, other: Expression | Number) -> BinOp:
        return BinOp(self, ast.Add(), other)

    def __radd__(self, other: Expression | Number) -> BinOp:
        return BinOp(other, ast.Add(), self)

    def __sub__(self, other: Expression | Number) -> BinOp:
        return BinOp(self, ast.Sub(), other)

    def __rsub__(self, other: Expression | Number) -> BinOp:
        return BinOp(other, ast.Sub(), self)

    def __mul__(self, other: Any) -> BinOp | Constant:
        return BinOp(self, ast.Mult(), other)

    def __rmul__(self, other: Number) -> BinOp | Constant:
        if not isinstance(other, (int, float)):  # pragma: no cover
            raise TypeError("Right multiplication must be with a number")
        return Constant(other) * self

    def __truediv__(self, other: Number) -> BinOp:
        return BinOp(self, ast.Div(), other)

    def __rtruediv__(self, other: Number) -> BinOp:
        return BinOp(other, ast.Div(), self)

    # unary operators

    def __neg__(self) -> UnaryOp:
        return UnaryOp(ast.USub(), self)

    def __pos__(self) -> UnaryOp:
        # usually a no-op
        return UnaryOp(ast.UAdd(), self)

class Objective:
    """A linear (or quadratic) objective function to minimize or maximize."""

    def __init__(self, size: int = 0) -> None:
        """Create an empty minimizing objective with `size` zero coefficients."""
        self._sense = Sense.Minimize
        self._constant = 0.0
        self._coeffs: list[float] = []
        self._quad_coeffs: dict[tuple[int, int], float] = {}

    def set_constant(self, value: float) -> None:
        """Set the constant term added to the objective."""
        self._constant = value

    def get_constant(self) -> float:
        """Return the constant term of the objective."""
        return self._constant

    def resize(self, size: int) -> None:
        """Resize the objective function. New coefficients are set to 0."""
        if size < 0:
            raise ValueError("Size must be non-negative.")
        current_size = len(self)
        if current_size < size:
            self._coeffs.extend([0] * (size - current_size))
        elif current_size > size:
            self._coeffs = self._coeffs[:size]

    def set_coefficient(self, i: SupportsIndex, value: float) -> None:
        """Set the linear coefficient of variable `i`, growing storage as needed."""
        i = int(i)
        if i >= len(self):
            self.resize(i + 1)
        self._coeffs[i] = value

    def get_coefficients(self) -> list[float]:
        """Return a copy of the linear coefficients."""
        return list(self._coeffs)

    def __iter__(self) -> Iterator[float]:
        return iter(self._coeffs)

    def set_quadratic_coefficient(
        self, i: SupportsIndex, j: SupportsIndex, value: float
    ) -> None:
        """Set the quadratic coefficient for the term `x_i * x_j`."""
        i, j = int(i), int(j)
        if i >= len(self) or j >= len(self):
            self.resize(max(i, j) + 1)
        if value == 0:
            self._quad_coeffs.pop((i, j), None)
        else:
            self._quad_coeffs[(i, j)] = value

    def get_quadratic_coefficients(self) -> Mapping[tuple[int, int], float]:
        """Return the quadratic coefficients, keyed by variable-index pairs."""
        return MappingProxyType(self._quad_coeffs)

    def set_sense(self, sense: Sense) -> None:
        """Set the sense (`Sense.Minimize` or `Sense.Maximize`)."""
        self._sense = sense

    def get_sense(self) -> Sense:
        """Return the sense of this objective."""
        return self._sense

    def __len__(self) -> int:
        return len(self._coeffs)

    @classmethod
    def from_coefficients(
        cls,
        coefficients: LinearCoeffs = (),
        quadratic_coefficients: QCoeffs = (),
        constant: float = 0,
        sense: Sense = Sense.Minimize,
    ) -> Objective:
        """Build an `Objective` from coefficients, a constant, and a sense."""
        obj = cls()
        iter_coeffs = (
            coefficients.items()
            if isinstance(coefficients, Mapping)
            else enumerate(coefficients)
        )
        for i, coeff in iter_coeffs:
            obj.set_coefficient(i, coeff)
        iter_quadratic_coeffs = (
            quadratic_coefficients.items()
            if isinstance(quadratic_coefficients, Mapping)
            else quadratic_coefficients
        )
        for (i, j), coeff in iter_quadratic_coeffs:
            obj.set_quadratic_coefficient(i, j, coeff)

        obj.set_constant(constant)
        obj.set_sense(sense)
        return obj

class Preference(IntEnum):
    """Preference for a solver backend.

    A "full" Gurobi license means one that is *not* the size-limited license
    bundled with the `gurobipy` pip wheel. See
    https://support.gurobi.com/hc/en-us/articles/360051597492

    - `Any`: Use Gurobi if a full license is available, otherwise fall back
      to SCIP. The bundled size-limited license is treated as "no license" to
      avoid silent "Model too large" failures on problems with >2000 variables.
    - `Scip`: Use SCIP. Raises if `pyscipopt` is not installed.
    - `Gurobi`: Use Gurobi; requires a full license. Raises otherwise. Use
      `GurobiRestricted` if you only have the bundled pip license.
    - `GurobiRestricted`: Use Gurobi with whatever license resolves
      (including the bundled size-limited pip license). Suitable for small
      problems (<2000 variables); larger ones will fail at solve time.
    """

    Any = auto()
    Scip = auto()
    Gurobi = auto()
    GurobiRestricted = auto()

class Relation(IntEnum):
    """Relation used in a linear constraint."""

    LessEqual = auto()
    """Left-hand side is less than or equal to the right-hand side."""
    Equal = auto()
    """Left-hand side equals the right-hand side."""
    GreaterEqual = auto()
    """Left-hand side is greater than or equal to the right-hand side."""

class Sense(IntEnum):
    """Direction of an objective function."""

    Minimize = auto()
    """Minimize the objective."""
    Maximize = auto()
    """Maximize the objective."""

@dataclass
class Solution:
    """The result of solving an optimization problem.

    Attributes
    ----------
    variable_values : Sequence[float]
        The values assigned to each variable by the solver.
    objective_value : float
        The value of the objective at the returned solution.
    status : SolverStatus
        Normalized status reported by the solver.
    time : float
        Wall-clock time (seconds) spent solving.
    native_status : Any
        The backend-specific status object, for callers who need more detail
        than `SolverStatus` provides.
    """

    variable_values: Sequence[float]
    objective_value: float
    status: SolverStatus
    time: float
    native_status: Any = None

    def __array__(
        self, dtype: npt.DTypeLike | None = None, copy: bool | None = None
    ) -> np.ndarray:
        import numpy as np

        return np.asarray(self.variable_values, dtype=dtype, copy=copy)

    def __iter__(self) -> Iterator[float]:
        return iter(self.variable_values)

    def get_value(self) -> float:
        """Return the objective value at this solution."""
        return self.objective_value

    def __getitem__(self, key: int) -> float:
        return self.variable_values[key]

    def __setitem__(self, key: int, value: float) -> None:
        self.variable_values[key] = value  # type: ignore

    def get_status(self) -> str:
        """Return the solver status as a string (the enum member name)."""
        return self.status.name

class Solver:
    """High-level wrapper around an ILP solver backend."""

    def __init__(
        self,
        num_variables: int,
        default_variable_type: VariableType,
        variable_types: dict[int, VariableType] | None = None,
        preference: Preference = Preference.Any,
    ) -> None:
        """Create a solver with `num_variables` decision variables.

        Parameters
        ----------
        num_variables : int
            The number of decision variables in the problem.
        default_variable_type : VariableType
            The type used for variables not listed in `variable_types`.
        variable_types : dict[int, VariableType], optional
            Per-variable overrides for the default variable type.
        preference : Preference
            Backend preference.  `Preference.Any` picks the first available.
        """
        vtpes: dict[int, VariableType] = dict(variable_types) if variable_types else {}
        self._backend: SolverBackend = create_solver_backend(preference)
        self._num_variables = num_variables
        self._backend.initialize(num_variables, default_variable_type, vtpes)

    def set_objective(self, objective: Objective | Expression) -> None:
        """Set the objective, converting from an `Expression` if needed."""
        if isinstance(objective, Expression):
            objective = objective.as_objective()
        self._backend.set_objective(objective)

    def set_constraints(self, constraints: Constraints) -> None:
        """Replace the current constraint set."""
        self._backend.set_constraints(constraints)

    def add_constraint(self, constraint: Constraint | Expression) -> None:
        """Add a single constraint (or an `Expression` convertible to one)."""
        if isinstance(constraint, Expression):
            constraint = constraint.as_constraint()
        self._backend.add_constraint(constraint)

    def set_timeout(self, timeout: float) -> None:
        """Set a wall-clock time limit (in seconds) for solving."""
        self._backend.set_timeout(timeout)

    def set_optimality_gap(self, gap: float, absolute: bool = False) -> None:
        """Set the optimality gap at which the solver may stop.

        If `absolute` is True, `gap` is the absolute gap; otherwise it is
        interpreted as a relative gap.
        """
        self._backend.set_optimality_gap(gap, absolute)

    def set_num_threads(self, num_threads: int) -> None:
        """Set the number of threads the backend may use."""
        self._backend.set_num_threads(num_threads)

    def set_verbose(self, verbose: bool) -> None:
        """Enable or disable solver log output."""
        self._backend.set_verbose(verbose)

    def set_event_callback(self, callback: Callable[[EventData], None] | None) -> None:
        """Set (or clear) a callback invoked on backend progress events."""
        self._backend.set_event_callback(callback)

    def solve(self) -> Solution:
        """Solve the problem and return a `Solution`."""
        return self._backend.solve()

    def native_model(self) -> Any:
        """Return the backend's native model object (e.g. a gurobipy Model)."""
        return self._backend.native_model()

class SolverBackend(ABC):
    """Abstract base class implemented by each concrete solver backend."""

    def __init__(self) -> None:
        self._event_callback: Callable[[EventData], None] | None = None

    def set_event_callback(self, callback: Callable[[EventData], None] | None) -> None:
        """Set (or clear) a callback invoked on solver progress events."""
        self._event_callback = callback

    def emit_event_data(self, data: EventData) -> None:
        """Dispatch `data` to the registered event callback (no-op if none)."""
        if self._event_callback:
            self._event_callback(data)

    @abstractmethod
    def initialize(
        self,
        num_variables: int,
        default_variable_type: VariableType,
        variable_types: Mapping[int, VariableType],
    ) -> None:
        """Initialize the backend with decision variables and their types."""

    @abstractmethod
    def set_objective(self, objective: Objective) -> None:
        """Set the objective function for the problem."""

    @abstractmethod
    def set_constraints(self, constraints: Constraints) -> None:
        """Replace the backend's current constraint set."""

    @abstractmethod
    def add_constraint(self, constraint: Constraint) -> None:
        """Add a single constraint to the problem."""

    @abstractmethod
    def set_timeout(self, timeout: float) -> None:
        """Set the wall-clock time limit (in seconds) for solving."""

    @abstractmethod
    def set_optimality_gap(self, gap: float, absolute: bool) -> None:
        """Set the optimality gap (absolute or relative) for early termination."""

    @abstractmethod
    def set_num_threads(self, num_threads: int) -> None:
        """Set the number of threads the backend may use."""

    @abstractmethod
    def set_verbose(self, verbose: bool) -> None:
        """Enable or disable backend log output."""

    @abstractmethod
    def solve(self) -> Solution:
        """Solve the problem and return a `Solution`."""

    @abstractmethod
    def native_model(self) -> Any:
        """Return the underlying native model object for this backend."""