pyoframe 1.0.1__py3-none-any.whl → 1.1.0__py3-none-any.whl

pyoframe/__init__.py

@@ -11,6 +11,7 @@ from pyoframe._core import Constraint, Expression, Set, Variable, sum, sum_by
 from pyoframe._model import Model
 from pyoframe._monkey_patch import patch_dataframe_libraries
 from pyoframe._objective import Objective
+from pyoframe._param import Param
 
 try:
     from pyoframe._version import __version__, __version_tuple__  # noqa: F401
@@ -25,6 +26,7 @@ __all__ = [
     "Expression",
     "Constraint",
     "Objective",
+    "Param",
     "Set",
     "Config",
     "sum",

pyoframe/_arithmetic.py

@@ -42,7 +42,7 @@ def multiply(self: Expression, other: Expression) -> Expression:
         >>> m.x3 = pf.Variable()
         >>> result = 5 * m.x1 * m.x2
         >>> result
-        <Expression terms=1 type=quadratic>
+        <Expression (quadratic) terms=1>
         5 x2 * x1
         >>> result * m.x3
         Traceback (most recent call last):
@@ -112,7 +112,7 @@ def _quadratic_multiplication(self: Expression, other: Expression) -> Expression
         >>> expr1 = df * m.x1
         >>> expr2 = df * m.x2 * 2 + 4
         >>> expr1 * expr2
-        <Expression height=3 terms=6 type=quadratic>
+        <Expression (quadratic) height=3 terms=6>
         ┌─────┬───────────────────┐
         │ dim ┆ expression        │
         │ (3) ┆                   │
@@ -122,7 +122,7 @@ def _quadratic_multiplication(self: Expression, other: Expression) -> Expression
         │ 3   ┆ 12 x1 +18 x2 * x1 │
         └─────┴───────────────────┘
         >>> (expr1 * expr2) - df * m.x1 * df * m.x2 * 2
-        <Expression height=3 terms=3 type=linear>
+        <Expression (linear) height=3 terms=3>
         ┌─────┬────────────┐
         │ dim ┆ expression │
         │ (3) ┆            │

pyoframe/_constants.py

@@ -141,19 +141,18 @@ class _Config:
             Only consider enabling after you have thoroughly tested your code.
 
         Examples:
-            >>> import polars as pl
-            >>> population = pl.DataFrame(
+            >>> population = pf.Param(
             ...     {
             ...         "city": ["Toronto", "Vancouver", "Montreal"],
             ...         "pop": [2_731_571, 631_486, 1_704_694],
             ...     }
-            ... ).to_expr()
-            >>> population_influx = pl.DataFrame(
+            ... )
+            >>> population_influx = pf.Param(
             ...     {
             ...         "city": ["Toronto", "Vancouver", "Montreal"],
             ...         "influx": [100_000, 50_000, None],
             ...     }
-            ... ).to_expr()
+            ... )
 
             Normally, an error warns users that the two expressions have conflicting labels:
             >>> population + population_influx
@@ -174,7 +173,7 @@ class _Config:
             But if `Config.disable_extras_checks = True`, the error is suppressed and the sum is considered to be `population.keep_extras() + population_influx.keep_extras()`:
             >>> pf.Config.disable_extras_checks = True
             >>> population + population_influx
-            <Expression height=3 terms=3 type=constant>
+            <Expression (parameter) height=3 terms=3>
             ┌───────────┬────────────┐
             │ city      ┆ expression │
             │ (3)       ┆            │
@@ -228,11 +227,11 @@ class _Config:
             >>> m.X = pf.Variable()
             >>> expr = 100.752038759 * m.X
             >>> expr
-            <Expression terms=1 type=linear>
+            <Expression (linear) terms=1>
             100.752 X
             >>> pf.Config.float_to_str_precision = None
             >>> expr
-            <Expression terms=1 type=linear>
+            <Expression (linear) terms=1>
             100.752038759 X
         """
         return self._settings.float_to_str_precision
@@ -280,7 +279,7 @@ class _Config:
             >>> m = pf.Model()
             >>> m.X = pf.Variable(pf.Set(x=range(100)), pf.Set(y=range(100)))
             >>> m.X.sum("y")
-            <Expression height=100 terms=10000 type=linear>
+            <Expression (linear) height=100 terms=10000>
             ┌───────┬───────────────────────────────┐
             │ x     ┆ expression                    │
             │ (100) ┆                               │
@@ -298,7 +297,7 @@ class _Config:
             │ 99    ┆ X[99,0] + X[99,1] + X[99,2] … │
             └───────┴───────────────────────────────┘
             >>> m.X.sum()
-            <Expression terms=10000 type=linear>
+            <Expression (linear) terms=10000>
             X[0,0] + X[0,1] + X[0,2] …
         """
         return self._settings.print_max_terms

pyoframe/_core.py

@@ -169,7 +169,7 @@ class BaseOperableBlock(BaseBlock):
             └───────┴─────────┴──────────────────┘
 
             >>> m.v.rename({"city": "location"})
-            <Expression height=12 terms=12 type=linear>
+            <Expression (linear) height=12 terms=12>
             ┌───────┬──────────┬──────────────────┐
             │ hour  ┆ location ┆ expression       │
             │ (4)   ┆ (3)      ┆                  │
@@ -228,7 +228,7 @@ class BaseOperableBlock(BaseBlock):
             ...     ]
             ... )
             >>> m.v.pick(hour="06:00")
