pyoframe 1.0.0a0__py3-none-any.whl → 1.1.0__py3-none-any.whl

pyoframe/_constants.py

@@ -17,41 +17,54 @@ CONSTRAINT_KEY = "__constraint_id"
 SOLUTION_KEY = "solution"
 DUAL_KEY = "dual"
 
-# TODO: move as configuration since this could be too small... also add a test to make sure errors occur on overflow.
-KEY_TYPE = pl.UInt32
-
 
 @dataclass
 class _Solver:
     name: SUPPORTED_SOLVER_TYPES
     supports_integer_variables: bool = True
-    supports_quadratics: bool = True
+    supports_quadratic_constraints: bool = True
+    supports_non_convex: bool = True
     supports_duals: bool = True
     supports_objective_sense: bool = True
     supports_write: bool = True
-    block_auto_names: bool = False
+    accelerate_with_repeat_names: bool = False
     """
-    When True, Pyoframe blocks automatic variable and constraint name
-    generation to improve performance by setting all the variable names to 'V'
-    and all the constraint names to 'C'. This should only be True for solvers
-    that support conflicting variable and constraint names. Benchmarking
-    should be performed to verify that this improves performance before turning
-    this on for other solvers.
+    If True, Pyoframe sets all the variable and constraint names to 'V'
+    and 'C', respectively, which, for some solvers, was found to improve
+    performance. This setting should only be enabled for a given solver after
+    testing that a) it actually improves performance, and b) the solver can
+    handle conflicting variable and constraint names.
+    So far, only Gurobi has been tested.
+    Note, that when enabled, Model.write() is not supported
+    (unless solver_uses_variable_names=True) because the outputted files would
+    be meaningless as all variables/constraints would have identical names.
     """
 
+    def __post_init__(self):
+        if self.supports_non_convex:
+            assert self.supports_quadratic_constraints, (
+                "Non-convex solvers typically support quadratic constraints. Are you sure this is correct?"
+            )
+
     def __repr__(self):
         return self.name
 
 
 SUPPORTED_SOLVERS = [
-    _Solver("gurobi", block_auto_names=True),
-    _Solver("highs", supports_quadratics=False, supports_duals=False),
+    _Solver("gurobi", accelerate_with_repeat_names=True),
+    _Solver(
+        "highs",
+        supports_quadratic_constraints=False,
+        supports_non_convex=False,
+        supports_duals=False,
+    ),
     _Solver(
         "ipopt",
         supports_integer_variables=False,
         supports_objective_sense=False,
         supports_write=False,
     ),
+    _Solver("copt", supports_non_convex=False),
 ]
 
 
@@ -71,7 +84,7 @@ RESERVED_COL_KEYS = (
 @dataclass
 class ConfigDefaults:
     default_solver: SUPPORTED_SOLVER_TYPES | _Solver | Literal["raise", "auto"] = "auto"
-    disable_unmatched_checks: bool = False
+    disable_extras_checks: bool = False
     enable_is_duplicated_expression_safety_check: bool = False
     integer_tolerance: float = 1e-8
     float_to_str_precision: int | None = 5
@@ -85,6 +98,7 @@ class ConfigDefaults:
     )
     print_max_terms: int = 5
     maintain_order: bool = True
+    id_dtype = pl.UInt32
 
 
 class _Config:
@@ -114,55 +128,52 @@ class _Config:
         self._settings.default_solver = value
 
     @property
-    def disable_unmatched_checks(self) -> bool:
-        """When `True`, improves performance by skipping unmatched checks (not recommended).
+    def disable_extras_checks(self) -> bool:
+        """When `True`, improves performance by skipping checks for extra values (not recommended).
 
-        When `True`, unmatched checks are disabled which effectively means that all expressions
-        are treated as if they contained [`.keep_unmatched()`][pyoframe.Expression.keep_unmatched]
-        (unless [`.drop_unmatched()`][pyoframe.Expression.drop_unmatched] was applied).
+        When `True`, checks for extra values are disabled which effectively means that all expressions
+        are treated as if they contained [`.keep_extras()`][pyoframe.Expression.keep_extras]
+        (unless [`.drop_extras()`][pyoframe.Expression.drop_extras] was applied).
 
         !!! warning
