pyoframe 1.0.0a0__tar.gz → 1.0.1__tar.gz

{pyoframe-1.0.0a0 → pyoframe-1.0.1}/.github/actions/setup_optimizers_linux/action.yml

@@ -8,9 +8,12 @@ inputs:
   GUROBI_WLS:
     description: "..."
     required: true
-  # COPT_CLIENT_INI:
-  #   description: "..."
-  #   required: true
+  COPT_LICENSE_KEY:
+    description: "..."
+    required: true
+  COPT_LICENSE_DAT:
+    description: "..."
+    required: true
   # MOSEK_LICENSE:
   #   description: "..."
   #   required: true
@@ -46,8 +49,7 @@ runs:
       run: |
         curl -L -o ~/installers/gurobi.tar.gz https://packages.gurobi.com/12.0/gurobi12.0.2_linux64.tar.gz
         curl -L -o ~/installers/idaes-solvers.tar.gz https://github.com/IDAES/idaes-ext/releases/download/3.4.2/idaes-solvers-ubuntu2204-x86_64.tar.gz
-
-    # curl -L -o ~/installers/copt.tar.gz https://pub.shanshu.ai/download/copt/7.2.8/linux64/CardinalOptimizer-7.2.8-lnx64.tar.gz
+        curl -L -o ~/installers/copt.tar.gz https://pub.shanshu.ai/download/copt/7.2.11/linux64/CardinalOptimizer-7.2.11-lnx64.tar.gz
     # curl -L -o ~/installers/mosek.tar.bz2 https://download.mosek.com/stable/10.2.0/mosektoolslinux64x86.tar.bz2
 
     - name: Setup Gurobi Installation
@@ -76,28 +78,28 @@ runs:
         timeout_minutes: 1
         command: gurobi_cl
 
-    # - name: Setup COPT Installation
-    #   shell: bash
-    #   env:
-    #     COPT_CLIENT_INI: ${{ inputs.COPT_CLIENT_INI }}
-    #   run: |
-    #     tar xfz ~/installers/copt.tar.gz -C ~/
-    #     ls ~/copt72
-    #     # set environment variables
-    #     export COPT_HOME="${HOME}/copt72"
-    #     echo "COPT_HOME=${COPT_HOME}" >> $GITHUB_ENV
-    #     echo "PATH=${PATH}:${COPT_HOME}/bin" >> $GITHUB_ENV
-    #     echo "LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${COPT_HOME}/lib" >> $GITHUB_ENV
-    #     echo $COPT_HOME
-
-    #     # Just use the size-limited license
-    #     # echo "$COPT_CLIENT_INI" > ~/client.ini
-    #     # echo "COPT_LICENSE_DIR=${HOME}" >> $GITHUB_ENV
-    # - name: Test COPT
-    #   if: ${{ inputs.CHECK_LICENSE == 'true' }}
-    #   shell: bash
-    #   run: |
-    #     copt_cmd -c "quit"
+    - name: Setup COPT Installation
+      shell: bash
+      env:
+        COPT_LICENSE_KEY: ${{ inputs.COPT_LICENSE_KEY }}
+        COPT_LICENSE_DAT: ${{ inputs.COPT_LICENSE_DAT }}
+      run: |
+        tar xfz ~/installers/copt.tar.gz -C ~/
+        ls ~/copt72
+        # set environment variables
+        export COPT_HOME="${HOME}/copt72"
+        echo "COPT_HOME=${COPT_HOME}" >> $GITHUB_ENV
+        echo "PATH=${PATH}:${COPT_HOME}/bin" >> $GITHUB_ENV
+        echo "LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${COPT_HOME}/lib" >> $GITHUB_ENV
+        echo $COPT_HOME
+        echo "$COPT_LICENSE_KEY" > ${COPT_HOME}/license.key
+        echo "$COPT_LICENSE_DAT" > ${COPT_HOME}/license.dat
+        echo "COPT_LICENSE_DIR=${COPT_HOME}" >> $GITHUB_ENV
+    - name: Test COPT
+      if: ${{ inputs.CHECK_LICENSE == 'true' }}
+      shell: bash
+      run: |
+        copt_cmd -c "quit"
 
     # - name: Setup MOSEK Installation
     #   shell: bash

pyoframe-1.0.1/.github/dependabot.yml

