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

pyoframe/{util.py → _utils.py}

@@ -1,37 +1,49 @@
-"""
-File containing utility functions and classes.
-"""
+"""Contains utility functions and classes."""
 
+from __future__ import annotations
+
+import itertools
+import sys
+from collections.abc import Iterable
 from dataclasses import dataclass, field
 from functools import wraps
-from typing import (
-    TYPE_CHECKING,
-    Any,
-    Dict,
-    Iterable,
-    List,
-    Optional,
-    Sequence,
-    Type,
-    Union,
-)
+from typing import TYPE_CHECKING, Any, Callable
 
 import pandas as pd
 import polars as pl
 
-from pyoframe.constants import COEF_KEY, CONST_TERM, RESERVED_COL_KEYS, VAR_KEY, Config
+from pyoframe._constants import (
+    COEF_KEY,
+    CONST_TERM,
+    RESERVED_COL_KEYS,
+    VAR_KEY,
+    Config,
+)
 
 if TYPE_CHECKING:  # pragma: no cover
-    from pyoframe.model import Variable
-    from pyoframe.model_element import ModelElementWithId
+    from pyoframe._core import SupportsMath
+    from pyoframe._model import Variable
+    from pyoframe._model_element import ModelElementWithId
 
+if sys.version_info >= (3, 10):
+    pairwise = itertools.pairwise
+else:
 
-def get_obj_repr(obj: object, _props: Iterable[str] = (), **kwargs):
-    """
-    Helper function to generate __repr__ strings for classes. See usage for examples.
+    def pairwise(iterable):
+        iterator = iter(iterable)
+        a = next(iterator)
+
+        for b in iterator:
+            yield a, b
+            a = b
+
+
+def get_obj_repr(obj: object, *props: str | None, **kwargs):
+    """Generates __repr__() strings for classes.
+
+    See usage for examples.
     """
-    props = {prop: getattr(obj, prop) for prop in _props}
-    props_str = " ".join(f"{k}={v}" for k, v in props.items() if v is not None)
+    props_str = " ".join(f"'{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)
@@ -39,10 +51,10 @@ def get_obj_repr(obj: object, _props: Iterable[str] = (), **kwargs):
 
 
 def parse_inputs_as_iterable(
-    *inputs: Union[Any, Iterable[Any]],
+    *inputs: Any | Iterable[Any],
 ) -> Iterable[Any]:
-    """
-    Converts a parameter *x: Any | Iteraable[Any] to a single Iterable[Any] object.
+    """Converts a parameter *x: Any | Iterable[Any] to a single Iterable[Any] object.
+
     This is helpful to support these two ways of passing arguments:
         - foo([1, 2, 3])
         - foo(1, 2, 3)
@@ -59,7 +71,7 @@ def parse_inputs_as_iterable(
     return inputs
 
 
-def _is_iterable(input: Union[Any, Iterable[Any]]) -> bool:
+def _is_iterable(input: Any | Iterable[Any]) -> bool:
     # Inspired from the polars library, TODO: Consider using opposite check, i.e. equals list or tuple
     return isinstance(input, Iterable) and not isinstance(
         input,
@@ -78,15 +90,11 @@ def _is_iterable(input: Union[Any, Iterable[Any]]) -> bool:
 
 
 def concat_dimensions(
-    df: pl.DataFrame,
-    prefix: Optional[str] = None,
-    keep_dims: bool = True,
-    ignore_columns: Sequence[str] = RESERVED_COL_KEYS,
-    replace_spaces: bool = True,
-    to_col: str = "concated_dim",
+    df: pl.DataFrame, prefix: str, keep_dims: bool = True, to_col: str = "concated_dim"
 ) -> pl.DataFrame:
-    """
-    Returns a new DataFrame with the column 'concated_dim'. Reserved columns are ignored.
+    """Returns a new DataFrame with the column 'concated_dim'.
+
+    Reserved columns are ignored. Spaces are replaced with underscores.
 
     Parameters:
         df:
@@ -94,9 +102,7 @@ def concat_dimensions(
         prefix:
             The prefix to be added to the concated dimension.
         keep_dims:
-            If True, the original dimensions are kept in the new DataFrame.
-        replace_spaces : bool, optional
-            If True, replaces spaces with underscores.
+            If `True`, the original dimensions are kept in the new DataFrame.
 
     Examples:
         >>> import polars as pl
@@ -106,20 +112,6 @@ def concat_dimensions(
         ...         "dim2": ["Y", "Y", "Y", "N", "N", "N"],
         ...     }
         ... )
-        >>> concat_dimensions(df)
-        shape: (6, 3)
-        ┌──────┬──────┬──────────────┐
-        │ dim1 ┆ dim2 ┆ concated_dim │
-        │ ---  ┆ ---  ┆ ---          │
-        │ i64  ┆ str  ┆ str          │
-        ╞══════╪══════╪══════════════╡
-        │ 1    ┆ Y    ┆ [1,Y]        │
-        │ 2    ┆ Y    ┆ [2,Y]        │
-        │ 3    ┆ Y    ┆ [3,Y]        │
-        │ 1    ┆ N    ┆ [1,N]        │
-        │ 2    ┆ N    ┆ [2,N]        │
-        │ 3    ┆ N    ┆ [3,N]        │
-        └──────┴──────┴──────────────┘
         >>> concat_dimensions(df, prefix="x")
         shape: (6, 3)
         ┌──────┬──────┬──────────────┐
@@ -134,7 +126,7 @@ def concat_dimensions(
         │ 2    ┆ N    ┆ x[2,N]       │
         │ 3    ┆ N    ┆ x[3,N]       │
         └──────┴──────┴──────────────┘
-        >>> concat_dimensions(df, keep_dims=False)
+        >>> concat_dimensions(df, prefix="", keep_dims=False)
         shape: (6, 1)
         ┌──────────────┐
         │ concated_dim │
@@ -148,7 +140,8 @@ def concat_dimensions(
         │ [2,N]        │
         │ [3,N]        │
         └──────────────┘
-        >>> # Properly handles cases with no dimensions and ignores reserved columns
+
+        Properly handles cases with no dimensions and ignores reserved columns
         >>> df = pl.DataFrame({VAR_KEY: [1, 2]})
         >>> concat_dimensions(df, prefix="x")
         shape: (2, 2)
@@ -163,7 +156,7 @@ def concat_dimensions(
     """
     if prefix is None:
         prefix = ""
