pyoframe 1.0.1__tar.gz → 1.2.0__tar.gz

pyoframe-1.2.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.2.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.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyoframe
-Version: 1.0.1
+Version: 1.2.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.2.0}/docs/.nav.yml

@@ -4,10 +4,10 @@ nav:
   - Home: index.md
   - Learn:
     - learn/get-started
+    - learn/develop
     - learn/concepts
-    - learn/advanced-concepts
     - learn/migrate
   - examples
-  - reference
+  - Reference API: reference
   - why-pyoframe/index.md
   - contribute

pyoframe-1.2.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/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.2.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/docs/learn/advanced-concepts → pyoframe-1.2.0/docs/learn/concepts}/.nav.yml

@@ -1,5 +1,5 @@
 nav:
-  - datastructure.md
+  - addition.md
   - performance.md
   - quadratics.md
   - troubleshooting.md

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

@@ -4,19 +4,13 @@ In Pyoframe, [`Expression`][pyoframe.Expression] objects can be added using the
 
 However, sometimes an addition is ambiguous or indicative of a potential mistake in your model. In these situations, Pyoframe forces you to use _addition modifiers_ to specify exactly how you'd like the addition to be performed. This safety feature helps prevent and quickly fix mistakes in your model.
 
-There are three common addition modifiers in Pyoframe: [`.over(…)`][pyoframe.Expression.over], [`.keep_extras()`][pyoframe.Expression.keep_extras], and [`.drop_extras()`][pyoframe.Expression.drop_extras].
+There are three common addition modifiers in Pyoframe: [`.over(…)`][pyoframe.Expression.over], [`.keep_extras()`][pyoframe.Expression.keep_extras], and [`.drop_extras()`][pyoframe.Expression.drop_extras]. We'll discuss each of these as well as how the bitwise OR operator (`|`) can be used as a shortcut.
 
-Before delving into these addition modifiers, please note that **these addition rules also apply to subtraction as well as the `<=` and `>=` operators used to create constraints**. This is because subtraction is actually computed as an addition (`a - b` is computed as `a + (-b)`). Similarly, creating a constraint with the `<=` or `>=` operators involves combining the left and right hand sides using addition (`a <= b` becomes `a + (-b) <= 0`). So, although I may only mention addition from now on, please remember that this page also applies to subtraction and to constraint creation.
+!!! warning "Addition modifiers also apply to subtraction and constraint creation"
 
-The rest of the page is organized as follows:
+    Please note that **the addition rules described here also apply to subtraction as well as the `<=` and `>=` operators used to create constraints**. This is because subtraction is actually computed as an addition (`a - b` is computed as `a + (-b)`). Similarly, creating a constraint with the `<=` or `>=` operators involves combining the left and right hand sides using addition (`a <= b` becomes `a + (-b) <= 0`). So, although I may only mention addition from now on, please remember that this page also applies to subtraction and to constraint creation.
 
