pyoframe 0.0.11__py3-none-any.whl → 0.1.1__py3-none-any.whl

pyoframe/model.py

@@ -1,27 +1,56 @@
-from typing import Any, Iterable, List, Optional, Union
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional, Union
+
+import pandas as pd
+import polars as pl
+import pyoptinterface as poi
+
 from pyoframe.constants import (
-    ObjSense,
-    VType,
+    CONST_TERM,
+    SUPPORTED_SOLVER_TYPES,
     Config,
-    Result,
-    PyoframeError,
+    ObjSense,
     ObjSenseValue,
+    PyoframeError,
+    VType,
 )
-from pyoframe.io_mappers import NamedVariableMapper, IOMappers
+from pyoframe.core import Constraint, Variable
 from pyoframe.model_element import ModelElement, ModelElementWithId
-from pyoframe.core import Constraint
 from pyoframe.objective import Objective
-from pyoframe.user_defined import Container, AttrContainerMixin
-from pyoframe.core import Variable
-from pyoframe.io import to_file
-from pyoframe.solvers import solve, Solver
-import polars as pl
-import pandas as pd
+from pyoframe.util import Container, NamedVariableMapper, for_solvers, get_obj_repr
 
 
-class Model(AttrContainerMixin):
+class Model:
     """
-    Represents a mathematical optimization model. Add variables, constraints, and an objective to the model by setting attributes.
+    The object that holds all the variables, constraints, and the objective.
+
+    Parameters:
+        name:
+            The name of the model. Currently it is not used for much.
+        solver:
+            The solver to use. If `None`, `Config.default_solver` will be used.
+            If `Config.default_solver` has not been set (`None`), Pyoframe will try to detect whichever solver is already installed.
+        solver_env:
+            Gurobi only: a dictionary of parameters to set when creating the Gurobi environment.
+        use_var_names:
+            Whether to pass variable names to the solver. Set to `True` if you'd like outputs from e.g. `Model.write()` to be legible.
+        sense:
+            Either "min" or "max". Indicates whether it's a minmization or maximization problem.
+            Typically, this parameter can be omitted (`None`) as it will automatically be
+            set when the objective is set using `.minimize` or `.maximize`.
+
+    Example:
+        >>> m = pf.Model()
+        >>> m.X = pf.Variable()
+        >>> m.my_constraint = m.X <= 10
+        >>> m
+        <Model vars=1 constrs=1 objective=False>
+
+        Try setting the Gurobi license:
+        >>> m = pf.Model(solver="gurobi", solver_env=dict(ComputeServer="myserver", ServerPassword="mypassword"))
+        Traceback (most recent call last):
+        ...
+        RuntimeError: Could not resolve host: myserver (code 6, command POST http://myserver/api/v1/cluster/jobs)
     """
 
     _reserved_attributes = [
@@ -32,29 +61,89 @@ class Model(AttrContainerMixin):
         "io_mappers",
         "name",
         "solver",
-        "solver_model",
+        "poi",
         "params",
         "result",
         "attr",
         "sense",
         "objective",
+        "_use_var_names",
+        "ONE",
+        "solver_name",
+        "minimize",
+        "maximize",
     ]
 
-    def __init__(self, min_or_max: Union[ObjSense, ObjSenseValue], name=None, **kwargs):
-        super().__init__(**kwargs)
+    def __init__(
+        self,
+        name=None,
+        solver: Optional[SUPPORTED_SOLVER_TYPES] = None,
+        solver_env: Optional[Dict[str, str]] = None,
+        use_var_names=False,
+        sense: Union[ObjSense, ObjSenseValue, None] = None,
+    ):
+        self.poi, self.solver_name = Model.create_poi_model(solver, solver_env)
         self._variables: List[Variable] = []
         self._constraints: List[Constraint] = []
-        self.sense = ObjSense(min_or_max)
+        self.sense = ObjSense(sense) if sense is not None else None
         self._objective: Optional[Objective] = None
         self.var_map = (
             NamedVariableMapper(Variable) if Config.print_uses_variable_names else None
         )
-        self.io_mappers: Optional[IOMappers] = None
         self.name = name