-            This might improve performance, but it will suppress the "unmatched" errors that alert developers to unexpected
-            behaviors (see [here](../learn/concepts/special-functions.md#drop_unmatched-and-keep_unmatched)).
+            This might improve performance, but it will suppress the errors that alert you of unexpected
+            behaviors ([learn more](../../learn/concepts/addition.md)).
             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 indices:
+            Normally, an error warns users that the two expressions have conflicting labels:
             >>> population + population_influx
             Traceback (most recent call last):
             ...
-            pyoframe._constants.PyoframeError: Cannot add the two expressions below because of unmatched values.
+            pyoframe._constants.PyoframeError: Cannot add the two expressions below because expression 1 has extra labels.
             Expression 1:   pop
             Expression 2:   influx
-            Unmatched values:
-            shape: (1, 2)
-            ┌──────────┬────────────┐
-            │ city     ┆ city_right │
-            │ ---      ┆ ---        │
-            │ str      ┆ str        │
-            ╞══════════╪════════════╡
-            │ Montreal ┆ null       │
-            └──────────┴────────────┘
-            If this is intentional, use .drop_unmatched() or .keep_unmatched().
-
-            But if `Config.disable_unmatched_checks = True`, the error is suppressed and the sum is considered to be `population.keep_unmatched() + population_influx.keep_unmatched()`:
-            >>> pf.Config.disable_unmatched_checks = True
+            Extra labels in expression 1:
+            ┌──────────┐
+            │ city     │
+            ╞══════════╡
+            │ Montreal │
+            └──────────┘
+            Use .drop_extras() or .keep_extras() to indicate how the extra labels should be handled. Learn more at
+                https://bravos-power.github.io/pyoframe/latest/learn/concepts/addition
+
+            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)       ┆            │
@@ -172,11 +183,11 @@ class _Config:
             │ Montreal  ┆ 1704694    │
             └───────────┴────────────┘
         """
-        return self._settings.disable_unmatched_checks
+        return self._settings.disable_extras_checks
 
-    @disable_unmatched_checks.setter
-    def disable_unmatched_checks(self, value: bool):
-        self._settings.disable_unmatched_checks = value
+    @disable_extras_checks.setter
+    def disable_extras_checks(self, value: bool):
+        self._settings.disable_extras_checks = value
 
     @property
     def enable_is_duplicated_expression_safety_check(self) -> bool:
@@ -216,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
@@ -268,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) ┆                               │
@@ -286,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
@@ -308,17 +319,52 @@ class _Config:
     def maintain_order(self, value: bool):
         self._settings.maintain_order = value
 
+    @property
+    def id_dtype(self):
+        """The Polars data type to use for variable and constraint IDs.
+
+        Defaults to `pl.UInt32` which should be ideal for most users.
+
+        Users with more than 4 billion variables or constraints can change this to `pl.UInt64`.
+
+        Users concerned with memory usage and with fewer than 65k variables or constraints can change this to `pl.UInt16`.
+
+        !!! warning
+            Changing this setting after creating a model will lead to errors.
+            You should only change this setting before creating any models.
+
+        Examples:
+            An error is automatically raised if the number of variables or constraints exceeds the chosen data type:
+            >>> pf.Config.id_dtype = pl.UInt8
+            >>> m = pf.Model()
+            >>> big_set = pf.Set(x=range(2**8 + 1))
+            >>> m.X = pf.Variable()
+            >>> m.constraint = m.X.over("x") <= big_set
+            Traceback (most recent call last):
+            ...
+            TypeError: Number of constraints exceeds the current data type (UInt8). Consider increasing the data type by changing Config.id_dtype.
+            >>> m.X_large = pf.Variable(big_set)
+            Traceback (most recent call last):
+            ...
+            TypeError: Number of variables exceeds the current data type (UInt8). Consider increasing the data type by changing Config.id_dtype.
+        """
+        return self._settings.id_dtype
+
+    @id_dtype.setter
+    def id_dtype(self, value):
+        self._settings.id_dtype = value
+
     def reset_defaults(self):
         """Resets all configuration options to their default values.
 
         Examples:
-            >>> pf.Config.disable_unmatched_checks
+            >>> pf.Config.disable_extras_checks
             False
-            >>> pf.Config.disable_unmatched_checks = True
-            >>> pf.Config.disable_unmatched_checks
+            >>> pf.Config.disable_extras_checks = True
+            >>> pf.Config.disable_extras_checks
             True
             >>> pf.Config.reset_defaults()
-            >>> pf.Config.disable_unmatched_checks
+            >>> pf.Config.disable_extras_checks
             False
         """
         self._settings = ConfigDefaults()
@@ -389,8 +435,8 @@ class VType(Enum):
             raise ValueError(f"Invalid variable type: {self}")  # pragma: no cover
 
 
-class UnmatchedStrategy(Enum):
-    """An enum to specify how to handle unmatched values in expressions."""
+class ExtrasStrategy(Enum):
+    """An enum to specify how to handle extra values in expressions."""
 
     UNSET = "not_set"
     DROP = "drop"
@@ -404,7 +450,7 @@ VTypeValue = Literal["continuous", "binary", "integer"]
 for enum, type in [(ObjSense, ObjSenseValue), (VType, VTypeValue)]:
     assert set(typing.get_args(type)) == {vtype.value for vtype in enum}
 
-SUPPORTED_SOLVER_TYPES = Literal["gurobi", "highs", "ipopt"]
+SUPPORTED_SOLVER_TYPES = Literal["gurobi", "highs", "ipopt", "copt"]
 assert set(typing.get_args(SUPPORTED_SOLVER_TYPES)) == {
     s.name for s in SUPPORTED_SOLVERS
 }