@@ -0,0 +1,16 @@
+version: 2
+updates:
+- package-ecosystem: pip
+  directory: "/"
+  schedule:
+    interval: daily
+    time: "17:00"
+  groups:
+    python-production-packages:
+      dependency-type: production
+      patterns:
+        - "*"
+    python-dev-packages:
+      dependency-type: development
+      patterns:
+        - "*"

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

@@ -45,9 +45,9 @@ jobs:
           username: ${{ github.triggering_actor }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      # If neither has permissions and no 'safe to test' label throw error
+      # If neither has permissions and no 'safe to test' label and not dependabot throw error
       - name: Check User Permission
-        if: steps.checkAccess.outputs.require-result == 'false' && steps.checkTriggeringAccess.outputs.require-result == 'false' && !contains(github.event.pull_request.labels.*.name, 'safe to test')
+        if: steps.checkAccess.outputs.require-result == 'false' && steps.checkTriggeringAccess.outputs.require-result == 'false' && !contains(github.event.pull_request.labels.*.name, 'safe to test') && (github.actor != 'dependabot[bot]')
         shell: bash
         run: |
           echo "${{ github.triggering_actor }} does not have permissions on this repo."
@@ -80,12 +80,15 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
           cache: "pip"
-      - name: Install dependencies
-        run: pip install -e .[dev]
-      - uses: ./.github/actions/setup_optimizers_linux
+      - name: Setup optimizers
+        uses: ./.github/actions/setup_optimizers_linux
         with:
           GUROBI_WLS: ${{ secrets.GUROBI_WLS }}
+          COPT_LICENSE_KEY: ${{ secrets.COPT_LICENSE_KEY }}
+          COPT_LICENSE_DAT: ${{ secrets.COPT_LICENSE_DAT }}
           CHECK_LICENSE: true
+      - name: Install dependencies
+        run: pip install -e .[dev]
       - name: Run tests and collect coverage
         run: pytest --cov
       - name: Upload coverage to Codecov

{pyoframe-1.0.0a0 → pyoframe-1.0.1}/.gitignore

@@ -13,4 +13,4 @@ site
 .idea
 src/pyoframe/_version.py
 htmlcov/
-.snakemake
+.snakemake/

{pyoframe-1.0.0a0 → pyoframe-1.0.1}/.pre-commit-config.yaml

@@ -12,4 +12,4 @@ repos:
     rev: v2025.4.8
     hooks:
     -   id: doccmd
-        args: ["--language", "python", "--no-pad-file", "--command", "ruff format", "docs/"]
+        args: ["--language", "python", "--no-pad-file", "--no-use-pty", "--command", "ruff format", "docs/"]

{pyoframe-1.0.0a0 → pyoframe-1.0.1}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: pyoframe
-Version: 1.0.0a0
+Version: 1.0.1
 Summary: Blazing fast linear program interface
 Author-email: Bravos Power <dev@bravospower.com>
 License-Expression: MIT
-Project-URL: Homepage, https://bravos-power.github.io/pyoframe/
-Project-URL: documentation, https://bravos-power.github.io/pyoframe/
+Project-URL: Homepage, https://bravos-power.github.io/pyoframe/latest
+Project-URL: documentation, https://bravos-power.github.io/pyoframe/latest
 Project-URL: repository, https://github.com/Bravos-Power/pyoframe/
 Project-URL: Issues, https://github.com/Bravos-Power/pyoframe/issues
 Classifier: Programming Language :: Python :: 3
@@ -16,12 +16,11 @@ Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: polars~=1.0
-Requires-Dist: numpy
 Requires-Dist: pyarrow
-Requires-Dist: pandas
-Requires-Dist: pyoptinterface<1,>=0.4.1
+Requires-Dist: pandas<3
+Requires-Dist: pyoptinterface==0.5.1
 Provides-Extra: highs
-Requires-Dist: highsbox; extra == "highs"
+Requires-Dist: highsbox<=1.11.0; extra == "highs"
 Provides-Extra: ipopt
 Requires-Dist: pyoptinterface[nlp]; extra == "ipopt"
 Requires-Dist: llvmlite<=0.44.0; extra == "ipopt"
@@ -35,9 +34,9 @@ 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: highsbox<=1.11.0; extra == "dev"
 Requires-Dist: pyoptinterface[nlp]; extra == "dev"
-Requires-Dist: llvmlite<=0.44.0; extra == "dev"
+Requires-Dist: numpy; extra == "dev"
 Provides-Extra: docs
 Requires-Dist: mkdocs-material~=9.6.18; extra == "docs"
 Requires-Dist: mkdocstrings[python]~=0.30.0; extra == "docs"
@@ -57,7 +56,7 @@ Dynamic: license-file
 
 [![codecov](https://codecov.io/gh/Bravos-Power/pyoframe/graph/badge.svg?token=8258XESRYQ)](https://codecov.io/gh/Bravos-Power/pyoframe)
 [![Build](https://github.com/Bravos-Power/pyoframe/actions/workflows/ci.yml/badge.svg)](https://github.com/Bravos-Power/pyoframe/actions/workflows/ci.yml)
-[![Docs](https://github.com/Bravos-Power/pyoframe/actions/workflows/publish_doc.yml/badge.svg)](https://Bravos-Power.github.io/pyoframe/reference/)
+[![Docs](https://github.com/Bravos-Power/pyoframe/actions/workflows/publish_doc.yml/badge.svg)](https://Bravos-Power.github.io/pyoframe/latest/reference/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Issues Needing Triage](https://img.shields.io/github/issues-search/Bravos-Power/pyoframe?query=no%3Alabel%20is%3Aopen&label=Needs%20Triage)](https://github.com/Bravos-Power/pyoframe/issues?q=is%3Aopen+is%3Aissue+no%3Alabel)
 [![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)
@@ -65,9 +64,9 @@ Dynamic: license-file
 
 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/)**
+## **[Documentation](https://bravos-power.github.io/pyoframe/latest/)**
 
-[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).
+[Read the documentation](https://bravos-power.github.io/pyoframe/latest/) to get started or to learn how to [contribute](https://bravos-power.github.io/pyoframe/latest/contribute/index.md).
 
 
 ## Acknowledgments

{pyoframe-1.0.0a0 → pyoframe-1.0.1}/README.md

@@ -2,7 +2,7 @@
 
 [![codecov](https://codecov.io/gh/Bravos-Power/pyoframe/graph/badge.svg?token=8258XESRYQ)](https://codecov.io/gh/Bravos-Power/pyoframe)
 [![Build](https://github.com/Bravos-Power/pyoframe/actions/workflows/ci.yml/badge.svg)](https://github.com/Bravos-Power/pyoframe/actions/workflows/ci.yml)
-[![Docs](https://github.com/Bravos-Power/pyoframe/actions/workflows/publish_doc.yml/badge.svg)](https://Bravos-Power.github.io/pyoframe/reference/)
+[![Docs](https://github.com/Bravos-Power/pyoframe/actions/workflows/publish_doc.yml/badge.svg)](https://Bravos-Power.github.io/pyoframe/latest/reference/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Issues Needing Triage](https://img.shields.io/github/issues-search/Bravos-Power/pyoframe?query=no%3Alabel%20is%3Aopen&label=Needs%20Triage)](https://github.com/Bravos-Power/pyoframe/issues?q=is%3Aopen+is%3Aissue+no%3Alabel)
 [![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)
@@ -10,9 +10,9 @@
 
 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/)**
+## **[Documentation](https://bravos-power.github.io/pyoframe/latest/)**
 
-[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).
+[Read the documentation](https://bravos-power.github.io/pyoframe/latest/) to get started or to learn how to [contribute](https://bravos-power.github.io/pyoframe/latest/contribute/index.md).
 
 
 ## Acknowledgments

{pyoframe-1.0.0a0 → pyoframe-1.0.1}/docs/contribute/index.md

@@ -42,10 +42,10 @@ We use [Material Docs](https://squidfunk.github.io/mkdocs-material/) for documen
 
 ## Additional tips
 
-- 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 core developers:
 
-## Details for repository maintainers
+- 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`).
 
-### Expired Gurobi License
+For repository maintainers:
 
-We use a Gurobi license to run our tests. If the tests fail an give a license expired error, generate a new one and copy the contents of the `guorbi.lic` file into the `GUROBI_WLS` Github secret (Settings -> Secrets and variables -> actions).
+- 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.0a0 → pyoframe-1.0.1}/docs/examples/diet.md

@@ -28,9 +28,9 @@ m.Buy = pf.Variable(food["food"], lb=0, ub=food[["food", "stock"]])
 
 nutrient_intake = (m.Buy * food_nutrients).sum_by("category")
 m.min_nutrients = (
-    nutrients[["category", "min"]] <= nutrient_intake.drop_unmatched()  # (1)!
+    nutrients[["category", "min"]] <= nutrient_intake.drop_extras()  # (1)!
 )
-m.max_nutrients = nutrient_intake.drop_unmatched() <= nutrients[["category", "max"]]
+m.max_nutrients = nutrient_intake.drop_extras() <= nutrients[["category", "max"]]
 
 total_cost = (m.Buy * food[["food", "cost"]]).sum()
 m.minimize = total_cost
@@ -39,7 +39,7 @@ m.minimize = total_cost
 m.optimize()
 ```
 
-1. `.drop_unmatched()` ensures that if `min_nutrient` is `null` for certain foods, no constraint will be created for those foods. [Learn more](../learn/concepts/special-functions.md#drop_unmatched-and-keep_unmatched)
+1. `.drop_extras()` ensures that if `min_nutrient` is `null` for certain foods, no constraint will be created for those foods. [Learn more](../learn/concepts/addition.md)
 
 So the solution is...
 

{pyoframe-1.0.0a0 → pyoframe-1.0.1}/docs/index.md

@@ -12,7 +12,7 @@ hide:
 - Seamlessly integrates with pandas thanks to its dataframe-centric design.
 - Extremely **fast and memory efficient** (even for sparse problems) thanks to Polars, Rust, and Pyoptinterface.
 - Clear Pythonic syntax for writing mathematical models.
-- Supports Gurobi, HiGHS, and Ipopt solvers.
+- Supports Gurobi, HiGHS, Ipopt and COPT solvers.
 - Continuously used in high-stakes production environments.
 - 100% open-source (MIT License).
 

{pyoframe-1.0.0a0 → pyoframe-1.0.1}/docs/learn/advanced-concepts/performance.md

@@ -6,9 +6,9 @@ Pyoframe is already one of the fastest and most memory-efficient libraries for f
 
 [Polars](https://pola.rs/) is much faster than Pandas. Moreover, if you use Pandas, there will be a (very small) overhead because Pyoframe converts all DataFrames to Polars prior to computations.
 
-## Use integer indices
+## Use integer labels
 
-Pyoframe will work with all types of indices, however integer indices are faster and more memory efficient than alternatives (e.g. string indices).
+Pyoframe works with any label data type (e.g. string labels, date labels, etc.), but integer labels are fastest and most memory efficient.
 
 ## Disable `maintain_order`
 
@@ -18,14 +18,14 @@ By default, Pyoframe ensures that the order of variables, constraints, and mathe
 pf.Config.maintain_order = False
 ```
 
-## Disable unmatched checks
+## Disable checks for extra values
 
-Disabling unmatched checks means that, instead of raising [unmatched term exceptions](../concepts/special-functions.md#drop_unmatched-and-keep_unmatched), pyoframe will process sums with unmatched terms as if [`keep_unmatched`][pyoframe.Expression.keep_unmatched] had been applied. While this may improve performance, it will silence potentially important errors meant to help you build your model. If you'd like to disable unmatched checks, we recommend you do so only after thoroughly testing your model and ensuring that all potential unmatched term exceptions have been handled.
+Disabling checks for extra values means that, instead of raising [extra value exceptions](../concepts/addition.md), pyoframe will process sums with extra values as if [`keep_extras`][pyoframe.Expression.keep_extras] had been applied. While this may improve performance, it will silence potentially important errors meant to help you build your model. If you'd like to disable checks for extra values, we recommend you do so only after thoroughly testing your model and ensuring that all potential extra value exceptions have been handled.
 
-The following code disables unmatched checks:
+The following code disables checks for extra values:
 
 ```python
-pf.Config.disable_unmatched_checks = True
+pf.Config.disable_extras_checks = True
 ```
 
 <!-- TODO REVISIT

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

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

pyoframe-1.0.1/docs/learn/concepts/addition.md

@@ -0,0 +1,238 @@
+# Addition and its quirks
+
+In Pyoframe, [`Expression`][pyoframe.Expression] objects can be added using the `+` operator, as you might expect.
+
+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].
+
+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.
+
+The rest of the page is organized as follows:
+
+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(…)`
+
+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.**
+
+The following examples help illustrate when `.over(…)` should and shouldn't be used.
+
+### Example 1: Catching a mistake
+
+Say you're developing an optimization model to study aviation emissions. You'd like to express the sum of in-flight emissions and on-the-ground ([taxiing](https://en.wikipedia.org/wiki/Taxiing)) emissions, _for each flight_, but when you try to add both `Expression` objects, you get an error:
+
+<!-- invisible-code-block: python
+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()
+-->
+
+```pycon
+>>> model.flight_emissions = model.air_emissions + model.ground_emissions
+Traceback (most recent call last):
+...
+pyoframe._constants.PyoframeError: Cannot add the two expressions below because their
+  dimensions are different (['flight_no'] != ['flight_number']).
+Expression 1:  air_emissions
+Expression 2:  ground_emissions
+If this is intentional, use .over(…) to broadcast. Learn more at
+  https://bravos-power.github.io/pyoframe/latest/learn/concepts/addition/#adding-expressions-with-differing-dimensions-using-over
+
+```
+
+Do you understand what happened? The error informs us that `model.air_emissions` has dimension _`flight_no`_, but `model.ground_emissions` has dimension _`flight_number`_. Oops, the two datasets use slightly different spellings! You can use [`.rename(…)`][pyoframe.Expression.rename] to correct for the `Expression` objects having differing dimension names.
+
+```pycon
+>>> model.flight_emissions = model.air_emissions + model.ground_emissions.rename({"flight_number": "flight_no"})
+
+```
+
+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(…)`
+
+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.
+
+You try to express this constraint in Pyoframe, but get an error:
+
+```pycon
+>>> model.E_max = pf.Variable()
+>>> model.minimize = model.E_max
+>>> model.emission_constraint = model.E_max >= model.flight_emissions
+Traceback (most recent call last):
+...
+pyoframe._constants.PyoframeError: Cannot subtract the two expressions below because their
+    dimensions are different ([] != ['flight_no']).
+Expression 1:  E_max
+Expression 2:  flight_emissions
+If this is intentional, use .over(…) to broadcast. Learn more at
+    https://bravos-power.github.io/pyoframe/latest/learn/concepts/addition/#adding-expressions-with-differing-dimensions-using-over
+
+```
+
+The error indicates that `E_max` has no dimensions but `flight_emissions` has dimensions `flight_no`. The error is raised because, by default, combining terms with differing dimensions is not allowed (as explained in [example 1](#example-1-catching-a-mistake)).
+
+What we'd like to do is effectively 'copy' (aka. 'broadcast') `E_max` _over_ every flight number. `E_max.over("flight_no")` does just this:
+
+```pycon
+>>> model.E_max.over("flight_no")
+<Expression terms=1 type=linear>
+┌───────────┬────────────┐
+│ flight_no ┆ expression │
+╞═══════════╪════════════╡
+│ *         ┆ E_max      │
+└───────────┴────────────┘
+
+```
+
+Notice how applying `.over("flight_no")` added a dimension `flight_no` with value `*`. The asterix (`*`) indicates that `flight_no` will take the shape of whichever expression `E_max` is later combined with. Since `E_max` is being combined with `flight_emissions`, `*` will be replaced with an entry for every flight number in `flight_emissions`. Now creating our constraint works properly:
+
+```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>
+┌───────────┬───────────────────────────────┐
+│ flight_no ┆ constraint                    │
+│ (2)       ┆                               │
+╞═══════════╪═══════════════════════════════╡
+│ A4543     ┆ E_max -1.4 Fly[A4543] >= 0.02 │
+│ K937      ┆ E_max -2.4 Fly[K937] >= 0.05  │
+└───────────┴───────────────────────────────┘
+
+```
+
+## Handling 'extra' labels with `.keep_extras()` and `.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?
+
+If one of the two expressions in an addition has extras labels not present in the other, [`.keep_extras()`][pyoframe.Expression.keep_extras] or [`.drop_extras()`][pyoframe.Expression.drop_extras] must be used to indicate how the extra labels should be handled.
+
+### Example 3: Deciding how to handle extra labels
+
+<!-- invisible-code-block: python
+import pyoframe as pf
+import polars as pl
+
+air_data = pl.DataFrame(
+    {
+        "flight_no": ["A4543", "K937", "D2082", "D8432", "D1206"],
+        "emissions": [1.4, 2.4, 4, 7.6, 4],
+    }
+)
+ground_data = pl.DataFrame(
+    {"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.
+Let's say that you fixed the error in example 1, but when you try the addition again you get the following error:
+
+```pycon
+>>> model.air_emissions + model.ground_emissions
+Traceback (most recent call last):
+...
+pyoframe._constants.PyoframeError: Cannot add the two expressions below because expression 1 has extra labels.
+Expression 1:       air_emissions
+Expression 2:       ground_emissions
+Extra labels in expression 1:
+┌───────────┐
+│ flight_no │
+╞═══════════╡
+│ D2082     │
+│ D8432     │
+│ D1206     │
+└───────────┘
+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
+
+```
+
+Do you understand what happened? The error explains that `air_emissions` contains flight numbers that are not present in `ground_emissions` (specifically flight numbers `D2082`, `D8432`, and `D1206`). Your ground emissions dataset is missing some flights!
+
+Pyoframe raised an error because it is unclear how you'd like the addition to be performed. In fact, you have three options:
+
+1. Decide to discard all flights with missing ground data (`model.air_emissions.drop_extras()`).
+2. Decide to keep all flights, assuming `0` ground emissions when the data is missing (`model.air_emissions.keep_extras()`).
+3. Go back to your data processing and fix the root cause of the missing data.
+
+After investigating, you realize that the data is missing because the ground emissions for those flights were negligible. As such, you decide to use `.keep_extras()` (option 2), effectively setting ground emissions to `0` whenever the data is missing.
+
+Let's try again!
+
+```pycon
+>>> model.air_emissions.keep_extras() + model.ground_emissions
+Traceback (most recent call last):
+...
+pyoframe._constants.PyoframeError: Cannot add the two expressions below because expression 2 has extra labels.
+Expression 1:	air_emissions.keep_extras()
+Expression 2:	ground_emissions
+Extra labels in expression 2:
+┌───────────┐
+│ flight_no │
+╞═══════════╡
+│ B3420     │
+└───────────┘
+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
+
+```
+
+Argh, another error! Do you understand what happened? This time `ground_emissions` has extra labels: flight `B3420` is present in `ground_emissions` but not `air_emissions`. Again, Pyoframe raised an error because it is unclear what should be done:
+
+1. Discard flight `B3420` because the air emissions data is missing.
+2. Keep flight `B3420`, assuming the air emissions data is `0`.
+3. Go back to your data processing and fix the root cause of the missing air emissions data.
+
+Option 2 hardly seems reasonable this time considering that air emissions make up the majority of a flight's emissions. You end up deciding to discard the flight entirely (option 1) using `.drop_extras()`. Now, the addition works perfectly!
+
+```pycon
+>>> model.air_emissions.keep_extras() + model.ground_emissions.drop_extras()
+<Expression height=5 terms=5 type=constant>
+┌───────────┬────────────┐
+│ flight_no ┆ expression │
+│ (5)       ┆            │
+╞═══════════╪════════════╡
+│ A4543     ┆ 1.42       │
+│ K937      ┆ 2.45       │
+│ D2082     ┆ 4          │
+│ D8432     ┆ 7.6        │
+│ D1206     ┆ 4          │
+└───────────┴────────────┘
+
+```
+
+## Order of operations for addition modifiers
+
+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.
+
+There are two exceptions to this rule:
+
+1. _Negation_. Negation preserves addition modifiers. If it weren't for this exception, `-my_obj.drop_extras()` wouldn't work as expected; you would have to write `(-my_obj).drop_extras()` which is unintuitive!
+
+2. _Addition/subtraction_. A `.keep_extras()` or `.drop_extras()` in the left and/or right side of an addition or subtraction is preserved in the result because this allows you to write
+    ```
+    a.keep_extras() + b.keep_extras() + c.keep_extras()
+    ```
+    instead of the annoyingly verbose,
+    ```
+    (a.keep_extras() + b.keep_extras()).keep_extras() + c.keep_extras()
+    ```
+    (If the left and right sides have conflicting addition modifiers, e.g., `a.keep_extras() + b.drop_extras()`, no addition modifiers are preserved. Also, if you'd like an addition or subtraction _not_ to preserve addition modifiers, you can force the result back to the default of raising errors whenever there are extra labels by using [`.raise_extras()`][pyoframe.Expression.raise_extras].)