pyoframe 1.1.0__tar.gz → 1.2.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyoframe
-Version: 1.1.0
+Version: 1.2.1
 Summary: Blazing fast linear program interface
 Author-email: Bravos Power <dev@bravospower.com>
 License-Expression: MIT
@@ -20,7 +20,7 @@ Requires-Dist: pyarrow
 Requires-Dist: pandas<3
 Requires-Dist: pyoptinterface==0.5.1
 Provides-Extra: highs
-Requires-Dist: highsbox<=1.12.0; extra == "highs"
+Requires-Dist: highsbox<=1.13.0; extra == "highs"
 Provides-Extra: ipopt
 Requires-Dist: pyoptinterface[nlp]; extra == "ipopt"
 Requires-Dist: llvmlite<=0.46.0; extra == "ipopt"
@@ -34,7 +34,7 @@ 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.12.0; extra == "dev"
+Requires-Dist: highsbox<=1.13.0; extra == "dev"
 Requires-Dist: pyoptinterface[nlp]; extra == "dev"
 Requires-Dist: numpy; extra == "dev"
 Provides-Extra: docs

{pyoframe-1.1.0 → pyoframe-1.2.1}/docs/.nav.yml

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

{pyoframe-1.1.0 → pyoframe-1.2.1}/docs/contribute/index.md

@@ -54,7 +54,7 @@ We use Ruff for linting and formatting. The pre-commit hooks will run `ruff form
 
 ## Additional tips
 
-I recommend skimming or reading the [Internal Details](../learn/advanced-concepts/internals.md) page for some background on how Pyoframe works.
+I recommend skimming or reading the [Internal Details](../learn/concepts/internals.md) page for some background on how Pyoframe works.
 
 For core developers:
 

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

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

{pyoframe-1.1.0 → pyoframe-1.2.1}/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.**
 
@@ -62,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.
 
@@ -114,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?
 
@@ -215,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.2.1/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.1/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.1/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.1/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]
+
+```

pyoframe-1.2.1/docs/learn/develop/create-variables.md