-    dimensions = [col for col in df.columns if col not in ignore_columns]
+    dimensions = [col for col in df.columns if col not in RESERVED_COL_KEYS]
     if dimensions:
         query = pl.concat_str(
             pl.lit(prefix + "["),
@@ -173,10 +166,7 @@ def concat_dimensions(
     else:
         query = pl.lit(prefix)
 
-    df = df.with_columns(query.alias(to_col))
-
-    if replace_spaces:
-        df = df.with_columns(pl.col(to_col).str.replace_all(" ", "_"))
+    df = df.with_columns(query.str.replace_all(" ", "_").alias(to_col))
 
     if not keep_dims:
         df = df.drop(*dimensions)
@@ -185,10 +175,12 @@ def concat_dimensions(
 
 
 def cast_coef_to_string(
-    df: pl.DataFrame, column_name: str = COEF_KEY, drop_ones: bool = True
+    df: pl.DataFrame,
+    column_name: str = COEF_KEY,
+    drop_ones: bool = True,
+    always_show_sign: bool = True,
 ) -> pl.DataFrame:
-    """
-    Converts column `column_name` of the dataframe `df` to a string. Rounds to `Config.print_float_precision` decimal places if not None.
+    """Converts column `column_name` of the DataFrame `df` to a string. Round to `Config.print_float_precision` decimal places if not None.
 
     Parameters:
         df:
@@ -196,7 +188,9 @@ def cast_coef_to_string(
         column_name:
             The name of the column to be casted.
         drop_ones:
-            If True, 1s are replaced with an empty string for non-constant terms.
+            If `True`, 1s are replaced with an empty string for non-constant terms.
+        always_show_sign:
+            If `True`, the sign of the coefficient is always shown, i.e. 1 becomes `+1` not just `1`.
 
     Examples:
         >>> import polars as pl
@@ -214,22 +208,26 @@ def cast_coef_to_string(
         │ +4  ┆ 4             │
         └─────┴───────────────┘
     """
-    df = df.with_columns(
-        pl.col(column_name).abs(),
-        _sign=pl.when(pl.col(column_name) < 0).then(pl.lit("-")).otherwise(pl.lit("+")),
-    )
-
     if Config.float_to_str_precision is not None:
         df = df.with_columns(pl.col(column_name).round(Config.float_to_str_precision))
 
+    if always_show_sign:
+        df = df.with_columns(
+            pl.col(column_name).abs(),
+            _sign=pl.when(pl.col(column_name) < 0)
+            .then(pl.lit("-"))
+            .otherwise(pl.lit("+")),
+        )
+
     df = df.with_columns(
-        pl.when(pl.col(column_name) == pl.col(column_name).floor())
+        pl.when(pl.col(column_name) == pl.col(column_name).round())
         .then(pl.col(column_name).cast(pl.Int64).cast(pl.String))
         .otherwise(pl.col(column_name).cast(pl.String))
         .alias(column_name)
     )
 
     if drop_ones:
+        assert always_show_sign, "drop_ones requires always_show_sign=True"
         condition = pl.col(column_name) == str(1)
         if VAR_KEY in df.columns:
             condition = condition & (pl.col(VAR_KEY) != CONST_TERM)
@@ -239,15 +237,16 @@ def cast_coef_to_string(
             .otherwise(pl.col(column_name))
             .alias(column_name)
         )
-    else:
-        df = df.with_columns(pl.col(column_name).cast(pl.Utf8))
-    return df.with_columns(pl.concat_str("_sign", column_name).alias(column_name)).drop(
-        "_sign"
-    )
+
+    if always_show_sign:
+        df = df.with_columns(
+            pl.concat_str("_sign", column_name).alias(column_name)
+        ).drop("_sign")
+    return df
 
 
 def unwrap_single_values(func):
-    """Decorator for functions that return DataFrames. Returned dataframes with a single value will instead return the value."""
+    """Returns the DataFrame unless it is a single value in which case return the value."""
 
     @wraps(func)
     def wrapper(*args, **kwargs):
@@ -259,52 +258,20 @@ def unwrap_single_values(func):
     return wrapper
 
 
-def dataframe_to_tupled_list(
-    df: pl.DataFrame, num_max_elements: Optional[int] = None
-) -> str:
-    """
-    Converts a dataframe into a list of tuples. Used to print a Set to the console. See examples for behaviour.
-
-    Examples:
-        >>> df = pl.DataFrame({"x": [1, 2, 3, 4, 5]})
-        >>> dataframe_to_tupled_list(df)
-        '[1, 2, 3, 4, 5]'
-        >>> dataframe_to_tupled_list(df, 3)
-        '[1, 2, 3, ...]'
-
-        >>> df = pl.DataFrame({"x": [1, 2, 3, 4, 5], "y": [2, 3, 4, 5, 6]})
-        >>> dataframe_to_tupled_list(df, 3)
-        '[(1, 2), (2, 3), (3, 4), ...]'
-    """
-    elipse = False
-    if num_max_elements is not None:
-        if len(df) > num_max_elements:
-            elipse = True
-            df = df.head(num_max_elements)
-
-    res = (row for row in df.iter_rows())
-    if len(df.columns) == 1:
-        res = (row[0] for row in res)
-
-    res = str(list(res))
-    if elipse:
-        res = res[:-1] + ", ...]"
-    return res
-
-
 @dataclass
 class FuncArgs:
-    args: List
-    kwargs: Dict = field(default_factory=dict)
+    args: list
+    kwargs: dict = field(default_factory=dict)
 
 
 class Container:
-    """
-    A placeholder object that makes it easy to set and get attributes. Used in Model.attr and Model.params, for example.
+    """A placeholder object that makes it easy to set and get attributes. Used in Model.attr and Model.params, for example.
 
     Examples:
         >>> x = {}
-        >>> params = Container(setter=lambda n, v: x.__setitem__(n, v), getter=lambda n: x[n])
+        >>> params = Container(
+        ...     setter=lambda n, v: x.__setitem__(n, v), getter=lambda n: x[n]
+        ... )
         >>> params.a = 1
         >>> params.b = 2
         >>> params.a
@@ -329,22 +296,21 @@ class Container:
 
 
 class NamedVariableMapper:
-    """
-    Maps variables to a string representation using the object's name and dimensions.
+    """Maps variables to a string representation using the object's name and dimensions.
 
     Examples:
         >>> import polars as pl
         >>> m = pf.Model()
         >>> m.foo = pf.Variable(pl.DataFrame({"t": range(4)}))
-        >>> pf.sum(m.foo)
-        <Expression size=1 dimensions={} terms=4>
-        foo[0] + foo[1] + foo[2] + foo[3]
+        >>> m.foo.sum()
+        <Expression terms=4 type=linear>
+        foo[0] + foo[1] + foo[2] + foo[3]
     """
 
     CONST_TERM_NAME = "_ONE"
     NAME_COL = "__name"
 
-    def __init__(self, cls: Type["ModelElementWithId"]) -> None:
+    def __init__(self, cls: type[ModelElementWithId]) -> None:
         self._ID_COL = VAR_KEY
         self.mapping_registry = pl.DataFrame(
             {self._ID_COL: [], self.NAME_COL: []},
@@ -357,7 +323,7 @@ class NamedVariableMapper:
             )
         )
 
-    def add(self, element: "Variable") -> None:
+    def add(self, element: Variable) -> None:
         self._extend_registry(self._element_to_map(element))
 
     def _extend_registry(self, df: pl.DataFrame) -> None:
@@ -375,16 +341,17 @@ class NamedVariableMapper:
             validate="m:1",
             left_on=id_col,
             right_on=self._ID_COL,
+            maintain_order="left" if Config.maintain_order else None,
         ).rename({self.NAME_COL: to_col})
 
-    def _element_to_map(self, element) -> pl.DataFrame:
+    def _element_to_map(self, element: Variable) -> pl.DataFrame:
         element_name = element.name  # type: ignore
         assert element_name is not None, (
             "Element must have a name to be used in a named mapping."
         )
         element._assert_has_ids()
         return concat_dimensions(
-            element.data.select(element.dimensions_unsafe + [VAR_KEY]),
+            element.data.select(element._dimensions_unsafe + [VAR_KEY]),
             keep_dims=False,
             prefix=element_name,
             to_col=self.NAME_COL,
@@ -392,19 +359,32 @@ class NamedVariableMapper:
 
 
 def for_solvers(*solvers: str):
-    """
-    Decorator that limits the function to only be called when the solver is in the `only` list.
-    """
+    """Limits the decorated function to only be available when the solver is in the `solvers` list."""
 
     def decorator(func):
         @wraps(func)
         def wrapper(self, *args, **kwargs):
-            if self.solver_name not in solvers:
+            if self.solver.name not in solvers:
                 raise NotImplementedError(
-                    f"Method '{func.__name__}' is not implemented for solver '{self.solver_name}'."
+                    f"Method '{func.__name__}' is not implemented for solver '{self.solver}'."
                 )
             return func(self, *args, **kwargs)
 
         return wrapper
 
     return decorator
+
+
+# TODO: rename and change to return_expr once Set is split away from SupportsMath
+def return_new(func: Callable[..., pl.DataFrame]) -> Callable[..., SupportsMath]:
+    """Decorator that upcasts the returned DataFrame to an Expression.
+
+    Requires the first argument (self) to support self._new().
+    """
+
+    @wraps(func)
+    def wrapper(self: SupportsMath, *args, **kwargs):
+        result = func(self, *args, **kwargs)
+        return self._new(result, name=f"{self.name}.{func.__name__}(…)")
+
+    return wrapper

pyoframe/_version.py

@@ -1,7 +1,14 @@
 # file generated by setuptools-scm
 # don't change, don't track in version control
 
-__all__ = ["__version__", "__version_tuple__", "version", "version_tuple"]
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
 
 TYPE_CHECKING = False
 if TYPE_CHECKING:
@@ -9,13 +16,19 @@ if TYPE_CHECKING:
     from typing import Union
 
     VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
 else:
     VERSION_TUPLE = object
+    COMMIT_ID = object
 
 version: str
 __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
 
-__version__ = version = '0.2.0'
-__version_tuple__ = version_tuple = (0, 2, 0)
+__version__ = version = '1.0.0a0'
+__version_tuple__ = version_tuple = (1, 0, 0, 'a0')
+
+__commit_id__ = commit_id = None

{pyoframe-0.2.0.dist-info → pyoframe-1.0.0a0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyoframe
-Version: 0.2.0
+Version: 1.0.0a0
 Summary: Blazing fast linear program interface
 Author-email: Bravos Power <dev@bravospower.com>
 License-Expression: MIT
@@ -20,30 +20,37 @@ Requires-Dist: numpy
 Requires-Dist: pyarrow
 Requires-Dist: pandas
 Requires-Dist: pyoptinterface<1,>=0.4.1
-Provides-Extra: dev
-Requires-Dist: ruff; extra == "dev"
-Requires-Dist: polars>=1.30.0; extra == "dev"
-Requires-Dist: bumpver; extra == "dev"
-Requires-Dist: pip-tools; extra == "dev"
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: pytest-cov; extra == "dev"
-Requires-Dist: pre-commit; extra == "dev"
-Requires-Dist: gurobipy; extra == "dev"
-Requires-Dist: highsbox; extra == "dev"
-Requires-Dist: coverage; extra == "dev"
-Requires-Dist: ipykernel; extra == "dev"
-Requires-Dist: pytest-markdown-docs; extra == "dev"
-Requires-Dist: mkdocs-material==9.*; extra == "dev"
-Requires-Dist: mkdocstrings[python]; extra == "dev"
-Requires-Dist: mkdocs-git-revision-date-localized-plugin; extra == "dev"
-Requires-Dist: mkdocs-git-committers-plugin-2; extra == "dev"
-Requires-Dist: mkdocs-gen-files; extra == "dev"
-Requires-Dist: mkdocs-section-index; extra == "dev"
-Requires-Dist: mkdocs-literate-nav; extra == "dev"
-Requires-Dist: mkdocs-table-reader-plugin; extra == "dev"
-Requires-Dist: markdown-hide-code>=0.1.1; extra == "dev"
 Provides-Extra: highs
 Requires-Dist: highsbox; extra == "highs"
+Provides-Extra: ipopt
+Requires-Dist: pyoptinterface[nlp]; extra == "ipopt"
+Requires-Dist: llvmlite<=0.44.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: 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; extra == "dev"
+Requires-Dist: pyoptinterface[nlp]; extra == "dev"
+Requires-Dist: llvmlite<=0.44.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs-material~=9.6.18; extra == "docs"
+Requires-Dist: mkdocstrings[python]~=0.30.0; extra == "docs"
+Requires-Dist: mkdocs-git-revision-date-localized-plugin~=1.4.7; extra == "docs"
+Requires-Dist: mkdocs-git-committers-plugin-2~=2.5.0; extra == "docs"
+Requires-Dist: mkdocs-gen-files~=0.5.0; extra == "docs"
+Requires-Dist: mkdocs-section-index~=0.3.10; extra == "docs"
+Requires-Dist: mkdocs-awesome-nav~=3.1.2; extra == "docs"
+Requires-Dist: doccmd==2025.4.8; extra == "docs"
+Requires-Dist: mkdocs-table-reader-plugin~=3.1.0; extra == "docs"
+Requires-Dist: markdown-katex==202406.1035; extra == "docs"
+Requires-Dist: mike==2.1.3; extra == "docs"
+Requires-Dist: ruff==0.12.11; extra == "docs"
 Dynamic: license-file
 
 # Pyoframe: Fast and low-memory linear programming models 
@@ -56,11 +63,11 @@ Dynamic: license-file
 [![Open Bugs](https://img.shields.io/github/issues-search/Bravos-Power/pyoframe?query=label%3Abug%20is%3Aopen&label=Open%20Bugs)](https://github.com/Bravos-Power/pyoframe/issues?q=is%3Aopen+is%3Aissue+label%3Abug)
 
 
-A library to rapidly and memory-efficiently formulate large and sparse optimization models using Pandas or Polars dataframes.
+A library to rapidly and memory-efficiently formulate large and sparse optimization models using Pandas or Polars DataFrames.
 
 ## **[Documentation](https://bravos-power.github.io/pyoframe/)**
 
-[Read the documentation](https://bravos-power.github.io/pyoframe/) to get started or to learn how to [contribute](https://bravos-power.github.io/pyoframe/contribute/).
+[Read the documentation](https://bravos-power.github.io/pyoframe/) to get started or to learn how to [contribute](https://bravos-power.github.io/pyoframe/contribute/index.md).
 
 
 ## Acknowledgments

pyoframe-1.0.0a0.dist-info/RECORD

@@ -0,0 +1,15 @@
+pyoframe/__init__.py,sha256=Nlql3FYed7bXWumvUeMd3rjnoL4l8XC5orO4uxWrDAc,839
+pyoframe/_arithmetic.py,sha256=3_LkyDbKZ74KxY_KF_99PENj6FgZQa_hVl5RkPyFNJU,20420
+pyoframe/_constants.py,sha256=afwAHreaAKLIrpIEAHtuCn7q9aZuFDEgfLn0ySGZEeY,16066
+pyoframe/_core.py,sha256=xCPU0Uw8g18cxBQbA644RY0fjDan2lJ2pLw6c0ODL6s,113495
+pyoframe/_model.py,sha256=h2sx-JpkSv6o2eS6qcdbQCfQi9Me-zv4IGXumPziBT4,21689
+pyoframe/_model_element.py,sha256=8dvPlRc3hVnlvd-8bxze_ol1fWRd3QiN8UBS25OgwZ4,5771
+pyoframe/_monkey_patch.py,sha256=j206jGoP4Q2eSQrmAkI047gSxftb80Tva0UEc32cDKY,3309
+pyoframe/_objective.py,sha256=Sadl6rhweAKSf2XpRiRCCyAPUVKszjF9s7GEd8g74zg,4375
+pyoframe/_utils.py,sha256=48YTdB1Tlfu-A-xDWb06zA-pXoVtrZGOVMAWw0ClOWM,12554
+pyoframe/_version.py,sha256=KQnBwkHr_bCl4qNrncHrejtChdGSaDU6A5ii5fv_e0U,712
+pyoframe-1.0.0a0.dist-info/licenses/LICENSE,sha256=u_Spw4ynlwTMRZeCX-uacv_hBU547pBygiA6d2ONNV4,1074
+pyoframe-1.0.0a0.dist-info/METADATA,sha256=SSJg9dGl5xKSaUXnZESRYx8W_P1wGF07rhLSQXLnz5k,4039
+pyoframe-1.0.0a0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pyoframe-1.0.0a0.dist-info/top_level.txt,sha256=10z3OOJSVLriQ0IrFLMH8CH9zByugPWolqhlHlkNjV4,9
+pyoframe-1.0.0a0.dist-info/RECORD,,