-        self.solver: Optional[Solver] = None
-        self.solver_model: Optional[Any] = None
-        self.params = Container()
-        self.result: Optional[Result] = None
+
+        self.params = Container(self._set_param, self._get_param)
+        self.attr = Container(self._set_attr, self._get_attr)
+        self._use_var_names = use_var_names
+
+    @property
+    def use_var_names(self):
+        return self._use_var_names
+
+    @classmethod
+    def create_poi_model(
+        cls, solver: Optional[str], solver_env: Optional[Dict[str, str]]
+    ):
+        if solver is None:
+            if Config.default_solver is None:
+                for solver_option in ["highs", "gurobi"]:
+                    try:
+                        return cls.create_poi_model(solver_option, solver_env)
+                    except RuntimeError:
+                        pass
+                raise ValueError(
+                    'Could not automatically find a solver. Is one installed? If so, specify which one: e.g. Model(solver="gurobi")'
+                )
+            else:
+                solver = Config.default_solver
+
+        solver = solver.lower()
+        if solver == "gurobi":
+            from pyoptinterface import gurobi
+
+            if solver_env is None:
+                model = gurobi.Model()
+            else:
+                env = gurobi.Env(empty=True)
+                for key, value in solver_env.items():
+                    env.set_raw_parameter(key, value)
+                env.start()
+                model = gurobi.Model(env)
+        elif solver == "highs":
+            from pyoptinterface import highs
+
+            model = highs.Model()
+        else:
+            raise ValueError(
+                f"Solver {solver} not recognized or supported."
+            )  # pragma: no cover
+
+        constant_var = model.add_variable(lb=1, ub=1, name="ONE")
+        if constant_var.index != CONST_TERM:
+            raise ValueError(
+                "The first variable should have index 0."
+            )  # pragma: no cover
+        return model, solver
 
     @property
     def variables(self) -> List[Variable]:
@@ -62,10 +151,26 @@ class Model(AttrContainerMixin):
 
     @property
     def binary_variables(self) -> Iterable[Variable]:
+        """
+        Examples:
+            >>> m = pf.Model()
+            >>> m.X = pf.Variable(vtype=pf.VType.BINARY)
+            >>> m.Y = pf.Variable()
+            >>> len(list(m.binary_variables))
+            1
+        """
         return (v for v in self.variables if v.vtype == VType.BINARY)
 
     @property
     def integer_variables(self) -> Iterable[Variable]:
+        """
+        Examples:
+            >>> m = pf.Model()
+            >>> m.X = pf.Variable(vtype=pf.VType.INTEGER)
+            >>> m.Y = pf.Variable()
+            >>> len(list(m.integer_variables))
+            1
+        """
         return (v for v in self.variables if v.vtype == VType.INTEGER)
 
     @property
@@ -78,10 +183,43 @@ class Model(AttrContainerMixin):
 
     @objective.setter
     def objective(self, value):
-        value = Objective(value)
+        if self._objective is not None and (
+            not isinstance(value, Objective) or not value._constructive
+        ):
+            raise ValueError("An objective already exists. Use += or -= to modify it.")
+        if not isinstance(value, Objective):
+            value = Objective(value)
         self._objective = value
         value.on_add_to_model(self, "objective")
 
