pyoframe 1.0.1__tar.gz → 1.1.0__tar.gz

pyoframe-1.1.0/.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+- package-ecosystem: pip
+  directory: "/"
+  schedule:
+    interval: daily
+    time: "17:00"
+  allow:
+    - dependency-type: production
+    - dependency-name: highsbox
+    - dependency-name: llvmlite

{pyoframe-1.0.1 → pyoframe-1.1.0}/.github/workflows/ci.yml

@@ -55,7 +55,8 @@ jobs:
           exit 1
   run:
     if: |
-      (github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository) || 
+      (github.event_name == 'pull_request_target' && github.actor == 'dependabot[bot]') ||
+      (github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository && github.actor != 'dependabot[bot]') || 
       (github.event_name == 'pull_request_target' && github.event.pull_request.head.repo.full_name != github.repository) || 
       (github.event_name != 'pull_request_target' && github.event_name != 'pull_request')
     runs-on: ubuntu-latest

{pyoframe-1.0.1 → pyoframe-1.1.0}/PKG-INFO

@@ -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.0.1 → pyoframe-1.1.0}/docs/.nav.yml

@@ -8,6 +8,6 @@ nav:
     - learn/advanced-concepts
     - learn/migrate
   - examples
-  - reference
+  - Reference API: reference
   - why-pyoframe/index.md
   - contribute

pyoframe-1.1.0/docs/contribute/index.md