-            <Expression height=3 terms=3 type=linear>
+            <Expression (linear) height=3 terms=3>
             ┌─────────┬──────────────────┐
             │ city    ┆ expression       │
             │ (3)     ┆                  │
@@ -238,7 +238,7 @@ class BaseOperableBlock(BaseBlock):
             │ Paris   ┆ v[06:00,Paris]   │
             └─────────┴──────────────────┘
             >>> m.v.pick(hour="06:00", city="Toronto")
-            <Expression terms=1 type=linear>
+            <Expression (linear) terms=1>
             v[06:00,Toronto]
 
         See Also:
@@ -290,7 +290,7 @@ class BaseOperableBlock(BaseBlock):
             >>> m = pf.Model()
             >>> m.v = pf.Variable()
             >>> m.v**2
-            <Expression terms=1 type=quadratic>
+            <Expression (quadratic) terms=1>
             v * v
             >>> m.v**3
             Traceback (most recent call last):
@@ -320,7 +320,7 @@ class BaseOperableBlock(BaseBlock):
             >>> df = pl.DataFrame({"dim1": [1, 2, 3], "value": [1, 2, 3]})
             >>> m.v = pf.Variable(df["dim1"])
             >>> m.v - df
-            <Expression height=3 terms=6 type=linear>
+            <Expression (linear) height=3 terms=6>
             ┌──────┬────────────┐
             │ dim1 ┆ expression │
             │ (3)  ┆            │
@@ -331,7 +331,7 @@ class BaseOperableBlock(BaseBlock):
             └──────┴────────────┘
         """
         if not isinstance(other, (int, float)):
-            other = other.to_expr()
+            other = other.to_expr()  # TODO don't rely on monkey patch
         return self.to_expr() + (-other)
 
     def __rmul__(self, other):
@@ -348,7 +348,7 @@ class BaseOperableBlock(BaseBlock):
             >>> m = pf.Model()
             >>> m.v = Variable({"dim1": [1, 2, 3]})
             >>> m.v / 2
-            <Expression height=3 terms=3 type=linear>
+            <Expression (linear) height=3 terms=3>
             ┌──────┬────────────┐
             │ dim1 ┆ expression │
             │ (3)  ┆            │
@@ -360,6 +360,13 @@ class BaseOperableBlock(BaseBlock):
         """
         return self.to_expr() * (1 / other)
 