+    @property
+    def minimize(self):
+        if self.sense != ObjSense.MIN:
+            raise ValueError("Can't get .minimize in a maximization problem.")
+        return self._objective
+
+    @minimize.setter
+    def minimize(self, value):
+        if self.sense is None:
+            self.sense = ObjSense.MIN
+        if self.sense != ObjSense.MIN:
+            raise ValueError("Can't set .minimize in a maximization problem.")
+        self.objective = value
+
+    @property
+    def maximize(self):
+        if self.sense != ObjSense.MAX:
+            raise ValueError("Can't get .maximize in a minimization problem.")
+        return self._objective
+
+    @maximize.setter
+    def maximize(self, value):
+        if self.sense is None:
+            self.sense = ObjSense.MAX
+        if self.sense != ObjSense.MAX:
+            raise ValueError("Can't set .maximize in a minimization problem.")
+        self.objective = value
+
     def __setattr__(self, __name: str, __value: Any) -> None:
         if __name not in Model._reserved_attributes and not isinstance(
             __value, (ModelElement, pl.DataFrame, pd.DataFrame)
@@ -110,7 +248,101 @@ class Model(AttrContainerMixin):
         return super().__setattr__(__name, __value)
 
     def __repr__(self) -> str:
-        return f"""Model '{self.name}' ({len(self.variables)} vars, {len(self.constraints)} constrs, {1 if self.objective else "no"} obj)"""
+        return get_obj_repr(
+            self,
+            name=self.name,
+            vars=len(self.variables),
+            constrs=len(self.constraints),
+            objective=bool(self.objective),
+        )
+
+    def write(self, file_path: Union[Path, str]):
+        file_path = Path(file_path)
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+        self.poi.write(str(file_path))
+
+    def optimize(self):
+        self.poi.optimize()
+
+    @for_solvers("gurobi")
+    def convert_to_fixed(self) -> None:
+        """
+        Turns a mixed integer program into a continuous one by fixing
+        all the integer and binary variables to their solution values.
+
+        !!! warning "Gurobi only"
+            This method only works with the Gurobi solver. Open an issue if you'd like to see support for other solvers.
+
+        Example:
+            >>> m = pf.Model(solver="gurobi")
+            >>> m.X = pf.Variable(vtype=pf.VType.BINARY, lb=0)
+            >>> m.Y = pf.Variable(vtype=pf.VType.INTEGER, lb=0)
+            >>> m.Z = pf.Variable(lb=0)
+            >>> m.my_constraint = m.X + m.Y + m.Z <= 10
+            >>> m.maximize = 3 * m.X + 2 * m.Y + m.Z
+            >>> m.optimize()
+            >>> m.X.solution, m.Y.solution, m.Z.solution
+            (1.0, 9.0, 0.0)
+            >>> m.my_constraint.dual
+            Traceback (most recent call last):
+            ...
+            polars.exceptions.ComputeError: RuntimeError: Unable to retrieve attribute 'Pi'
+            >>> m.convert_to_fixed()
+            >>> m.optimize()
+            >>> m.my_constraint.dual
+            1.0
+
+            Only works for Gurobi:
+
+            >>> m = pf.Model("max", solver="highs")
+            >>> m.convert_to_fixed()
+            Traceback (most recent call last):
+            ...
+            NotImplementedError: Method 'convert_to_fixed' is not implemented for solver 'highs'.
+        """
+        self.poi._converttofixed()
+
+    @for_solvers("gurobi", "copt")
+    def compute_IIS(self):
+        """
+        Computes the Irreducible Infeasible Set (IIS) of the model.
+
+        !!! warning "Gurobi only"
+            This method only works with the Gurobi solver. Open an issue if you'd like to see support for other solvers.
+
+        Example:
+            >>> m = pf.Model(solver="gurobi")
+            >>> m.X = pf.Variable(lb=0, ub=2)
+            >>> m.Y = pf.Variable(lb=0, ub=2)
+            >>> m.bad_constraint = m.X >= 3
+            >>> m.minimize = m.X + m.Y
+            >>> m.optimize()
+            >>> m.attr.TerminationStatus
+            <TerminationStatusCode.INFEASIBLE: 3>
+            >>> m.bad_constraint.attr.IIS
+            Traceback (most recent call last):
+            ...
+            polars.exceptions.ComputeError: RuntimeError: Unable to retrieve attribute 'IISConstr'
+            >>> m.compute_IIS()
+            >>> m.bad_constraint.attr.IIS
+            True
+        """
+        self.poi.computeIIS()
+
+    def _set_param(self, name, value):
+        self.poi.set_raw_parameter(name, value)
+
+    def _get_param(self, name):
+        return self.poi.get_raw_parameter(name)
+
+    def _set_attr(self, name, value):
+        try:
+            self.poi.set_model_attribute(poi.ModelAttribute[name], value)
+        except KeyError:
+            self.poi.set_model_raw_attribute(name, value)
 
-    to_file = to_file
-    solve = solve
+    def _get_attr(self, name):
+        try:
+            return self.poi.get_model_attribute(poi.ModelAttribute[name])
+        except KeyError:
+            return self.poi.get_model_raw_attribute(name)

pyoframe/model_element.py

@@ -1,13 +1,19 @@
 from __future__ import annotations
+
 from abc import ABC, abstractmethod
 from collections import defaultdict
-from typing import Any, Dict, List, Optional
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+
 import polars as pl
-from typing import TYPE_CHECKING
 
-from pyoframe.constants import COEF_KEY, RESERVED_COL_KEYS, VAR_KEY
 from pyoframe._arithmetic import _get_dimensions
-from pyoframe.user_defined import AttrContainerMixin
+from pyoframe.constants import (
+    COEF_KEY,
+    KEY_TYPE,
+    QUAD_VAR_KEY,
+    RESERVED_COL_KEYS,
+    VAR_KEY,
+)
 
 if TYPE_CHECKING:  # pragma: no cover
     from pyoframe.model import Model
@@ -32,7 +38,9 @@ class ModelElement(ABC):
         if COEF_KEY in data.columns:
             data = data.cast({COEF_KEY: pl.Float64})
         if VAR_KEY in data.columns:
-            data = data.cast({VAR_KEY: pl.UInt32})
+            data = data.cast({VAR_KEY: KEY_TYPE})
+        if QUAD_VAR_KEY in data.columns:
+            data = data.cast({QUAD_VAR_KEY: KEY_TYPE})
 
         self._data = data
         self._model: Optional[Model] = None
@@ -57,12 +65,11 @@ class ModelElement(ABC):
         The names of the data's dimensions.
 
         Examples:
-            >>> from pyoframe.core import Variable
             >>> # A variable with no dimensions
-            >>> Variable().dimensions
+            >>> pf.Variable().dimensions
 
             >>> # A variable with dimensions of "hour" and "city"
-            >>> Variable([{"hour": ["00:00", "06:00", "12:00", "18:00"]}, {"city": ["Toronto", "Berlin", "Paris"]}]).dimensions
+            >>> pf.Variable([{"hour": ["00:00", "06:00", "12:00", "18:00"]}, {"city": ["Toronto", "Berlin", "Paris"]}]).dimensions
             ['hour', 'city']
         """
         return _get_dimensions(self.data)
@@ -84,12 +91,11 @@ class ModelElement(ABC):
         The number of indices in each dimension.
 
         Examples:
-            >>> from pyoframe.core import Variable
             >>> # A variable with no dimensions
-            >>> Variable().shape
+            >>> pf.Variable().shape
             {}
             >>> # A variable with dimensions of "hour" and "city"
-            >>> Variable([{"hour": ["00:00", "06:00", "12:00", "18:00"]}, {"city": ["Toronto", "Berlin", "Paris"]}]).shape
+            >>> pf.Variable([{"hour": ["00:00", "06:00", "12:00", "18:00"]}, {"city": ["Toronto", "Berlin", "Paris"]}]).shape
             {'hour': 4, 'city': 3}
         """
         dims = self.dimensions
@@ -135,48 +141,41 @@ class SupportPolarsMethodMixin(ABC):
     @abstractmethod
     def data(self): ...
 
+    def pick(self, **kwargs):
+        """
+        Filters elements by the given criteria and then drops the filtered dimensions.
+
+        Example:
+            >>> m = pf.Model()
+            >>> m.v = pf.Variable([{"hour": ["00:00", "06:00", "12:00", "18:00"]}, {"city": ["Toronto", "Berlin", "Paris"]}])
+            >>> m.v.pick(hour="06:00")
+            <Expression size=3 dimensions={'city': 3} terms=3>
+            [Toronto]: v[06:00,Toronto]
+            [Berlin]: v[06:00,Berlin]
+            [Paris]: v[06:00,Paris]
+            >>> m.v.pick(hour="06:00", city="Toronto")
+            <Expression size=1 dimensions={} terms=1>
+            v[06:00,Toronto]
+        """
+        return self._new(self.data.filter(**kwargs).drop(kwargs.keys()))
+
 
-class ModelElementWithId(ModelElement, AttrContainerMixin):
+class ModelElementWithId(ModelElement):
     """
     Provides a method that assigns a unique ID to each row in a DataFrame.
     IDs start at 1 and go up consecutively. No zero ID is assigned since it is reserved for the constant variable term.
     IDs are only unique for the subclass since different subclasses have different counters.
     """
 
-    # Keys are the subclass names and values are the next unasigned ID.
-    _id_counters: Dict[str, int] = defaultdict(lambda: 1)
-
-    @classmethod
-    def reset_counters(cls):
-        """
-        Resets all the ID counters.
-        This function is called before every unit test to reset the code state.
-        """
-        cls._id_counters = defaultdict(lambda: 1)
-
-    def __init__(self, data: pl.DataFrame, **kwargs) -> None:
-        super().__init__(data, **kwargs)
-        self._data = self._assign_ids(self.data)
-
-    @classmethod
-    def _assign_ids(cls, df: pl.DataFrame) -> pl.DataFrame:
-        """
-        Adds the column `to_column` to the DataFrame `df` with the next batch
-        of unique consecutive IDs.
-        """
-        cls_name = cls.__name__
-        cur_count = cls._id_counters[cls_name]
-        id_col_name = cls.get_id_column_name()
+    @property
+    def _has_ids(self) -> bool:
+        return self.get_id_column_name() in self.data.columns
 
-        if df.height == 0:
-            df = df.with_columns(pl.lit(cur_count).alias(id_col_name))
-        else:
-            df = df.with_columns(
-                pl.int_range(cur_count, cur_count + pl.len()).alias(id_col_name)
+    def _assert_has_ids(self):
+        if not self._has_ids:
+            raise ValueError(
+                f"Cannot use '{self.__class__.__name__}' before it has beed added to a model."
             )
-        df = df.with_columns(pl.col(id_col_name).cast(pl.UInt32))
-        cls._id_counters[cls_name] += df.height
-        return df
 
     @classmethod
     @abstractmethod
@@ -184,43 +183,3 @@ class ModelElementWithId(ModelElement, AttrContainerMixin):
         """
         Returns the name of the column containing the IDs.
         """
-
-    @property
-    def ids(self) -> pl.DataFrame:
-        return self.data.select(self.dimensions_unsafe + [self.get_id_column_name()])
-
-    def _extend_dataframe_by_id(self, addition: pl.DataFrame):
-        cols = addition.columns
-        assert len(cols) == 2
-        id_col = self.get_id_column_name()
-        assert id_col in cols
-        cols.remove(id_col)
-        new_col = cols[0]
-
-        original = self.data
-
-        if new_col in original.columns:
-            original = original.drop(new_col)
-        self._data = original.join(addition, on=id_col, how="left", validate="1:1")
-
-    def _preprocess_attr(self, name: str, value: Any) -> Any:
-        dims = self.dimensions
-        ids = self.ids
-        id_col = self.get_id_column_name()
-
-        if isinstance(value, pl.DataFrame):
-            if value.shape == (1, 1):
-                value = value.item()
-            else:
-                assert (
-                    dims is not None
-                ), "Attribute must be a scalar since there are no dimensions"
-                result = value.join(ids, on=dims, validate="1:1", how="inner").drop(
-                    dims
-                )
-                assert len(result.columns) == 2, "Attribute has too many columns"
-                value_col = [c for c in result.columns if c != id_col][0]
-                return result.rename({value_col: name})
-
-        assert ids.height == 1, "Attribute is a scalar but there are multiple IDs."
-        return pl.DataFrame({name: [value], id_col: ids.get_column(id_col)})

pyoframe/monkey_patch.py

@@ -1,10 +1,10 @@
+from functools import wraps
+
 import pandas as pd
 import polars as pl
-from pyoframe.core import SupportsMath
-from pyoframe.core import Expression
-from functools import wraps
 
 from pyoframe.constants import COEF_KEY, CONST_TERM, VAR_KEY
+from pyoframe.core import Expression, SupportsMath
 
 # pyright: reportAttributeAccessIssue=false
 

pyoframe/objective.py

@@ -1,45 +1,95 @@
-from typing import Optional
-from pyoframe.constants import COEF_KEY
-from pyoframe.core import SupportsMath, Expression
+from __future__ import annotations
+
+import pyoptinterface as poi
+
+from pyoframe.core import Expression, SupportsToExpr
 
 
 class Objective(Expression):
-    r"""
+    """
     Examples:
-        >>> from pyoframe import Variable, Model, sum
-        >>> m = Model("max")
-        >>> m.a = Variable()
-        >>> m.b = Variable({"dim1": [1, 2, 3]})
-        >>> m.objective = m.a + sum("dim1", m.b)
-        >>> m.objective
-        <Objective size=1 dimensions={} terms=4>
-        objective: a + b[1] + b[2] + b[3]
+        An `Objective` is automatically created when an `Expression` is assigned to `.minimize` or `.maximize`
+
+        >>> m = pf.Model()
+        >>> m.A, m.B = pf.Variable(lb=0), pf.Variable(lb=0)
+        >>> m.con = m.A + m.B <= 10
+        >>> m.maximize = 2 * m.B + 4
+        >>> m.maximize
+        <Objective size=1 dimensions={} terms=2>
+        objective: 2 B +4
+
+        The objective value can be retrieved with from the solver once the model is solved using `.value`.
+
+        >>> m.optimize()
+        >>> m.maximize.value
+        24.0
+
+        Objectives support `+=` and `-=` operators.
+
+        >>> m.maximize += 3 * m.A
+        >>> m.optimize()
+        >>> m.A.solution, m.B.solution
+        (10.0, 0.0)
+        >>> m.maximize -= 2 * m.A
+        >>> m.optimize()
+        >>> m.A.solution, m.B.solution
+        (0.0, 10.0)
+
+        Objectives cannot be created from dimensioned expressions since an objective must be a single expression.
+
+        >>> m = pf.Model()
+        >>> m.dimensioned_variable = pf.Variable({"city": ["Toronto", "Berlin", "Paris"]})
+        >>> m.maximize = m.dimensioned_variable
+        Traceback (most recent call last):
+        ...
+        ValueError: Objective cannot be created from a dimensioned expression. Did you forget to use pf.sum()?
+
+        Objectives cannot be overwritten.
+
+        >>> m = pf.Model()
+        >>> m.A = pf.Variable(lb=0)
+        >>> m.maximize = 2 * m.A
+        >>> m.maximize = 3 * m.A
+        Traceback (most recent call last):
+        ...
+        ValueError: An objective already exists. Use += or -= to modify it.
     """
 
-    def __init__(self, expr: SupportsMath) -> None:
-        expr = expr.to_expr()
+    def __init__(
+        self, expr: SupportsToExpr | int | float, _constructive: bool = False
+    ) -> None:
+        self._constructive = _constructive
+        if isinstance(expr, (int, float)):
+            expr = Expression.constant(expr)
+        else:
+            expr = expr.to_expr()
         super().__init__(expr.data)
         self._model = expr._model
-        assert (
-            self.dimensions is None
-        ), "Objective cannot have dimensions as it must be a single expression"
-        self._value: Optional[float] = None
+        if self.dimensions is not None:
+            raise ValueError(
+                "Objective cannot be created from a dimensioned expression. Did you forget to use pf.sum()?"
+            )
 
     @property
-    def value(self):
-        if self._value is None:
+    def value(self) -> float:
+        """
+        The value of the objective function (only available after solving the model).
+
+        This value is obtained by directly querying the solver.
+        """
+        return self._model.poi.get_model_attribute(poi.ModelAttribute.ObjectiveValue)
+
+    def on_add_to_model(self, model, name):
+        super().on_add_to_model(model, name)
+        assert self._model is not None
+        if self._model.sense is None:
             raise ValueError(
-                "Objective value is not available before solving the model"
+                "Can't set an objective without specifying the sense. Did you use .objective instead of .minimize or .maximize ?"
             )
-        return self._value
+        self._model.poi.set_objective(self.to_poi(), sense=self._model.sense.to_poi())
 
-    @value.setter
-    def value(self, value):
-        self._value = value
+    def __iadd__(self, other):
+        return Objective(self + other, _constructive=True)
 
-    @property
-    def has_constant(self):
-        constant_terms = self.constant_terms
-        if len(constant_terms) == 0:
-            return False
-        return constant_terms.get_column(COEF_KEY).item() != 0
+    def __isub__(self, other):
+        return Objective(self - other, _constructive=True)