-1. [The `.over(…)` addition modifier](#adding-expressions-with-differing-dimensions-using-over)
-
-2. [The `.keep_extras()` and `.drop_extras()` addition modifiers](#handling-extra-labels-with-keep_extras-and-drop_extras)
-
-3. [Important note on the order of operations of addition modifiers](#order-of-operations-for-addition-modifiers)
-
-## Adding expressions with differing dimensions using `.over(…)`
+## `.over(…)`
 
 To help catch mistakes, adding expressions with differing dimensions is disallowed by default. [`.over(…)`][pyoframe.Expression.over] overrides this default and **indicates that an addition should be performed by "broadcasting" the differing dimensions.**
 
@@ -31,14 +25,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
@@ -63,7 +56,7 @@ Do you understand what happened? The error informs us that `model.air_emissions`
 
 Benign mistakes like these are relatively common and Pyoframe's error messages help you detect them early. Now, let's examine a case where `.over(…)` is needed.
 
-### Example 2: Broadcasting with `.over(…)`
+### Example 2: Broadcasting
 
 Say, you'd like to see what happens if, instead of minimizing total emissions, you were to minimize the emissions of the _most emitting flight_. Mathematically, this is equivalent to minimizing variable `E_max` where `E_max` is constrained to be greater or equal to the emissions of every flight.
 
@@ -90,7 +83,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 +97,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)       ┆                               │
@@ -115,7 +108,7 @@ Notice how applying `.over("flight_no")` added a dimension `flight_no` with valu
 
 ```
 
-## Handling 'extra' labels with `.keep_extras()` and `.drop_extras()`
+## `.keep_extras()` / `.drop_extras()`
 
 Addition is performed by pairing the labels in the left `Expression` with those in the right `Expression`. But, what happens when the left and right labels differ?
 
@@ -127,19 +120,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 +195,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)       ┆            │
@@ -219,7 +209,32 @@ Option 2 hardly seems reasonable this time considering that air emissions make u
 
 ```
 
-## Order of operations for addition modifiers
+## The bitwise OR operator
+
+In practice, you'll find that it is common to want to keep extra labels on both sides of an addition or subtraction. As such, Pyoframe offers the bitwise OR operator (`|`) as a convenient shortcut. Instead of
+
+<!-- invisible-code-block: python
+a = model.air_emissions
+b = model.ground_emissions
+-->
+
+```python
+a.keep_extras() + b.keep_extras()
+```
+you can simply write
+
+```python
+a | b
+```
+
+For subtraction, the following lines are equivalent:
+
+```python
+a.keep_extras() - b.keep_extras()
+a | -b
+```
+
+## Note on order of operations
 
 When an operation creates a new [Expression][pyoframe.Expression], any previously applied addition modifiers are discarded to prevent unexpected behaviors. As such, **addition modifiers only work if they're applied _right before_ an addition**. For example, `a.drop_extras().sum("time") + b` won't work but `a.sum("time").drop_extras() + b` will.
 

{pyoframe-1.0.1/docs/learn/advanced-concepts → pyoframe-1.2.0/docs/learn/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.2.0/docs/learn/develop/.nav.yml

@@ -0,0 +1,8 @@
+nav:
+  - create-a-model.md
+  - create-variables.md
+  - create-expressions.md
+  - create-constraints.md
+  - define-objective.md
+  - run-and-configure-the-solver.md
+  - read-results.md

pyoframe-1.2.0/docs/learn/develop/create-a-model.md

@@ -0,0 +1,41 @@
+# Create a model
+
+To create a model write:
+
+```python
+import pyoframe as pf
+
+m = pf.Model()
+```
+
+## Specify a solver
+
+By default, Pyoframe will try to use whichever solver is installed on your computer. To specify a particular solver, use the `solver` argument.
+
+=== "Gurobi"
+
+    ```python
+    m = pf.Model(solver="gurobi")
+    ```
+
+=== "HiGHS"
+
+    ```python
+    m = pf.Model(solver="highs")
+    ```
+
+=== "COPT"
+
+    ```python
+    m = pf.Model(solver="copt")
+    ```
+
+=== "Ipopt"
+
+    ```python
+    m = pf.Model(solver="ipopt")
+    ```
+
+## Advanced options
+
+Additional options are detailed in the [`Model`][pyoframe.Model] API documentation.

pyoframe-1.2.0/docs/learn/develop/create-constraints.md

@@ -0,0 +1,27 @@
+# Create constraints
+
+Create constraints by using the `<=`, `>=`, and `==` operators between two expressions. For example,
+
+<!-- invisible-code-block: python
+import pyoframe as pf
+
+m = pf.Model()
+m.Hours_Worked = pf.Variable({"day": ["Mon", "Tue", "Wed", "Thu", "Fri"]})
+
+-->
+
+```python
+m.Con_Max_Weekly_Hours = m.Hours_Worked.sum() <= 40
+```
+
+!!! tip "Naming constraints"
+    I like prefixing constraint names with `Con_` to easily distinguish them from other module attributes.
+
+
+## Handle extra labels
+
+When creating constraints, Pyoframe always merges the left- and right-hand side expressions into a single expression (e.g. `a <= b` becomes `(a - b) <= 0`). Thus, if the left- and/or right-hand sides have labels not present in the other side, you will need to handle these extra labels using `drop_extras()` or `keep_extras()`. Read [Addition and its quirks](../concepts/addition.md) to learn more or see the [diet problem](../../examples/diet.md) for an example.
+
+## Relax a constraint
+
+Refer to the API documentation for [`.relax()`][pyoframe.Constraint.relax].

pyoframe-1.2.0/docs/learn/develop/create-expressions.md

@@ -0,0 +1,95 @@
+# Create expressions
+
+Mathematical expressions in Pyoframe are represented by the [`Expression`][pyoframe.Expression] class and can be created in a few ways.
+
+## Using arithmetic operators
+
+Expressions are automatically created whenever standard arithmetic operators (`+`, `-`, `*`, `/`, `**`) are used between Pyoframe objects. For example, the following code creates the expression `m.hours_remaining`:
+
+```python
+import pyoframe as pf
+
+m = pf.Model()
+m.Hours_Worked = pf.Variable({"day": ["Mon", "Tue", "Wed", "Thu", "Fri"]}, lb=0)
+m.Hours_Sleep = pf.Variable({"day": ["Fri", "Thu", "Wed", "Tue", "Mon"]}, lb=0)
+m.hours_remaining = 24 - m.Hours_Worked - m.Hours_Sleep
+```
+
+```pycon
+>>> m.hours_remaining
+<Expression (linear) height=5 terms=15>
+┌─────┬───────────────────────────────────────────┐
+│ day ┆ expression                                │
+│ (5) ┆                                           │
+╞═════╪═══════════════════════════════════════════╡
+│ Mon ┆ 24 - Hours_Worked[Mon] - Hours_Sleep[Mon] │
+│ Tue ┆ 24 - Hours_Worked[Tue] - Hours_Sleep[Tue] │
+│ Wed ┆ 24 - Hours_Worked[Wed] - Hours_Sleep[Wed] │
+│ Thu ┆ 24 - Hours_Worked[Thu] - Hours_Sleep[Thu] │
+│ Fri ┆ 24 - Hours_Worked[Fri] - Hours_Sleep[Fri] │
+└─────┴───────────────────────────────────────────┘
+
+```
+
+!!! warning "Pyoframe always aligns labels and dimensions"
+
+    Pyoframe always performs operations label-by-label. For example, Pyoframe subtracted `m.Hours_Sleep` from `m.Hours_Worked` using the labels; the fact that the days were listed in reverse order in `m.Hours_Sleep` (see above) does not matter.
+
+    When the left- and/or right-hand side expressions have labels not present in the other, it may be necessary to use `.keep_extras()` or `.drop_extras()` to specify how these extra labels should be handled. Similarly, if one of the two operands is missing a dimension, it may be necessary to use `.over` to force broadcasting. Read [Addition and its quirks](../concepts/addition.md) to learn more.
+
+
+
+## Using parameters
+
+External data can be incorporated into an optimization problem by using [`pf.Param(data)`][pyoframe.Param] which converts a DataFrame into a Pyoframe expression. The last column of the DataFrame will be treated as the expression value, and all other columns will be treated as labels. For example, the following code creates a Pyoframe expression equal to `1` on Friday and `0` otherwise.
+
+```python
+import pandas as pd
+
+is_holiday = pd.DataFrame(
+    {"day": ["Mon", "Tue", "Wed", "Thu", "Fri"], "is_holiday": [0, 0, 0, 0, 1]}
+)
+```
+
+```pycon
+>>> pf.Param(is_holiday)
+<Expression (parameter) height=5 terms=5>
+┌─────┬────────────┐
+│ day ┆ expression │
+│ (5) ┆            │
+╞═════╪════════════╡
+│ Mon ┆ 0          │
+│ Tue ┆ 0          │
+│ Wed ┆ 0          │
+│ Thu ┆ 0          │
+│ Fri ┆ 1          │
+└─────┴────────────┘
+
+```
+
+The expression can then be used like any other Pyoframe object:
+
+```python
+m.holiday_hours_worked = m.Hours_Worked * pf.Param(is_holiday)
+```
+
+Note that `pf.Param` is automatically applied when a Pyoframe object is operated with a DataFrame so the previous line can be simplified to
+
+```python
+m.holiday_hours_worked = m.Hours_Worked * is_holiday
+```
+
+!!! tip "`pf.Param` also accepts file paths"
+
+    `pf.Param` also accepts a file path to a `.csv` or `.parquet` file, see the [`Param`][pyoframe.Param] API documentation to learn more.
+
+## Using transforms
+
+The functions [`sum`][pyoframe.Expression.sum], [`sum_by`][pyoframe.Expression.sum_by], [`map`][pyoframe.Expression.map], [`next`][pyoframe.Variable.next], [`rolling_sum`][pyoframe.Expression.rolling_sum], and [`within`][pyoframe.Expression.within] are _transforms_ that make it easy to convert an expression or variable from one shape to another. For example, `sum` can be used to collapse a dimensioned expression into a dimensionless one:
+
+```pycon
+>>> m.Hours_Worked.sum()
+<Expression (linear) terms=5>
+Hours_Worked[Mon] + Hours_Worked[Tue] + Hours_Worked[Wed] + Hours_Worked[Thu] + Hours_Worked[Fri]
+
+```