+    def __rtruediv__(self, other):
+        # This just improves error messages when trying to divide by a Set or Variable.
+        # When dividing by an Expression, see the Expression.__rtruediv__ method.
+        raise PyoframeError(
+            f"Cannot divide by '{self.name}' because it is not a number or parameter."
+        )
+
     def __rsub__(self, other):
         """Supports right subtraction.
 
@@ -367,7 +374,7 @@ class BaseOperableBlock(BaseBlock):
             >>> m = pf.Model()
             >>> m.v = Variable({"dim1": [1, 2, 3]})
             >>> 1 - m.v
-            <Expression height=3 terms=6 type=linear>
+            <Expression (linear) height=3 terms=6>
             ┌──────┬────────────┐
             │ dim1 ┆ expression │
             │ (3)  ┆            │
@@ -571,7 +578,7 @@ class Set(BaseOperableBlock):
     def __repr__(self):
         header = get_obj_repr(
             self,
-            "unnamed" if self.name == "unnamed_set" else self.name,
+            "'unnamed'" if self.name == "unnamed_set" else f"'{self.name}'",
             height=self.data.height,
         )
         data = self._add_shape_to_columns(self.data)
@@ -645,7 +652,7 @@ class Expression(BaseOperableBlock):
         >>> m.Size = pf.Variable(df.index)
         >>> expr = df["cost"] * m.Time + df["cost"] * m.Size
         >>> expr
-        <Expression height=5 terms=10 type=linear>
+        <Expression (linear) height=5 terms=10>
         ┌──────┬──────┬──────────────────────────────┐
         │ item ┆ time ┆ expression                   │
         │ (2)  ┆ (3)  ┆                              │
@@ -691,7 +698,7 @@ class Expression(BaseOperableBlock):
 
         Examples:
             >>> pf.Expression.constant(5)
-            <Expression terms=1 type=constant>
+            <Expression (parameter) terms=1>
             5
         """
         return cls(
@@ -712,7 +719,7 @@ class Expression(BaseOperableBlock):
         If no dimensions are specified, the sum is taken over all of the expression's dimensions.
 
         Examples:
-            >>> expr = pl.DataFrame(
+            >>> expr = pf.Param(
             ...     {
             ...         "time": ["mon", "tue", "wed", "mon", "tue"],
             ...         "place": [
@@ -724,9 +731,9 @@ class Expression(BaseOperableBlock):
             ...         ],
             ...         "tiktok_posts": [1e6, 3e6, 2e6, 1e6, 2e6],
             ...     }
-            ... ).to_expr()
+            ... )
             >>> expr
-            <Expression height=5 terms=5 type=constant>
+            <Expression (parameter) height=5 terms=5>
             ┌──────┬───────────┬────────────┐
             │ time ┆ place     ┆ expression │
             │ (3)  ┆ (2)       ┆            │
@@ -738,7 +745,7 @@ class Expression(BaseOperableBlock):
             │ tue  ┆ Vancouver ┆ 2000000    │
             └──────┴───────────┴────────────┘
             >>> expr.sum("time")
-            <Expression height=2 terms=2 type=constant>
+            <Expression (parameter) height=2 terms=2>
             ┌───────────┬────────────┐
             │ place     ┆ expression │
             │ (2)       ┆            │
@@ -747,7 +754,7 @@ class Expression(BaseOperableBlock):
             │ Vancouver ┆ 3000000    │
             └───────────┴────────────┘
             >>> expr.sum()
-            <Expression terms=1 type=constant>
+            <Expression (parameter) terms=1>
             9000000
 
             If the given dimensions don't exist, an error will be raised:
@@ -783,7 +790,7 @@ class Expression(BaseOperableBlock):
         """Like [`Expression.sum`][pyoframe.Expression.sum], but the sum is taken over all dimensions *except* those specified in `by` (just like a `group_by().sum()` operation).
 
         Examples:
-            >>> expr = pl.DataFrame(
+            >>> expr = pf.Param(
             ...     {
             ...         "time": ["mon", "tue", "wed", "mon", "tue"],
             ...         "place": [
@@ -795,9 +802,9 @@ class Expression(BaseOperableBlock):
             ...         ],
             ...         "tiktok_posts": [1e6, 3e6, 2e6, 1e6, 2e6],
             ...     }
-            ... ).to_expr()
+            ... )
             >>> expr
-            <Expression height=5 terms=5 type=constant>
+            <Expression (parameter) height=5 terms=5>
             ┌──────┬───────────┬────────────┐
             │ time ┆ place     ┆ expression │
             │ (3)  ┆ (2)       ┆            │
@@ -810,7 +817,7 @@ class Expression(BaseOperableBlock):
             └──────┴───────────┴────────────┘
 
             >>> expr.sum_by("place")
-            <Expression height=2 terms=2 type=constant>
+            <Expression (parameter) height=2 terms=2>
             ┌───────────┬────────────┐
             │ place     ┆ expression │
             │ (2)       ┆            │
@@ -873,13 +880,13 @@ class Expression(BaseOperableBlock):
 
         Examples:
             >>> import polars as pl
-            >>> pop_data = pl.DataFrame(
+            >>> pop_data = pf.Param(
             ...     {
             ...         "city": ["Toronto", "Vancouver", "Boston"],
             ...         "year": [2024, 2024, 2024],
             ...         "population": [10, 2, 8],
             ...     }
-            ... ).to_expr()
+            ... )
             >>> cities_and_countries = pl.DataFrame(
             ...     {
             ...         "city": ["Toronto", "Vancouver", "Boston"],
@@ -887,7 +894,7 @@ class Expression(BaseOperableBlock):
             ...     }
             ... )
             >>> pop_data.map(cities_and_countries)
-            <Expression height=2 terms=2 type=constant>
+            <Expression (parameter) height=2 terms=2>
             ┌──────┬─────────┬────────────┐
             │ year ┆ country ┆ expression │
             │ (1)  ┆ (2)     ┆            │
@@ -897,7 +904,7 @@ class Expression(BaseOperableBlock):
             └──────┴─────────┴────────────┘
 
             >>> pop_data.map(cities_and_countries, drop_shared_dims=False)
-            <Expression height=3 terms=3 type=constant>
+            <Expression (parameter) height=3 terms=3>
             ┌───────────┬──────┬─────────┬────────────┐
             │ city      ┆ year ┆ country ┆ expression │
             │ (3)       ┆ (1)  ┆ (2)     ┆            │
@@ -967,7 +974,7 @@ class Expression(BaseOperableBlock):
             >>> m = pf.Model()
             >>> m.quantity = pf.Variable(cost[["item", "time"]])
             >>> (m.quantity * cost).rolling_sum(over="time", window_size=2)
-            <Expression height=5 terms=8 type=linear>
+            <Expression (linear) height=5 terms=8>
             ┌──────┬──────┬──────────────────────────────────┐
             │ item ┆ time ┆ expression                       │
             │ (2)  ┆ (3)  ┆                                  │
@@ -1003,11 +1010,8 @@ class Expression(BaseOperableBlock):
         """Filters this expression to only include the dimensions within the provided set.
 
         Examples:
-            >>> import pandas as pd
-            >>> general_expr = pd.DataFrame(
-            ...     {"dim1": [1, 2, 3], "value": [1, 2, 3]}
-            ... ).to_expr()
-            >>> filter_expr = pd.DataFrame({"dim1": [1, 3], "value": [5, 6]}).to_expr()
+            >>> general_expr = pf.Param({"dim1": [1, 2, 3], "value": [1, 2, 3]})
+            >>> filter_expr = pf.Param({"dim1": [1, 3], "value": [5, 6]})
             >>> general_expr.within(filter_expr).data
             shape: (2, 3)
             ┌──────┬─────────┬───────────────┐
@@ -1068,11 +1072,10 @@ class Expression(BaseOperableBlock):
                 If `False`, returns the degree as an integer (0, 1, or 2).
 
         Examples:
-            >>> import pandas as pd
             >>> m = pf.Model()
             >>> m.v1 = pf.Variable()
             >>> m.v2 = pf.Variable()
-            >>> expr = pd.DataFrame({"dim1": [1, 2, 3], "value": [1, 2, 3]}).to_expr()
+            >>> expr = pf.Param({"dim1": [1, 2, 3], "value": [1, 2, 3]})
             >>> expr.degree()
             0
             >>> expr *= m.v1
@@ -1090,18 +1093,17 @@ class Expression(BaseOperableBlock):
         elif (self.data.get_column(VAR_KEY) != CONST_TERM).any():
             return "linear" if return_str else 1
         else:
-            return "constant" if return_str else 0
+            return "parameter" if return_str else 0
 
     def __add__(self, other):
         """Adds another expression or a constant to this expression.
 
         Examples:
-            >>> import pandas as pd
             >>> m = pf.Model()
-            >>> add = pd.DataFrame({"dim1": [1, 2, 3], "add": [10, 20, 30]}).to_expr()
+            >>> add = pf.Param({"dim1": [1, 2, 3], "add": [10, 20, 30]})
             >>> m.v = Variable(add)
             >>> m.v + add
-            <Expression height=3 terms=6 type=linear>
+            <Expression (linear) height=3 terms=6>
             ┌──────┬────────────┐
             │ dim1 ┆ expression │
             │ (3)  ┆            │
@@ -1112,7 +1114,7 @@ class Expression(BaseOperableBlock):
             └──────┴────────────┘
 
             >>> m.v + add + 2
-            <Expression height=3 terms=6 type=linear>
+            <Expression (linear) height=3 terms=6>
             ┌──────┬────────────┐
             │ dim1 ┆ expression │
             │ (3)  ┆            │
@@ -1138,12 +1140,12 @@ class Expression(BaseOperableBlock):
                 https://bravos-power.github.io/pyoframe/latest/learn/concepts/addition
             >>> m.v2 = Variable()
             >>> 5 + 2 * m.v2
-            <Expression terms=2 type=linear>
+            <Expression (linear) terms=2>
             2 v2 +5
         """
         if isinstance(other, (int, float)):
             return self._add_const(other)
-        other = other.to_expr()
+        other = other.to_expr()  # TODO don't rely on monkey patch
         self._learn_from_other(other)
         return add(self, other)
 
@@ -1156,10 +1158,25 @@ class Expression(BaseOperableBlock):
                 name=f"({other} * {self.name})",
             )
 