@@ -0,0 +1,215 @@
+# Create variables
+
+To create a variable, attach it to a `Model`:
+
+```python
+import pyoframe as pf
+
+m = pf.Model()
+
+m.Var_Name = pf.Variable()
+```
+
+The variable can later be accessed via the model attribute,
+
+```pycon
+>>> m.Var_Name
+<Variable 'Var_Name' >
+Var_Name
+
+```
+
+!!! tip "Tip: Use uppercase names for variables"
+
+    Uppercase names for variables (i.e. `Var_Name` not `var_name`) makes variables (the most important part of your model) easy to distinguish from other model attributes.
+
+
+## Set bounds
+
+By default, variables are unbounded. To set a lower or upper bound, use the `lb` or `ub` arguments. For example,
+
+```python
+m.Positive_Var = pf.Variable(lb=0)
+```
+
+!!! tip "Bounds can be expressions"
+
+    `lb` and `ub` accepts fully formed [Pyoframe expressions](./create-expressions.md), not only constants.
+
+## Set domain
+
+By default, variables are continuous. To create a binary or integer variable use the `vtype` argument:
+
+```python
+m.Binary_Var = pf.Variable(vtype="binary")
+m.Integer_Var = pf.Variable(vtype="integer")
+```
+
+## Use dimensions and labels
+
+Passing a DataFrame to `pf.Variable` will create a variable for every row in the DataFrame. I call this a _dimensioned variable_.
+
+=== "pandas"
+
+    ```python
+    import pandas as pd
+    import pyoframe as pf
+
+    years = pd.DataFrame({"year": [2025, 2026, 2027]})
+
+    m = pf.Model()
+    m.Yearly_Var = pf.Variable(years)
+    ```
+
+=== "polars"
+
+    ```python
+    import polars as pl
+    import pyoframe as pf
+
+    years = pl.DataFrame({"year": [2025, 2026, 2027]})
+
+    m = pf.Model()
+    m.Yearly_Var = pf.Variable(years)
+    ```
+
+Notice how the DataFrame's column name becomes the dimension name and the DataFrame's values become the variable's labels:
+
+```pycon
+>>> m.Yearly_Var
+<Variable 'Yearly_Var' height=3>
+┌──────┬──────────────────┐
+│ year ┆ variable         │
+│ (3)  ┆                  │
+╞══════╪══════════════════╡
+│ 2025 ┆ Yearly_Var[2025] │
+│ 2026 ┆ Yearly_Var[2026] │
+│ 2027 ┆ Yearly_Var[2027] │
+└──────┴──────────────────┘
+
+```
+
+!!! warning "Labels must be unique"
+
+    An error will be raised if the input DataFrame contains duplicate rows since every variable must have its own unique label.
+
+### Combine dimensions
+
+Passing multiple DataFrames to `pf.Variable()` will create a variable for every row in the [cartesian product](https://en.wikipedia.org/wiki/Cartesian_product) of the DataFrames.
+
+
+=== "pandas"
+
+    ```python
+    years = pd.DataFrame({"year": [2025, 2026, 2027]})
+    locations = pd.DataFrame({"city": ["Toronto", "Mexico City"]})
+
+    m = pf.Model()
+    m.Cartesian_Var = pf.Variable(years, locations)
+    ```
+
+=== "polars"
+
+    ```python
+    years = pl.DataFrame({"year": [2025, 2026, 2027]})
+    locations = pl.DataFrame({"city": ["Toronto", "Mexico City"]})
+
+    m = pf.Model()
+    m.Cartesian_Var = pf.Variable(years, locations)
+    ```
+
+```pycon
+>>> m.Cartesian_Var
+<Variable 'Cartesian_Var' height=6>
+┌──────┬─────────────┬─────────────────────────────────┐
+│ year ┆ city        ┆ variable                        │
+│ (3)  ┆ (2)         ┆                                 │
+╞══════╪═════════════╪═════════════════════════════════╡
+│ 2025 ┆ Toronto     ┆ Cartesian_Var[2025,Toronto]     │
+│ 2025 ┆ Mexico City ┆ Cartesian_Var[2025,Mexico_City] │
+│ 2026 ┆ Toronto     ┆ Cartesian_Var[2026,Toronto]     │
+│ 2026 ┆ Mexico City ┆ Cartesian_Var[2026,Mexico_City] │
+│ 2027 ┆ Toronto     ┆ Cartesian_Var[2027,Toronto]     │
+│ 2027 ┆ Mexico City ┆ Cartesian_Var[2027,Mexico_City] │
+└──────┴─────────────┴─────────────────────────────────┘
+
+```
+
+!!! tip "Use a multi-column DataFrame to create sparse variables"
+
+    An alternative way to create a variable with multiple dimensions (e.g. `year` and `city`) is to pass a single DataFrame with multiple columns to `pf.Variable`. This approach lets you control exactly which rows to include, allowing for sparsely populated variables instead of the cartesian product.
+
+### Other approaches
+
+<!-- invisible-code-block: python
+years = pl.DataFrame({"year": [2025, 2026, 2027]})
+
+m = pf.Model()
+m.Yearly_Var = pf.Variable(years)
+-->
+
+
+DataFrames are not the only way to create a dimensioned variable. In the following examples, all the `m.Yearly_Var` are equivalent.
+
+=== "Pyoframe sets"
+    
+    Pyoframe offers a [`Set`][pyoframe.Set] class to easily define dimensioned variables in a reusable way.
+
+    ```python
+    years = pf.Set(year=[2025, 2026, 2027])  # define once, reuse for multiple variables
+    m.Yearly_Var_1 = pf.Variable(years)
+    ```
+
+=== "Dictionaries"
+
+    Dictionaries are shortcuts for writing `pf.Variable(pl.DataFrame(dict_data))`.
+
+    ```python
+    m.Yearly_Var_2 = pf.Variable({"year": [2025, 2026, 2027]})
+    ```
+
+=== "Other Pyoframe objects"
+
+    Passing a Pyoframe object such as an expression or another variable to `pf.Variable()` will create a variable with the same labels as the object.
+
+    ```python
+    m.Yearly_Var_3 = pf.Variable(
+        m.Yearly_Var
+    )  # Creates a variable with the same labels as m.Yearly_Var
+    ```
+
+=== "Series or indexes"
+
+    A pandas `Index` or `Series` (or a polars `Series`) is treated as a DataFrame.
+
+    ```python
+    years = pd.Series([2025, 2026, 2027], name="year")
+    m.Yearly_Var_4 = pf.Variable(years)
+    ```
+
+    ```python
+    years = pd.Index([2025, 2026, 2027], name="year")
+    m.Yearly_Var_5 = pf.Variable(years)
+    ```
+
+
+
+
+
+<!-- invisible-code-block: python
+from polars.testing import assert_frame_equal
+
+for con in [
+    m.Yearly_Var,
+    m.Yearly_Var_1,
+    m.Yearly_Var_2,
+    m.Yearly_Var_3,
+    m.Yearly_Var_4,
+    m.Yearly_Var_5,
+]:
+    assert "year" in con.data.columns
+    assert len(con.data) == 3
+
+-->
+
+

pyoframe-1.2.1/docs/learn/develop/define-objective.md

@@ -0,0 +1,42 @@
+# Define an objective
+
+To set an objective for your optimization problem, assign an expression to either the `.minimize` or `.maximize` attribute of the Model. For example:
+
+<!-- invisible-code-block: python
+import pyoframe as pf
+
+m = pf.Model()
+capital_costs = pf.Expression.constant(3)
+operating_costs = pf.Expression.constant(3)
+
+-->
+
+```python
+m.minimize = capital_costs + operating_costs
+```
+
+Note that the objective expression must be dimensionless (it makes no sense to have multiple objectives with different labels). You can use [`.sum()`](./create-expressions.md) to collapse a dimensioned expression into a dimensionless one.
+
+## Define an objective incrementally
+
+For larger models, it is often convenient to define the objective function incrementally. To do so, use the `+=` operator:
+
+```python
+m = pf.Model()
+m.minimize = 0
+
+# Later in your code
+m.minimize += capital_costs
+
+# Somewhere else in your code
+m.minimize += operating_costs
+```
+
+## Alternative approach
+
+Alternatively, rather than use `.minimize` or `.maximize`, you can use `.objective` and define the direction using the `sense` argument during model creation:
+
+```python
+m = pf.Model(sense="min")
+m.objective = capital_costs + operating_costs
+```

pyoframe-1.2.1/docs/learn/develop/read-results.md

@@ -0,0 +1,11 @@
+# Read results
+
+Use [`.solution`][pyoframe.Variable.solution] to read the optimal values of Variables after optimization (e.g. `m.Hours_Worked.solution`). For dimensioned variables, `.solution` returns a polars DataFrame.
+
+Similarly, use [`.dual`][pyoframe.Constraint.dual] to read the dual values (aka. shadow prices) of Constraints (e.g. `m.Con_Max_Weekly_Hours.dual`).
+
+You can also output your model problem or solution using [`.write(…)`][pyoframe.Model.write].
+
+!!! info "Returning Pandas DataFrames"
+
+    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.1.0/docs/learn/concepts/solver-access.md → pyoframe-1.2.1/docs/learn/develop/run-and-configure-the-solver.md

@@ -1,28 +1,20 @@
-# Solver interface
+# Run and configure the solver
 
-Pyoframe provides a friendly API that allows you to read and set the various attributes and parameters your solver has to offer.
+To run your optimization model call,
 
-## Model attributes
+<!-- invisible-code-block: python
+import pyoframe as pf
 
-Pyoframe lets you read and set solver attributes using `model.attr.<your-attribute>`. For example, if you'd like to prevent the solver from printing to the console you can do:
+m = pf.Model()
+-->
 
 ```python
-m = pf.Model()
-m.attr.Silent = True
+m.optimize()
 ```
 
-Pyoframe supports a set of [standard attributes](https://metab0t.github.io/PyOptInterface/model.html#id1) as well as additional [Gurobi attributes](https://docs.gurobi.com/projects/optimizer/en/current/reference/attributes/model.html) and [COPT attributes](https://guide.coap.online/copt/en-doc/attribute.html).
-
-```pycon
->>> m.optimize()
->>> m.attr.TerminationStatus  # PyOptInterface attribute (always available)
-<TerminationStatusCode.OPTIMAL: 2>
->>> m.attr.Status  # Gurobi attribute (only available with Gurobi)
-2
-
-```
+Recall that you chose your solver upon [creating your model](./create-a-model.md#specify-a-solver).
 
-## Model parameters
+## Configure solver parameters
 
 Every solver has a set of parameters that you can read or set using `model.params.<your-param>`.
 
@@ -70,7 +62,29 @@ Every solver has a set of parameters that you can read or set using `model.param
         Ipopt does not support reading parameters (only setting them).
 
 
-## Variable and constraint attributes
+## Configure solver attributes
+
+Pyoframe lets you read and set solver attributes using `model.attr.<your-attribute>`. For example, if you'd like to prevent the solver from printing to the console you can do:
+
+```python
+m = pf.Model()
+m.attr.Silent = True
+```
+
+Pyoframe supports a set of [standard attributes](https://metab0t.github.io/PyOptInterface/model.html#id1) as well as additional [Gurobi attributes](https://docs.gurobi.com/projects/optimizer/en/current/reference/attributes/model.html) and [COPT attributes](https://guide.coap.online/copt/en-doc/attribute.html).
+
+```pycon
+>>> m.optimize()
+>>> m.attr.TerminationStatus  # PyOptInterface attribute (always available)
+<TerminationStatusCode.OPTIMAL: 2>
+>>> m.attr.Status  # Gurobi attribute (only available with Gurobi)
+2
+
+```
+
+
+
+### Variable and constraint attributes
 
 Similar to above, Pyoframe allows directly accessing the PyOptInterface or the solver's variable and constraint attributes.
 
@@ -82,7 +96,7 @@ m.X.attr.PrimalStart = 5  # Set initial value for warm start
 
 If the variable or constraint is dimensioned, the attribute can accept/return a DataFrame instead of a constant.
 
-## License configuration (COPT and Gurobi)
+## Configure an advanced license
 
 Both COPT and Gurobi support advanced license configurations through the `solver_env` parameter:
 

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

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

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

@@ -114,7 +114,7 @@ First, multiply the variable by the protein amount.
 
 As you can see, Pyoframe with a bit of magic converted the `Variable` into an `Expression` where the coefficients are the protein amounts.
 
-*[with a bit of magic]: Pyoframe always converts DataFrames into Expressions by taking the first columns as dimensions and the last column as values. Additionally, multiplication is always done between elements with the same dimensions.
+*[with a bit of magic]: Pyoframe always converts DataFrames into Expressions by taking the first columns as dimensions and the last column as values. Additionally, operations are always compute between values with the same labels.
 
 Second, notice that the `Expression` still has the `food` dimension—it really contains two separate expressions, one for tofu and one for chickpeas. All objective functions must be a single expression (without dimensions) so let's sum over the `food` dimension.