@@ -0,0 +1,65 @@
+---
+hide:
+  - navigation
+---
+# Contribute
+
+Contributions are more than welcome! Submit a pull request, or [open an issue](https://github.com/Bravos-Power/pyoframe/issues/new) and I (Martin) will gladly answer your questions on how to contribute.
+
+## Setup a development environment
+
+1. Clone this repository.
+```console
+git clone https://github.com/Bravos-Power/pyoframe
+```
+
+2. Install the dependencies. 
+```console
+pip install --editable .[dev,docs]
+```
+
+3. Install the pre-commit hooks. 
+```console
+pre-commit install
+```
+
+## Running the test suite
+
+Run `pytest` to execute the test suite. (If you'd like to view coverage information add the flag `--cov` and then run `coverage html`.)
+
+The only errors you should see when running the test suite are those related to a solver not being installed.
+
+Pyoframe has several types of tests.
+
+1. Your typical unit tests under the `tests/` folder.
+
+2. Integration tests in `tests/test_examples.py`. These tests will run all the models in `tests/examples` and make sure that your changes haven't altered the model results (stored under `tests/examples/<model>/results`). In the rare cases where you _want_ the model results to change (e.g. if you've changed the model), you can regenerate the results using `python -m tests.test_examples`.
+
+3. Doctests in the docstrings of the source code (`src/`).
+
+4. Documentation tests (in `docs/`). All Python code blocks in the documentation are run to ensure the documentation doesn't become outdated. This is done using Sybil. Refer to the [Sybil documentation](https://sybil.readthedocs.io/en/latest/markdown.html#code-blocks) to learn how to create setup code or skip code blocks you don't wish to test.
+
+!!! warning "Non-breaking spaces"
+    Be aware that Pyoframe uses non-breaking spaces to improve the formatting of expressions. If your Sybil tests are unexpectedly failing, make sure that the expected output contains all the needed non-breaking spaces.
+
+## Writing documentation
+
+You can preview the documentation website by running `mkdocs serve` and navigating to [`http://127.0.0.1:8000/pyoframe/`](http://127.0.0.1:8000/pyoframe/).
+
+We use [Material Docs](https://squidfunk.github.io/mkdocs-material/) for documentation with several plugins to enable features like automatically compiling the docstrings into the reference API. Please follow the [Google docstring style](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) and the [Google style guide](https://developers.google.com/style). We use Mike to allow readers to view the documentation for previous releases (preview available via `mike serve`).
+
+## Linting and formatting
+
+We use Ruff for linting and formatting. The pre-commit hooks will run `ruff format` on commit. You should also make sure `ruff check` returns no errors before submitting a PR. To format code blocks in the documentation run: `doccmd --language=python --no-pad-file --command="ruff format" docs/`.
+
+## Additional tips
+
+I recommend skimming or reading the [Internal Details](../learn/advanced-concepts/internals.md) page for some background on how Pyoframe works.
+
+For core developers:
+
+- If you use `.unique`, `.join`, `.sort`, or `.group_by` on a Polars dataframe, make sure to set the `maintain_order` parameter appropriately (typically, `maintain_order=Config.maintain_order`).
+
+For repository maintainers:
+
+- Our CI pipeline on Github Actions requires a Gurobi and COPT license to run. If the Gurobi license expires, generate a new one and copy the contents of the `guorbi.lic` file into the `GUROBI_WLS` Github secret (Settings -> Secrets and variables -> actions). Similarly, if the COPT license expires, request a new academic license (or email COPT sales for a free one) and copy the contents of both license files to the matching Github secrets.

{pyoframe-1.0.1 → pyoframe-1.1.0}/docs/examples/facility_location.md

@@ -26,12 +26,12 @@ model.customers = model.x_axis * model.y_axis  # (1)!
 
 
 model.facility_position = pf.Variable(model.facilities, model.axis, lb=0, ub=1)
-model.customer_position_x = pd.DataFrame(
+model.customer_position_x = pf.Param(
     {"x": range(G), "x_pos": [step / (G - 1) for step in range(G)]}
-).to_expr()
-model.customer_position_y = pd.DataFrame(
+)
+model.customer_position_y = pf.Param(
     {"y": range(G), "y_pos": [step / (G - 1) for step in range(G)]}
-).to_expr()
+)
 
 model.max_distance = pf.Variable(lb=0)
 

{pyoframe-1.0.1 → pyoframe-1.1.0}/docs/learn/advanced-concepts/internals.md

@@ -1,7 +1,6 @@
 # Internal details
 
-Pyoframe's inner workings involve a few tricks that you should be aware of
-if you wish to modify Pyoframe's internal code.
+Pyoframe's inner workings involve a few tricks that you should be aware of if you wish to contribute to Pyoframe's code base.
 
 ## The zero variable
 
@@ -16,4 +15,10 @@ constant terms and also simplifies the [handling of quadratics](#quadratics).
 
 Internally, [Expression][pyoframe.Expression] is used to represent both linear and quadratic mathematical expressions. When a quadratic expression is formed, column `__quadratic_variable_id` is added to [Expression.data][pyoframe.Expression.data]. If an expression's quadratic terms happen to cancel out (e.g. `(ab + c) - ab`), this column is automatically removed.
 
-Column `__quadratic_variable_id` records the ID of the _second_ variable in a quadratic term (the `b` in `3ab`). For linear terms, which have no second variable, this column contains the [Zero Variable](#the-zero-variable). Quadratic terms are always stored such that the first term's variable ID (in column `__variable_id`) is greater or equal to the second term's variable id (in column `__quadratic_variable_id`). For example, `var_7 * var_8` would be rearranged and stored as `var_8 * var_7`. This helps simplify expressions and provides a useful guarantee: If the variable in the first column (`__variable_id`) is the Zero Variable (`var_0`) we know the variable in the second column must also be the Zero Variable and, thus, the term must be a constant.
+Column `__quadratic_variable_id` records the ID of the _second_ variable in a quadratic term (the `b` in `3ab`). For linear terms, which have no second variable, this column contains the [Zero Variable](#the-zero-variable).
+
+Quadratic terms are always stored such that the first term's variable ID (in column `__variable_id`) is greater or equal to the second term's variable id (in column `__quadratic_variable_id`). For example, `var_7 * var_8` would be rearranged and stored as `var_8 * var_7`. This helps simplify expressions and provides a useful guarantee: If the variable in the first column (`__variable_id`) is the Zero Variable (`var_0`) we know the variable in the second column must also be the Zero Variable and, thus, the term must be a constant.
+
+## Division
+
+Divisions are rearranged into multiplications when possible. Specifically, `a / b` is computed as `a * (1 / b)` (see `BaseOperableBlock.__truediv__`) except for the special case where `a` is a `float` or `int`. In that case, a Polars operation is used to compute the division (see `Expression.__rtruediv__`).

{pyoframe-1.0.1 → pyoframe-1.1.0}/docs/learn/concepts/.nav.yml

@@ -1,5 +1,4 @@
 nav:
-  - building-blocks.md
   - addition.md
   - special-functions.md
   - solver-access.md

{pyoframe-1.0.1 → pyoframe-1.1.0}/docs/learn/concepts/addition.md

@@ -31,14 +31,13 @@ import pyoframe as pf
 import polars as pl
 
 air_data = pl.DataFrame({"flight_no": ["A4543", "K937"], "emissions": [1.4, 2.4]})
-ground_data = pl.DataFrame(
-    {"flight_number": ["A4543", "K937"], "emissions": [0.02, 0.05]}
-)
 
 model = pf.Model()
 model.Fly = pf.Variable(air_data["flight_no"], vtype="binary")
 model.air_emissions = model.Fly * air_data
-model.ground_emissions = ground_data.to_expr()
+model.ground_emissions = pf.Param(
+    {"flight_number": ["A4543", "K937"], "emissions": [0.02, 0.05]}
+)
 -->
 
 ```pycon
@@ -90,7 +89,7 @@ What we'd like to do is effectively 'copy' (aka. 'broadcast') `E_max` _over_ eve
 
 ```pycon
 >>> model.E_max.over("flight_no")
-<Expression terms=1 type=linear>
+<Expression (linear) terms=1>
 ┌───────────┬────────────┐
 │ flight_no ┆ expression │
 ╞═══════════╪════════════╡
@@ -104,7 +103,7 @@ Notice how applying `.over("flight_no")` added a dimension `flight_no` with valu
 ```pycon
 >>> model.emission_constraint = model.E_max.over("flight_no") >= model.flight_emissions
 >>> model.emission_constraint
-<Constraint 'emission_constraint' height=2 terms=6 type=linear>
+<Constraint 'emission_constraint' (linear) height=2 terms=6>
 ┌───────────┬───────────────────────────────┐
 │ flight_no ┆ constraint                    │
 │ (2)       ┆                               │
@@ -127,19 +126,16 @@ If one of the two expressions in an addition has extras labels not present in th
 import pyoframe as pf
 import polars as pl
 
-air_data = pl.DataFrame(
+model = pf.Model()
+model.air_emissions = pf.Param(
     {
         "flight_no": ["A4543", "K937", "D2082", "D8432", "D1206"],
         "emissions": [1.4, 2.4, 4, 7.6, 4],
     }
 )
-ground_data = pl.DataFrame(
+model.ground_emissions = pf.Param(
     {"flight_no": ["A4543", "K937", "B3420"], "emissions": [0.02, 0.05, 0.001]}
 )
-
-model = pf.Model()
-model.air_emissions = air_data.to_expr()
-model.ground_emissions = ground_data.to_expr()
 -->
 
 Consider again [example 1](#example-1-catching-a-mistake) where we added air emissions and ground emissions.
@@ -205,7 +201,7 @@ Option 2 hardly seems reasonable this time considering that air emissions make u
 
 ```pycon
 >>> model.air_emissions.keep_extras() + model.ground_emissions.drop_extras()
-<Expression height=5 terms=5 type=constant>
+<Expression (parameter) height=5 terms=5>
 ┌───────────┬────────────┐
 │ flight_no ┆ expression │
 │ (5)       ┆            │

{pyoframe-1.0.1 → pyoframe-1.1.0}/docs/learn/concepts/solver-access.md

@@ -27,6 +27,7 @@ Pyoframe supports a set of [standard attributes](https://metab0t.github.io/PyOpt
 Every solver has a set of parameters that you can read or set using `model.params.<your-param>`.
 
 === "Gurobi"
+
     Refer to the list of [Gurobi parameters](https://docs.gurobi.com/projects/optimizer/en/current/reference/parameters.html).
     
     ```python
@@ -36,6 +37,7 @@ Every solver has a set of parameters that you can read or set using `model.param
     ```
 
 === "COPT"
+
     Refer to the list of [COPT parameters](https://guide.coap.online/copt/en-doc/parameter.html).
     
     ```python
@@ -45,6 +47,7 @@ Every solver has a set of parameters that you can read or set using `model.param
     ```
 
 === "HiGHS"
+
     Refer to the list of [HiGHS options](https://ergo-code.github.io/HiGHS/stable/options/definitions/).
     
     ```python
@@ -54,6 +57,7 @@ Every solver has a set of parameters that you can read or set using `model.param
     ```
 
 === "Ipopt"
+
     Refer to the list of [Ipopt options](https://coin-or.github.io/Ipopt/OPTIONS.html).
     
     ```python

pyoframe-1.1.0/docs/learn/concepts/special-functions.md

@@ -0,0 +1,12 @@
+# Transforms
+
+!!! info "Work in progress"
+
+    This documentation could use some help. [Learn how you can contribute](../../contribute/index.md).
+
+Pyoframe has a few special functions that make working with dataframes easy and intuitive. Here they are:
+
+## `sum` and `sum_by`
+
+## `Expression.map()`
+

pyoframe-1.1.0/docs/learn/get-started/.nav.yml

@@ -0,0 +1,5 @@
+nav:
+  - installation.md
+  - basic-example/example.md
+  - basic-example/example-with-dimensions.md
+  - basics.md

{pyoframe-1.0.1 → pyoframe-1.1.0}/docs/learn/get-started/basic-example/example-with-dimensions.md

@@ -6,14 +6,18 @@ import os
 os.chdir(os.path.join(os.getcwd(), "docs/learn/get-started/basic-example"))
 -->
 
+You are going to re-build the [previous example](./example.md) using a dataset, `food_data.csv`, instead of hard-coded values. This way, you can add as many vegetarian proteins as you like without needing to write more code. If you're impatient, [skip to the end](#put-it-all-together) to see the final result.
+
 !!! tip "Pyoframe is built on DataFrames"
 
     Most other optimization libraries require you to convert your data from its `DataFrame` format to another format.[^1] Not Pyoframe! DataFrames form the core of Pyoframe making it easy to seamlessly — and efficiently — integrate large datasets into your models.
 
 [^1]: For example, Pyomo converts your DataFrames to individual Python objects, Linopy uses multi-dimensional matrices via xarray, and gurobipy requires Python lists, dictionaries and tuples. While gurobipy-pandas uses dataframes, it only works with Gurobi!
 
-You are going to re-build the [previous example](./example.md) using a dataset, `food_data.csv`, instead of hard-coded values. This way, you can add as many vegetarian proteins as you like without needing to write more code. If you're impatient, [skip to the end](#put-it-all-together) to see the final result.
 
+## The data
+
+You can download the CSV file from [here](https://github.com/Bravos-Power/pyoframe/blob/7af213c52ad33b9c01c9a14baa4cffca1ded1046/docs/learn/get-started/basic-example/food_data.csv) or create it yourself with the following content:
 
 > `food_data.csv`
 >
@@ -22,9 +26,7 @@ You are going to re-build the [previous example](./example.md) using a dataset,
 > | tofu_block   | 18      | 4    |
 > | chickpea_can | 15      | 3    |
 
-
-
-### Step 1: Load the data
+## Step 1: Load the data
 
 Load `food_data.csv` using [Polars](https://pola.rs/) or [Pandas](https://pandas.pydata.org/).
 
@@ -48,9 +50,9 @@ Load `food_data.csv` using [Polars](https://pola.rs/) or [Pandas](https://pandas
 
     Pyoframe works the same whether you're using [Polars](https://pola.rs/) or [Pandas](https://pandas.pydata.org/), two similar libraries for manipulating data with DataFrames. We prefer using Polars because it is much faster (and generally better), but you can use whichever library you're most comfortable with.
     
-    Note that, internally, Pyoframe always uses Polars during computations to ensure the best performance. If you're using Pandas, your DataFrames will automatically be converted to Polars prior to computations. If needed, you can convert a Polars DataFrame back to Pandas using [`polars.DataFrame.to_pandas()`](https://docs.pola.rs/api/python/stable/reference/dataframe/api/polars.DataFrame.to_pandas.html#polars.DataFrame.to_pandas).
+    Note that, internally, Pyoframe always uses Polars during computations to ensure the best performance. If you're using Pandas, your DataFrames will automatically be converted to Polars prior to computations.
  
-### Step 2: Create the model
+## Step 2: Create the model
 
 ```python
 import pyoframe as pf
@@ -60,7 +62,7 @@ m = pf.Model()
 
 A [`pyoframe.Model`][pyoframe.Model] instance sets the foundation of your optimization model onto which you can add optimization variables, constraints, and an objective.
 
-### Step 3: Create a dimensioned variable
+## Step 3: Create a dimensioned variable
 
 Previously, you created two variables: `m.tofu_blocks` and `m.chickpea_cans`. Instead, create a single variable **dimensioned over the column `food`**.
 
@@ -83,11 +85,7 @@ Printing the variable shows that it contains a `food` dimension with labels `tof
 
 ```
 
-!!! tip "Capitalize model variables"
-
-    We suggest capitalizing model variables (i.e. `m.Buy`, not `m.buy`) to make distinguishing what is and isn't a variable easy.
-
-### Step 3: Create the objective with `.sum()`
+## Step 3: Create the objective with `.sum()`
 
 Previously you had:
 
@@ -103,7 +101,7 @@ First, multiply the variable by the protein amount.
 
 ```pycon
 >>> data[["food", "cost"]] * m.Buy
-<Expression height=2 terms=2 type=linear>
+<Expression (linear) height=2 terms=2>
 ┌──────────────┬─────────────────────┐
 │ food         ┆ expression          │
 │ (2)          ┆                     │
@@ -122,7 +120,7 @@ Second, notice that the `Expression` still has the `food` dimension—it really
 
 ```pycon
 >>> (data[["food", "cost"]] * m.Buy).sum("food")
-<Expression terms=2 type=linear>
+<Expression (linear) terms=2>
 4 Buy[tofu_block] +3 Buy[chickpea_can]
 
 ```
@@ -133,7 +131,7 @@ This works and since `food` is the only dimensions you don't even need to specif
 m.minimize = (data[["food", "cost"]] * m.Buy).sum()
 ```
 
-### Step 4: Add the constraint
+## Step 4: Add the constraint
 
 This is similar to how you created the objective, except now you're using `protein` and you turn the `Expression` into a `Constraint` with the `>=` operation.
 
@@ -146,7 +144,9 @@ m.optimize()
 assert m.Buy.solution["solution"].to_list() == [2, 1]
 -->
 
-### Put it all together
+## Put it all together
+
+If you've followed the steps above your code should look like:
 
 <!-- clear-namespace -->
 
@@ -164,7 +164,7 @@ m.protein_constraint = (data[["food", "protein"]] * m.Buy).sum() >= 50
 m.optimize()
 ```
 
-So you should buy:
+And you can retrieve the problem's solution as follows:
 
 ```pycon
 >>> m.Buy.solution
@@ -179,9 +179,6 @@ So you should buy:
 
 ```
 
-Notice that since `m.Buy` is dimensioned, `m.Buy.solution` returned a DataFrame with the solution for each of the labels.
-
-!!! info "Returning Pandas DataFrames"
+Since `m.Buy` is dimensioned, `m.Buy.solution` returned a DataFrame with the solution for each of the labels!
 
-    Pyoframe currently always returns Polars DataFrames but you can easily convert them to Pandas using [`.to_pandas()`](https://docs.pola.rs/api/python/stable/reference/dataframe/api/polars.DataFrame.to_pandas.html#polars.DataFrame.to_pandas). In the future, we plan to add support for automatically returning Pandas DataFrames. [Upvote the issue](https://github.com/Bravos-Power/pyoframe/issues/47) if you'd like this feature.
 <!--  -->

{pyoframe-1.0.1 → pyoframe-1.1.0}/docs/learn/get-started/basic-example/example.md

@@ -1,4 +1,4 @@
-# Build a simple model
+# Solve a simple problem
 
 <!-- invisible-code-block: python
 import os
@@ -6,13 +6,13 @@ import os
 os.chdir(os.path.join(os.getcwd(), "docs/learn/get-started/basic-example"))
 -->
 
-To start, you'll solve a simple optimization problem with Pyoframe.
+To start, you will solve a simple optimization problem with Pyoframe.
 
 !!! quote "Problem statement"
 
     Imagine you're a vegetarian hesitating between tofu and chickpeas as
     a source of protein for tomorrow's dinner. You'd like to spend as little money as
-    possible while still consuming at least 50 grams of protein. How many blocks
+    possible while still consuming at least 50g of protein. How many blocks
     of tofu ($4 each, 18g of protein) and cans of chickpeas ($3 each, 15g of protein) should you buy?
 
 Click on the :material-plus-circle: buttons below to understand the code, and then run it on your computer.
@@ -58,4 +58,4 @@ Tofu blocks: 2
 Chickpea cans: 1
 ```
 
-On the next page, you'll [integrate DataFrames](./example-with-dimensions.md) into your solution.
+On the [next page](./example-with-dimensions.md), you'll resolve this problem but instead of hard-coded values, you'll use DataFrames, Pyoframe's secret sauce!