-        other = other.to_expr()
+        other: Expression = other.to_expr()  # TODO don't rely on monkey patch
         self._learn_from_other(other)
         return multiply(self, other)
 
+    def __rtruediv__(self, other):
+        """Support dividing by an expression when that expression is a constant."""
+        assert isinstance(other, (int, float)), (
+            f"Expected a number not a {type(other)} when dividing by an expression."
+        )
+        if self.degree() != 0:
+            raise PyoframeError(
+                f"Cannot divide by '{self.name}' because denominators cannot contain variables."
+            )
+
+        return self._new(
+            self.data.with_columns((pl.lit(other) / pl.col(COEF_KEY)).alias(COEF_KEY)),
+            name=f"({other} / {self.name})",
+        )
+
     def to_expr(self) -> Expression:
         """Returns the expression itself."""
         return self
@@ -1181,13 +1198,13 @@ class Expression(BaseOperableBlock):
             >>> m.x1 = Variable()
             >>> m.x2 = Variable()
             >>> m.x1 + 5
-            <Expression terms=2 type=linear>
+            <Expression (linear) terms=2>
             x1 +5
             >>> m.x1**2 + 5
-            <Expression terms=2 type=quadratic>
+            <Expression (quadratic) terms=2>
             x1 * x1 +5
             >>> m.x1**2 + m.x2 + 5
-            <Expression terms=3 type=quadratic>
+            <Expression (quadratic) terms=3>
             x1 * x1 + x2 +5
 
             It also works with dimensions
@@ -1195,7 +1212,7 @@ class Expression(BaseOperableBlock):
             >>> m = pf.Model()
             >>> m.v = Variable({"dim1": [1, 2, 3]})
             >>> m.v * m.v + 5
-            <Expression height=3 terms=6 type=quadratic>
+            <Expression (quadratic) height=3 terms=6>
             ┌──────┬─────────────────┐
             │ dim1 ┆ expression      │
             │ (3)  ┆                 │
@@ -1558,9 +1575,9 @@ class Expression(BaseOperableBlock):
         """Returns a string representation of the expression's header."""
         return get_obj_repr(
             self,
+            f"({self.degree(return_str=True)})",
             height=len(self) if self.dimensions else None,
             terms=self.terms,
-            type=self.degree(return_str=True),
         )
 
     def __repr__(self) -> str:
@@ -1581,7 +1598,7 @@ class Expression(BaseOperableBlock):
             >>> m.v = pf.Variable({"t": [1, 2]})
             >>> coef = pl.DataFrame({"t": [1, 2], "coef": [0, 1]})
             >>> coef * (m.v + 4)
-            <Expression height=2 terms=3 type=linear>
+            <Expression (linear) height=2 terms=3>
             ┌─────┬────────────┐
             │ t   ┆ expression │
             │ (2) ┆            │
@@ -2189,10 +2206,10 @@ class Constraint(BaseBlock):
         return (
             get_obj_repr(
                 self,
-                self.name,
+                f"'{self.name}'",
+                f"({self.lhs.degree(return_str=True)})",
                 height=len(self) if self.dimensions else None,
                 terms=len(self.lhs.data),
-                type=self.lhs.degree(return_str=True),
             )
             + "\n"
             + self.to_str()
@@ -2202,18 +2219,22 @@ class Constraint(BaseBlock):
 class Variable(BaseOperableBlock):
     """A decision variable for an optimization model.
 
+    !!! tip
+        If `lb` or `ub` are a dimensioned object (e.g. an [Expression][pyoframe.Expression]), they will automatically be [broadcasted](../../learn/concepts/addition.md#adding-expressions-with-differing-dimensions-using-over) to match the variable's dimensions.
+
     Parameters:
         *indexing_sets:
             If no indexing_sets are provided, a single variable with no dimensions is created.
             Otherwise, a variable is created for each element in the Cartesian product of the indexing_sets (see Set for details on behaviour).
-        lb:
-            The lower bound for all variables.
-        ub:
-            The upper bound for all variables.
         vtype:
             The type of the variable. Can be either a VType enum or a string. Default is VType.CONTINUOUS.
+        lb:
+            The lower bound for the variables.
+        ub:
+            The upper bound for the variables.
         equals:
-            When specified, a variable is created and a constraint is added to make the variable equal to the provided expression.
+            When specified, a variable is created for every label in `equals` and a constraint is added to make the variable equal to the provided expression.
+            `indexing_sets` cannot be provided when using `equals`.
 
     Examples:
         >>> import pandas as pd
@@ -2298,7 +2319,7 @@ class Variable(BaseOperableBlock):
                 assert len(indexing_sets) == 0, (
                     "Cannot specify both 'equals' and 'indexing_sets'"
                 )
-                equals = equals.to_expr()
+                equals = equals.to_expr()  # TODO don't rely on monkey patch
                 indexing_sets = (equals,)
 
         data = Set(*indexing_sets).data if len(indexing_sets) > 0 else pl.DataFrame()
@@ -2309,10 +2330,16 @@ class Variable(BaseOperableBlock):
         self._equals: Expression | None = equals
 
         if lb is not None and not isinstance(lb, (float, int)):
+            lb: Expression = lb.to_expr()  # TODO don't rely on monkey patch
+            if not self.dimensionless:
+                lb = lb.over(*self.dimensions)
             self._lb_expr, self.lb = lb, None
         else:
             self._lb_expr, self.lb = None, lb
         if ub is not None and not isinstance(ub, (float, int)):
+            ub = ub.to_expr()  # TODO don't rely on monkey patch
+            if not self.dimensionless:
+                ub = ub.over(*self.dimensions)  # pyright: ignore[reportOptionalIterable]
             self._ub_expr, self.ub = ub, None
         else:
             self._ub_expr, self.ub = None, ub
@@ -2518,7 +2545,7 @@ class Variable(BaseOperableBlock):
         result = (
             get_obj_repr(
                 self,
-                self.name,
+                f"'{self.name}'",
                 lb=self.lb,
                 ub=self.ub,
                 height=self.data.height if self.dimensions else None,
@@ -2581,7 +2608,7 @@ class Variable(BaseOperableBlock):
                 https://bravos-power.github.io/pyoframe/latest/learn/concepts/addition
 
             >>> (m.bat_charge + m.bat_flow).drop_extras() == m.bat_charge.next("time")
-            <Constraint 'unnamed' height=6 terms=18 type=linear>
+            <Constraint 'unnamed' (linear) height=6 terms=18>
             ┌───────┬─────────┬────────────────────────────────────────────────────────────────────────────────┐
             │ time  ┆ city    ┆ constraint                                                                     │
             │ (3)   ┆ (2)     ┆                                                                                │
@@ -2603,7 +2630,7 @@ class Variable(BaseOperableBlock):
             >>> (m.bat_charge + m.bat_flow) == m.bat_charge.next(
             ...     "time", wrap_around=True
             ... )
-            <Constraint 'unnamed' height=8 terms=24 type=linear>
+            <Constraint 'unnamed' (linear) height=8 terms=24>
             ┌───────┬─────────┬────────────────────────────────────────────────────────────────────────────────┐
             │ time  ┆ city    ┆ constraint                                                                     │
             │ (4)   ┆ (2)     ┆                                                                                │

pyoframe/_model.py

@@ -234,7 +234,7 @@ class Model:
                 from pyoptinterface import ipopt
             except ModuleNotFoundError as e:  # pragma: no cover
                 raise ModuleNotFoundError(
-                    "Failed to import the Ipopt solver. Did you run `pip install pyoptinterface[ipopt]`?"
+                    "Failed to import the Ipopt solver. Did you run `pip install pyoptinterface[nlp]`?"
                 ) from e
 
             try:
@@ -335,7 +335,7 @@ class Model:
             ValueError: Objective is not defined.
             >>> m.maximize = m.X
             >>> m.objective
-            <Objective terms=1 type=linear>
+            <Objective (linear) terms=1>
             X
 
         See Also:
@@ -417,7 +417,7 @@ class Model:
     def __repr__(self) -> str:
         return get_obj_repr(
             self,
-            self.name,
+            f"'{self.name}'" if self.name is not None else None,
             vars=len(self.variables),
             constrs=len(self.constraints),
             has_objective=self.has_objective,

pyoframe/_model_element.py

@@ -48,6 +48,8 @@ class BaseBlock(ABC):
         self._data = data
         self._model: Model | None = None
         self.name: str = name  # gets overwritten if object is added to model
+        """A user-friendly name that is displayed when printing the object or in error messages.
+        When an object is added to a model, this name is updated to the name used in the model."""
 
     def _on_add_to_model(self, model: Model, name: str):
         self.name = name

pyoframe/_monkey_patch.py

@@ -5,8 +5,8 @@ from functools import wraps
 import pandas as pd
 import polars as pl
 
-from pyoframe._constants import COEF_KEY, CONST_TERM, VAR_KEY
-from pyoframe._core import BaseOperableBlock, Expression
+from pyoframe._core import BaseOperableBlock
+from pyoframe._param import Param
 
 
 def _patch_class(cls):
@@ -29,54 +29,10 @@ def _patch_class(cls):
     cls.__contains__ = _patch_method(cls.__contains__)
 
 
-def polars_df_to_expr(self: pl.DataFrame) -> Expression:
-    """Converts a [polars](https://pola.rs/) `DataFrame` to a Pyoframe [Expression][pyoframe.Expression] by using the last column for values and the previous columns as dimensions.
-
-    See [Special Functions](../../learn/concepts/special-functions.md#dataframeto_expr) for more details.
-
-    Examples:
-        >>> import polars as pl
-        >>> df = pl.DataFrame({"x": [1, 2, 3], "y": [4, 5, 6], "z": [7, 8, 9]})
-        >>> df.to_expr()
-        <Expression height=3 terms=3 type=constant>
-        ┌─────┬─────┬────────────┐
-        │ x   ┆ y   ┆ expression │
-        │ (3) ┆ (3) ┆            │
-        ╞═════╪═════╪════════════╡
-        │ 1   ┆ 4   ┆ 7          │
-        │ 2   ┆ 5   ┆ 8          │
-        │ 3   ┆ 6   ┆ 9          │
-        └─────┴─────┴────────────┘
-    """
-    name = self.columns[-1]
-    return Expression(
-        self.rename({name: COEF_KEY})
-        .drop_nulls(COEF_KEY)
-        .with_columns(pl.lit(CONST_TERM).alias(VAR_KEY)),
-        name=name,
-    )
-
-
-def pandas_df_to_expr(self: pd.DataFrame) -> Expression:
-    """Same as [`polars.DataFrame.to_expr`](./polars.DataFrame.to_expr.md), but for [pandas](https://pandas.pydata.org/) DataFrames."""
-    return polars_df_to_expr(pl.from_pandas(self))
-
-
-def pandas_series_to_expr(self: pd.Series) -> Expression:
-    """Converts a [pandas](https://pandas.pydata.org/) `Series` to a Pyoframe [Expression][pyoframe.Expression], using the index for labels.
-
-    See [Special Functions](../../learn/concepts/special-functions.md#dataframeto_expr) for more details.
-
-    Note that no equivalent method exists for Polars Series, as Polars does not support indexes.
-    """
-    return pandas_df_to_expr(self.to_frame().reset_index())
-
-
 def patch_dataframe_libraries():
     _patch_class(pd.DataFrame)
     _patch_class(pd.Series)
     _patch_class(pl.DataFrame)
-    _patch_class(pl.Series)
-    pl.DataFrame.to_expr = polars_df_to_expr
-    pd.DataFrame.to_expr = pandas_df_to_expr
-    pd.Series.to_expr = pandas_series_to_expr
+    pl.DataFrame.to_expr = lambda self: Param(self)  # type: ignore
+    pd.DataFrame.to_expr = lambda self: Param(self)  # type: ignore
+    pd.Series.to_expr = lambda self: Param(self)  # type: ignore

pyoframe/_objective.py

@@ -20,7 +20,7 @@ class Objective(Expression):
         >>> m.con = m.A + m.B <= 10
         >>> m.maximize = 2 * m.B + 4
         >>> m.maximize
-        <Objective terms=2 type=linear>
+        <Objective (linear) terms=2>
         2 B +4
 
         The objective value can be retrieved with from the solver once the model is solved using `.value`.
@@ -67,7 +67,7 @@ class Objective(Expression):
         if isinstance(expr, (int, float)):
             expr = Expression.constant(expr)
         else:
-            expr = expr.to_expr()
+            expr = expr.to_expr()  # TODO don't rely on monkey patch
         super().__init__(expr.data, name="objective")
         self._model = expr._model
         if self.dimensions is not None:

pyoframe/_param.py

@@ -0,0 +1,99 @@
+"""Defines the function for creating model parameters."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pandas as pd
+import polars as pl
+
+from pyoframe._constants import COEF_KEY, CONST_TERM, VAR_KEY
+from pyoframe._core import Expression
+
+
+def Param(
+    data: pl.DataFrame | pd.DataFrame | pd.Series | dict | str | Path,
+) -> Expression:
+    """Creates a model parameter, i.e. an [Expression][pyoframe.Expression] that doesn't involve any variables.
+
+    A Parameter can be created from a DataFrame, CSV file, Parquet file, data dictionary, or a Pandas Series.
+
+    !!! info "`Param` is a function, not a class"
+        Technically, `Param(data)` is a function that returns an [Expression][pyoframe.Expression], not a class.
+        However, for consistency with other modeling frameworks, we provide it as a class-like function (i.e. an uppercase function).
+
+    !!! tip "Smart naming"
+        If a Param is not given a name (i.e. if it is not assigned to a model: `m.my_name = Param(...)`),
+        then its [name][pyoframe._model_element.BaseBlock.name] is inferred from the name of the column in `data` that contains the parameter values.
+        This makes debugging models with inline parameters easier.
+
+    Args:
+        data: The data to use for the parameter.
+
+            If `data` is a polars or pandas `DataFrame`, the last column will be treated as the values of the parameter, and all other columns as labels.
+
+            If `data` is a string or `Path`, it will be interpreted as a path to a CSV or Parquet file that will be read and used as a `DataFrame`. The file extension must be `.csv` or `.parquet`.
+
+            If `data` is a `pandas.Series`, the index(es) will be treated as columns for labels and the series values as the parameter values.
+
+            If `data` is of any other type (e.g. a dictionary), it will be used as if you had called `Param(pl.DataFrame(data))`.
+
+    Returns:
+        An Expression representing the parameter.
+
+    Examples:
+        >>> m = pf.Model()
+        >>> m.fixed_cost = pf.Param({"plant": ["A", "B"], "cost": [1000, 1500]})
+        >>> m.fixed_cost
+        <Expression (parameter) height=2 terms=2>
+        ┌───────┬────────────┐
+        │ plant ┆ expression │
+        │ (2)   ┆            │
+        ╞═══════╪════════════╡
+        │ A     ┆ 1000       │
+        │ B     ┆ 1500       │
+        └───────┴────────────┘
+
+        Since `Param` simply returns an Expression, you can use it in building larger expressions as usual:
+
+        >>> m.variable_cost = pf.Param(
+        ...     pl.DataFrame({"plant": ["A", "B"], "cost": [50, 60]})
+        ... )
+        >>> m.total_cost = m.fixed_cost + m.variable_cost
+        >>> m.total_cost
+        <Expression (parameter) height=2 terms=2>
+        ┌───────┬────────────┐
+        │ plant ┆ expression │
+        │ (2)   ┆            │
+        ╞═══════╪════════════╡
+        │ A     ┆ 1050       │
+        │ B     ┆ 1560       │
+        └───────┴────────────┘
+    """
+    if isinstance(data, pd.Series):
+        data = data.to_frame().reset_index()
+    if isinstance(data, pd.DataFrame):
+        data = pl.from_pandas(data)
+
+    if isinstance(data, (str, Path)):
+        data = Path(data)
+        if data.suffix.lower() == ".csv":
+            data = pl.read_csv(data)
+        elif data.suffix.lower() in {".parquet"}:
+            data = pl.read_parquet(data)
+        else:
+            raise NotImplementedError(
+                f"Could not create parameter. Unsupported file format: {data.suffix}"
+            )
+
+    if not isinstance(data, pl.DataFrame):
+        data = pl.DataFrame(data)
+
+    value_col = data.columns[-1]
+
+    return Expression(
+        data.rename({value_col: COEF_KEY})
+        .drop_nulls(COEF_KEY)
+        .with_columns(pl.lit(CONST_TERM).alias(VAR_KEY)),
+        name=value_col,
+    )

pyoframe/_utils.py

@@ -42,7 +42,7 @@ def get_obj_repr(obj: object, *props: str | None, **kwargs):
 
     See usage for examples.
     """
-    props_str = " ".join(f"'{v}'" for v in props if v is not None)
+    props_str = " ".join(v for v in props if v is not None)
     if props_str:
         props_str += " "
     kwargs_str = " ".join(f"{k}={v}" for k, v in kwargs.items() if v is not None)
@@ -302,7 +302,7 @@ class NamedVariableMapper:
         >>> m = pf.Model()
         >>> m.foo = pf.Variable(pl.DataFrame({"t": range(4)}))
         >>> m.foo.sum()
-        <Expression terms=4 type=linear>
+        <Expression (linear) terms=4>
         foo[0] + foo[1] + foo[2] + foo[3]
     """
 

pyoframe/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '1.0.1'
-__version_tuple__ = version_tuple = (1, 0, 1)
+__version__ = version = '1.1.0'
+__version_tuple__ = version_tuple = (1, 1, 0)
 
 __commit_id__ = commit_id = None

{pyoframe-1.0.1.dist-info → pyoframe-1.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyoframe
-Version: 1.0.1
+Version: 1.1.0
 Summary: Blazing fast linear program interface
 Author-email: Bravos Power <dev@bravospower.com>
 License-Expression: MIT
@@ -20,21 +20,21 @@ Requires-Dist: pyarrow
 Requires-Dist: pandas<3
 Requires-Dist: pyoptinterface==0.5.1
 Provides-Extra: highs
-Requires-Dist: highsbox<=1.11.0; extra == "highs"
+Requires-Dist: highsbox<=1.12.0; extra == "highs"
 Provides-Extra: ipopt
 Requires-Dist: pyoptinterface[nlp]; extra == "ipopt"
-Requires-Dist: llvmlite<=0.44.0; extra == "ipopt"
+Requires-Dist: llvmlite<=0.46.0; extra == "ipopt"
 Provides-Extra: dev
 Requires-Dist: ruff==0.12.11; extra == "dev"
 Requires-Dist: polars>=1.32.3; extra == "dev"
 Requires-Dist: pytest==8.4.1; extra == "dev"
 Requires-Dist: pytest-cov==6.2.1; extra == "dev"
-Requires-Dist: sybil[pytest]==9.2.0; extra == "dev"
+Requires-Dist: sybil[pytest]==9.3.0; extra == "dev"
 Requires-Dist: pre-commit==4.3.0; extra == "dev"
 Requires-Dist: gurobipy==12.0.3; extra == "dev"
 Requires-Dist: coverage==7.10.6; extra == "dev"
 Requires-Dist: ipykernel==6.30.1; extra == "dev"
-Requires-Dist: highsbox<=1.11.0; extra == "dev"
+Requires-Dist: highsbox<=1.12.0; extra == "dev"
 Requires-Dist: pyoptinterface[nlp]; extra == "dev"
 Requires-Dist: numpy; extra == "dev"
 Provides-Extra: docs

pyoframe-1.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+pyoframe/__init__.py,sha256=Ij-9priyKTHaGzVhMhtZlDKWz0ggAwGAS9DqB4O6zWU,886
+pyoframe/_arithmetic.py,sha256=VZAlZZQ7StYMRbJcfWGZ7he2Ds6b6zoY0J1GxG99UWM,20549
+pyoframe/_constants.py,sha256=LWlry4K5w-3vVyq7CpEQ28UfM3LulbKxkO-nBlWWJzE,17847
+pyoframe/_core.py,sha256=EiuAhW9M2616gjW8htJqP4FuSlUb3zfwWP1ydTsQ1Qo,118507
+pyoframe/_model.py,sha256=IcmqfJ1agNF4LzHUR-bXr-K-3NXsJGcBU6Ga55jcmik,22503
+pyoframe/_model_element.py,sha256=VVRqh2uM8HFvRFvqQmgM93jqofa-8mPwyB-qYA0YjRU,6345
+pyoframe/_monkey_patch.py,sha256=7FWMRXZIHK7mRkZfOKQ8Y724q1sPbq_EiPjlJCTfYoA,1168
+pyoframe/_objective.py,sha256=HeiP4KjlXn-IplqV-MALF26yMmh41JyHXjZhhtKJIsQ,4367
+pyoframe/_param.py,sha256=FUSfITPb-WZA-xwVcF9dCCHO2K_pky5GBWooImsSy6I,4147
+pyoframe/_utils.py,sha256=XaPZ8j9YQ-HnAuT2NLAvDCJGVzKSjUmRxARNuGWykIM,12508
+pyoframe/_version.py,sha256=ePNVzJOkxR8FY5bezqKQ_fgBRbzH1G7QTaRDHvGQRAY,704
+pyoframe-1.1.0.dist-info/licenses/LICENSE,sha256=u_Spw4ynlwTMRZeCX-uacv_hBU547pBygiA6d2ONNV4,1074
+pyoframe-1.1.0.dist-info/METADATA,sha256=cO4Wu3bBxixzFjhmkzi40kRkPbAmRiQ161L8dz0MQjo,4060
+pyoframe-1.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pyoframe-1.1.0.dist-info/top_level.txt,sha256=10z3OOJSVLriQ0IrFLMH8CH9zByugPWolqhlHlkNjV4,9
+pyoframe-1.1.0.dist-info/RECORD,,

pyoframe-1.0.1.dist-info/RECORD

@@ -1,15 +0,0 @@
-pyoframe/__init__.py,sha256=Nlql3FYed7bXWumvUeMd3rjnoL4l8XC5orO4uxWrDAc,839
-pyoframe/_arithmetic.py,sha256=9V3N2Yq7Ib13UfTQnINxa9oS7786f5DnRsrAPcFlYYE,20558
-pyoframe/_constants.py,sha256=n80so80usutTJpeDlDXkHRE-_dpPD1LxF2plscXhbwQ,17925
-pyoframe/_core.py,sha256=NXH_ze1iN61vk38Fj6Ire0uqKUJRSDUlD6PVc8mTHrQ,116975
-pyoframe/_model.py,sha256=MtA9gleQoUAqO2dxhCFZ8GOZvyyJB_PIYBzvQ0m8enc,22466
-pyoframe/_model_element.py,sha256=oQ7nykJ5XEzJ6Klq3lT6ZwQvDrxY_wgZYVaN7pgyZOs,6149
-pyoframe/_monkey_patch.py,sha256=Y2zXN5MpqDeAWELddyaFQNam57fehSXHiza1PFaZ-QY,3128
-pyoframe/_objective.py,sha256=yIHoaBLsjGCKzIB6RQErV3vzE2U5DGORlhifRStB_Mc,4335
-pyoframe/_utils.py,sha256=5yy-5DOWCW7q3QzPv9tKquLUQJtNdpJJilEqxAq7TN8,12518
-pyoframe/_version.py,sha256=JvmBpae6cHui8lSCsCcZQAxzawN2NERHGsr-rIUeJMo,704
-pyoframe-1.0.1.dist-info/licenses/LICENSE,sha256=u_Spw4ynlwTMRZeCX-uacv_hBU547pBygiA6d2ONNV4,1074
-pyoframe-1.0.1.dist-info/METADATA,sha256=UtnvQdR7vJQvLm8p0RvgwdGfR7yCISswH_V4KuihBr4,4060
-pyoframe-1.0.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pyoframe-1.0.1.dist-info/top_level.txt,sha256=10z3OOJSVLriQ0IrFLMH8CH9zByugPWolqhlHlkNjV4,9
-pyoframe-1.0.1.dist-info/RECORD,,