# HLPL / VerTeX — full content

> Complete machine-readable reference. MCP endpoint: https://vertex.elytica.com/mcp (no auth).



---

# Verified formulation techniques

Every technique below ships as a complete VerTeX model that has been run and checked. Each model's optimum was computed twice — once by the interpreter, once by an independent reference solver working from the same instance data (exhaustive enumeration, a two-phase simplex, or integer enumeration…

Path: `docs/formulation-techniques`

# Verified formulation techniques

Every technique below ships as a complete VerTeX model that has been run and
checked. Each model's optimum was computed twice — once by the interpreter,
once by an independent reference solver working from the same instance data
(exhaustive enumeration, a two-phase simplex, or integer enumeration with an
LP for the continuous part) — and only models where the two agree are
published here.

Fetch any one with the `get_formulation` tool, or read the source directly
under `formulations/`.

## Techniques

| Technique | What it does | Reference |
|---|---|---|
| `absolute-value` | Absolute value in the objective | Charnes, A [doi:10.2307/3006550](https://doi.org/10.2307/3006550) |
| `assignment` | Linear assignment | Kuhn, H [doi:10.1002/nav.3800020109](https://doi.org/10.1002/nav.3800020109) |
| `bin-packing` | Bin packing | Martello, S |
| `binary-product` | Product of two binary variables | Glover, F [doi:10.1287/opre.22.1.180](https://doi.org/10.1287/opre.22.1.180) |
| `capacitated-facility-location` | Capacitated facility location | Balinski, M [doi:10.1287/mnsc.12.3.253](https://doi.org/10.1287/mnsc.12.3.253) |
| `capacitated-lot-sizing` | Capacitated lot sizing | Bitran, G |
| `chance-constraint` | Chance constraint via scenario binaries | Charnes, A |
| `count-cardinality` | Counting and cardinality | Nemhauser, G [doi:10.1002/9781118627372](https://doi.org/10.1002/9781118627372) |
| `criterion-as-constraint` | Secondary criterion moved into a constraint | Haimes, Y [doi:10.1109/TSMC.1971.4308298](https://doi.org/10.1109/TSMC.1971.4308298) |
| `cvrp-mtz` | Capacitated vehicle routing (MTZ load form) | Miller, C [doi:10.1145/321043.321046](https://doi.org/10.1145/321043.321046) |
| `diet-blending` | Diet / blending | Stigler, G [doi:10.2307/1231810](https://doi.org/10.2307/1231810) |
| `dominating-set` | Minimum dominating set | Haynes, T [doi:10.1201/9781482246582](https://doi.org/10.1201/9781482246582) |
| `edge-matching` | Maximum weight matching | Edmonds, J [doi:10.6028/jres.069B.013](https://doi.org/10.6028/jres.069B.013) |
| `either-or` | Disjunctive (either-or) constraints | Balas, E [doi:10.1016/S0167-5060(08)70342-X](https://doi.org/10.1016/S0167-5060(08)70342-X) |
| `fixed-charge` | Fixed-charge (setup) cost | Beale, E |
| `fixed-charge-continuous` | Fixed charge with continuous production | Balinski, M [doi:10.1287/mnsc.12.3.253](https://doi.org/10.1287/mnsc.12.3.253) |
| `fixed-charge-network-design` | Fixed-charge network design | Magnanti, T [doi:10.1287/trsc.18.1.1](https://doi.org/10.1287/trsc.18.1.1) |
| `goal-programming` | Soft constraints by goal programming | Charnes, A [doi:10.2307/1909344](https://doi.org/10.2307/1909344) |
| `graph-colouring` | Graph colouring | Mehrotra, A [doi:10.1287/ijoc.8.4.344](https://doi.org/10.1287/ijoc.8.4.344) |
| `implication` | Logical implication between binaries | Williams, H |
| `independent-set` | Maximum weighted independent set | Nemhauser, G [doi:10.1007/BF01580444](https://doi.org/10.1007/BF01580444) |
| `job-shop-disjunctive` | Job shop, disjunctive formulation | Manne, A |
| `knapsack-01` | 0/1 knapsack | Dantzig, G [doi:10.1287/opre.5.2.266](https://doi.org/10.1287/opre.5.2.266) |
| `knapsack-bounded` | Bounded knapsack | Martello, S |
| `knapsack-multidim` | Multidimensional knapsack | Fréville, A [doi:10.1016/S0377-2217(03)00274-1](https://doi.org/10.1016/S0377-2217(03)00274-1) |
| `knapsack-unbounded` | Unbounded knapsack | Gilmore, P |
| `linking-aggregated` | Aggregated (big-M) linking constraint | Vielma, J [doi:10.1137/130915303](https://doi.org/10.1137/130915303) |
| `linking-disaggregated` | Disaggregated linking constraint | Vielma, J [doi:10.1137/130915303](https://doi.org/10.1137/130915303) |
| `logarithmic-encoding` | Logarithmic encoding of a choice | Vielma, J |
| `lot-sizing` | Single-item lot sizing with setups | Wagner, H [doi:10.1287/mnsc.5.1.89](https://doi.org/10.1287/mnsc.5.1.89) |
| `m-tsp` | Multiple travelling salesman | Bektas, T |
| `max-clique` | Maximum clique | Bomze, I |
| `max-covering` | Maximal covering location | Church, R [doi:10.1007/BF01942293](https://doi.org/10.1007/BF01942293) |
| `max-cut` | Maximum cut | Barahona, F., Grötschel, M., Jünger, M [doi:10.1287/opre.36.3.493](https://doi.org/10.1287/opre.36.3.493) |
| `max-flow` | Maximum flow | Ford, L [doi:10.4153/CJM-1956-045-5](https://doi.org/10.4153/CJM-1956-045-5) |
| `maximin` | Maximising a minimum | Rawls, J |
| `maximin-continuous` | Maximising a minimum over continuous shares | Rawls, J |
| `min-cost-flow` | Minimum-cost network flow | Ford, L [doi:10.1515/9781400875184](https://doi.org/10.1515/9781400875184) |
| `minimax` | Minimising a maximum | Dantzig, G [doi:10.1515/9781400884179](https://doi.org/10.1515/9781400884179) |
| `multi-period-production` | Multi-period production planning | Johnson, L |
| `multicommodity-flow` | Multi-commodity flow | Ford, L [doi:10.1287/mnsc.5.1.97](https://doi.org/10.1287/mnsc.5.1.97) |
| `multiple-knapsack` | Multiple knapsack | Martello, S |
| `mutual-exclusion` | Mutual exclusion and complementarity | Padberg, M [doi:10.1007/BF01580121](https://doi.org/10.1007/BF01580121) |
| `p-center` | p-center (minimax location) | Kariv, O |
| `p-median` | p-median facility location | Hakimi, S [doi:10.1287/opre.12.3.450](https://doi.org/10.1287/opre.12.3.450) |
| `piecewise-incremental` | Piecewise-linear, incremental (delta) form | Markowitz, H [doi:10.2307/1907744](https://doi.org/10.2307/1907744) |
| `piecewise-lambda` | Piecewise-linear cost, convex-combination form | Dantzig, G [doi:10.1515/9781400884179](https://doi.org/10.1515/9781400884179) |
| `prize-collecting-tsp` | Prize-collecting / orienteering tour | Balas, E |
| `product-binary-continuous` | Product of a binary and a bounded continuous variable | Glover, F [doi:10.1287/mnsc.22.4.455](https://doi.org/10.1287/mnsc.22.4.455) |
| `product-mix` | Product mix | Dantzig, G [doi:10.1515/9781400884179](https://doi.org/10.1515/9781400884179) |
| `robust-box-uncertainty` | Robust counterpart under box uncertainty | Soyster, A |
| `semi-continuous` | Semi-continuous variable | Beale, E |
| `set-cover` | Weighted set covering | Balas, E [doi:10.1137/1018115](https://doi.org/10.1137/1018115) |
| `set-partitioning` | Set partitioning | Balas, E [doi:10.1137/1018115](https://doi.org/10.1137/1018115) |
| `shortest-path-arc` | Shortest path by arc selection | Ahuja, R |
| `single-machine-disjunctive` | Single-machine sequencing, disjunctive (big-M) formulation | Manne, A |
| `sos1-at-most-one` | At most one nonzero (SOS1 by binaries) | Beale, E |
| `sos2-piecewise` | Piecewise-linear via SOS2-style adjacency | Beale, E |
| `spanning-tree` | Minimum spanning tree | Edmonds, J |
| `subset-sum` | Subset sum | Karp, R |
| `time-indexed-scheduling` | Time-indexed scheduling | Pritsker, A |
| `transportation` | Transportation problem | Hitchcock, F [doi:10.1002/sapm1941201224](https://doi.org/10.1002/sapm1941201224) |
| `transshipment` | Transshipment | Orden, A [doi:10.1287/mnsc.2.3.276](https://doi.org/10.1287/mnsc.2.3.276) |
| `tsp-dfj-subtour` | Travelling salesman, DFJ subtour elimination | Dantzig, G., Fulkerson, R |
| `tsp-mtz` | Travelling salesman with MTZ subtour elimination | Miller, C [doi:10.1145/321043.321046](https://doi.org/10.1145/321043.321046) |
| `two-stage-recourse` | Two-stage stochastic programme with recourse | Dantzig, G |
| `uncapacitated-facility-location` | Uncapacitated facility location | Balinski, M [doi:10.1287/mnsc.12.3.253](https://doi.org/10.1287/mnsc.12.3.253) |
| `vertex-cover` | Minimum weighted vertex cover | Nemhauser, G [doi:10.1007/BF01580444](https://doi.org/10.1007/BF01580444) |
| `weighted-single-objective` | Weighted single objective over several criteria | Zadeh, L [doi:10.1109/TAC.1963.1105511](https://doi.org/10.1109/TAC.1963.1105511) |
| `zero-sum-game` | Zero-sum matrix game | Dantzig, G [doi:10.1515/9781400884179](https://doi.org/10.1515/9781400884179) |

## By modelling feature

- **absolute-value** — `absolute-value`
- **adjacency** — `sos2-piecewise`
- **aggregated-linking** — `linking-aggregated`
- **assignment** — `assignment`, `bin-packing`, `graph-colouring`, `multiple-knapsack`
- **at-most-one** — `sos1-at-most-one`
- **auxiliary-binary** — `binary-product`
- **auxiliary-continuous** — `absolute-value`, `maximin`, `minimax`, `p-center`
- **big-M** — `chance-constraint`, `either-or`, `fixed-charge-network-design`, `job-shop-disjunctive`, `linking-aggregated`, `product-binary-continuous`, `single-machine-disjunctive`
- **bin-packing** — `bin-packing`
- **binary-expansion** — `logarithmic-encoding`
- **binary-selection** — `knapsack-01`
- **blending** — `diet-blending`
- **bounded-counts** — `knapsack-bounded`
- **box-uncertainty** — `robust-box-uncertainty`
- **bundle-constraint** — `multicommodity-flow`
- **capacity** — `capacitated-facility-location`, `capacitated-lot-sizing`, `cvrp-mtz`
- **capacity-gating** — `bin-packing`
- **cardinality** — `binary-product`, `count-cardinality`, `p-median`
- **chance-constraint** — `chance-constraint`
- **clique** — `max-clique`
- **colouring** — `graph-colouring`
- **compact-formulation** — `logarithmic-encoding`
- **complement-graph** — `max-clique`
- **conflict-pairs** — `mutual-exclusion`
- **continuous** — `diet-blending`, `fixed-charge-continuous`, `max-flow`, `maximin-continuous`, `min-cost-flow`, `multi-period-production`, `multicommodity-flow`, `product-mix`, `transportation`, `transshipment`, `zero-sum-game`
- **continuous-time** — `single-machine-disjunctive`
- **counting** — `count-cardinality`
- **covering** — `dominating-set`, `max-covering`, `set-cover`, `vertex-cover`
- **covering-lp** — `diet-blending`
- **criteria-tradeoff** — `criterion-as-constraint`, `weighted-single-objective`
- **delta-form** — `piecewise-incremental`
- **deviation-variables** — `goal-programming`
- **disaggregated-linking** — `linking-disaggregated`
- **disjunction** — `either-or`
- **disjunctive** — `job-shop-disjunctive`, `single-machine-disjunctive`
- **epsilon-constraint** — `criterion-as-constraint`
- **equality-constraint** — `subset-sum`
- **exact-cover** — `set-partitioning`
- **exponential-family** — `tsp-dfj-subtour`
- **facility-location** — `capacitated-facility-location`, `uncapacitated-facility-location`
- **fairness** — `maximin`, `maximin-continuous`
- **feasibility** — `subset-sum`
- **fixed-charge** — `fixed-charge`, `fixed-charge-continuous`, `fixed-charge-network-design`
- **flow-conservation** — `min-cost-flow`, `shortest-path-arc`, `transshipment`
- **game-theory** — `zero-sum-game`
- **glover-linearization** — `product-binary-continuous`
- **goal-programming** — `absolute-value`, `goal-programming`
- **graph** — `dominating-set`, `edge-matching`, `independent-set`, `vertex-cover`
- **ideal-formulation** — `linking-disaggregated`
- **implication** — `implication`
- **incremental-form** — `piecewise-incremental`
- **index-arithmetic** — `capacitated-lot-sizing`, `lot-sizing`, `multi-period-production`
- **index-mapping** — `independent-set`, `max-clique`, `max-cut`, `mutual-exclusion`, `spanning-tree`, `vertex-cover`
- **indicator-binary** — `either-or`
- **integer-variables** — `knapsack-bounded`, `knapsack-unbounded`
- **intermediate-nodes** — `transshipment`
- **inventory-balance** — `lot-sizing`, `multi-period-production`
- **job-shop** — `job-shop-disjunctive`
- **knapsack** — `knapsack-01`, `knapsack-bounded`, `knapsack-multidim`, `knapsack-unbounded`, `multiple-knapsack`
- **lambda-form** — `piecewise-lambda`, `sos2-piecewise`
- **linear-program** — `product-mix`
- **load-balancing** — `minimax`
- **location** — `max-covering`, `p-center`, `p-median`
- **logarithmic-encoding** — `logarithmic-encoding`
- **logical-constraint** — `implication`
- **lot-sizing** — `capacitated-lot-sizing`, `lot-sizing`
- **lp-duality** — `zero-sum-game`
- **m-tsp** — `m-tsp`
- **matching** — `edge-matching`
- **matroid** — `spanning-tree`
- **max-flow** — `max-flow`
- **maximin** — `maximin`, `maximin-continuous`
- **min-cut-duality** — `max-flow`
- **minimax** — `minimax`, `p-center`, `zero-sum-game`
- **minimum-level** — `semi-continuous`
- **mixed-integer** — `fixed-charge-continuous`, `fixed-charge-network-design`
- **mtz** — `cvrp-mtz`, `m-tsp`, `prize-collecting-tsp`, `tsp-mtz`
- **multi-constraint** — `knapsack-multidim`
- **multi-container** — `multiple-knapsack`
- **multi-period** — `multi-period-production`
- **multi-vehicle** — `m-tsp`
- **multicommodity** — `multicommodity-flow`
- **network** — `shortest-path-arc`
- **network-design** — `fixed-charge-network-design`
- **no-extra-variables** — `robust-box-uncertainty`
- **not-tu** — `multicommodity-flow`
- **on-off-binary** — `semi-continuous`
- **optional-visits** — `prize-collecting-tsp`
- **ordering** — `piecewise-incremental`
- **orienteering** — `prize-collecting-tsp`
- **p-center** — `p-center`
- **p-median** — `p-median`
- **packing** — `independent-set`, `max-clique`
- **parametric-set** — `dominating-set`, `edge-matching`, `max-covering`, `min-cost-flow`, `set-cover`, `set-partitioning`, `shortest-path-arc`
- **partitioning** — `max-cut`
- **period-capacity** — `time-indexed-scheduling`
- **piecewise-linear** — `piecewise-incremental`, `piecewise-lambda`, `sos2-piecewise`
- **precedence** — `implication`, `job-shop-disjunctive`
- **prize-collecting** — `prize-collecting-tsp`
- **product** — `product-binary-continuous`
- **quadratic-linearization** — `binary-product`
- **recourse** — `two-stage-recourse`
- **resource-constraints** — `product-mix`
- **resource-vector** — `knapsack-multidim`
- **robust** — `robust-box-uncertainty`
- **routing** — `cvrp-mtz`, `m-tsp`
- **scalarization** — `weighted-single-objective`
- **scenario-binaries** — `chance-constraint`
- **scenario-indexed** — `two-stage-recourse`
- **semi-continuous** — `semi-continuous`
- **sequencing** — `single-machine-disjunctive`, `tsp-mtz`
- **set-packing** — `mutual-exclusion`
- **set-partitioning** — `set-cover`, `set-partitioning`
- **setup-binary** — `capacitated-lot-sizing`, `fixed-charge`, `lot-sizing`
- **single-constraint** — `knapsack-01`
- **single-objective** — `criterion-as-constraint`, `weighted-single-objective`
- **soft-constraint** — `goal-programming`
- **sos1** — `sos1-at-most-one`
- **sos2** — `sos2-piecewise`
- **sos2-like** — `piecewise-lambda`
- **spanning-tree** — `spanning-tree`
- **stochastic** — `chance-constraint`, `two-stage-recourse`
- **strong-relaxation** — `linking-disaggregated`, `tsp-dfj-subtour`
- **subset-constraints** — `spanning-tree`
- **subset-restriction** — `count-cardinality`
- **subset-sum** — `subset-sum`
- **subtour-elimination** — `cvrp-mtz`, `tsp-dfj-subtour`, `tsp-mtz`
- **symmetry-prone** — `graph-colouring`
- **tight-relaxation** — `time-indexed-scheduling`
- **time-indexed** — `time-indexed-scheduling`
- **totally-unimodular** — `assignment`, `min-cost-flow`, `transportation`
- **transportation** — `transportation`
- **tsp** — `tsp-dfj-subtour`
- **two-index** — `assignment`, `uncapacitated-facility-location`
- **two-stage** — `two-stage-recourse`
- **unbounded** — `knapsack-unbounded`
- **variable-upper-bound** — `capacitated-facility-location`, `fixed-charge`, `sos1-at-most-one`, `uncapacitated-facility-location`
- **vrp** — `cvrp-mtz`
- **weak-relaxation** — `linking-aggregated`
- **weighted-sum** — `weighted-single-objective`
- **worst-case** — `robust-box-uncertainty`
- **xor-linearization** — `max-cut`

## What "verified" means here

The interpreter and the reference solver share no code. The reference works
from the instance data, never from the VerTeX source, and for a linearization
it evaluates the *original* construct — a product as an actual product, an
absolute value as an actual absolute value — so a formulation that is merely
self-consistent still fails if it does not agree with what it claims to
linearize. Where the two disagreed, the instance was discarded rather than
reconciled.



---

# MIP/LP Modelling Language Syntax (HLPL Files)

IMPORTANT: Read this entire syntax guide BEFORE creating any optimization models.

Path: `docs/syntax`

# MIP/LP Modelling Language Syntax (HLPL Files)

IMPORTANT: Read this entire syntax guide BEFORE creating any optimization models.

This is a domain-specific modelling language for Linear Programming (LP) and Mixed Integer Programming (MIP) that combines:
- Mathematical optimization model declarations
- Python/Lua scripting for data processing and results analysis
- LaTeX for documentation
- Template-based reusable constraint blocks

## File Format

HLPL files use the .hlpl extension and are plain text files containing:
1. Optional template definitions
2. Model declaration (between "model" and "end")
3. Python or Lua implementation code
4. REQUIRED: main() function that returns integer exit code

## Basic Structure

```hlpl
# Optional: Define reusable constraint templates
template templateName()
  <constraint declarations>
end

# Main model definition — the model name MAY contain underscores (`shortest_path`), unlike set,
# constant and variable names. Whatever it is, the `init_model`/`run_model` calls in the Python
# section below must use exactly the same string.
model modelName
  <set declarations>
  <parameter declarations>
  <variable declarations>
  <objective function>
  <constraints>
  <template inclusions>
end

# Python/Lua implementation
import elytica
def main():
    elytica.init_model("modelName")
    elytica.run_model("modelName")
    # ... process results
    return 0  # REQUIRED: Return 0 for success
```

## CRITICAL SYNTAX RESTRICTIONS

Before writing your model, understand these critical restrictions:

1. **NO TUPLE/PAIR NOTATION IN SETS**: Sets can only contain simple integers
   - INVALID: `set A = {(1,2), (1,3), (2,4)}`
   - VALID: `set A = {1, 2, 3, 4}` with constants for source/target nodes

2. **NO UNDERSCORES IN NAMES**: Use only in indexing (e.g., `x_{i}`)
   - INVALID: `set TIME_PERIODS`, `bin my_var`, `const max_cost`
   - VALID: `set T`, `bin x`, `const c`
   - **The model name is exempt**: `model shortest_path` is valid. This rule is about sets,
     constants and variables — the names that appear in indexed expressions. A model name never
     does, so an underscore in it is not ambiguous with subscript notation.
     VALID: `model knapsack`, `model shortest_path`, `model office_allocation`
   - **Why the rule exists**: `_` is the subscript operator, and its braces are optional for a
     single index — `x_i` is read as exactly `x_{i}`. A name containing an underscore is therefore
     parsed as a name plus a subscript, and the declaration never registers the name you wrote.
     Use the braced form `x_{i}` in models; the unbraced one is what makes the rule necessary.
   - **The error you get will not point at the declaration.** Three shapes to recognise:
     - `error[reference::undefined-name]: 'xarc' was not defined in the model` — an underscored
       *variable* name, reported with the underscore removed. `bin x_arc` gives this at every use
       of `x_arc_{i,j}`, and rewriting the uses as `xarc_{i,j}` does not help: the declaration is
       what failed, not the reference.
     - `error[type::non-linear-term]: product of two expressions that both contain variables` —
       an underscored *constant* name multiplied by a real variable. `const d_ist` used as
       `d_ist_{e} * x_{i,j}` gives this, and it names neither the constant nor the underscore.
     - `error[reference::set-not-found]: set 'N_' was not declared in the model` — an underscored
       *set* name whose suffix is a single character, such as `set N_i`.
   - A set name with a longer suffix (`set N_ODES`) does happen to parse. That is one spelling
     surviving, not the rule being soft: a parameterized `set sig_ma(N)` fails with a syntax error
     inside the `sum` that uses it. Keep the rule uniformly.

3. **ONLY THREE CONSTRAINT OPERATORS**: `=`, `>=`, `<=`
   - INVALID: `<`, `>`, `!=`, `==` (comparison in constraint filters)
   - VALID: `=`, `>=`, `<=`

4. **NO RANGE NOTATION**: Cannot use `{1..10}`
   - INVALID: `set I = {1..10}`
   - VALID: `set I = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}` or use function

5. **USE [] FOR GROUPING, NOT ()**: Parentheses only for function calls and set functions
   - INVALID: `sum_{i in I}{(x_{i} + y_{i}) * c_{i}}`
   - VALID: `sum_{i in I}{[x_{i} + y_{i}] * c_{i}}`

6. **SUMMATION MUST HAVE CURLY BRACES WITH EXPRESSION**: Cannot use empty brackets
   - INVALID: `sum_{i in I}[]`
   - INVALID: `sum_{i in I}()`
   - VALID: `sum_{i in I}{x_{i}}`

7. **NO PROGRAMMATIC OPERATORS IN CONSTRAINTS**: Cannot use `? :`, `==`, `!=` for filtering
   - INVALID: `sum_{a in A}{f_{a} * (s_{a} == n ? 1 : 0)}`
   - VALID: Use indicator constants or `setminus {}` for set operations

## Model Components

### Sets

**IMPORTANT NAMING RULES**:
- Set names MUST NOT contain underscores. `set N_i` fails as
  `error[reference::set-not-found]: set 'N_' was not declared` — the `_i` is read as a subscript
- PREFER single letters (I, J, K, T, N, A) for mathematical readability
- Document what each set represents in comments

**IMPORTANT DATA LOADING**: PREFER loading sets from functions over hardcoding values.

**CRITICAL: TUPLE/PAIR NOTATION NOT ALLOWED**
- Sets can ONLY contain simple integers: {1, 2, 3, 4, 5}
- Tuple notation like {(1,2), (1,3), (2,4)} is NOT supported
- For arcs/edges/pairs, use separate indices in forall loops

```hlpl
# PREFERRED: Load from functions
set I = getItems()                     # Items (preferred: function-based)
set T = getTimeperiods()               # Time periods (preferred: function-based)
set N = getNodes()                     # Nodes (preferred: function-based)
set A = getArcs()                      # Arcs - returns simple integers (preferred: function-based)

# Less preferred: Hardcoded values (only for small examples)
set I = {1, 2, 3, 4, 5}                # Hardcoded (use only for examples)
set J = {1..10}                        # INVALID: Range notation not allowed!
set TIMEPERIODS = {1, 2}               # Valid but not preferred: less readable
set TIME_PERIODS = {1, 2}              # INVALID: underscore in set name

# INVALID: Tuple/pair notation NOT allowed
set A = {(1,2), (1,3), (2,3), (2,4), (3,4), (3,5), (4,5), (1,4), (2,5)}  # INVALID!
set E = {(1,3), (1,4), (2,3)}          # INVALID!
```

Set functions (parameterized sets):
```hlpl
set I = getItems()                     # Base set loaded from function
set P(I) = getProductIdsSubsets()      # Function-based parameterized set
```

**Correct approach for arcs/edges/pairs:**

Since tuple notation is not supported, use one of these approaches:

**Approach 1: Separate node sets with filtering in Python**
```hlpl
set N = {1, 2, 3, 4, 5}                          # Nodes
const hasArc = getArcMatrix(), forall i in N, forall j in N  # Adjacency matrix

# Arc flow variables
var 0<=f<=infty, forall i in N, forall j in N    # Flow on arc (i,j)

# Constraint: flow only on existing arcs
constr f_{i,j} <= 1000 * hasArc_{i,j}, forall i in N, forall j in N
```

```python
# Python: Load adjacency matrix where 1 means arc exists, 0 means no arc
getArcMatrix = lambda: {
    1: {1: 0, 2: 1, 3: 1, 4: 1, 5: 0},
    2: {1: 0, 2: 0, 3: 1, 4: 1, 5: 1},
    3: {1: 0, 2: 0, 3: 0, 4: 1, 5: 1},
    4: {1: 0, 2: 0, 3: 0, 4: 0, 5: 1},
    5: {1: 0, 2: 0, 3: 0, 4: 0, 5: 0}
}
```

**Approach 2: Use a simple arc ID set with mapping constants**
```hlpl
set A = {1, 2, 3, 4, 5, 6, 7, 8, 9}              # Arc IDs
const source = getSources(), forall a in A        # Source node of each arc
const target = getTargets(), forall a in A        # Target node of each arc
const cost = getArcCosts(), forall a in A         # Cost of each arc

# Arc flow variables
var 0<=f<=infty, forall a in A                    # Flow on arc a

# Flow conservation: sum outgoing - sum incoming = supply
# Define subsets for outgoing and incoming arcs per node in Python
const outarc = getOutgoingArcs(), forall n in N, forall a in A  # 1 if arc a starts at node n, 0 otherwise
const inarc = getIncomingArcs(), forall n in N, forall a in A   # 1 if arc a ends at node n, 0 otherwise
constr sum_{a in A}[f_{a} * outarc_{n,a}] - sum_{a in A}[f_{a} * inarc_{n,a}] = supply_{n}, forall n in N
```

```python
# Python: Define arc mappings and constants
getSources = lambda: {1: 1, 2: 1, 3: 2, 4: 2, 5: 3, 6: 3, 7: 4, 8: 1, 9: 2}
getTargets = lambda: {1: 2, 2: 3, 3: 3, 4: 4, 5: 4, 6: 5, 7: 5, 8: 4, 9: 5}
getArcCosts = lambda: {1: 5, 2: 3, 3: 8, 4: 2, 5: 6, 6: 4, 7: 1, 8: 7, 9: 3}

# Define binary indicators for arc-node relationships
def getOutgoingArcs():
    sources = getSources()
    return {n: {a: (1 if sources[a] == n else 0) for a in sources} for n in range(1, 6)}

def getIncomingArcs():
    targets = getTargets()
    return {n: {a: (1 if targets[a] == n else 0) for a in targets} for n in range(1, 6)}
```

**Key point**: Always use simple integer sets and represent relationships using constants or adjacency matrices.

Set Operators:
```hlpl
constr x_{i} <= 5, forall i in I setminus {1} # Remove 1 from the set
constr x_{i} <= 5, forall i in I setminus {PythonFunction()} # PythonFunction() should return a list of unsigned integers
```

### Constants

**IMPORTANT NAMING RULES**:
- Constant names MUST NOT contain underscores (underscores ONLY for indexing: `v_{i}`).
  `const d_ist` used as `d_ist_{e} * x_{i,j}` fails as
  `error[type::non-linear-term]: product of two expressions that both contain variables`, which
  names neither the constant nor the underscore
- PREFER Greek letters (alpha, beta, gamma, lambda, mu, sigma) and single letters (c, v, w, p, d)
- Document what each constant represents in comments

**IMPORTANT DATA LOADING**: PREFER loading constants from functions over hardcoding values.

```hlpl
# PREFERRED: Load from functions
const c = getCosts(), forall i in I             # Cost (preferred: function-based)
const v = getValues(), forall i in I            # Value (preferred: function-based)
const w = getWeights(), forall i in I           # Weight (preferred: function-based)
const alpha = getDiscounts(), forall i in I     # Discount factor (preferred: function-based)
const mu = getDemands(), forall i in I          # Mean demand (preferred: function-based)
const d = getDistances(), forall i in I, forall j in J  # Distance matrix (function-based)

# Less preferred: Hardcoded values (only for small examples)
const c = {1.0, 2.0, 3.0}, forall i in I        # Hardcoded (use only for examples)
const v = {0.5, 1, 2.5}, forall i in I          # Hardcoded (use only for examples)

# Valid but less readable
const capacity = {10, 20}, forall i in I        # Valid but less readable
const maxcost = {1.0, 2.0}, forall i in I       # Valid but less readable

# INVALID
const max_cost = {1.0, 2.0}, forall i in I      # INVALID: underscore in constant name
```

### Data functions

A set or constant written `= someFunction()` is filled by calling that function in the
script section. What each must return:

| Declaration | The function returns | Example |
|---|---|---|
| `set I = getItems()` | a list of integers | `[1, 2, 3]` |
| `set P(I) = getSubsets()` | a dict from each index to a list of integers; use as `j in P(i)` | `{1: [2, 3], 2: [3], 3: [1]}` |
| `const c = getCosts(), forall i in I` | a dict keyed by index | `{1: 0.5, 2: 1.0, 3: 2.5}` |
| `const d = getD(), forall i in I, forall j in J` | nested dicts, one level per index (up to 7) | `{1: {1: 0.5, 2: 2.0}, 2: {1: 1.0, 2: 3.0}}` |
| `const C = getCapacity()` | a number | `12` |

- **Return plain JSON values.** Results are serialized as JSON, so lists, tuples, dicts and
  numbers work, and dict keys may be ints or strings. A Python `range`, `set` or numpy array
  does not: wrap it, `list(range(1, 11))`. A function that raises is reported as
  `error[reference::function-not-found]: script function '…' did not return a value`, so
  when you see that, run the function by hand to find the real error.
- **Lambdas and `def`s are both data functions**, and may call each other:
  `getItems = lambda: list(data)` and `def getWeights(): …` are equivalent.
- They are called with no arguments, from inside `elytica.init_model("…")` — so after
  `main()` has started, and after module-level code such as
  `data = json.load(open('input.json'))`.
- **Single-value constants** can be written in the model (`const C = 12`) or filled by a
  function (`const C = getCapacity()`). Both run. The editor's checker currently flags the
  function form as `data::error` "invalid data", so prefer the literal when the value is
  fixed.
- Data functions only run when the script runs. A checker, and the interpreter's
  script-less `runHlpl` mode, report every one as not run; that is not an error in the model.

**Best Practice**:
Load a `data.json` file in Python, then use functions to extract data for the model:
```python
import json
data = json.load(open('data/input.json'))
getCosts = lambda: data['costs']
getValues = lambda: data['values']
```

### Decision Variables

**IMPORTANT NAMING RULES**:
- Variable names MUST NOT contain underscores (underscores ONLY for indexing: `x_{i}`).
  `bin x_arc` fails as `error[reference::undefined-name]: 'xarc' was not defined in the model` at
  every use — the underscore is stripped from the reported name, and the declaration is what failed
- PREFER Greek letters (lambda, epsilon, theta, pi, rho) and single letters (x, y, z, f, q)
- Document what each variable represents in comments

Binary variables (0 or 1):
```hlpl
bin x, forall i in I                    # Item selection (preferred: single letter)
bin y, forall i in I, forall j in J     # Assignment (preferred: single letter)
bin lambda, forall i in I               # Binary indicator (preferred: Greek letter)
bin theta, forall k in K                # Configuration choice (preferred: Greek letter)
bin selected, forall i in I             # Valid but less readable
bin myvar, forall i in I                # Valid but less readable
bin my_var, forall i in I               # INVALID: underscore in variable name
```

Continuous variables with bounds:
```hlpl
var z, forall i in I                          # Objective contribution (preferred: single letter)
var f, forall a in A                          # Flow (preferred: single letter)
var q, forall i in I                          # Quantity (preferred: single letter)
var 0<=epsilon<=infty, forall t in T          # Slack variable (preferred: Greek letter)
var 0<=rho<=infty, forall i in I              # Utilization (preferred: Greek letter)
var 0<=pi<=1, forall i in I                   # Proportion (preferred: Greek letter)
var flow, forall a in A                       # Valid but less readable
var maxflow, forall a in A                    # Valid but less readable
var max_flow, forall a in A                   # INVALID: underscore in variable name
```

### Objective Function

IMPORTANT: Summations use format: sum_{index in SET}{expression}
Use [] for grouping complex expressions, NOT ()

Maximization:
```hlpl
max sum_{i in I}{v_{i} * x_{i}}
max sum_{i in I}{[v_{i} + bonus_{i}] * x_{i}}  # Use [] for grouping
```

Minimization:
```hlpl
min sum_{i in I}{c_{i} * x_{i}}
min sum_{i in I}{[c_{i} + penalty_{i}] * x_{i}}  # Use [] for grouping
```

### Constraints

**IMPORTANT**: Only three constraint operators are allowed: `=`, `>=`, `<=`
**IMPORTANT**: Use [] for grouping expressions, NOT ()
**IMPORTANT**: No programmatic operators (? :, ==, !=) in mathematical expressions

Simple constraints:
```hlpl
constr sum_{i in I}{w_{i} * x_{i}} <= 15                    # Less than or equal
constr x_{i} + y_{j} >= 1, forall i in I, forall j in J    # Greater than or equal
constr x_{i} = 1, forall i in I                             # Equality
constr x_{i} < 5, forall i in I                             # INVALID: < not allowed
constr x_{i} > 0, forall i in I                             # INVALID: > not allowed
constr x_{i} != 1, forall i in I                            # INVALID: != not allowed
constr sum_{a in A}{f_{a} * [s_{a} == n ? 1 : 0]} = b_{n}, forall n in N # INVALID: cannot use () outside functions, cannot use ternary ? :
constr sum_{a in A : s_{a} == n}{f_{a}} = b_{n}, forall n in N # INVALID: cannot use : filtering with ==, use setminus {} or define indicator constants
```

## Python Integration

After the model declaration, use Python with the elytica module.

IMPORTANT: Scripts MUST have a main() function that returns an integer (the program exit code).
- Return 0 for success
- Return non-zero for failure

### Basic elytica API

```python
import elytica

def main():
    # Solver configuration
    elytica.set_gap_limit("model_name", 0.01)      # 1% MIP gap
    elytica.set_time_limit("model_name", 3600)     # 1 hour time limit

    # Initialize and solve
    elytica.init_model("model_name")
    elytica.run_model("model_name")

    # Get variable values
    value = elytica.get_variable_value("model_name", "x1")
    multi_index = elytica.get_variable_value("model_name", "alpha1,2,3")

    # Get objective value
    obj = elytica.get_best_primal_bound("model_name")

    # Write results (JSON, plain text, or any format)
    elytica.write_results(str(obj))

    return 0  # REQUIRED: Return 0 for success
```

### Generating Charts with ECharts (Optional)

You can optionally generate interactive visualizations by writing chart configurations to the results file.
Charts are rendered in the tutorial interface using ECharts.

**Note**: Charts are OPTIONAL. Only create charts when specifically requested by the user.

**CRITICAL CHART REQUIREMENTS (when creating charts):**
- Charts MUST be fully JSON serializable
- Use integers 0 and 1 instead of boolean True/False
- NO None values - calculate all values beforehand
- NO function references - all data must be literal values
- NO null values - use 0 or empty string instead

```python
import elytica
import json

def main():
    elytica.init_model("model_name")
    elytica.run_model("model_name")

    # Create a chart configuration (ECharts format)
    # All values must be JSON serializable - no True/False/None
    chart = {
        "title": {"text": "Optimization Results"},
        "tooltip": {},
        "xAxis": {
            "type": "category",
            "data": ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
        },
        "yAxis": {
            "type": "value"
        },
        "series": [
            {
                "name": "Variable Values",
                "data": [3, 4, 5, 6, 4, 3, 1],  # Good: literal integers
                "type": "line"
            }
        ]
    }

    # Write results with chart
    elytica.write_results(json.dumps({"chart": chart}))

    return 0
```

Multiple charts can be included using the "charts" key (array):

```python
import elytica
import json

def main():
    elytica.init_model("model_name")
    elytica.run_model("model_name")

    # Create multiple charts
    # Remember: Use 0/1 for booleans, no None/null values
    chart1 = {
        "title": {"text": "Decision Variables"},
        "xAxis": {"type": "category", "data": ["x1", "x2", "x3", "x4", "x5"]},
        "yAxis": {"type": "value"},
        "series": [{"data": [1, 0, 1, 1, 0], "type": "bar"}]  # Good: 1/0 not True/False
    }

    chart2 = {
        "title": {"text": "Objective Value Over Time"},
        "xAxis": {"type": "category", "data": ["Iter 1", "Iter 2", "Iter 3"]},
        "yAxis": {"type": "value"},
        "series": [{"data": [100, 150, 180], "type": "line"}]
    }

    # Write multiple charts
    elytica.write_results(json.dumps({"charts": [chart1, chart2]}))

    return 0
```

Common chart types supported:
- `"type": "line"` - Line charts
- `"type": "bar"` - Bar charts
- `"type": "pie"` - Pie charts
- `"type": "scatter"` - Scatter plots

**Chart Data Best Practices:**
1. Calculate all values before creating chart structure
2. Convert boolean results to integers: `int(value)` gives 0 or 1
3. Replace None with 0 or appropriate default: `value if value is not None else 0`
4. Use list comprehensions to ensure all data is literal values
5. Test with `json.dumps()` before writing - it will fail on non-serializable data

For full ECharts documentation, visit: https://echarts.apache.org/en/option.html

## Example: Simple Knapsack Problem

This example demonstrates preferred naming: single letters with clear documentation.

```hlpl
model knapsack
set I = {1, 2, 3, 4, 5}                        # Items
const v = {0.5, 1, 2.5, 0.1, 6.0}, forall i in I  # Value of item i
const w = {3, 4, 5, 4.5, 8.0}, forall i in I      # Weight of item i
bin x, forall i in I                           # 1 if item i is selected, 0 otherwise
max sum_{i in I}{v_{i} * x_{i}}                # Maximize total value
constr sum_{i in I}{w_{i} * x_{i}} <= 15       # Weight capacity constraint
end

import elytica

def main():
    elytica.init_model("knapsack")
    elytica.run_model("knapsack")

    for i in range(1,6):
        vname = "x" + str(i)
        val = elytica.get_variable_value("knapsack", vname)
        print(vname, val)

    elytica.write_results(str(elytica.get_best_primal_bound("knapsack")))
    return 0
```

## Example: Knapsack with Chart Visualization (Optional)

This example demonstrates preferred naming with clear documentation and OPTIONAL chart generation.
**Only create charts when specifically requested by the user.**

**Important**: Chart data uses int(val) to convert to 0/1 instead of True/False.

```hlpl
model knapsack
set I = {1, 2, 3, 4, 5}                        # Items
const v = {0.5, 1, 2.5, 0.1, 6.0}, forall i in I  # Value of item i
const w = {3, 4, 5, 4.5, 8.0}, forall i in I      # Weight of item i
bin x, forall i in I                           # 1 if item i is selected, 0 otherwise
max sum_{i in I}{v_{i} * x_{i}}                # Maximize total value
constr sum_{i in I}{w_{i} * x_{i}} <= 15       # Weight capacity constraint
end

import elytica
import json

def main():
    elytica.init_model("knapsack")
    elytica.run_model("knapsack")

    # Collect results - calculate all values beforehand
    items = []
    selected = []
    values = []
    weights = []

    # Define data arrays
    value_data = [0.5, 1, 2.5, 0.1, 6.0]
    weight_data = [3, 4, 5, 4.5, 8.0]

    for i in range(1, 6):
        vname = "x" + str(i)
        val = elytica.get_variable_value("knapsack", vname)
        items.append("Item " + str(i))
        # CRITICAL: Use int(val) to get 0 or 1, NOT boolean True/False
        selected.append(int(val))
        values.append(value_data[i-1])
        weights.append(weight_data[i-1])

    # Create chart showing selected items
    # All data is pre-calculated - no None, True/False, or function references
    chart = {
        "title": {"text": "Knapsack Solution"},
        "tooltip": {},
        "legend": {"data": ["Selected", "Value", "Weight"]},
        "xAxis": {
            "type": "category",
            "data": items  # List of strings
        },
        "yAxis": {
            "type": "value"
        },
        "series": [
            {
                "name": "Selected",
                "data": selected,  # List of 0/1 integers (not True/False)
                "type": "bar",
                "itemStyle": {"color": "#5470c6"}
            },
            {
                "name": "Value",
                "data": values,  # List of floats
                "type": "line",
                "itemStyle": {"color": "#91cc75"}
            },
            {
                "name": "Weight",
                "data": weights,  # List of floats
                "type": "line",
                "itemStyle": {"color": "#fac858"}
            }
        ]
    }

    # Write results with chart
    obj_value = elytica.get_best_primal_bound("knapsack")
    elytica.write_results(json.dumps({
        "objective": obj_value,
        "chart": chart
    }))

    return 0
```

## Available Solvers

- CPLEX (commercial, high-performance)
- CoinOR/CBC (open-source)
- Gurobi (commercial, high-performance)
- HiGHS (open-source)
- SCIP (open-source)

## MIP/LP Modelling Language Syntax Rules Summary

1. **Constraint Operators**: ONLY `=`, `>=`, `<=` are allowed (no `<`, `>`, `!=`)

2. **Summation Format**: Always use `sum_{index in SET}{expression}` with curly braces and an expression
   - INVALID: `sum_{i in I}[]` or `sum_{i in I}()`
   - VALID: `sum_{i in I}{x_{i}}`

3. **Grouping**: Use `[]` for grouping expressions, NOT `()` (parentheses only for function calls)

4. **No Programmatic Operators**: Cannot use `? :`, `==`, `!=` in mathematical expressions
   - Use indicator constants defined in Python instead
   - Use `setminus {}` for set operations

5. **Data Loading (CRITICAL)**:
   - PREFER loading sets and constants from functions over hardcoding
   - Function-based: `set I = getItems()`, `const c = getCosts(), forall i in I`
   - Hardcoding is acceptable only for small examples/demonstrations
   - Best practice: Load `data.json` in Python and use functions to extract data

6. **Naming Conventions (CRITICAL)**:
   - MUST NOT contain underscores in names (underscores ONLY for indexing: `x_{i}`, `v_{i,j}`).
     `_` is the subscript operator and its braces are optional for one index, so `x_i` is read as
     `x_{i}` and a name carrying one never registers. Interpreter-verified for sets, constants and
     variables; the three diagnostics it produces are listed under CRITICAL SYNTAX RESTRICTIONS
   - **The model name itself is exempt**: `model shortest_path` is valid, and several of the
     provided examples use one. The rule exists so a name cannot be confused with subscript
     notation, and a model name never appears in an indexed expression.
   - PREFER single letters: I, J, K, T, x, y, z, c, v, w, f, q
   - PREFER Greek letters: alpha, beta, gamma, lambda, mu, sigma, epsilon, theta, pi, rho
   - ALWAYS document what each variable/constant/set represents in comments
   - Mathematical readability: `x_{i}` is more readable than `itemselection_{i}`
   - Valid names: `x`, `lambda`, `epsilon`, `c`, `I`, `T`
   - Less preferred (but valid): `cost`, `flow`, `NODES`, `selected`
   - Invalid: `x_var`, `max_cost`, `flow_rate`, `TIME_PERIODS`

7. **Return Code**: Always return 0 for success, non-zero for failure

8. **Semicolons**: Not required at the end of statements (see examples)



---

# Chart generation — rules and constraints

HLPL scripts can OPTIONALLY generate interactive visualizations using ECharts when specifically requested. Charts appear automatically in tutorial interfaces when your script writes chart configurations.

Path: `docs/charts/intro`

# Generating Interactive Charts in HLPL Scripts

HLPL scripts can OPTIONALLY generate interactive visualizations using ECharts when specifically requested.
Charts appear automatically in tutorial interfaces when your script writes chart configurations.

**Note**: Only create charts when the user specifically requests them.

## CRITICAL REQUIREMENTS

Charts MUST be fully JSON serializable:
- Use integers **0 and 1** instead of boolean **True/False**
- NO **None** values - calculate all values beforehand
- NO function references - only literal values (strings, numbers, lists, dicts)
- NO **null** values - use 0 or empty string instead
- Use `json.dumps()` to ensure proper serialization

## ECharts Documentation

For complete chart options and examples, visit:
**https://echarts.apache.org/examples/en/index.html** - Interactive examples gallery
**https://echarts.apache.org/en/option.html** - Full API reference

You can browse examples and copy the configuration (option) to your HLPL script.

## Basic Syntax

```python
import elytica
import json  # REQUIRED for json.dumps()

def main():
    # ... your model code ...

    # Create chart configuration (ECharts format - Python dict)
    # CRITICAL: All values must be JSON serializable - no True/False/None
    chart = {
        "title": {"text": "Chart Title"},
        "xAxis": {"type": "category", "data": ["A", "B", "C"]},
        "yAxis": {"type": "value"},
        "series": [{"data": [1, 2, 3], "type": "bar"}]  # Good: literal integers
    }

    # REQUIRED: Convert to JSON and write results
    elytica.write_results(json.dumps({"chart": chart}))
    return 0
```

**Key Points:**
- Always `import json` at the top of your script
- Chart configuration is a Python dictionary
- **CRITICAL**: Use 0/1 not True/False, no None values
- Use `json.dumps()` to convert to JSON before writing
- Charts render automatically in tutorial interfaces



---

# Line charts

Line charts are ideal for showing trends over time or continuous data.

Path: `docs/charts/line`


## Line Chart Example

Line charts are ideal for showing trends over time or continuous data.

```python
import elytica
import json

def main():
    # ... your optimization code ...

    # Calculate all data beforehand
    chart = {
        "title": {"text": "Variable Values Over Time"},
        "tooltip": {
            "trigger": "axis"
        },
        "xAxis": {
            "type": "category",
            "data": ["Iter 1", "Iter 2", "Iter 3", "Iter 4", "Iter 5"]
        },
        "yAxis": {
            "type": "value"
        },
        "series": [
            {
                "name": "Objective Value",
                "data": [120, 200, 150, 280, 300],  # List of numbers
                "type": "line",
                "smooth": 1  # Use 1 not True (0 for False)
            }
        ]
    }

    elytica.write_results(json.dumps({"chart": chart}))
    return 0
```

Multiple lines:

```python
chart = {
    "title": {"text": "Comparison"},
    "legend": {"data": ["Series 1", "Series 2"]},
    "xAxis": {"type": "category", "data": ["A", "B", "C", "D", "E"]},
    "yAxis": {"type": "value"},
    "series": [
        {
            "name": "Series 1",
            "data": [3, 4, 5, 6, 4],
            "type": "line"
        },
        {
            "name": "Series 2",
            "data": [1, 2, 1, 3, 1],
            "type": "line"
        }
    ]
}
```



---

# Bar charts

Bar charts are perfect for comparing discrete categories or showing binary variables.

Path: `docs/charts/bar`


## Bar Chart Example

Bar charts are perfect for comparing discrete categories or showing binary variables.

```python
import elytica
import json

def main():
    # ... collect variable values ...

    # Example: Showing which items were selected (0 or 1)
    # Use int(val) to convert boolean to 0/1
    items = ["Item 1", "Item 2", "Item 3", "Item 4", "Item 5"]
    selected = [1, 0, 1, 1, 0]  # Good: integers not True/False

    chart = {
        "title": {"text": "Selected Items"},
        "tooltip": {},
        "xAxis": {
            "type": "category",
            "data": items
        },
        "yAxis": {
            "type": "value"
        },
        "series": [
            {
                "name": "Selected",
                "data": selected,
                "type": "bar",
                "itemStyle": {"color": "#5470c6"}
            }
        ]
    }

    elytica.write_results(json.dumps({"chart": chart}))
    return 0
```

Grouped bar chart:

```python
chart = {
    "title": {"text": "Resource Allocation"},
    "legend": {"data": ["Allocated", "Available"]},
    "xAxis": {"type": "category", "data": ["Resource 1", "Resource 2", "Resource 3"]},
    "yAxis": {"type": "value"},
    "series": [
        {"name": "Allocated", "data": [8, 5, 7], "type": "bar"},
        {"name": "Available", "data": [10, 10, 10], "type": "bar"}
    ]
}
```



---

# Pie charts

Pie charts show proportions and percentages.

Path: `docs/charts/pie`


## Pie Chart Example

Pie charts show proportions and percentages.

```python
import elytica
import json

def main():
    # ... analyze solution ...

    chart = {
        "title": {"text": "Resource Distribution"},
        "tooltip": {
            "trigger": "item"
        },
        "legend": {
            "orient": "vertical",
            "left": "left"
        },
        "series": [
            {
                "name": "Resources",
                "type": "pie",
                "radius": "50%",
                "data": [
                    {"value": 30, "name": "Type A"},
                    {"value": 25, "name": "Type B"},
                    {"value": 45, "name": "Type C"}
                ]
            }
        ]
    }

    elytica.write_results(json.dumps({"chart": chart}))
    return 0
```



---

# Scatter plots

Scatter plots show relationships between variables.

Path: `docs/charts/scatter`


## Scatter Plot Example

Scatter plots show relationships between variables.

```python
import elytica
import json

def main():
    # ... collect data points ...

    chart = {
        "title": {"text": "Variable Relationship"},
        "xAxis": {},
        "yAxis": {},
        "series": [
            {
                "type": "scatter",
                "data": [
                    [10, 8.04],
                    [8, 6.95],
                    [13, 7.58],
                    [9, 8.81],
                    [11, 8.33]
                ]
            }
        ]
    }

    elytica.write_results(json.dumps({"chart": chart}))
    return 0
```



---

# Multiple charts in one result

Display multiple visualizations by using the "charts" key (array):

Path: `docs/charts/multiple`


## Multiple Charts

Display multiple visualizations by using the "charts" key (array):

```python
import elytica
import json

def main():
    # ... solve optimization problem ...

    # First chart: Selected items
    chart1 = {
        "title": {"text": "Decision Variables"},
        "xAxis": {"type": "category", "data": ["x1", "x2", "x3", "x4", "x5"]},
        "yAxis": {"type": "value"},
        "series": [{"data": [1, 0, 1, 1, 0], "type": "bar"}]
    }

    # Second chart: Objective value progression
    chart2 = {
        "title": {"text": "Convergence"},
        "xAxis": {"type": "category", "data": ["Start", "Iter 1", "Iter 2", "Final"]},
        "yAxis": {"type": "value"},
        "series": [{"data": [100, 150, 180, 200], "type": "line"}]
    }

    # Write multiple charts
    elytica.write_results(json.dumps({"charts": [chart1, chart2]}))
    return 0
```



---

# Complete worked example with charts

Path: `docs/charts/complete`


## Complete Knapsack Example

```python
import elytica
import json

def main():
    elytica.init_model("knapsack")
    elytica.run_model("knapsack")

    # Collect results
    items = []
    selected = []
    values = [0.5, 1, 2.5, 0.1, 6.0]
    weights = [3, 4, 5, 4.5, 8.0]

    for i in range(1, 6):
        vname = "x" + str(i)
        val = elytica.get_variable_value("knapsack", vname)
        items.append("Item " + str(i))  # String concatenation
        selected.append(int(val))  # CRITICAL: int(val) gives 0 or 1, not True/False

    # Create comprehensive visualization
    chart = {
        "title": {"text": "Knapsack Solution"},
        "tooltip": {"trigger": "axis"},
        "legend": {"data": ["Selected (0/1)", "Value", "Weight"]},
        "xAxis": {
            "type": "category",
            "data": items
        },
        "yAxis": {
            "type": "value"
        },
        "series": [
            {
                "name": "Selected (0/1)",
                "data": selected,
                "type": "bar",
                "itemStyle": {"color": "#5470c6"}
            },
            {
                "name": "Value",
                "data": values,
                "type": "line",
                "itemStyle": {"color": "#91cc75"}
            },
            {
                "name": "Weight",
                "data": weights,
                "type": "line",
                "itemStyle": {"color": "#fac858"}
            }
        ]
    }

    # Include additional data in results
    obj_value = elytica.get_best_primal_bound("knapsack")
    results = {
        "objective_value": obj_value,
        "chart": chart
    }

    elytica.write_results(json.dumps(results))
    return 0
```



---

# ECharts reference and troubleshooting

Path: `docs/charts/reference`


## Quick Reference

### Chart Types
- `"type": "line"` - Line chart (trends, time series)
- `"type": "bar"` - Bar chart (comparisons, binary variables)
- `"type": "pie"` - Pie chart (proportions, distributions)
- `"type": "scatter"` - Scatter plot (relationships, correlations)

### Common Options
```python
{
    "title": {"text": "Title"},           # Chart title
    "tooltip": {},                         # Show values on hover
    "legend": {"data": ["Series 1"]},     # Legend for multiple series
    "xAxis": {
        "type": "category",                # Or "value" for continuous
        "data": ["A", "B", "C"]           # Category labels
    },
    "yAxis": {"type": "value"},           # Numeric axis
    "series": [...]                        # Data series (see examples above)
}
```

### Color Customization
```python
"itemStyle": {"color": "#5470c6"}  # Hex color code
```

### Need More Options?

Browse **hundreds of chart examples** with live previews:
https://echarts.apache.org/examples/en/index.html

Each example shows:
- Interactive preview
- Full configuration code (copy the "option" object)
- Customization options

**API Reference** (all available options):
https://echarts.apache.org/en/option.html

**Tips for Using ECharts Examples:**
1. Find an example you like on echarts.apache.org/examples
2. Click "View Code" to see the configuration
3. Copy the `option` object (the chart configuration)
4. Convert it to Python dictionary format
5. **CRITICAL**: When converting JavaScript to Python:
   - Replace `true` with `1` (not True)
   - Replace `false` with `0` (not False)
   - Replace `null` with `0` or `""` (not None)
   - Remove function references - calculate values beforehand
6. Use `json.dumps()` to write it to results

**Common Conversion Mistakes:**
```python
# WRONG - JavaScript converted incorrectly
"smooth": True        # Will cause JSON error
"show": False         # Will cause JSON error
"value": None         # Will cause JSON error

# CORRECT - Proper Python for JSON
"smooth": 1           # Use 1 instead of True
"show": 0             # Use 0 instead of False
"value": 0            # Use 0 or "" instead of None
```



---

# Facility Location Problem Example

Complete facility location optimization problem demonstrating multiple facility site selection with capacity constraints and customer assignments.

Path: `examples/facility-location`

```
# Facility Location Problem
# Selects which facilities to open and assigns customers to facilities
# to minimize total cost while respecting capacity constraints

model facility_location
set L = {1, 2, 3, 4, 5}                                          # Locations (customers)
set F = {1, 2, 3}                                                # Facilities (potential sites)

const c = {{4, 2, 9},
           {1, 3, 3},
           {7, 4, 5},
           {3, 2, 1},
           {3, 1, 7}}, forall i in L, forall j in F             # Cost to serve customer i from facility j

const f = {100, 200, 300}, forall j in F                        # Fixed cost to open facility j
const d = {5, 11, 9, 7, 18}, forall i in L                      # Demand of customer i
const k = {20, 15, 25}, forall j in F                           # Capacity of facility j

bin x, forall i in L, forall j in F                             # 1 if customer i served by facility j
bin y, forall j in F                                            # 1 if facility j is opened

# Objective: Minimize total cost (assignment + fixed costs)
min sum_{i in L}{sum_{j in F}{c_{i,j} * x_{i,j}}} + sum_{j in F}{f_{j} * y_{j}}

# Each customer must be assigned to exactly one facility
constr sum_{j in F}{x_{i,j}} = 1, forall i in L

# Can only assign customer to an open facility
constr x_{i,j} <= y_{j}, forall i in L, forall j in F

# Facility capacity constraint
constr sum_{i in L}{d_{i} * x_{i,j}} <= k_{j} * y_{j}, forall j in F
end

import elytica
import json

def main():
    elytica.init_model("facility_location")
    elytica.run_model("facility_location")

    # Get sets from model
    L = elytica.get_model_set("facility_location", "L")
    F = elytica.get_model_set("facility_location", "F")

    # Collect solution
    print("\n" + "="*60)
    print("FACILITY LOCATION SOLUTION")
    print("="*60)

    opened_facilities = []
    assignments = {}

    # Check which facilities are opened
    for j in F:
        y_val = elytica.get_variable_value("facility_location", f"y{j}")
        if y_val > 0.5:
            opened_facilities.append(j)
            assignments[j] = []

    print(f"\nOpened Facilities: {opened_facilities}")
    print("\n" + "-"*60)
    print("Customer Assignments:")
    print("-"*60)

    # Get customer assignments
    for j in opened_facilities:
        print(f"\nFacility {j}:")
        for i in L:
            x_val = elytica.get_variable_value("facility_location", f"x{i},{j}")
            if x_val > 0.5:
                assignments[j].append(i)
                print(f"  Customer {i}")

    # Get objective value
    obj_value = elytica.get_best_primal_bound("facility_location")
    print("\n" + "-"*60)
    print(f"Total Cost: {obj_value:.2f}")
    print("="*60)

    # Prepare results for output
    results = {
        "objective_value": obj_value,
        "opened_facilities": opened_facilities,
        "assignments": assignments
    }

    elytica.write_results(json.dumps(results, indent=2))

    return 0
```


---

# 0/1 Knapsack Example

The smallest complete model, and the one to start from: a set and indexed constants loaded from Python functions (lambdas and defs), a single-value constant, and results written with write_results. Runs as is with run.mjs.

Path: `examples/knapsack`

```
# 0/1 Knapsack Problem
# Choose which items to pack to maximise total value without exceeding the
# bag's capacity. The smallest complete model that loads its data from Python:
# a set and indexed constants from functions, plus a single-value constant.
#
# Runs as is: `node run.mjs knapsack.hlpl` with the interpreter from
# get_interpreter prints the packed items and writes ./results.

model knapsack
set I = getItems()                             # Items
const v = getValues(), forall i in I           # Value of item i
const w = getWeights(), forall i in I          # Weight of item i
const C = 12                                   # Capacity of the bag
bin x, forall i in I                           # 1 if item i is packed, 0 otherwise

max sum_{i in I}{v_{i} * x_{i}}                # Maximise the value packed
constr sum_{i in I}{w_{i} * x_{i}} <= C        # Stay within capacity
end

import elytica
import json

# Data functions: a set returns a list of integers, an indexed constant a dict
# keyed by index. Lambdas and defs both work.
ITEMS = {1: (10, 5), 2: (40, 4), 3: (30, 6), 4: (50, 3), 5: (35, 7)}  # item: (value, weight)

getItems = lambda: list(ITEMS)
getValues = lambda: {i: value for i, (value, _) in ITEMS.items()}

def getWeights():
    return {i: weight for i, (_, weight) in ITEMS.items()}

def main():
    elytica.init_model("knapsack")
    elytica.run_model("knapsack")

    packed = [i for i in ITEMS if elytica.get_variable_value("knapsack", f"x{i}") > 0.5]
    value = elytica.get_best_primal_bound("knapsack")

    print(f"Packed items {packed}, total value {value:g}")
    elytica.write_results(json.dumps({"packed": packed, "value": value}))
    return 0
```


---

# MMORPG Skill Rotation Optimization Example

Complete MMORPG skill rotation optimizer demonstrating temporal sequencing, resource management (energy/combo points), finishing move constraints, and damage maximization with CSV data loading. Reads rogue.csv (not included) with pandas, so it does not run as is.

Path: `examples/mmorpg-rotation`

```
# MMORPG Skill Rotation Optimizer (Rogue Class)
# Optimizes skill rotation to maximize total damage output
# Subject to energy/combo point resource constraints and ability cooldowns
# Demonstrates temporal sequencing with time-indexed variables and resource tracking

model max_damage
set S = getSkills()                                         # Available skills
set T = getTime()                                           # Time steps in rotation
set F = {0}                                                 # Singleton set for constant indexing
set G = {0, 1}                                              # Energy level options

# Continuous variables for resource tracking
var 0 <= e <= 100, forall t in T                            # Energy at time t
var 0 <= k <= 5, forall t in T                              # Combo points at time t
var 0 <= pi <= 100, forall t in T                           # Energy spent at time t
var 0 <= gamma <= 5, forall t in T                          # Combo points spent at time t

# Skill properties loaded from CSV
const d = getDamage(), forall s in S                        # Base damage of skill s
const epsilon = getEnergy(), forall s in S                  # Energy cost/gain of skill s (negative = cost)
const delta = {100, 150}, forall g in G                     # Starting energy levels
const kappa = getComboPoints(), forall s in S               # Combo points generated/consumed by skill s
const tau = getCooldowns(), forall s in S                   # Cooldown duration of skill s
const rho = {0.2}, forall f in F                            # Energy regeneration rate
const r = {10}, forall f in F                               # Energy regeneration per tick
const M = {323}, forall f in F                              # Big-M constant for logical constraints
const psi = getFinishingMove(), forall s in S               # 1 if skill is finishing move, 0 otherwise

# Decision variables
bin x forall t in T, forall s in S                          # 1 if skill s is used at time t
bin y, forall t in T, forall s in S                         # Auxiliary variable for constraints

# Objective: Maximize total damage over the rotation
max sum_{s in S}{sum_{t in T}{x_{t,s} * d_{s}}}

# Energy balance constraint (for t > 0)
# Energy at time t = energy at t-1 + energy from skills - energy spent + regeneration
constr e_{t} = e_{t-1} + sum_{s in S}{epsilon_{s} * x_{t,s}} - pi_{t} + r_{0} * rho_{0},
  forall t in T setminus {0}

# Combo point balance constraint (for t > 0)
# Combo points at time t = combo points at t-1 + points generated - points consumed
constr k_{t} = k_{t-1} + sum_{s in S}{kappa_{s} * x_{t,s}} - gamma_{t},
  forall t in T setminus {0}

# Exactly one skill must be used at each time step
constr sum_{s in S}{x_{t,s}} = 1, forall t in T

# Finishing move constraint: If finishing move is used, must have required combo points
# This ensures that when a finishing move s is selected at time t, the combo points k_{t}
# must be at least equal to the combo points consumed by that skill
constr -x_{t,s} * kappa_{s} * psi_{s} + M_{0} - M_{0} * x_{t,s} >= k_{t} * psi_{s},
  forall s in S, forall t in T

# Initial combo points constraint (at t=0)
# Set initial combo points based on skills used at start
constr k_{t} = sum_{s in S}{kappa_{s} * x_{t,s}},
  forall t in T bigcap {0}

# Initial energy constraint (at t=0)
# Set starting energy level plus energy from first skill
constr e_{t} = delta_{0} + sum_{s in S}{epsilon_{s} * x_{t,s}},
  forall t in T bigcap {0}

end

import elytica
import pandas
import json

# Global variables for model data
data = None
steps = None

def h(t, T):
    """Helper function to generate time range from t to T"""
    return json.dumps([i for i in range(int(t), int(T))])

def getSkills():
    """Return list of skill IDs (indices into data frame)"""
    return json.dumps([i for i in range(0, len(data["Name"].to_list()))])

def getDamage():
    """Return base damage values for all skills"""
    return json.dumps(data["BaseDamage"].to_list())

def getEnergy():
    """Return energy cost/gain for all skills (negative values = cost)"""
    return json.dumps(data["Energy"].to_list())

def getComboPoints():
    """Return combo points generated/consumed by each skill (negative = consumed)"""
    return json.dumps(data["ComboPoints"].to_list())

def getCooldowns():
    """Return cooldown duration for each skill"""
    return json.dumps(data["Cooldown"].to_list())

def getFinishingMove():
    """Return indicator: 1 if skill is a finishing move, 0 otherwise"""
    return json.dumps(data["FinishingMove"].to_list())

def getTime():
    """Return list of time steps in the rotation"""
    return json.dumps([i for i in range(0, steps)])

def main():
    global data, steps

    # Configuration
    steps = 5  # Number of time steps to optimize

    # Load skill data from CSV
    data = pandas.read_csv(
        "rogue.csv",
        usecols=["Name", "BaseDamage", "ComboPoints", "Energy", "Cooldown",
                 "FinishingMove", "Visible", "IncreasedDamage", "DurationIncreasedDamage"]
    )

    # Initialize and solve the optimization model
    elytica.init_model("max_damage")
    elytica.run_model("max_damage")

    print("\n" + "="*70)
    print("MMORPG SKILL ROTATION OPTIMIZATION SOLUTION")
    print("="*70)
    print("\nOptimized Rotation:")
    print("-"*70)

    # Collect and display the optimal rotation
    rotation = []
    for t in range(0, steps):
        energy = elytica.get_variable_value("max_damage", f"e{t}")
        combopoints = elytica.get_variable_value("max_damage", f"k{t}")

        for s in range(0, len(data["Name"].to_list())):
            val = elytica.get_variable_value("max_damage", f"x{t},{s}")
            if val > 0:
                skill_name = data["Name"][s]
                damage = data["BaseDamage"][s]
                time_sec = t * 0.2  # Convert time step to seconds (assuming 0.2s GCD)

                rotation.append({
                    "time_step": t,
                    "time_sec": time_sec,
                    "skill": skill_name,
                    "damage": damage,
                    "energy": energy,
                    "combo_points": combopoints
                })

                print(f"  t={t} ({time_sec:.1f}s): {skill_name:20s} | "
                      f"Damage={damage:5.0f} | Energy={energy:5.1f} | CP={combopoints:.0f}")

    # Get objective value (total damage)
    total_damage = elytica.get_best_primal_bound("max_damage")

    print("-"*70)
    print(f"Total Damage: {total_damage:.2f}")
    print("="*70)

    # Prepare results for output
    results = {
        "objective_value": total_damage,
        "rotation": rotation,
        "time_steps": steps
    }

    elytica.write_results(json.dumps(results, indent=2))

    return 0


# Expected CSV file format (rogue.csv):
#
# Name,BaseDamage,ComboPoints,Energy,Cooldown,FinishingMove,Visible,IncreasedDamage,DurationIncreasedDamage
# Eviscerate1,495,-1,-35,0,1,1,0,0
# Eviscerate2,990,-2,-35,0,1,1,0,0
# Eviscerate3,1485,-3,-35,0,1,1,0,0
# Eviscerate4,1980,-4,-35,0,1,1,0,0
# Eviscerate5,2475,-5,-35,0,1,1,0,0
# MarkedForDeath,0,5,0,30,0,1,0,0
# Backstab,956,1,-35,0,0,1,0,0
# AutoAttack,7,0,0,1.8,0,1,0,0
# Idle,0,0,0,0,0,1,0,0
# SymbolsOfDeath,0,0,40,30,0,1,0.15,10
#
# Field descriptions:
# - Name: Skill name
# - BaseDamage: Base damage dealt by the skill
# - ComboPoints: Combo points generated (positive) or consumed (negative)
# - Energy: Energy cost (negative) or gain (positive)
# - Cooldown: Cooldown duration in seconds
# - FinishingMove: 1 if finishing move (requires combo points), 0 otherwise
# - Visible: 1 if skill should be displayed in UI
# - IncreasedDamage: Damage multiplier buff applied by skill
# - DurationIncreasedDamage: Duration of damage buff in seconds
```


---

# Office Allocation & Scheduling Example

Complete office allocation and time slot scheduling problem demonstrating preference-based assignment, bid optimization, temporal constraints, and advanced set functions with dynamic exclusion ranges.

Path: `examples/office-allocation`

```
# Office Allocation and Time Slot Scheduling
# Assigns staff members to offices and time slots based on their preferences (bids)
# Subject to capacity, duration, and scheduling constraints
# Demonstrates advanced set functions with dynamic exclusion ranges

model office_allocation
set D = loadDays()                                          # Days in the planning period
set T = loadTimes()                                         # Available time slots
set O = loadOffices()                                       # Available offices
set S = loadStaff()                                         # Staff members
set L = loadLots()                                          # Duration options (time blocks)

# Staff preferences and requirements
const r = loadDurations(), forall s in S, forall d in D     # Required duration for staff s on day d
const b = loadBids(), forall s in S, forall d in D, forall l in L  # Bid value for duration l

# Decision variables
bin x, forall s in S, forall d in D forall o in O, forall t in T   # 1 if staff s uses office o at time t on day d
var 0 <= y <= 1, forall s in S, forall d in D, forall o in O, forall l in L  # 1 if staff s is assigned duration l in office o on day d

# Objective: Maximize total satisfaction based on bid values
max sum_{s in S}{sum_{d in D}{sum_{o in O}{sum_{l in L}{b_{s,d,l} * y_{s,d,o,l}}}}}

# Each staff member can be assigned at most one duration per office per day
constr sum_{l in L}{y_{s,d,o,l}} <= 1, forall s in S, forall d in D, forall o in O

# Each staff member can use at most one office at any given time
constr sum_{o in O}{x_{s,d,o,t}} <= 1, forall s in S, forall d in D, forall t in T

# Each office can be used by at most one staff member at any given time
constr sum_{s in S}{x_{s,d,o,t}} <= 1, forall d in D, forall t in T, forall o in O

# Total time slots assigned cannot exceed required duration
constr sum_{o in O}{sum_{t in T}{x_{s,d,o,t}}} <= r_{s,d}, forall s in S, forall d in D

# Link time slot assignments to duration assignments
# If assigned duration l, must use exactly r * l time slots
constr sum_{o in O}{sum_{t in T}{x_{s,d,o,t}}} <= sum_{o in O}{sum_{l in L}{r_{s,d} * y_{s,d,o,l}}}, forall s in S, forall d in D

# Duration block constraint with dynamic exclusion range
# If assigned duration l in office o, must occupy at least l consecutive time slots
# Uses set function g() to exclude time slots outside the valid range
constr sum_{k in T setminus {g(l, s, d, |T|)}}{x_{s,d,o,k}} >= l * y_{s,d,o,l},
  forall s in S, forall d in D, forall o in O, forall l in L

end

import elytica
import json
import random

# Global data dictionary
data = None

def g(r, s, d, T):
    """
    Set function: Returns time slots that are OUTSIDE the valid window
    for a staff member's scheduled block.

    This is used with 'setminus' to constrain assignments to valid time slots.
    For a duration r starting at time t, valid slots are [t, t+r-1].
    This function returns all OTHER slots to exclude them.
    """
    result = []
    t = data["starts"][int(s)][int(d)]  # Get start time for staff s on day d

    for j in range(1, int(T) + 1):
        k = int(t) + int(r) - 1  # Calculate end time of block
        if j < int(t) or j > k:  # If outside valid range
            result.append(j)

    return result

def defineStarts():
    """
    Generate random start times for each staff member on each day.
    Returns nested dictionary: {staff_id: {day_id: start_time}}
    """
    results = {}
    for staff in data["staff"]:
        result = {}
        for day in data["day"]:
            result[day] = random.randint(1, len(data["times"]))
        results[staff] = result
    return results

def loadDurations():
    """
    Generate random duration requirements for each staff member on each day.
    Duration is expressed in number of time slots needed.
    """
    results = []
    for staff in data["staff"]:
        result = []
        for day in data["day"]:
            result.append(random.randint(1, len(data["lots"])))
        results.append(result)
    return json.dumps(results)

def loadBids():
    """
    Generate bid values for each staff member's preference for different duration blocks.
    Higher bids indicate stronger preference for longer blocks.
    """
    results = []
    for staff in data["staff"]:
        result = []
        for day in data["day"]:
            lot_result = []
            for lot in data["lots"]:
                # Bid value increases with lot size plus random factor
                lot_result.append(random.uniform(1.0, 2.0) * lot)
            result.append(lot_result)
        results.append(result)
    return json.dumps(results)

def loadStaff():
    """Return list of staff member IDs"""
    return json.dumps(data["staff"])

def loadDays():
    """Return list of day IDs"""
    return json.dumps(data["day"])

def loadTimes():
    """Return list of time slot IDs"""
    return json.dumps(data["times"])

def loadOffices():
    """Return list of office IDs"""
    return json.dumps(data["offices"])

def loadLots():
    """Return list of duration lot sizes"""
    return json.dumps(data["lots"])

def getResults():
    """
    Extract solution and format for visualization.
    Returns list of assignments with day, office, time, staff name, and color.
    """
    results = []
    for s in data["staff"]:
        for d in data["day"]:
            for o in data["offices"]:
                for t in data["times"]:
                    xname = "x" + ','.join([str(z) for z in [s, d, o, t]])
                    xval = elytica.get_variable_value("office_allocation", xname)

                    if xval > 0.5:
                        # Generate unique color for each staff member
                        hs = hash(str(s))
                        hsr = hs % 256
                        hsg = (hs >> 8) % 256
                        hsb = (hs >> 16) % 256
                        col = '#%02x%02x%02x' % (hsr, hsg, hsb)

                        entry = {
                            "day": d,
                            "office": o,
                            "time": t,
                            "staff_name": data["names"][s - 1],
                            "staff_id": s,
                            "color": col
                        }
                        results.append(entry)
    return results

def getTimeframes():
    """Define time slot labels for visualization"""
    return [
        {"id": 0, "name": "Time", "color": "#defeee"},
        {"id": 1, "name": "10:00 - 11:00", "color": "#d0f0e0"},
        {"id": 2, "name": "11:00 - 12:00", "color": "#d0f0e0"},
        {"id": 3, "name": "12:00 - 13:00", "color": "#d0f0e0"},
        {"id": 4, "name": "13:00 - 14:00", "color": "#d0f0e0"},
        {"id": 5, "name": "14:00 - 15:00", "color": "#d0f0e0"},
        {"id": 6, "name": "15:00 - 16:00", "color": "#d0f0e0"},
        {"id": 7, "name": "16:00 - 17:00", "color": "#d0f0e0"}
    ]

def main():
    global data

    # Initialize problem data
    data = {
        "staff": [i for i in range(1, 5)],          # 4 staff members
        "day": [1, 2, 3, 4, 5],                     # 5 days
        "lots": [1, 2, 3, 4],                       # Duration options: 1-4 time slots
        "offices": [i for i in range(1, 5)],        # 4 offices
        "times": [1, 2, 3, 4, 5, 6, 7],            # 7 time slots per day
        "names": [f"Staff_{i}" for i in range(1, 5)],  # Staff names
        "starts": {}
    }

    # Generate random start times
    data["starts"] = defineStarts()

    # Initialize and solve the model
    elytica.init_model("office_allocation")
    elytica.set_gap_limit("office_allocation", 0.5)  # Allow 50% optimality gap for faster solve
    elytica.run_model("office_allocation")

    print("\n" + "="*70)
    print("OFFICE ALLOCATION SOLUTION")
    print("="*70)

    # Get and display results
    floor_assignments = getResults()
    timeframes = getTimeframes()

    print(f"\nTotal Assignments: {len(floor_assignments)}")
    print("\nSample Assignments:")
    print("-"*70)

    # Display first 10 assignments
    for assignment in floor_assignments[:10]:
        print(f"  Day {assignment['day']}, Office {assignment['office']}, "
              f"Time {assignment['time']}: {assignment['staff_name']}")

    if len(floor_assignments) > 10:
        print(f"  ... and {len(floor_assignments) - 10} more assignments")

    # Get objective value
    obj_value = elytica.get_best_primal_bound("office_allocation")
    print("\n" + "-"*70)
    print(f"Total Satisfaction Score (Objective Value): {obj_value:.2f}")
    print("="*70)

    # Prepare results for output
    results = {
        "objective_value": obj_value,
        "floor": floor_assignments,
        "timeframes": timeframes,
        "summary": {
            "num_staff": len(data["staff"]),
            "num_days": len(data["day"]),
            "num_offices": len(data["offices"]),
            "num_time_slots": len(data["times"]),
            "total_assignments": len(floor_assignments)
        }
    }

    elytica.write_results(json.dumps(results, indent=2))

    # Optionally save the model for debugging
    # elytica.save_model("office_allocation")

    return 0
```


---

# Passive Optical Network (PON) Planning Example

Complete PON network design optimization demonstrating multi-commodity flow, splitter placement, capacity constraints, bidirectional arc generation, and network visualization with ECharts graph layout. Reads micronet.json (not included), so it does not run as is.

Path: `examples/pon-planning`

```
# Passive Optical Network (PON) Planning
# Optimizes placement of optical splitters and fiber connections
# to minimize total network cost while satisfying flow requirements
# Demonstrates multi-commodity flow with bidirectional arcs and capacity constraints

model pon
set S = loadSplitters()                                     # Potential splitter locations
set U = loadONUs()                                          # Optical Network Units (end users)
set C = loadCOs()                                           # Central Offices
set I = loadIntermediate()                                  # Intermediate nodes
set V = loadVertices()                                      # All vertices in network
set K = loadCommodities()                                   # Commodities (ONU and splitter flows)
set E = loadEdges()                                         # Undirected edges
set A = loadArcs()                                          # Directed arcs (bidirectional)

# Adjacency structure
set sigma(V) = loadIncomming()                              # Incoming arcs for each vertex
set delta(V) = loadOutgoing()                               # Outgoing arcs for each vertex

# Cost parameters
const c = loadNodeCosts(), forall v in V                    # Cost to install equipment at vertex v
const d = loadArcWeights(), forall a in A                   # Distance/cost weight for arc a
const t = 10.0                                              # Cost multiplier for fiber installation
const gamma = 1.0                                           # Cost per unit flow per distance
const kappa = 32                                            # Maximum capacity per splitter
const M = loadM()                                           # Big-M constant for logical constraints

# Decision variables
bin y, forall i in S                                        # 1 if splitter is installed at location i
int 0 <= N <= 8, forall i in S                              # Number of connections at splitter i
var 0 <= f <= 1, forall k in K, forall a in A              # Flow of commodity k on arc a
bin x, forall e in E                                        # 1 if edge e is selected for fiber

# Objective: Minimize total network cost (splitters + fiber + flow routing)
min sum_{s in S}{y_{s} * c_{s}} + sum_{e in E}{x_{e} * d_{e} * t} + sum_{k in K}{sum_{a in A}{f_{k, a} * d_{a} * gamma}}

# Flow conservation for ONUs: Each ONU generates -1 unit of its own commodity
constr sum_{k in U}{[sum_{a in delta(v)}{f_{k,a}} - sum_{a in sigma(v)}{f_{k,a}}]} = -1, forall v in U

# Flow conservation for splitters: Splitters aggregate N connections
constr sum_{k in U}{[sum_{a in delta(v)}{f_{k,a}} - sum_{a in sigma(v)}{f_{k,a}}]} = N_{v}, forall v in S

# Flow conservation for COs: Central offices are neutral for ONU flows
constr sum_{k in U}{[sum_{a in delta(v)}{f_{k,a}} - sum_{a in sigma(v)}{f_{k,a}}]} = 0, forall v in C

# Flow conservation for intermediate nodes: Pass-through for ONU flows
constr sum_{k in U}{[sum_{a in delta(v)}{f_{k,a}} - sum_{a in sigma(v)}{f_{k,a}}]} = 0, forall v in I

# Edge capacity constraint: Flow on both directions of edge limited by edge selection
constr sum_{k in K}{f_{k,e} + f_{k,e + |E|}} <= x_{e} * M, forall e in E

# Splitter capacity constraint: Number of connections limited by splitter capacity
constr N_{s} <= kappa * y_{s}, forall s in S

# Flow conservation for splitter commodity at splitters: Each installed splitter generates -1 unit
constr sum_{k in S}{[sum_{a in delta(v)}{f_{k,a}} - sum_{a in sigma(v)}{f_{k,a}}]} = -y_{v}, forall v in S

# Flow conservation for splitter commodity at COs: All splitter flows terminate at COs
constr sum_{k in S}{[sum_{a in delta(v)}{f_{k,a}} - sum_{a in sigma(v)}{f_{k,a}}]} = sum_{s in S}{y_{s}}, forall v in C

# Flow conservation for splitter commodity at ONUs: Pass-through
constr sum_{k in S}{[sum_{a in delta(v)}{f_{k,a}} - sum_{a in sigma(v)}{f_{k,a}}]} = 0, forall v in U

# Flow conservation for splitter commodity at intermediate nodes: Pass-through
constr sum_{k in S}{[sum_{a in delta(v)}{f_{k,a}} - sum_{a in sigma(v)}{f_{k,a}}]} = 0, forall v in I

end

import elytica
import json

# Load network topology from JSON file
file = open('micronet.json')
graph = json.load(file)

# Add node IDs for indexing
edges = [{**item, 'nid': index} for index, item in enumerate(graph["edges"])]
nodes = [{**item, 'nid': index} for index, item in enumerate(graph["nodes"])]

def loadSplitters():
    """Return IDs of potential splitter locations (triangle nodes)"""
    return [n['nid'] for n in nodes if n['type'] == 'triangle']

def loadONUs():
    """Return IDs of Optical Network Units (circle nodes)"""
    return [n['nid'] for n in nodes if n['type'] == 'circle']

def loadIntermediate():
    """Return IDs of intermediate routing nodes"""
    return [n['nid'] for n in nodes if n['type'] is None]

def loadCOs():
    """Return IDs of Central Offices (square nodes)"""
    return [n['nid'] for n in nodes if n['type'] == 'square']

def loadCommodities():
    """Commodities are flows from ONUs and splitters"""
    return loadONUs() + loadSplitters()

def loadVertices():
    """Return all vertex IDs"""
    return [n['nid'] for n in nodes]

def loadEdges():
    """Return all edge IDs"""
    return [a['nid'] for a in edges]

def loadM():
    """Big-M constant: large enough to not restrict flow"""
    return len(edges) * 2

def generateArcs(edges):
    """
    Generate bidirectional arcs from undirected edges.
    Each edge becomes two arcs: forward and backward.
    Arc IDs: forward arc keeps original nid, backward arc gets nid + |E|
    """
    edge_len = len(edges)
    return [
        {
            'weight': edge['weight'],
            'source': direction[0],
            'target': direction[1],
            'id': edge['id'] + suffix,
            'label': edge['label'],
            'nid': edge['nid'] if index == 0 else edge['nid'] + edge_len
        }
        for edge in edges
        for index, (direction, suffix) in enumerate([
            ((edge['source'], edge['target']), '-1'),
            ((edge['target'], edge['source']), '-2')
        ])
    ]

# Generate directed arcs from undirected edges
arcs = generateArcs(edges)

def loadArcs():
    """Return all arc IDs"""
    return [a['nid'] for a in arcs]

def loadIncomming():
    """Return incoming arcs for each vertex"""
    return {n['nid']: [a['nid'] for a in arcs if a['target'] == n['id']] for n in nodes}

def loadOutgoing():
    """Return outgoing arcs for each vertex"""
    return {n['nid']: [a['nid'] for a in arcs if a['source'] == n['id']] for n in nodes}

def loadArcWeights():
    """Return weight (distance/cost) for each arc"""
    return {a['nid']: a['weight'] for a in arcs}

def loadNodeCosts():
    """Return installation cost for each node"""
    return {n['nid']: 0 if not n['modules'] else n['modules'][0]['cost'] for n in nodes}

def get_color(node):
    """Assign colors based on node type"""
    if node["type"] == 'triangle':
        return '#0000ff'  # Blue for splitters
    if node["type"] == 'square':
        return '#00ff00'  # Green for COs
    if node["type"] == 'circle':
        return '#ff0000'  # Red for ONUs
    return '#000000'    # Black for intermediate

def main():
    # Calculate network centroid for visualization
    mid_x = sum(node["x"] for node in nodes) / len(nodes)
    mid_y = sum(node["y"] for node in nodes) / len(nodes)

    # Translate nodes relative to centroid
    translated = [{"x": node["x"] - mid_x, "y": node["y"] - mid_y} for node in nodes]

    # Find scaling range
    min_x, max_x = min(node["x"] for node in translated), max(node["x"] for node in translated)
    min_y, max_y = min(node["y"] for node in translated), max(node["y"] for node in translated)

    # Prepare visual nodes with scaled coordinates
    visual_vertices = [{
        **node,
        "x": ((node["x"] - mid_x - min_x) / (max_x - min_x or 1)) * 500,
        "y": ((node["y"] - mid_y - min_y) / (max_y - min_y or 1)) * 500,
        "name": node["id"],
        "symbol": node["type"],
        "symbolSize": node["size"],
        "itemStyle": {"color": node["color"] if node["color"] is not None else get_color(node)},
        "id": None
    } for node in nodes]

    # Prepare visual edges
    visual_edges = [{
        **edge,
        "id": None,
        "weight": None,
        "label": None,
        "symbol": None
    } for edge in edges]

    # Clean up None values for JSON serialization
    visual_vertices = [{k: v for k, v in node.items() if v is not None} for node in visual_vertices]
    visual_edges = [{k: v for k, v in edge.items() if v is not None} for edge in visual_edges]

    # Initialize and solve the optimization model
    elytica.init_model("pon")
    elytica.run_model("pon")

    print("\n" + "="*70)
    print("PASSIVE OPTICAL NETWORK PLANNING SOLUTION")
    print("="*70)

    # Extract solution: selected edges and installed splitters
    resulting_edges = [
        e for e in elytica.get_model_set("pon", "E")
        if elytica.get_variable_value("pon", f"x{e}") > 0.5
    ]

    resulting_splitters = [
        s for s in elytica.get_model_set("pon", "S")
        if elytica.get_variable_value("pon", f"y{s}") > 0.5
    ]

    print(f"\nInstalled Splitters: {len(resulting_splitters)}")
    print(f"Selected Fiber Links: {len(resulting_edges)}")

    # Get splitter connections
    print("\nSplitter Details:")
    print("-"*70)
    for s in resulting_splitters:
        connections = elytica.get_variable_value("pon", f"N{s}")
        node_id = nodes[s]['id']
        print(f"  Splitter at {node_id}: {int(connections)} connections")

    # Get objective value
    obj_value = elytica.get_best_primal_bound("pon")
    print("\n" + "-"*70)
    print(f"Total Network Cost: {obj_value:.2f}")
    print("="*70)

    # Filter visualization to show only selected components
    visual_edges = [e for e in visual_edges if e['nid'] in resulting_edges]
    no_splitters = [v for v in visual_vertices if ('type' not in v) or (v['type'] != 'triangle')]
    splitters = [v for v in visual_vertices if v['nid'] in resulting_splitters]
    visual_vertices = splitters + no_splitters

    # Create ECharts graph visualization
    chart = {
        "title": {"text": "Optimal PON Network Design"},
        "tooltip": {},
        "series": [{
            "roam": 1,  # Enable zoom (use 1 instead of 'zoom' for JSON serialization)
            "type": 'graph',
            "layout": 'none',  # Use provided coordinates
            "data": visual_vertices,
            "edges": visual_edges,
            "lineStyle": {
                "opacity": 1,
                "width": 3
            }
        }]
    }

    # Prepare results
    results = {
        "objective_value": obj_value,
        "installed_splitters": resulting_splitters,
        "selected_edges": resulting_edges,
        "num_splitters": len(resulting_splitters),
        "num_fiber_links": len(resulting_edges),
        "chart": chart
    }

    elytica.write_results(json.dumps(results, indent=2))

    return 0


# Expected JSON file format (micronet.json):
#
# {
#   "nodes": [
#     {
#       "id": "node1",
#       "type": "circle",     # "circle" = ONU, "triangle" = splitter, "square" = CO, null = intermediate
#       "x": 100.5,
#       "y": 200.3,
#       "size": 10,
#       "color": "#ff0000",   # Optional
#       "modules": [{"cost": 1500}]  # Equipment cost
#     },
#     ...
#   ],
#   "edges": [
#     {
#       "id": "edge1",
#       "source": "node1",
#       "target": "node2",
#       "weight": 150.0,      # Distance in meters
#       "label": "Link A"
#     },
#     ...
#   ]
# }
#
# Node types:
# - "circle": Optical Network Units (end users/customers)
# - "triangle": Potential splitter locations
# - "square": Central Offices (headend equipment)
# - null: Intermediate routing nodes
```


---

# Resource Constrained Scheduling Problem (RCSP) Example

Complete RCSP optimization problem demonstrating project scheduling with resource constraints, time-indexed formulation, Excel data loading, and net present value maximization. Reads an Excel workbook (not included) with pandas, so it does not run as is.

Path: `examples/rcsp`

```
# Resource Constrained Scheduling Problem (RCSP)
# Schedules activities to maximize net present value of cash flows
# Subject to resource capacity constraints and activity durations
# Demonstrates Excel data loading and parameterized set functions

model rcsp
set I = load_activities()                                   # Activities to schedule
set T = load_time_periods()                                 # Time periods
set R = load_resources()                                    # Resources

set delta(I, T) = load_delta()                             # Time periods when activity i is active if started at t

const d = load_durations(), forall i in I                  # Duration of activity i
const u = load_resource_limits(), forall r in R            # Upper limit of resource r
const v = load_resource_values(), forall i in I, forall r in R  # Resource r consumed by activity i
const dc = load_discounted_cf(), forall i in I, forall t in T   # Discounted cash flow if activity i starts at t

bin x, forall i in I, forall t in T                        # 1 if activity i starts at time t

# Objective: Maximize net present value of cash flows
max sum_{t in T}{sum_{i in I}{dc_{i,t} * x_{i,t}}}

# Each activity must start exactly once
constr sum_{t in T}{x_{i,t}} = 1, forall i in I

# Resource capacity constraint at each time period
constr sum_{i in I}{sum_{k in delta(i, t)}{v_{i,r} * x_{i,k}}} <= u_{r}, forall t in T, forall r in R
end

import elytica
import pandas as pd
import json

# Excel file with three sheets: activities, resources, consumption
xls = "scheduling.xlsx"

# Load data from Excel
activity_sheet = json.loads((pd.read_excel(xls, sheet_name="activities")).to_json(orient='records'))
resource_sheet = json.loads((pd.read_excel(xls, sheet_name="resources")).to_json(orient='records'))
consumption_sheet = json.loads((pd.read_excel(xls, sheet_name="consumption")).to_json(orient='records'))

# Process activity data
activities = [i["activity_id"] for i in activity_sheet]
durations = {i["activity_id"]: i["duration"] for i in activity_sheet}
cash_flows = {i["activity_id"]: i["cash_flow"] for i in activity_sheet}

# Generate time periods based on total duration
time_periods = list(range(1, sum(durations.values())))

# Process resource data
resources = [r["resource_id"] for r in resource_sheet]
resource_limits = {r["resource_id"]: r["upper_limit"] for r in resource_sheet}

# Process consumption data
resource_values = {
    i["activity_id"]: {
        r["resource_id"]: r["value"]
        for r in consumption_sheet
        if r["activity_id"] == i["activity_id"]
    }
    for i in consumption_sheet
}

def load_activities():
    """Return list of activity IDs"""
    return activities

def load_time_periods():
    """Return list of time periods"""
    return time_periods

def load_resources():
    """Return list of resource IDs"""
    return resources

def load_durations():
    """Return duration for each activity"""
    return durations

def load_resource_limits():
    """Return capacity limit for each resource"""
    return resource_limits

def load_resource_values():
    """Return resource consumption for each activity and resource"""
    return resource_values

def load_discounted_cf():
    """Calculate discounted cash flow for each activity at each start time (10% discount rate)"""
    return {
        i: {t: cash_flows[i] / (1.1)**t for t in time_periods}
        for i in activities
    }

def load_delta():
    """
    Return time periods when activity i is active if started at time t
    delta(i,t) = [t, t+1, ..., t+d[i]-1]
    """
    return {
        i: {
            t: [k for k in time_periods if k >= t and k <= t + durations[i] - 1]
            for t in time_periods
        }
        for i in activities
    }

def main():
    elytica.init_model("rcsp")
    elytica.run_model("rcsp")

    I = elytica.get_model_set("rcsp", "I")
    T = elytica.get_model_set("rcsp", "T")

    print("\n" + "="*70)
    print("RESOURCE CONSTRAINED SCHEDULING SOLUTION")
    print("="*70)

    # Collect schedule
    schedule = []
    print("\nActivity Schedule:")
    print("-"*70)

    for i in I:
        for t in T:
            vname = f"x{i},{t}"
            val = elytica.get_variable_value("rcsp", vname)
            if val > 0.5:
                duration = durations[i]
                end_time = t + duration - 1
                schedule.append({
                    "activity": i,
                    "start_time": t,
                    "end_time": end_time,
                    "duration": duration
                })
                print(f"  Activity {i:3d}: Start={t:3d}, End={end_time:3d}, Duration={duration:2d}")

    # Sort schedule by start time
    schedule.sort(key=lambda x: x["start_time"])

    # Get objective value (NPV)
    obj_value = elytica.get_best_primal_bound("rcsp")

    print("-"*70)
    print(f"Net Present Value (NPV): {obj_value:.2f}")
    print("="*70)

    # Prepare results for output
    results = {
        "objective_value": obj_value,
        "schedule": schedule
    }

    elytica.write_results(json.dumps(results, indent=2))

    return 0


# Expected Excel file format (scheduling.xlsx):
#
# Sheet "activities":
# | activity_id | duration | cash_flow |
# |-------------|----------|-----------|
# | 1           | 3        | 1000      |
# | 2           | 2        | 500       |
# | ...         | ...      | ...       |
#
# Sheet "resources":
# | resource_id | upper_limit |
# |-------------|-------------|
# | 1           | 10          |
# | 2           | 8           |
# | ...         | ...         |
#
# Sheet "consumption":
# | activity_id | resource_id | value |
# |-------------|-------------|-------|
# | 1           | 1           | 5     |
# | 1           | 2           | 3     |
# | 2           | 1           | 2     |
# | ...         | ...         | ...   |
```


---

# Shortest Path Problem Example

Complete shortest path optimization problem demonstrating flow conservation constraints and network optimization using setminus for set operations.

Path: `examples/shortest-path`

```
# Shortest Path Problem
# Finds the shortest path from node 1 to node 4 in a directed network
# Demonstrates flow conservation constraints and use of setminus operator

model shortest_path
set N = {1, 2, 3, 4}                                            # Nodes in the network

const d = {{0, 2, infty, 11},
           {2, 0, 3, 8},
           {6, 3, 0, 4},
           {11, 8, 4, 0}}, forall i in N, forall j in N        # Distance from node i to node j

bin x, forall i in N, forall j in N                            # 1 if arc (i,j) is in the path

# Objective: Minimize total path distance
min sum_{i in N}{sum_{j in N setminus {i}}{d_{i,j} * x_{i,j}}}

# Flow conservation at source node (node 1): net outflow = 1
constr sum_{j in N setminus {1}}{x_{1,j}} - sum_{j in N setminus {1}}{x_{j,1}} = 1

# Flow conservation at intermediate nodes: net outflow = 0
constr sum_{j in N setminus {i}}{x_{i,j}} - sum_{j in N setminus {i}}{x_{j,i}} = 0, forall i in N setminus {1, 4}

# Flow conservation at sink node (node 4): net outflow = -1
constr sum_{j in N setminus {4}}{x_{4,j}} - sum_{j in N setminus {4}}{x_{j,4}} = -1
end

import elytica
import json

# The model's distance matrix, to print each edge's length. None is `infty`.
DIST = [[0, 2, None, 11],
        [2, 0, 3, 8],
        [6, 3, 0, 4],
        [11, 8, 4, 0]]

def main():
    elytica.init_model("shortest_path")
    elytica.run_model("shortest_path")

    N = elytica.get_model_set("shortest_path", "N")

    # Collect solution
    path_edges = []
    total_distance = 0

    print("\n" + "="*60)
    print("SHORTEST PATH SOLUTION")
    print("="*60)
    print("\nPath (node -> node):")
    print("-"*60)

    for i in N:
        for j in N:
            val = elytica.get_variable_value("shortest_path", f"x{i},{j}")
            if val > 0.5:
                dist = DIST[i - 1][j - 1]
                path_edges.append({"from": i, "to": j, "distance": dist})
                print(f"  {i} -> {j}  (distance: {dist})")

    # Get objective value (total distance)
    obj_value = elytica.get_best_primal_bound("shortest_path")

    print("-"*60)
    print(f"Total Distance: {obj_value:.2f}")
    print("="*60)

    # Construct ordered path from node 1 to node 4
    ordered_path = [1]
    current = 1
    while current != 4:
        for edge in path_edges:
            if edge["from"] == current:
                ordered_path.append(edge["to"])
                current = edge["to"]
                break

    print(f"\nOrdered Path: {' -> '.join(map(str, ordered_path))}")
    print("="*60)

    # Prepare results for output
    results = {
        "objective_value": obj_value,
        "path_edges": path_edges,
        "ordered_path": ordered_path
    }

    elytica.write_results(json.dumps(results, indent=2))

    return 0
```


---

# Traveling Salesman Problem (TSP) Example

Complete TSP optimization problem demonstrating subtour elimination using MTZ (Miller-Tucker-Zemlin) constraints, set functions, and edge-based formulation.

Path: `examples/tsp`

```
# Traveling Salesman Problem (TSP)
# Finds the shortest tour visiting all nodes exactly once and returning to start
# Uses MTZ (Miller-Tucker-Zemlin) constraints to eliminate subtours

model ts
set N = {1, 2, 3, 4, 5, 6, 7}                              # Nodes (cities)
set E = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13}       # Edges in the graph

set sigma(N) = load_sigma()                                 # Neighbors of each node

const d = {5, 3, 6, 4, 4, 3, 1, 2, 3, 1, 3, 1, 2}, forall e in E  # Distance of edge e

bin x, forall i in N, forall j in N                        # 1 if arc (i,j) is in tour
int 0 <= u <= infty, forall n in N                         # MTZ variables for subtour elimination

# Objective: Minimize total tour distance (considering edges are undirected)
min sum_{e in E}{d_{e} * x_{alpha(e), beta(e)} + d_{e} * x_{beta(e), alpha(e)}}

# Each node has exactly one outgoing arc
constr sum_{j in sigma(i)}{x_{i,j}} = 1, forall i in N

# Each node has exactly one incoming arc
constr sum_{j in sigma(i)}{x_{j,i}} = 1, forall i in N

# MTZ subtour elimination constraints
constr u_{i} - u_{j} + |N| * x_{i,j} <= |N| - 1, forall i in N setminus {1}, forall j in sigma(i) setminus {1}

# Bounds on MTZ variables
constr u_{n} <= |N| - 1, forall n in N setminus {1}
constr u_{n} >= 1, forall n in N setminus {1}
end

import elytica as e
import json

def load_sigma():
    """Load adjacency list for each node (neighbors)"""
    S = {
        1: [2, 3, 7],
        2: [1, 3, 4],
        3: [1, 2, 4, 5, 7],
        4: [2, 3, 5, 6],
        5: [3, 4, 6, 7],
        6: [4, 5, 7],
        7: [1, 3, 5, 6]
    }
    return S

def alpha(edge: int):
    """Get source node of edge"""
    A = {1: 1, 2: 1, 3: 1, 4: 2, 5: 2, 6: 3, 7: 3, 8: 3, 9: 5, 10: 4, 11: 4, 12: 5, 13: 7}
    return A[edge]

def beta(edge: int):
    """Get target node of edge"""
    B = {1: 2, 2: 3, 3: 7, 4: 4, 5: 3, 6: 4, 7: 5, 8: 7, 9: 7, 10: 6, 11: 5, 12: 6, 13: 6}
    return B[edge]

def main():
    e.init_model("ts")
    e.run_model("ts")

    N = e.get_model_set("ts", "N")

    print("\n" + "="*60)
    print("TRAVELING SALESMAN PROBLEM SOLUTION")
    print("="*60)

    # Collect tour edges
    tour_edges = []
    print("\nTour Edges:")
    print("-"*60)
    for i in N:
        for j in N:
            val = e.get_variable_value("ts", f"x{i},{j}")
            if val > 0.5:
                tour_edges.append({"from": i, "to": j})
                print(f"  {i} -> {j}")

    # Collect MTZ variables (for debugging/verification)
    print("\n" + "-"*60)
    print("MTZ Variables (order in tour):")
    print("-"*60)
    mtz_values = {}
    for i in N:
        u_val = e.get_variable_value("ts", f"u{i}")
        if u_val is not None:
            mtz_values[i] = u_val
            if i != 1:  # Node 1 is the depot, u_1 is not constrained
                print(f"  u[{i}] = {u_val:.2f}")

    # Reconstruct ordered tour starting from node 1
    ordered_tour = [1]
    current = 1
    visited = {1}

    while len(ordered_tour) < len(N):
        for edge in tour_edges:
            if edge["from"] == current and edge["to"] not in visited:
                ordered_tour.append(edge["to"])
                visited.add(edge["to"])
                current = edge["to"]
                break

    # Add return to start
    ordered_tour.append(1)

    # Get objective value
    obj_value = e.get_best_primal_bound("ts")

    print("\n" + "-"*60)
    print(f"Ordered Tour: {' -> '.join(map(str, ordered_tour))}")
    print(f"\nTotal Distance: {obj_value:.2f}")
    print("="*60)

    # Prepare results for output
    results = {
        "objective_value": obj_value,
        "tour_edges": tour_edges,
        "ordered_tour": ordered_tour,
        "mtz_values": mtz_values
    }

    e.write_results(json.dumps(results, indent=2))

    return 0
```


---

# Absolute value in the objective

Minimises total absolute deviation from a target vector. The absolute value is replaced by one auxiliary variable per term bounded below by both signs of the deviation; minimisation drives it down to the true absolute value. Replace |e| by t with t ≥ e and t ≥ −e when minimising.

Path: `formulations/absolute-value`

```
# Absolute value in the objective
#
# Minimises total absolute deviation from a target vector. The absolute
# value is replaced by one auxiliary variable per term bounded below by both
# signs of the deviation; minimisation drives it down to the true absolute
# value.
#
# Technique: Replace |e| by t with t ≥ e and t ≥ −e when minimising.
#
# On this instance the optimum is 2 (minimisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Charnes, A. and Cooper, W. W. (1955). Generalizations of the
# warehousing model. Operational Research Quarterly 6(4), 131–172.
# doi:10.2307/3006550
model m
set I = {1, 2, 3, 4}
const a = {2, 4, 1, 2}, forall i in I
const c = 7

int 0 <= x <= 8, forall i in I
int 0 <= t <= 20, forall i in I

min sum_{i in I}{t_{i}}

# t_i bounds |a_i - x_i| from both sides; minimisation makes it exact
constr t_{i} >= a_{i} - x_{i}, forall i in I
constr t_{i} >= x_{i} - a_{i}, forall i in I

constr sum_{i in I}{x_{i}} <= c
end

import elytica
```


---

# Linear assignment

Matches agents to tasks at least total cost. The constraint matrix is totally unimodular, so the LP relaxation is already integral and the binaries are a modelling convenience rather than a necessity. A doubly-stochastic 0/1 matrix: one row sum and one column sum equal to 1.

Path: `formulations/assignment`

```
# Linear assignment
#
# Matches agents to tasks at least total cost. The constraint matrix is
# totally unimodular, so the LP relaxation is already integral and the
# binaries are a modelling convenience rather than a necessity.
#
# Technique: A doubly-stochastic 0/1 matrix: one row sum and one column sum
#            equal to 1.
#
# On this instance the optimum is 15 (minimisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Kuhn, H. W. (1955). The Hungarian method for the assignment
# problem. Naval Research Logistics Quarterly 2(1–2), 83–97.
# doi:10.1002/nav.3800020109
model m
set I = {1, 2, 3, 4, 5}
set J = {1, 2, 3, 4, 5}
const c = {{9, 8, 13, 8, 5},
           {2, 14, 2, 7, 1},
           {13, 6, 13, 1, 3},
           {15, 11, 4, 9, 2},
           {11, 15, 2, 10, 15}}, forall i in I, forall j in J

bin x, forall i in I, forall j in J

min sum_{i in I}{sum_{j in J}{c_{i,j} * x_{i,j}}}

constr sum_{j in J}{x_{i,j}} = 1, forall i in I
constr sum_{i in I}{x_{i,j}} = 1, forall j in J
end

import elytica
```


---

# Bin packing

Packs items into as few bins as possible. Each bin's capacity row is multiplied by its open indicator so an unused bin can hold nothing, which is the fixed-charge pattern applied per bin. Assignment binaries plus per-bin capacity gated on a bin-used binary.

Path: `formulations/bin-packing`

```
# Bin packing
#
# Packs items into as few bins as possible. Each bin's capacity row is
# multiplied by its open indicator so an unused bin can hold nothing, which
# is the fixed-charge pattern applied per bin.
#
# Technique: Assignment binaries plus per-bin capacity gated on a bin-used
#            binary.
#
# On this instance the optimum is 3 (minimisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Martello, S. and Toth, P. (1990). Knapsack Problems: Algorithms
# and Computer Implementations. Wiley.
model m
set I = {1, 2, 3, 4, 5}
set B = {1, 2, 3, 4}
const s = {5, 4, 5, 2, 3}, forall i in I
const c = 7

bin x, forall i in I, forall b in B
bin y, forall b in B

min sum_{b in B}{y_{b}}

# each item in exactly one bin
constr sum_{b in B}{x_{i,b}} = 1, forall i in I
# a bin's contents fit only if the bin is open
constr sum_{i in I}{s_{i} * x_{i,b}} <= c * y_{b}, forall b in B
end

import elytica
```


---

# Product of two binary variables

Maximises a quadratic objective over binary selections subject to a cardinality limit. The quadratic term is linearised exactly with one auxiliary binary per pair, which is tight because the three inequalities force z to equal the product at every 0/1 point. Replace the product x_i·x_j by an auxiliary binary z_ij with z ≤ x_i, z ≤ x_j, z ≥ x_i + x_j − 1.

Path: `formulations/binary-product`

```
# Product of two binary variables
#
# Maximises a quadratic objective over binary selections subject to a
# cardinality limit. The quadratic term is linearised exactly with one
# auxiliary binary per pair, which is tight because the three inequalities
# force z to equal the product at every 0/1 point.
#
# Technique: Replace the product x_i·x_j by an auxiliary binary z_ij with z
#            ≤ x_i, z ≤ x_j, z ≥ x_i + x_j − 1.
#
# On this instance the optimum is 19 (maximisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Glover, F. and Woolsey, E. (1974). Technical Note—Converting
# the 0-1 Polynomial Programming Problem to a 0-1 Linear Program. Operations
# Research 22(1), 180–182. doi:10.1287/opre.22.1.180
model m
set I = {1, 2, 3, 4}
set P = {1, 2, 3, 4, 5, 6}
const a = {1, 1, 1, 2, 2, 3}, forall p in P
const b = {2, 3, 4, 3, 4, 4}, forall p in P
const q = {7, 8, 1, 4, 3, 1}, forall p in P
const k = 3

bin x, forall i in I
bin z, forall p in P

max sum_{p in P}{q_{p} * z_{p}}

# z_p may only be 1 when both endpoints of pair p are chosen
constr z_{p} <= x_{alpha(p)}, forall p in P
constr z_{p} <= x_{beta(p)}, forall p in P
# and must be 1 when both are, so the product is represented exactly
constr z_{p} >= x_{alpha(p)} + x_{beta(p)} - 1, forall p in P

constr sum_{i in I}{x_{i}} <= k
end

import elytica
def alpha(p):
  return {1: 1, 2: 1, 3: 1, 4: 2, 5: 2, 6: 3}[p]
def beta(p):
  return {1: 2, 2: 3, 3: 4, 4: 3, 5: 4, 6: 4}[p]
```


---

# Capacitated facility location

Opens facilities and assigns customers subject to each site's throughput limit. The capacity row folds the linking constraint into itself — an unopened facility has zero capacity, so assignments to it are already forbidden — but the disaggregated link is usually kept anyway because it strengthens the relaxation. Uncapacitated location plus a capacity row per facility: sum_i d_i x_{i,j} <= k_j y_j.

Path: `formulations/capacitated-facility-location`

```
# Capacitated facility location
#
# Opens facilities and assigns customers subject to each site's throughput
# limit. The capacity row folds the linking constraint into itself — an
# unopened facility has zero capacity, so assignments to it are already
# forbidden — but the disaggregated link is usually kept anyway because it
# strengthens the relaxation.
#
# Technique: Uncapacitated location plus a capacity row per facility: sum_i
#            d_i x_{i,j} <= k_j y_j.
#
# On this instance the optimum is 26 (minimisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Balinski, M. L. (1965). Integer programming: methods, uses,
# computation. Management Science 12(3), 253–313. doi:10.1287/mnsc.12.3.253
model m
set F = {1, 2, 3}
set C = {1, 2, 3, 4}
const f = {7, 13, 11}, forall j in F
const c = {{2, 5, 4},
           {5, 4, 3},
           {2, 3, 3},
           {9, 2, 1}}, forall i in C, forall j in F
const d = {4, 3, 4, 4}, forall i in C
const k = {9, 9, 10}, forall j in F

bin y, forall j in F
bin x, forall i in C, forall j in F

min sum_{i in C}{sum_{j in F}{c_{i,j} * x_{i,j}}} + sum_{j in F}{f_{j} * y_{j}}

constr sum_{j in F}{x_{i,j}} = 1, forall i in C
constr x_{i,j} <= y_{j}, forall i in C, forall j in F
# throughput limit; an unopened facility has zero capacity
constr sum_{i in C}{d_{i} * x_{i,j}} <= k_{j} * y_{j}, forall j in F
end

import elytica
```


---

# Capacitated lot sizing

Adds a production ceiling to uncapacitated lot sizing, which is what makes the problem hard: without it a period can always cover all future demand and the shortest-path reformulation applies. The big-M on the setup row is tightened to the smaller of the capacity and the demand still to be met, because a looser one weakens the relaxation for nothing. Wagner–Whitin balance plus a per-period capacity that the setup binary gates: x_t <= min(capacity, remaining demand) * y_t.

Path: `formulations/capacitated-lot-sizing`

```
# Capacitated lot sizing
#
# Adds a production ceiling to uncapacitated lot sizing, which is what makes
# the problem hard: without it a period can always cover all future demand
# and the shortest-path reformulation applies. The big-M on the setup row is
# tightened to the smaller of the capacity and the demand still to be met,
# because a looser one weakens the relaxation for nothing.
#
# Technique: Wagner–Whitin balance plus a per-period capacity that the
#            setup binary gates: x_t <= min(capacity, remaining demand) *
#            y_t.
#
# On this instance the optimum is 30 (minimisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Bitran, G. R. and Yanasse, H. H. (1982). Computational
# complexity of the capacitated lot size problem. Management Science 28(10),
# 1174–1186.
model m
set T = {1, 2, 3}
const d = {3, 3, 1}, forall t in T
const M = {3, 3, 1}, forall t in T
const f = 10
const h = 3
const lim = 3

int 0 <= x <= 3, forall t in T
int 0 <= s <= 7, forall t in T
bin y, forall t in T

min f * sum_{t in T}{y_{t}} + h * sum_{t in T}{s_{t}}

constr s_{1} = x_{1} - d_{1}
constr s_{t} = s_{t-1} + x_{t} - d_{t}, forall t in T setminus {1}
# production needs its setup, and cannot exceed capacity
constr x_{t} <= M_{t} * y_{t}, forall t in T
constr x_{t} <= lim, forall t in T
end

import elytica
```


---

# Chance constraint via scenario binaries

Requires a capacity limit to hold in at least a given fraction of scenarios rather than all of them. Each scenario gets an indicator that buys it out of the constraint, and a cardinality row caps how many may be bought out — the deterministic equivalent of "hold with probability at least 1 − alpha" when the scenarios are equally likely. A per-scenario binary z_s relaxes the constraint by big-M when the scenario is allowed to fail, and sum z_s bounds how many may.

Path: `formulations/chance-constraint`

```
# Chance constraint via scenario binaries
#
# Requires a capacity limit to hold in at least a given fraction of
# scenarios rather than all of them. Each scenario gets an indicator that
# buys it out of the constraint, and a cardinality row caps how many may be
# bought out — the deterministic equivalent of "hold with probability at
# least 1 − alpha" when the scenarios are equally likely.
#
# Technique: A per-scenario binary z_s relaxes the constraint by big-M when
#            the scenario is allowed to fail, and sum z_s bounds how many
#            may.
#
# On this instance the optimum is 13 (maximisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Charnes, A. and Cooper, W. W. (1959). Chance-constrained
# programming. Management Science 6(1), 73–79.
model m
set I = {1, 2, 3, 4}
set S = {1, 2, 3, 4}
const v = {8, 5, 2, 5}, forall i in I
const a = {{1, 4, 2, 3},
           {1, 3, 1, 4},
           {1, 4, 2, 3},
           {2, 2, 5, 1}}, forall s in S, forall i in I
const lim = 5
const M = 25

bin x, forall i in I
bin z, forall s in S

max sum_{i in I}{v_{i} * x_{i}}

# z_s = 1 buys scenario s out of the capacity limit
constr sum_{i in I}{a_{s,i} * x_{i}} <= lim + M * z_{s}, forall s in S
# at most 2 scenario(s) may be violated
constr sum_{s in S}{z_{s}} <= 2
end

import elytica
```


---

# Counting and cardinality

Selects exactly k items while an auxiliary count tracks how many of a distinguished subset were taken, which is then bounded. Counting is a plain sum of binaries; no auxiliary machinery is required. Constrain how many binaries may be 1 with a single sum, and count occurrences by summing indicators.

Path: `formulations/count-cardinality`

```
# Counting and cardinality
#
# Selects exactly k items while an auxiliary count tracks how many of a
# distinguished subset were taken, which is then bounded. Counting is a
# plain sum of binaries; no auxiliary machinery is required.
#
# Technique: Constrain how many binaries may be 1 with a single sum, and
#            count occurrences by summing indicators.
#
# On this instance the optimum is 10 (maximisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Nemhauser, G. L. and Wolsey, L. A. (1988). Integer and
# Combinatorial Optimization. Wiley. doi:10.1002/9781118627372
model m
set I = {1, 2, 3, 4, 5}
set S = {1, 2, 4}
const v = {8, 2, 2, 2, 1}, forall i in I

bin x, forall i in I

max sum_{i in I}{v_{i} * x_{i}}

constr sum_{i in I}{x_{i}} = 2
# at most 1 may come from the restricted subset S
constr sum_{i in S}{x_{i}} <= 1
end

import elytica
```


---

# Secondary criterion moved into a constraint

Maximises profit subject to an explicit ceiling on total risk. Since only one objective may be declared, the second criterion becomes a constraint rather than a weighted term. This reaches efficient points a weighted sum cannot, including ones in a non-convex region, at the cost of one solve per bound value. Keep one criterion in the single objective row and impose the others as bounds, re-solving for different bound values.

Path: `formulations/criterion-as-constraint`

```
# Secondary criterion moved into a constraint
#
# Maximises profit subject to an explicit ceiling on total risk. Since only
# one objective may be declared, the second criterion becomes a constraint
# rather than a weighted term. This reaches efficient points a weighted sum
# cannot, including ones in a non-convex region, at the cost of one solve
# per bound value.
#
# Technique: Keep one criterion in the single objective row and impose the
#            others as bounds, re-solving for different bound values.
#
# On this instance the optimum is 12 (maximisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Haimes, Y. Y., Lasdon, L. S. and Wismer, D. A. (1971). On a
# bicriterion formulation of the problems of integrated system
# identification and system optimization. IEEE Transactions on Systems, Man,
# and Cybernetics 1(3), 296–297. doi:10.1109/TSMC.1971.4308298
model m
set I = {1, 2, 3, 4, 5}
const p = {2, 4, 2, 2, 8}, forall i in I
const r = {1, 7, 8, 1, 8}, forall i in I
const eps = 11

bin x, forall i in I

max sum_{i in I}{p_{i} * x_{i}}

# the second criterion is a bound, since only one objective may be declared
constr sum_{i in I}{r_{i} * x_{i}} <= eps
end

import elytica
```


---

# Capacitated vehicle routing (MTZ load form)

Routes a fleet from one depot so every customer is visited once and no vehicle exceeds its capacity. The load variable does double duty — it rules out subtours the way MTZ does for the TSP, and because it accumulates demand along the route it enforces capacity at the same time, which is why this is the compact CVRP formulation of choice. Degree constraints per customer plus load potentials that both eliminate subtours and enforce capacity: u_j >= u_i + q_j - Q(1 - x_ij).

Path: `formulations/cvrp-mtz`

```
# Capacitated vehicle routing (MTZ load form)
#
# Routes a fleet from one depot so every customer is visited once and no
# vehicle exceeds its capacity. The load variable does double duty — it
# rules out subtours the way MTZ does for the TSP, and because it
# accumulates demand along the route it enforces capacity at the same time,
# which is why this is the compact CVRP formulation of choice.
#
# Technique: Degree constraints per customer plus load potentials that both
#            eliminate subtours and enforce capacity: u_j >= u_i + q_j -
#            Q(1 - x_ij).
#
# On this instance the optimum is 25 (minimisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Miller, C. E., Tucker, A. W. and Zemlin, R. A. (1960). Integer
# programming formulation of traveling salesman problems. Journal of the ACM
# 7(4), 326–329. doi:10.1145/321043.321046
model m
set V = {1, 2, 3, 4}
set C = {2, 3, 4}
const c = {{0, 1, 10, 12},
           {1, 0, 10, 10},
           {10, 10, 0, 1},
           {12, 10, 1, 0}}, forall i in V, forall j in V
const q = {0, 2, 2, 2}, forall i in V
const lim = 5
const K = 2

bin x, forall i in V, forall j in V
# accumulated load on arrival at each customer
var 0 <= u <= 5, forall i in V

min sum_{i in V}{sum_{j in V setminus {i}}{c_{i,j} * x_{i,j}}}

# every customer entered once and left once
constr sum_{i in V setminus {j}}{x_{i,j}} = 1, forall j in C
constr sum_{j in V setminus {i}}{x_{i,j}} = 1, forall i in C
# the depot dispatches and receives at most K vehicles
constr sum_{j in C}{x_{1,j}} <= K
constr sum_{i in C}{x_{i,1}} <= K

# load accumulates along a route: subtours cannot close, and capacity is
# enforced by u's own upper bound
constr u_{j} >= u_{i} + q_{j} - lim * [1 - x_{i,j}], forall i in C, forall j in C setminus {i}
constr u_{j} >= q_{j}, forall j in C
end

import elytica
```


---

# Diet / blending

Mixes ingredients at least cost while meeting minimum nutrient levels. The `>=` rows make this the covering counterpart of product mix, and the blend is naturally fractional. Minimise cost subject to lower bounds on each nutrient — a covering LP with `>=` rows.

Path: `formulations/diet-blending`

```
# Diet / blending
#
# Mixes ingredients at least cost while meeting minimum nutrient levels. The
# `>=` rows make this the covering counterpart of product mix, and the blend
# is naturally fractional.
#
# Technique: Minimise cost subject to lower bounds on each nutrient — a
#            covering LP with `>=` rows.
#
# On this instance the optimum is 16.5625 (minimisation), confirmed
# independently by two phase simplex before publication.
#
# Reference: Stigler, G. J. (1945). The cost of subsistence. Journal of Farm
# Economics 27(2), 303–314. doi:10.2307/1231810
model m
set F = {1, 2, 3, 4}
set N = {1, 2}
const c = {5, 5, 6, 5}, forall j in F
const a = {{2, 5, 4, 2},
           {2, 2, 3, 4}}, forall i in N, forall j in F
const r = {13, 9}, forall i in N

var 0 <= x <= infty, forall j in F

min sum_{j in F}{c_{j} * x_{j}}

# every nutrient requirement must be met or exceeded
constr sum_{j in F}{a_{i,j} * x_{j}} >= r_{i}, forall i in N
end

import elytica
```


---

# Minimum dominating set

Chooses the fewest vertices such that every vertex is either chosen or adjacent to a chosen one. The closed neighbourhood of each vertex comes from a parametric set, so the constraint sums over a script-defined index domain rather than a literal set. Closed-neighbourhood covering using a parametric set function N(v) supplied by the script.

Path: `formulations/dominating-set`

```
# Minimum dominating set
#
# Chooses the fewest vertices such that every vertex is either chosen or
# adjacent to a chosen one. The closed neighbourhood of each vertex comes
# from a parametric set, so the constraint sums over a script-defined index
# domain rather than a literal set.
#
# Technique: Closed-neighbourhood covering using a parametric set function
#            N(v) supplied by the script.
#
# On this instance the optimum is 3 (minimisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Haynes, T. W., Hedetniemi, S. T. and Slater, P. J. (2013).
# Fundamentals of Domination in Graphs. CRC Press. doi:10.1201/9781482246582
model m
set V = {1, 2, 3, 4}
set N(V) = closedNeighbourhood()
const w = {1, 3, 3, 6}, forall v in V

bin y, forall v in V

min sum_{v in V}{w_{v} * y_{v}}

# each vertex is dominated by something in its closed neighbourhood
constr sum_{u in N(v)}{y_{u}} >= 1, forall v in V
end

import elytica
def closedNeighbourhood():
  return {1: [1, 2, 3], 2: [1, 2, 3], 3: [1, 2, 3, 4], 4: [3, 4]}
```


---

# Maximum weight matching

Selects the heaviest set of edges with no two sharing a vertex. The incidence structure is a parametric set mapping each vertex to the edges it belongs to, which keeps the constraint one line regardless of graph density. Degree constraints written over a parametric incidence set inc(v), so each vertex bounds the edges touching it.

Path: `formulations/edge-matching`

```
# Maximum weight matching
#
# Selects the heaviest set of edges with no two sharing a vertex. The
# incidence structure is a parametric set mapping each vertex to the edges
# it belongs to, which keeps the constraint one line regardless of graph
# density.
#
# Technique: Degree constraints written over a parametric incidence set
#            inc(v), so each vertex bounds the edges touching it.
#
# On this instance the optimum is 10 (maximisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Edmonds, J. (1965). Maximum matching and a polyhedron with
# 0,1-vertices. Journal of Research of the National Bureau of Standards B
# 69, 125–130. doi:10.6028/jres.069B.013
model m
set V = {1, 2, 3, 4}
set E = {1, 2, 3}
set inc(V) = incidence()
const w = {7, 8, 3}, forall e in E

bin x, forall e in E

max sum_{e in E}{w_{e} * x_{e}}

# at most one selected edge may touch any given vertex
constr sum_{e in inc(v)}{x_{e}} <= 1, forall v in V
end

import elytica
def incidence():
  return {1: [1], 2: [1, 2], 3: [2, 3], 4: [3]}
```


---

# Disjunctive (either-or) constraints

Requires at least one of two resource constraints to hold rather than both. A binary selects which is active; the inactive one is relaxed by a big-M chosen large enough to be non-binding but no larger. Relax one of two constraints with a big-M term controlled by a binary, so exactly one is enforced.

Path: `formulations/either-or`

```
# Disjunctive (either-or) constraints
#
# Requires at least one of two resource constraints to hold rather than
# both. A binary selects which is active; the inactive one is relaxed by a
# big-M chosen large enough to be non-binding but no larger.
#
# Technique: Relax one of two constraints with a big-M term controlled by a
#            binary, so exactly one is enforced.
#
# On this instance the optimum is 23 (maximisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Balas, E. (1979). Disjunctive programming. Annals of Discrete
# Mathematics 5, 3–51. doi:10.1016/S0167-5060(08)70342-X
model m
set I = {1, 2, 3}
const v = {8, 9, 6}, forall i in I
const f = {4, 1, 1}, forall i in I
const g = {3, 1, 5}, forall i in I
const M = 25

bin x, forall i in I
bin y

max sum_{i in I}{v_{i} * x_{i}}

# y = 1 relaxes the first constraint, y = 0 relaxes the second;
# whichever is not relaxed must hold
constr sum_{i in I}{f_{i} * x_{i}} <= 6 + M * y
constr sum_{i in I}{g_{i} * x_{i}} <= 4 + M * [1 - y]
end

import elytica
```


---

# Fixed charge with continuous production

Pays a setup cost to open a line and then produces any continuous amount up to its capacity. This is the genuinely mixed case — the setup is discrete, the quantity is not — and its optimum is fractional wherever demand does not land on a capacity boundary. A binary setup gating a continuous level: x ≤ U·y, mixing integer and continuous variables in one model.

Path: `formulations/fixed-charge-continuous`

```
# Fixed charge with continuous production
#
# Pays a setup cost to open a line and then produces any continuous amount
# up to its capacity. This is the genuinely mixed case — the setup is
# discrete, the quantity is not — and its optimum is fractional wherever
# demand does not land on a capacity boundary.
#
# Technique: A binary setup gating a continuous level: x ≤ U·y, mixing
#            integer and continuous variables in one model.
#
# On this instance the optimum is 24 (minimisation), confirmed
# independently by integer enumeration plus simplex before publication.
#
# Reference: Balinski, M. L. (1965). Integer programming: methods, uses,
# computation. Management Science 12(3), 253–313. doi:10.1287/mnsc.12.3.253
model m
set I = {1, 2, 3}
const f = {11, 14, 6}, forall i in I
const c = {4, 2, 3}, forall i in I
const u = {7, 5, 4}, forall i in I
const d = 5

var 0 <= x <= infty, forall i in I
bin y, forall i in I

min sum_{i in I}{c_{i} * x_{i}} + sum_{i in I}{f_{i} * y_{i}}

# a line produces a continuous amount, but only if its setup is paid
constr x_{i} <= u_{i} * y_{i}, forall i in I
constr sum_{i in I}{x_{i}} >= d
end

import elytica
```


---

# Fixed-charge network design

Chooses which arcs to build as well as how much to send over them. The binaries are what take this out of the totally unimodular world — the flow part alone would be integral, but paying to open an arc makes it a genuine mixed-integer problem. A binary opens each arc and a big-M capacity link ties flow to it: f_a <= u_a · y_a, with the tightest valid M being the arc capacity.

Path: `formulations/fixed-charge-network-design`

```
# Fixed-charge network design
#
# Chooses which arcs to build as well as how much to send over them. The
# binaries are what take this out of the totally unimodular world — the flow
# part alone would be integral, but paying to open an arc makes it a genuine
# mixed-integer problem.
#
# Technique: A binary opens each arc and a big-M capacity link ties flow to
#            it: f_a <= u_a · y_a, with the tightest valid M being the arc
#            capacity.
#
# On this instance the optimum is 37 (minimisation), confirmed
# independently by integer enumeration plus simplex before publication.
#
# Reference: Magnanti, T. L. and Wong, R. T. (1984). Network design and
# transportation planning: models and algorithms. Transportation Science
# 18(1), 1–55. doi:10.1287/trsc.18.1.1
model m
set V = {1, 2, 3, 4}
set A = {1, 2, 3, 4, 5}
set outA(V) = outArcs()
set inA(V) = inArcs()
const c = {5, 3, 2, 2, 1}, forall a in A
const g = {5, 5, 4, 3, 2}, forall a in A
const u = {2, 2, 1, 3, 2}, forall a in A
const b = {4, 0, 0, -4}, forall v in V

var 0 <= f <= infty, forall a in A
bin y, forall a in A

min sum_{a in A}{c_{a} * f_{a}} + sum_{a in A}{g_{a} * y_{a}}

# flow only on an arc that has been built, capped at that arc's capacity
constr f_{a} <= u_{a} * y_{a}, forall a in A
constr sum_{a in outA(v)}{f_{a}} - sum_{a in inA(v)}{f_{a}} = b_{v}, forall v in V
end

import elytica

def outArcs():
  return {1: [1, 2], 2: [3, 4], 3: [5], 4: []}
def inArcs():
  return {1: [], 2: [1], 3: [2, 3], 4: [4, 5]}
```


---

# Fixed-charge (setup) cost

Chooses production levels where each active line incurs a one-off setup cost plus a per-unit cost. The linking constraint uses the tightest valid upper bound, which is the line's own capacity rather than a generic big-M. Link a continuous activity to a binary setup with x ≤ U·y so the fixed cost is paid exactly when the activity is nonzero.

Path: `formulations/fixed-charge`

```
# Fixed-charge (setup) cost
#
# Chooses production levels where each active line incurs a one-off setup
# cost plus a per-unit cost. The linking constraint uses the tightest valid
# upper bound, which is the line's own capacity rather than a generic big-M.
#
# Technique: Link a continuous activity to a binary setup with x ≤ U·y so
#            the fixed cost is paid exactly when the activity is nonzero.
#
# On this instance the optimum is 29 (minimisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Beale, E. M. L. and Tomlin, J. A. (1970). Special facilities in
# a general mathematical programming system for non-convex problems using
# ordered sets of variables. OR 69, 447–454.
model m
set I = {1, 2, 3}
const f = {7, 12, 5}, forall i in I
const c = {1, 2, 3}, forall i in I
const u = {4, 3, 2}, forall i in I
const d = 7

int 0 <= x <= 4, forall i in I
bin y, forall i in I

min sum_{i in I}{c_{i} * x_{i}} + sum_{i in I}{f_{i} * y_{i}}

# production only on an opened line, capped at that line's capacity
constr x_{i} <= u_{i} * y_{i}, forall i in I
constr sum_{i in I}{x_{i}} >= d
end

import elytica
```


---

# Soft constraints by goal programming

Hits production targets as closely as possible when hitting them exactly may be infeasible. Each target becomes an equality with a pair of non-negative deviations; penalising them keeps the model feasible and makes the trade-off explicit rather than hidden in constraint ordering. Add under/over deviation variables to a target and penalise them in the objective instead of enforcing the target strictly.

Path: `formulations/goal-programming`

```
# Soft constraints by goal programming
#
# Hits production targets as closely as possible when hitting them exactly
# may be infeasible. Each target becomes an equality with a pair of
# non-negative deviations; penalising them keeps the model feasible and
# makes the trade-off explicit rather than hidden in constraint ordering.
#
# Technique: Add under/over deviation variables to a target and penalise
#            them in the objective instead of enforcing the target
#            strictly.
#
# On this instance the optimum is 2 (minimisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Charnes, A. and Cooper, W. W. (1961). Management Models and
# Industrial Applications of Linear Programming. Wiley. doi:10.2307/1909344
model m
set I = {1, 2, 3, 4}
const g = {6, 3, 6, 3}, forall i in I
const pu = {3, 2, 1, 1}, forall i in I
const po = {3, 3, 3, 2}, forall i in I
const c = 16

int 0 <= x <= 8, forall i in I
int 0 <= u <= 8, forall i in I
int 0 <= o <= 8, forall i in I

min sum_{i in I}{pu_{i} * u_{i}} + sum_{i in I}{po_{i} * o_{i}}

# the target is met exactly, up to a shortfall or an excess
constr x_{i} + u_{i} - o_{i} = g_{i}, forall i in I
constr sum_{i in I}{x_{i}} <= c
end

import elytica
```


---

# Graph colouring

Assigns colours so no edge is monochromatic, minimising colours used. The colour-used indicator is dominated by the assignment variables, which is what turns a feasibility question into a minimisation. One binary per (vertex, colour); adjacent vertices may not share a colour; a colour-used binary counts the palette.

Path: `formulations/graph-colouring`

```
# Graph colouring
#
# Assigns colours so no edge is monochromatic, minimising colours used. The
# colour-used indicator is dominated by the assignment variables, which is
# what turns a feasibility question into a minimisation.
#
# Technique: One binary per (vertex, colour); adjacent vertices may not
#            share a colour; a colour-used binary counts the palette.
#
# On this instance the optimum is 3 (minimisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Mehrotra, A. and Trick, M. A. (1996). A column generation
# approach for graph coloring. INFORMS Journal on Computing 8(4), 344–354.
# doi:10.1287/ijoc.8.4.344
model m
set V = {1, 2, 3, 4, 5, 6}
set E = {1, 2, 3, 4, 5, 6, 7, 8}
set K = {1, 2, 3}

bin x, forall v in V, forall k in K
bin u, forall k in K

min sum_{k in K}{u_{k}}

# exactly one colour per vertex
constr sum_{k in K}{x_{v,k}} = 1, forall v in V
# endpoints of an edge differ in every colour class
constr x_{alpha(e),k} + x_{beta(e),k} <= 1, forall e in E, forall k in K
# a colour counts as used if any vertex takes it
constr x_{v,k} <= u_{k}, forall v in V, forall k in K
end

import elytica
def alpha(e):
  return {1: 1, 2: 2, 3: 3, 4: 4, 5: 5, 6: 1, 7: 2, 8: 3}[e]
def beta(e):
  return {1: 2, 2: 3, 3: 4, 4: 5, 5: 6, 6: 6, 7: 4, 8: 6}[e]
```


---

# Logical implication between binaries

Encodes prerequisite structure among selectable options: choosing a dependent option forces its prerequisite. The inequality form is exact and needs no auxiliary variable. x ⇒ y becomes x ≤ y; a conjunction premise needs x1 + x2 − 1 ≤ y.

Path: `formulations/implication`

```
# Logical implication between binaries
#
# Encodes prerequisite structure among selectable options: choosing a
# dependent option forces its prerequisite. The inequality form is exact and
# needs no auxiliary variable.
#
# Technique: x ⇒ y becomes x ≤ y; a conjunction premise needs x1 + x2 − 1 ≤
#            y.
#
# On this instance the optimum is 17 (maximisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Williams, H. P. (2013). Model Building in Mathematical
# Programming, 5th ed. Wiley.
model m
set I = {1, 2, 3, 4, 5}
set D = {1, 2, 3, 4}
const v = {7, 6, 4, 6, 9}, forall i in I
const k = 3

bin x, forall i in I

max sum_{i in I}{v_{i} * x_{i}}

# choosing the dependent forces its prerequisite
constr x_{dep(d)} <= x_{pre(d)}, forall d in D
constr sum_{i in I}{x_{i}} <= k
end

import elytica
def dep(d):
  return {1: 2, 2: 3, 3: 4, 4: 5}[d]
def pre(d):
  return {1: 1, 2: 2, 3: 3, 4: 4}[d]
```


---

# Maximum weighted independent set

Selects the heaviest set of mutually non-adjacent vertices. Uses the same edge-to-endpoint mapping as vertex cover with the inequality reversed, which is the standard complementary formulation. The complement pattern of vertex cover: y_{alpha(e)} + y_{beta(e)} <= 1 forbids both endpoints of any edge.

Path: `formulations/independent-set`

```
# Maximum weighted independent set
#
# Selects the heaviest set of mutually non-adjacent vertices. Uses the same
# edge-to-endpoint mapping as vertex cover with the inequality reversed,
# which is the standard complementary formulation.
#
# Technique: The complement pattern of vertex cover: y_{alpha(e)} +
#            y_{beta(e)} <= 1 forbids both endpoints of any edge.
#
# On this instance the optimum is 14 (maximisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Nemhauser, G. L. and Trotter, L. E. (1975). Vertex packings:
# structural properties and algorithms. Mathematical Programming 8, 232–248.
# doi:10.1007/BF01580444
model m
set V = {1, 2, 3, 4, 5}
set E = {1, 2, 3, 4, 5}
const w = {6, 6, 6, 1, 8}, forall v in V

bin y, forall v in V

max sum_{v in V}{w_{v} * y_{v}}

# no edge may have both endpoints selected
constr y_{alpha(e)} + y_{beta(e)} <= 1, forall e in E
end

import elytica

def alpha(e):
  return {1: 1, 2: 2, 3: 3, 4: 4, 5: 3}[e]
def beta(e):
  return {1: 2, 2: 3, 3: 4, 4: 5, 5: 5}[e]
```


---

# Job shop, disjunctive formulation

Schedules multi-operation jobs across machines where each job visits the machines in its own order. Two constraint families do the work: precedence within a job is a plain inequality, while non-interference on a machine needs the disjunctive pair, since either operation may go first. Precedence rows inside each job, plus a big-M either-or pair for every pair of operations sharing a machine.

Path: `formulations/job-shop-disjunctive`

```
# Job shop, disjunctive formulation
#
# Schedules multi-operation jobs across machines where each job visits the
# machines in its own order. Two constraint families do the work: precedence
# within a job is a plain inequality, while non-interference on a machine
# needs the disjunctive pair, since either operation may go first.
#
# Technique: Precedence rows inside each job, plus a big-M either-or pair
#            for every pair of operations sharing a machine.
#
# On this instance the optimum is 7 (minimisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Manne, A. S. (1960). On the job-shop scheduling problem.
# Operations Research 8(2), 219–223.
model m
set J = {1, 2}
set M = {1, 2}
set P = {1, 2}
const d = {{4, 1},
           {2, 2}}, forall j in J, forall k in M
const H = 9

var 0 <= s <= 9, forall j in J, forall k in M
var 0 <= mk <= 9
bin y, forall q in P

min mk

# each job runs machine 1 before machine 2
constr s_{j,2} >= s_{j,1} + d_{j,1}, forall j in J
# makespan dominates every completion
constr mk >= s_{j,k} + d_{j,k}, forall j in J, forall k in M
# on each machine the two jobs cannot overlap; y picks which goes first
constr s_{2,q} >= s_{1,q} + d_{1,q} - H * [1 - y_{q}], forall q in P
constr s_{1,q} >= s_{2,q} + d_{2,q} - H * y_{q}, forall q in P
end

import elytica
```


---

# 0/1 knapsack

Selects a subset of items maximising value within a weight budget. The canonical single-constraint integer program and the base case every other packing formulation specialises. One binary per item, a single capacity row.

Path: `formulations/knapsack-01`

```
# 0/1 knapsack
#
# Selects a subset of items maximising value within a weight budget. The
# canonical single-constraint integer program and the base case every other
# packing formulation specialises.
#
# Technique: One binary per item, a single capacity row.
#
# On this instance the optimum is 51 (maximisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Dantzig, G. B. (1957). Discrete-variable extremum problems.
# Operations Research 5(2), 266–277. doi:10.1287/opre.5.2.266
model m
set I = {1, 2, 3, 4, 5, 6, 7}
const v = {12, 15, 1, 15, 1, 19, 3}, forall i in I
const w = {7, 2, 2, 5, 2, 5, 11}, forall i in I
const c = 16

bin x, forall i in I

max sum_{i in I}{v_{i} * x_{i}}
constr sum_{i in I}{w_{i} * x_{i}} <= c
end

import elytica
```


---

# Bounded knapsack

Packs multiple copies of each item, up to a per-item limit. The only structural change from the 0/1 case is the variable type and its bound; the capacity row is identical, which is why the bounded case is usually presented as a variant rather than a separate problem. Integer counts with per-item upper bounds instead of binaries — int 0 <= x <= b_i rather than bin x.

Path: `formulations/knapsack-bounded`

```
# Bounded knapsack
#
# Packs multiple copies of each item, up to a per-item limit. The only
# structural change from the 0/1 case is the variable type and its bound;
# the capacity row is identical, which is why the bounded case is usually
# presented as a variant rather than a separate problem.
#
# Technique: Integer counts with per-item upper bounds instead of binaries
#            — int 0 <= x <= b_i rather than bin x.
#
# On this instance the optimum is 46 (maximisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Martello, S. and Toth, P. (1990). Knapsack Problems: Algorithms
# and Computer Implementations. Wiley.
model m
set I = {1, 2, 3}
const v = {10, 11, 7}, forall i in I
const w = {5, 1, 2}, forall i in I
const b = {1, 2, 2}, forall i in I
const c = 16

int 0 <= x <= 2, forall i in I

max sum_{i in I}{v_{i} * x_{i}}

# per-item copy limit
constr x_{i} <= b_{i}, forall i in I
constr sum_{i in I}{w_{i} * x_{i}} <= c
end

import elytica
```


---

# Multidimensional knapsack

Extends the knapsack to several simultaneous resource limits, so an item consumes a vector rather than a scalar. Adding rows does not change the variable structure, only the feasible region. Several independent capacity rows over the same binaries.

Path: `formulations/knapsack-multidim`

```
# Multidimensional knapsack
#
# Extends the knapsack to several simultaneous resource limits, so an item
# consumes a vector rather than a scalar. Adding rows does not change the
# variable structure, only the feasible region.
#
# Technique: Several independent capacity rows over the same binaries.
#
# On this instance the optimum is 47 (maximisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Fréville, A. (2004). The multidimensional 0-1 knapsack problem:
# an overview. European Journal of Operational Research 155(1), 1–21.
# doi:10.1016/S0377-2217(03)00274-1
model m
set I = {1, 2, 3, 4, 5, 6}
set D = {1, 2, 3}
const v = {16, 4, 1, 20, 17, 10}, forall i in I
const w = {{9, 4, 4, 7, 1, 3},
           {6, 6, 3, 7, 6, 3},
           {4, 7, 9, 3, 1, 1}}, forall d in D, forall i in I
const c = {13, 17, 12}, forall d in D

bin x, forall i in I

max sum_{i in I}{v_{i} * x_{i}}
# one capacity row per resource dimension
constr sum_{i in I}{w_{d,i} * x_{i}} <= c_{d}, forall d in D
end

import elytica
```


---

# Unbounded knapsack

Packs unlimited copies of each item. Removing the per-item bound from the bounded case leaves the capacity constraint as the only thing limiting any variable, which is what makes the greedy density heuristic so nearly right here and badly wrong in the 0/1 case. Integer counts with no per-item limit — only the capacity row bounds them.

Path: `formulations/knapsack-unbounded`

```
# Unbounded knapsack
#
# Packs unlimited copies of each item. Removing the per-item bound from the
# bounded case leaves the capacity constraint as the only thing limiting any
# variable, which is what makes the greedy density heuristic so nearly right
# here and badly wrong in the 0/1 case.
#
# Technique: Integer counts with no per-item limit — only the capacity row
#            bounds them.
#
# On this instance the optimum is 20 (maximisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Gilmore, P. C. and Gomory, R. E. (1963). A linear programming
# approach to the cutting stock problem — part II. Operations Research
# 11(6), 863–888.
model m
set I = {1, 2, 3, 4}
const v = {5, 10, 10, 8}, forall i in I
const w = {4, 4, 7, 7}, forall i in I
const c = 10

# no per-item bound: only the capacity row limits these
int 0 <= x <= 2, forall i in I

max sum_{i in I}{v_{i} * x_{i}}
constr sum_{i in I}{w_{i} * x_{i}} <= c
end

import elytica
```


---

# Aggregated (big-M) linking constraint

Links assignments to open facilities with one aggregated row per facility. Fewer constraints than the disaggregated form, and the same integer optimum, but a materially weaker bound — which is what a branch-and-bound search actually searches against. One row per facility: sum_i x_ij <= |C|·y_j. Compact, but the LP relaxation is weak because a single fractional y_j releases every assignment at once.

Path: `formulations/linking-aggregated`

```
# Aggregated (big-M) linking constraint
#
# Links assignments to open facilities with one aggregated row per facility.
# Fewer constraints than the disaggregated form, and the same integer
# optimum, but a materially weaker bound — which is what a branch-and-bound
# search actually searches against.
#
# Technique: One row per facility: sum_i x_ij <= |C|·y_j. Compact, but the
#            LP relaxation is weak because a single fractional y_j releases
#            every assignment at once.
#
# On this instance the optimum is 28 (minimisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Vielma, J. P. (2015). Mixed integer linear programming
# formulation techniques. SIAM Review 57(1), 3–57. doi:10.1137/130915303
model m
set F = {1, 2}
set C = {1, 2, 3, 4}
const f = {11, 9}, forall j in F
const c = {{8, 5},
           {9, 4},
           {4, 2},
           {2, 8}}, forall i in C, forall j in F

bin y, forall j in F
bin x, forall i in C, forall j in F

min sum_{i in C}{sum_{j in F}{c_{i,j} * x_{i,j}}} + sum_{j in F}{f_{j} * y_{j}}

constr sum_{j in F}{x_{i,j}} = 1, forall i in C
# aggregated: one row per facility, big-M = number of customers
constr sum_{i in C}{x_{i,j}} <= 4 * y_{j}, forall j in F
end

import elytica
```


---

# Disaggregated linking constraint

Links each assignment to its facility individually. It describes exactly the same integer feasible set as the aggregated form and reaches the same optimum, but its relaxation is at least as strong and usually strictly stronger, which is the classic size-versus-strength trade-off. One row per assignment: x_ij <= y_j. More rows, but the LP relaxation is tight — this is the ideal formulation of the same set.

Path: `formulations/linking-disaggregated`

```
# Disaggregated linking constraint
#
# Links each assignment to its facility individually. It describes exactly
# the same integer feasible set as the aggregated form and reaches the same
# optimum, but its relaxation is at least as strong and usually strictly
# stronger, which is the classic size-versus-strength trade-off.
#
# Technique: One row per assignment: x_ij <= y_j. More rows, but the LP
#            relaxation is tight — this is the ideal formulation of the
#            same set.
#
# On this instance the optimum is 16 (minimisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Vielma, J. P. (2015). Mixed integer linear programming
# formulation techniques. SIAM Review 57(1), 3–57. doi:10.1137/130915303
model m
set F = {1, 2}
set C = {1, 2, 3}
const f = {9, 4}, forall j in F
const c = {{8, 7},
           {6, 4},
           {3, 1}}, forall i in C, forall j in F

bin y, forall j in F
bin x, forall i in C, forall j in F

min sum_{i in C}{sum_{j in F}{c_{i,j} * x_{i,j}}} + sum_{j in F}{f_{j} * y_{j}}

constr sum_{j in F}{x_{i,j}} = 1, forall i in C
# disaggregated: one row per (customer, facility) pair
constr x_{i,j} <= y_{j}, forall i in C, forall j in F
end

import elytica
```


---

# Logarithmic encoding of a choice

Picks exactly one alternative while using logarithmically many binaries rather than one per alternative. The selection indicator is reconstructed from the bit pattern, trading a smaller variable count against a less transparent model. Select one of k alternatives with ceil(log2 k) binaries instead of k, using a binary expansion of the index.

Path: `formulations/logarithmic-encoding`

```
# Logarithmic encoding of a choice
#
# Picks exactly one alternative while using logarithmically many binaries
# rather than one per alternative. The selection indicator is reconstructed
# from the bit pattern, trading a smaller variable count against a less
# transparent model.
#
# Technique: Select one of k alternatives with ceil(log2 k) binaries
#            instead of k, using a binary expansion of the index.
#
# On this instance the optimum is 14 (maximisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Vielma, J. P. and Nemhauser, G. L. (2011). Modeling disjunctive
# constraints with a logarithmic number of binary variables and constraints.
# Mathematical Programming 128(1–2), 49–72.
model m
set A = {1, 2, 3, 4}
set Bt = {1, 2}
const v = {14, 9, 10, 13}, forall a in A
const bit = {{0, 0},
           {1, 0},
           {0, 1},
           {1, 1}}, forall a in A, forall b in Bt

bin z, forall b in Bt
var 0 <= lam <= 1, forall a in A

max sum_{a in A}{v_{a} * lam_{a}}

constr sum_{a in A}{lam_{a}} = 1
# lam_a can only be positive when every bit of z matches the code of a
constr sum_{a in A}{bit_{a,b} * lam_{a}} <= z_{b}, forall b in Bt
constr sum_{a in A}{[1 - bit_{a,b}] * lam_{a}} <= 1 - z_{b}, forall b in Bt
end

import elytica
```


---

# Single-item lot sizing with setups

Decides when to produce and how much, trading setup cost against holding cost. The balance constraint uses index arithmetic to reference the previous period, with the first period split out because t-1 would fall outside the set. Inventory balance across periods with index arithmetic s_{t} = s_{t-1} + x_{t} - d_{t}, and production gated on a setup binary.

Path: `formulations/lot-sizing`

```
# Single-item lot sizing with setups
#
# Decides when to produce and how much, trading setup cost against holding
# cost. The balance constraint uses index arithmetic to reference the
# previous period, with the first period split out because t-1 would fall
# outside the set.
#
# Technique: Inventory balance across periods with index arithmetic s_{t} =
#            s_{t-1} + x_{t} - d_{t}, and production gated on a setup
#            binary.
#
# On this instance the optimum is 18 (minimisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Wagner, H. M. and Whitin, T. M. (1958). Dynamic version of the
# economic lot size model. Management Science 5(1), 89–96.
# doi:10.1287/mnsc.5.1.89
model m
set T = {1, 2, 3, 4}
const d = {1, 1, 1, 1}, forall t in T
const f = 6
const h = 3
const M = 4

int 0 <= x <= 4, forall t in T
int 0 <= s <= 4, forall t in T
bin y, forall t in T

min f * sum_{t in T}{y_{t}} + h * sum_{t in T}{s_{t}}

# first period has no predecessor stock
constr s_{1} = x_{1} - d_{1}
# every later period carries stock forward from t-1
constr s_{t} = s_{t-1} + x_{t} - d_{t}, forall t in T setminus {1}
# producing in a period requires paying its setup
constr x_{t} <= M * y_{t}, forall t in T
end

import elytica
```


---

# Multiple travelling salesman

Partitions customers among m salesmen, each starting and ending at the depot, minimising total distance. Structurally it is CVRP with unlimited vehicle capacity, which isolates what the load variable contributes: with capacity removed the potentials are doing only subtour elimination. CVRP with the capacity row dropped: exactly m routes leave the depot, and potentials handle subtours alone.

Path: `formulations/m-tsp`

```
# Multiple travelling salesman
#
# Partitions customers among m salesmen, each starting and ending at the
# depot, minimising total distance. Structurally it is CVRP with unlimited
# vehicle capacity, which isolates what the load variable contributes: with
# capacity removed the potentials are doing only subtour elimination.
#
# Technique: CVRP with the capacity row dropped: exactly m routes leave the
#            depot, and potentials handle subtours alone.
#
# On this instance the optimum is 32 (minimisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Bektas, T. (2006). The multiple traveling salesman problem: an
# overview of formulations and solution procedures. Omega 34(3), 209–219.
model m
set V = {1, 2, 3, 4}
set C = {2, 3, 4}
const c = {{0, 2, 7, 9},
           {2, 0, 12, 9},
           {7, 12, 0, 12},
           {9, 9, 12, 0}}, forall i in V, forall j in V
const M = 2
const N = 4

bin x, forall i in V, forall j in V
int 1 <= u <= 4, forall i in V

min sum_{i in V}{sum_{j in V setminus {i}}{c_{i,j} * x_{i,j}}}

constr sum_{i in V setminus {j}}{x_{i,j}} = 1, forall j in C
constr sum_{j in V setminus {i}}{x_{i,j}} = 1, forall i in C
# exactly M routes leave and return
constr sum_{j in C}{x_{1,j}} = M
constr sum_{i in C}{x_{i,1}} = M

# potentials rule out cycles that miss the depot
constr u_{i} - u_{j} + N * x_{i,j} <= N - 1, forall i in C, forall j in C setminus {i}
end

import elytica
```


---

# Maximum clique

Finds the largest mutually adjacent set of vertices. The constraint runs over the complement graph, which is the mirror of independent set — a clique in G is an independent set in the complement of G, and the two formulations differ only in which pairs they forbid. Forbid every NON-edge: y_u + y_v <= 1 for each pair with no edge between them.

Path: `formulations/max-clique`

```
# Maximum clique
#
# Finds the largest mutually adjacent set of vertices. The constraint runs
# over the complement graph, which is the mirror of independent set — a
# clique in G is an independent set in the complement of G, and the two
# formulations differ only in which pairs they forbid.
#
# Technique: Forbid every NON-edge: y_u + y_v <= 1 for each pair with no
#            edge between them.
#
# On this instance the optimum is 10 (maximisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Bomze, I. M., Budinich, M., Pardalos, P. M. and Pelillo, M.
# (1999). The maximum clique problem. Handbook of Combinatorial
# Optimization, 1–74.
model m
set V = {1, 2, 3, 4, 5}
set N = {1, 2, 3, 4, 5, 6, 7}
const w = {9, 6, 1, 3, 3}, forall v in V

bin y, forall v in V

max sum_{v in V}{w_{v} * y_{v}}

# a pair with no edge between them cannot both be in a clique
constr y_{lo(k)} + y_{hi(k)} <= 1, forall k in N
end

import elytica
def lo(k):
  return {1: 1, 2: 1, 3: 1, 4: 2, 5: 2, 6: 2, 7: 3}[k]
def hi(k):
  return {1: 2, 2: 4, 3: 5, 4: 3, 5: 4, 6: 5, 7: 5}[k]
```


---

# Maximal covering location

Places a limited number of facilities to cover as much demand as possible within a service radius, rather than to minimise distance. Coverage is an indicator dominated by the open facilities that can reach the point, which is the covering counterpart of p-median. A demand point counts as covered when at least one facility within range is open: z_i ≤ sum of y_j over the covering set.

Path: `formulations/max-covering`

```
# Maximal covering location
#
# Places a limited number of facilities to cover as much demand as possible
# within a service radius, rather than to minimise distance. Coverage is an
# indicator dominated by the open facilities that can reach the point, which
# is the covering counterpart of p-median.
#
# Technique: A demand point counts as covered when at least one facility
#            within range is open: z_i ≤ sum of y_j over the covering set.
#
# On this instance the optimum is 14 (maximisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Church, R. and ReVelle, C. (1974). The maximal covering
# location problem. Papers of the Regional Science Association 32(1),
# 101–118. doi:10.1007/BF01942293
model m
set S = {1, 2, 3, 4, 5}
set C = {1, 2, 3, 4, 5, 6}
set cov(C) = coveringFacilities()
const w = {3, 1, 5, 2, 1, 2}, forall i in C
const p = 3

bin y, forall j in S
bin z, forall i in C

max sum_{i in C}{w_{i} * z_{i}}

# a point counts as covered only if some facility in range is open
constr z_{i} <= sum_{j in cov(i)}{y_{j}}, forall i in C
constr sum_{j in S}{y_{j}} <= p
end

import elytica
def coveringFacilities():
  return {1: [5], 2: [2, 4], 3: [4, 5], 4: [1, 4], 5: [2, 3, 4], 6: [1, 2]}
```


---

# Maximum cut

Splits vertices into two sides maximising the weight of edges crossing. The cut indicator is linearised by two inequalities that together force it to zero unless the endpoints differ, which is exact at 0/1 points. Partition indicator per vertex plus an edge-cut variable sandwiched by z ≤ y_a + y_b and z ≤ 2 − y_a − y_b.

Path: `formulations/max-cut`

```
# Maximum cut
#
# Splits vertices into two sides maximising the weight of edges crossing.
# The cut indicator is linearised by two inequalities that together force it
# to zero unless the endpoints differ, which is exact at 0/1 points.
#
# Technique: Partition indicator per vertex plus an edge-cut variable
#            sandwiched by z ≤ y_a + y_b and z ≤ 2 − y_a − y_b.
#
# On this instance the optimum is 26 (maximisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Barahona, F., Grötschel, M., Jünger, M. and Reinelt, G. (1988).
# An application of combinatorial optimization to statistical physics and
# circuit layout design. Operations Research 36(3), 493–513.
# doi:10.1287/opre.36.3.493
model m
set V = {1, 2, 3, 4, 5}
set E = {1, 2, 3, 4, 5, 6}
const w = {2, 4, 9, 6, 6, 8}, forall e in E

bin y, forall v in V
bin z, forall e in E

max sum_{e in E}{w_{e} * z_{e}}

# z_e can only be 1 when the endpoints fall on opposite sides
constr z_{e} <= y_{alpha(e)} + y_{beta(e)}, forall e in E
constr z_{e} <= 2 - y_{alpha(e)} - y_{beta(e)}, forall e in E
end

import elytica
def alpha(e):
  return {1: 1, 2: 2, 3: 3, 4: 4, 5: 2, 6: 3}[e]
def beta(e):
  return {1: 2, 2: 3, 3: 4, 4: 5, 5: 4, 6: 5}[e]
```


---

# Maximum flow

Pushes as much as possible from source to sink. By max-flow min-cut the optimum equals the capacity of the lightest cut separating them, which is the LP dual of this program — the reference here checks the primal value against enumeration of every cut. Maximise the flow leaving the source subject to node balance at every intermediate node and arc capacities.

Path: `formulations/max-flow`

```
# Maximum flow
#
# Pushes as much as possible from source to sink. By max-flow min-cut the
# optimum equals the capacity of the lightest cut separating them, which is
# the LP dual of this program — the reference here checks the primal value
# against enumeration of every cut.
#
# Technique: Maximise the flow leaving the source subject to node balance
#            at every intermediate node and arc capacities.
#
# On this instance the optimum is 5 (minimisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Ford, L. R. and Fulkerson, D. R. (1956). Maximal flow through a
# network. Canadian Journal of Mathematics 8, 399–404.
# doi:10.4153/CJM-1956-045-5
model m
set V = {1, 2, 3, 4}
set Mid = {2, 3}
set A = {1, 2, 3, 4, 5}
set outA(V) = outArcs()
set inA(V) = inArcs()
const u = {3, 2, 1, 6, 2}, forall a in A

var 0 <= f <= infty, forall a in A

max sum_{a in outA(1)}{f_{a}}

constr f_{a} <= u_{a}, forall a in A
# only the intermediate nodes must balance; source and sink are free
constr sum_{a in outA(v)}{f_{a}} - sum_{a in inA(v)}{f_{a}} = 0, forall v in Mid
end

import elytica

def outArcs():
  return {1: [1, 2], 2: [3, 4], 3: [5], 4: []}
def inArcs():
  return {1: [], 2: [1], 3: [2, 3], 4: [4, 5]}
```


---

# Maximising a minimum over continuous shares

Divides a divisible resource so the worst-off share is as large as possible. Because the quantities are continuous the optimum equalises the shares and is generally fractional, which an integer formulation of the same idea would round away. t ≤ e_i for every i with t continuous, maximised — the continuous form of the maximin pattern.

Path: `formulations/maximin-continuous`

```
# Maximising a minimum over continuous shares
#
# Divides a divisible resource so the worst-off share is as large as
# possible. Because the quantities are continuous the optimum equalises the
# shares and is generally fractional, which an integer formulation of the
# same idea would round away.
#
# Technique: t ≤ e_i for every i with t continuous, maximised — the
#            continuous form of the maximin pattern.
#
# On this instance the optimum is 17.142857142857142 (maximisation), confirmed
# independently by two phase simplex before publication.
#
# Reference: Rawls, J. (1971). A Theory of Justice. Harvard University
# Press.
model m
set A = {1, 2}
const u = {6, 1}, forall a in A
const T = 20

var 0 <= x <= infty, forall a in A
var 0 <= t <= infty

max t

# t sits below every agent's utility, so maximising it lifts the worst off
constr t <= u_{a} * x_{a}, forall a in A
constr sum_{a in A}{x_{a}} <= T
end

import elytica
```


---

# Maximising a minimum

Maximises the worst-off share in a fair-division problem. The mirror of the minimax pattern: a single auxiliary variable is dominated by every term, and maximisation lifts it to exactly the minimum. Replace min_i e_i by t with t ≤ e_i for all i, then maximise t.

Path: `formulations/maximin`

```
# Maximising a minimum
#
# Maximises the worst-off share in a fair-division problem. The mirror of
# the minimax pattern: a single auxiliary variable is dominated by every
# term, and maximisation lifts it to exactly the minimum.
#
# Technique: Replace min_i e_i by t with t ≤ e_i for all i, then maximise
#            t.
#
# On this instance the optimum is 17 (maximisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Rawls, J. (1971). A Theory of Justice. Harvard University
# Press.
model m
set A = {1, 2}
set I = {1, 2, 3, 4, 5}
const v = {{5, 6, 8, 8, 1},
           {5, 6, 8, 4, 9}}, forall a in A, forall i in I

bin x, forall i in I, forall a in A
int 0 <= t <= 45

max t

# every item goes to exactly one agent
constr sum_{a in A}{x_{i,a}} = 1, forall i in I
# t is dominated by every agent's total, so maximising it lifts the worst off
constr t <= sum_{i in I}{v_{a,i} * x_{i,a}}, forall a in A
end

import elytica
```


---

# Minimum-cost network flow

Routes supply to demand at least cost. This generalises transportation, transshipment and shortest path — each is this model with a particular supply vector and network shape. The node-arc incidence matrix is totally unimodular, so with integer supplies and capacities the LP optimum is already integral and no integer variables are needed. Node balance with arc capacities: outflow − inflow = supply at every node, flow bounded by capacity on every arc.

Path: `formulations/min-cost-flow`

```
# Minimum-cost network flow
#
# Routes supply to demand at least cost. This generalises transportation,
# transshipment and shortest path — each is this model with a particular
# supply vector and network shape. The node-arc incidence matrix is totally
# unimodular, so with integer supplies and capacities the LP optimum is
# already integral and no integer variables are needed.
#
# Technique: Node balance with arc capacities: outflow − inflow = supply at
#            every node, flow bounded by capacity on every arc.
#
# On this instance the optimum is 36 (minimisation), confirmed
# independently by two phase simplex before publication.
#
# Reference: Ford, L. R. and Fulkerson, D. R. (1962). Flows in Networks.
# Princeton University Press. doi:10.1515/9781400875184
model m
set V = {1, 2, 3, 4}
set A = {1, 2, 3, 4, 5}
set outA(V) = outArcs()
set inA(V) = inArcs()
const c = {8, 1, 6, 6, 7}, forall a in A
const u = {4, 4, 4, 2, 1}, forall a in A
const b = {3, 0, 0, -3}, forall v in V

var 0 <= f <= infty, forall a in A

min sum_{a in A}{c_{a} * f_{a}}

constr f_{a} <= u_{a}, forall a in A
constr sum_{a in outA(v)}{f_{a}} - sum_{a in inA(v)}{f_{a}} = b_{v}, forall v in V
end

import elytica

def outArcs():
  return {1: [1, 2], 2: [3, 4], 3: [5], 4: []}
def inArcs():
  return {1: [], 2: [1], 3: [2, 3], 4: [4, 5]}
```


---

# Minimising a maximum

Balances load across machines by minimising the largest load. The maximum becomes a single auxiliary variable dominating every term; minimisation pushes it to exactly the maximum. Replace max_i e_i by t with t ≥ e_i for all i.

Path: `formulations/minimax`

```
# Minimising a maximum
#
# Balances load across machines by minimising the largest load. The maximum
# becomes a single auxiliary variable dominating every term; minimisation
# pushes it to exactly the maximum.
#
# Technique: Replace max_i e_i by t with t ≥ e_i for all i.
#
# On this instance the optimum is 8 (minimisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Dantzig, G. B. (1963). Linear Programming and Extensions.
# Princeton University Press. doi:10.1515/9781400884179
model m
set J = {1, 2, 3, 4}
set M = {1, 2}
const p = {4, 3, 2, 6}, forall j in J

bin x, forall j in J, forall m in M
int 0 <= t <= 100

min t

# every job on exactly one machine
constr sum_{m in M}{x_{j,m}} = 1, forall j in J
# t dominates each machine load, so minimising t minimises the maximum
constr sum_{j in J}{p_{j} * x_{j,m}} <= t, forall m in M
end

import elytica
```


---

# Multi-period production planning

Plans production across periods where stock carries forward. Unlike lot sizing there is no setup binary, so the whole model stays an LP — the balance row is the only thing coupling periods, and it is what turns a sequence of independent decisions into one plan. Inventory balance links consecutive periods: s_t = s_{t-1} + x_t - d_t, with the first period split out.

Path: `formulations/multi-period-production`

```
# Multi-period production planning
#
# Plans production across periods where stock carries forward. Unlike lot
# sizing there is no setup binary, so the whole model stays an LP — the
# balance row is the only thing coupling periods, and it is what turns a
# sequence of independent decisions into one plan.
#
# Technique: Inventory balance links consecutive periods: s_t = s_{t-1} +
#            x_t - d_t, with the first period split out.
#
# On this instance the optimum is 50 (minimisation), confirmed
# independently by two phase simplex before publication.
#
# Reference: Johnson, L. A. and Montgomery, D. C. (1974). Operations
# Research in Production Planning, Scheduling, and Inventory Control. Wiley.
model m
set T = {1, 2, 3}
const d = {6, 5, 4}, forall t in T
const c = {3, 4, 3}, forall t in T
const h = 3
const lim = 7

var 0 <= x <= infty, forall t in T
var 0 <= s <= infty, forall t in T

min sum_{t in T}{c_{t} * x_{t}} + h * sum_{t in T}{s_{t}}

# per-period production limit
constr x_{t} <= lim, forall t in T
# first period starts from empty stock
constr s_{1} = x_{1} - d_{1}
# later periods carry stock forward
constr s_{t} = s_{t-1} + x_{t} - d_{t}, forall t in T setminus {1}
end

import elytica
```


---

# Multi-commodity flow

Routes several commodities across one network where arcs are shared. The bundle constraint is what destroys total unimodularity: each commodity alone would be integral, but together they can force fractional extreme points, which is why indivisible commodities need integer variables here and not in single-commodity flow. One flow variable per (commodity, arc) with per-commodity balance rows and a shared bundle capacity coupling them.

Path: `formulations/multicommodity-flow`

```
# Multi-commodity flow
#
# Routes several commodities across one network where arcs are shared. The
# bundle constraint is what destroys total unimodularity: each commodity
# alone would be integral, but together they can force fractional extreme
# points, which is why indivisible commodities need integer variables here
# and not in single-commodity flow.
#
# Technique: One flow variable per (commodity, arc) with per-commodity
#            balance rows and a shared bundle capacity coupling them.
#
# On this instance the optimum is 14 (minimisation), confirmed
# independently by two phase simplex before publication.
#
# Reference: Ford, L. R. and Fulkerson, D. R. (1958). A suggested
# computation for maximal multi-commodity network flows. Management Science
# 5(1), 97–101. doi:10.1287/mnsc.5.1.97
model m
set V = {1, 2, 3, 4}
set A = {1, 2, 3, 4, 5}
set K = {1, 2}
set outA(V) = outArcs()
set inA(V) = inArcs()
const c = {5, 2, 5, 3, 5}, forall a in A
const u = {2, 4, 5, 5, 4}, forall a in A
const b = {{1, 0, 0, -1}, {1, 0, 0, -1}}, forall k in K, forall v in V

var 0 <= f <= infty, forall k in K, forall a in A

min sum_{k in K}{sum_{a in A}{c_{a} * f_{k,a}}}

# each commodity conserves independently
constr sum_{a in outA(v)}{f_{k,a}} - sum_{a in inA(v)}{f_{k,a}} = b_{k,v}, forall k in K, forall v in V
# but they share the arc capacity -- this is the coupling that breaks TU
constr sum_{k in K}{f_{k,a}} <= u_{a}, forall a in A
end

import elytica

def outArcs():
  return {1: [1, 2], 2: [3, 4], 3: [5], 4: []}
def inArcs():
  return {1: [], 2: [1], 3: [2, 3], 4: [4, 5]}
```


---

# Multiple knapsack

Packs items into several knapsacks of different capacities. Unlike bin packing, items may be left out entirely and the objective is the value packed rather than the number of bins — the constraint is `<= 1`, not `= 1`. Assignment binaries x_{i,k} with one capacity row per knapsack, and each item assigned at most once across all of them.

Path: `formulations/multiple-knapsack`

```
# Multiple knapsack
#
# Packs items into several knapsacks of different capacities. Unlike bin
# packing, items may be left out entirely and the objective is the value
# packed rather than the number of bins — the constraint is `<= 1`, not `=
# 1`.
#
# Technique: Assignment binaries x_{i,k} with one capacity row per
#            knapsack, and each item assigned at most once across all of
#            them.
#
# On this instance the optimum is 26 (maximisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Martello, S. and Toth, P. (1990). Knapsack Problems: Algorithms
# and Computer Implementations. Wiley.
model m
set I = {1, 2, 3, 4}
set K = {1, 2}
const v = {6, 6, 7, 7}, forall i in I
const w = {4, 2, 3, 4}, forall i in I
const c = {7, 9}, forall k in K

bin x, forall i in I, forall k in K

max sum_{i in I}{sum_{k in K}{v_{i} * x_{i,k}}}

# an item goes into at most one knapsack — it may also be left out
constr sum_{k in K}{x_{i,k}} <= 1, forall i in I
constr sum_{i in I}{w_{i} * x_{i,k}} <= c_{k}, forall k in K
end

import elytica
```


---

# Mutual exclusion and complementarity

Selects from options where certain pairs cannot coexist. The pairwise form is the tightest encoding for isolated conflicts; a clique of mutually conflicting options is better written as one constraint summing over the clique. At most one of a conflicting pair may be chosen: x_i + x_j ≤ 1.

Path: `formulations/mutual-exclusion`

```
# Mutual exclusion and complementarity
#
# Selects from options where certain pairs cannot coexist. The pairwise form
# is the tightest encoding for isolated conflicts; a clique of mutually
# conflicting options is better written as one constraint summing over the
# clique.
#
# Technique: At most one of a conflicting pair may be chosen: x_i + x_j ≤
#            1.
#
# On this instance the optimum is 19 (maximisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Padberg, M. W. (1973). On the facial structure of set packing
# polyhedra. Mathematical Programming 5(1), 199–215. doi:10.1007/BF01580121
model m
set I = {1, 2, 3, 4, 5}
set K = {1, 2, 3, 4}
const v = {6, 7, 6, 3, 6}, forall i in I

bin x, forall i in I

max sum_{i in I}{v_{i} * x_{i}}

# conflicting options may not both be selected
constr x_{first(k)} + x_{second(k)} <= 1, forall k in K
end

import elytica
def first(k):
  return {1: 1, 2: 1, 3: 2, 4: 3}[k]
def second(k):
  return {1: 3, 2: 4, 3: 3, 4: 4}[k]
```


---

# p-center (minimax location)

Places p facilities so the furthest customer is as close as possible. The objective is minimax where p-median is min-sum, so the same data and the same assignment variables give a different answer — this is the equity-oriented counterpart, driven by the worst case rather than the average. Minimise the worst assignment distance with an auxiliary variable: t >= d_{i,j} x_{i,j} for every pair, then minimise t.

Path: `formulations/p-center`

```
# p-center (minimax location)
#
# Places p facilities so the furthest customer is as close as possible. The
# objective is minimax where p-median is min-sum, so the same data and the
# same assignment variables give a different answer — this is the
# equity-oriented counterpart, driven by the worst case rather than the
# average.
#
# Technique: Minimise the worst assignment distance with an auxiliary
#            variable: t >= d_{i,j} x_{i,j} for every pair, then minimise
#            t.
#
# On this instance the optimum is 5 (minimisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Kariv, O. and Hakimi, S. L. (1979). An algorithmic approach to
# network location problems. I: the p-centers. SIAM Journal on Applied
# Mathematics 37(3), 513–538.
model m
set S = {1, 2, 3, 4}
set C = {1, 2, 3, 4}
const d = {{9, 5, 7, 9},
           {1, 2, 10, 1},
           {6, 7, 10, 2},
           {7, 8, 11, 4}}, forall i in C, forall j in S
const p = 2

bin y, forall j in S
bin x, forall i in C, forall j in S
int 0 <= t <= 11

min t

constr sum_{j in S}{x_{i,j}} = 1, forall i in C
constr x_{i,j} <= y_{j}, forall i in C, forall j in S
constr sum_{j in S}{y_{j}} = p
# t dominates every realised assignment distance, so minimising it
# minimises the worst one
constr t >= d_{i,j} * x_{i,j}, forall i in C, forall j in S
end

import elytica
```


---

# p-median facility location

Places a fixed number of facilities to minimise average travel. Differs from uncapacitated location in that the count is a hard constraint rather than a cost, so there is no fixed charge to trade against. Open exactly p facilities and assign each demand point to an open one, minimising total weighted distance.

Path: `formulations/p-median`

```
# p-median facility location
#
# Places a fixed number of facilities to minimise average travel. Differs
# from uncapacitated location in that the count is a hard constraint rather
# than a cost, so there is no fixed charge to trade against.
#
# Technique: Open exactly p facilities and assign each demand point to an
#            open one, minimising total weighted distance.
#
# On this instance the optimum is 7 (minimisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Hakimi, S. L. (1964). Optimum locations of switching centers
# and the absolute centers and medians of a graph. Operations Research
# 12(3), 450–459. doi:10.1287/opre.12.3.450
model m
set S = {1, 2, 3, 4}
set C = {1, 2, 3}
const d = {{12, 12, 4, 10},
           {2, 8, 4, 2},
           {3, 8, 1, 11}}, forall i in C, forall j in S
const p = 3

bin y, forall j in S
bin x, forall i in C, forall j in S

min sum_{i in C}{sum_{j in S}{d_{i,j} * x_{i,j}}}

constr sum_{j in S}{x_{i,j}} = 1, forall i in C
constr x_{i,j} <= y_{j}, forall i in C, forall j in S
# exactly p facilities, no more and no fewer
constr sum_{j in S}{y_{j}} = p
end

import elytica
```


---

# Piecewise-linear, incremental (delta) form

An alternative to the convex-combination form. The level is the sum of filled segment fractions, and ordering constraints force segments to be consumed left to right, so the cost picks up each segment's slope in turn. Locally ideal, and uses one binary fewer than the lambda form. Fill segments in order: delta_s in [0,1], and a segment may only start once the previous one is full, enforced by z_s.

Path: `formulations/piecewise-incremental`

```
# Piecewise-linear, incremental (delta) form
#
# An alternative to the convex-combination form. The level is the sum of
# filled segment fractions, and ordering constraints force segments to be
# consumed left to right, so the cost picks up each segment's slope in turn.
# Locally ideal, and uses one binary fewer than the lambda form.
#
# Technique: Fill segments in order: delta_s in [0,1], and a segment may
#            only start once the previous one is full, enforced by z_s.
#
# On this instance the optimum is 10 (minimisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Markowitz, H. M. and Manne, A. S. (1957). On the solution of
# discrete programming problems. Econometrica 25(1), 84–110.
# doi:10.2307/1907744
model m
set S = {1, 2, 3, 4}
const w = {3, 2, 2, 1}, forall s in S
const g = {2, 2, 4, 5}, forall s in S
const d = 5

var 0 <= delta <= 1, forall s in S
bin z, forall s in S

min sum_{s in S}{g_{s} * w_{s} * delta_{s}}

# the level is the total of the filled segment fractions
constr sum_{s in S}{w_{s} * delta_{s}} >= d
# a segment may only be entered once the previous one is completely full
constr delta_{s} <= z_{s-1}, forall s in S setminus {1}
constr z_{s} <= delta_{s}, forall s in S
end

import elytica
```


---

# Piecewise-linear cost, convex-combination form

Prices an activity along a piecewise-linear cost curve. Both the level and its cost are written as convex combinations of the same breakpoint weights, so any feasible weighting names a point on the curve. Adjacency is enforced with segment binaries, which is what makes the form exact for a non-convex curve rather than only for a convex one. Express x and f(x) as the same convex combination of breakpoints, with the lambda weights summing to 1 and at most two adjacent ones nonzero.

Path: `formulations/piecewise-lambda`

```
# Piecewise-linear cost, convex-combination form
#
# Prices an activity along a piecewise-linear cost curve. Both the level and
# its cost are written as convex combinations of the same breakpoint
# weights, so any feasible weighting names a point on the curve. Adjacency
# is enforced with segment binaries, which is what makes the form exact for
# a non-convex curve rather than only for a convex one.
#
# Technique: Express x and f(x) as the same convex combination of
#            breakpoints, with the lambda weights summing to 1 and at most
#            two adjacent ones nonzero.
#
# On this instance the optimum is 3 (minimisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Dantzig, G. B. (1963). Linear Programming and Extensions.
# Princeton University Press. doi:10.1515/9781400884179
model m
set B = {1, 2, 3}
set S = {1, 2}
const xb = {0, 2, 4}, forall b in B
const fb = {0, 3, 6}, forall b in B
const adj = {{1, 0},
           {1, 1},
           {0, 1}}, forall b in B, forall s in S
const d = 2

var 0 <= lam <= 1, forall b in B
bin z, forall s in S
var 0 <= x <= 4
var 0 <= cost <= 7

min cost

# x and its cost are the SAME convex combination of the breakpoints
constr x = sum_{b in B}{xb_{b} * lam_{b}}
constr cost = sum_{b in B}{fb_{b} * lam_{b}}
constr sum_{b in B}{lam_{b}} = 1

# exactly one segment is active, and only its two endpoints may carry weight
constr sum_{s in S}{z_{s}} = 1
constr lam_{b} <= sum_{s in S}{adj_{b,s} * z_{s}}, forall b in B

constr x >= d
end

import elytica
```


---

# Prize-collecting / orienteering tour

Chooses which customers are worth visiting as well as the order. The degree constraints are equalities against y_i rather than against 1, so a skipped node has no arcs at all; that single change turns a routing problem into a selection-and-routing problem. Visiting is optional — a per-node binary y_i gates its degree constraints, and the objective trades collected prize against travel.

Path: `formulations/prize-collecting-tsp`

```
# Prize-collecting / orienteering tour
#
# Chooses which customers are worth visiting as well as the order. The
# degree constraints are equalities against y_i rather than against 1, so a
# skipped node has no arcs at all; that single change turns a routing
# problem into a selection-and-routing problem.
#
# Technique: Visiting is optional — a per-node binary y_i gates its degree
#            constraints, and the objective trades collected prize against
#            travel.
#
# On this instance the optimum is 25 (maximisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Balas, E. (1989). The prize collecting traveling salesman
# problem. Networks 19(6), 621–636.
model m
set V = {1, 2, 3, 4}
set C = {2, 3, 4}
const c = {{0, 6, 12, 1},
           {6, 0, 10, 4},
           {12, 10, 0, 2},
           {1, 4, 2, 0}}, forall i in V, forall j in V
const p = {0, 19, 11, 14}, forall i in V
const N = 4

bin x, forall i in V, forall j in V
bin y, forall i in V
int 1 <= u <= 4, forall i in V

# prize collected, less the distance travelled
max sum_{i in C}{p_{i} * y_{i}} - sum_{i in V}{sum_{j in V setminus {i}}{c_{i,j} * x_{i,j}}}

# a node has one in-arc and one out-arc exactly when it is visited
constr sum_{i in V setminus {j}}{x_{i,j}} = y_{j}, forall j in C
constr sum_{j in V setminus {i}}{x_{i,j}} = y_{i}, forall i in C
# the tour leaves and returns to the depot once, if it goes anywhere
constr sum_{j in C}{x_{1,j}} = y_{1}
constr sum_{i in C}{x_{i,1}} = y_{1}
constr y_{j} <= y_{1}, forall j in C

constr u_{i} - u_{j} + N * x_{i,j} <= N - 1, forall i in C, forall j in C setminus {i}
end

import elytica
```


---

# Product of a binary and a bounded continuous variable

Switches a continuous quantity on or off inside the objective. The four inequalities pin the auxiliary variable to the product at every integer point of the binary, which is the standard Glover linearization and is exact rather than a relaxation. z = y·x with y binary and 0 ≤ x ≤ U becomes z ≤ Ux, z ≤ y, z ≥ y − U(1 − x), z ≥ 0.

Path: `formulations/product-binary-continuous`

```
# Product of a binary and a bounded continuous variable
#
# Switches a continuous quantity on or off inside the objective. The four
# inequalities pin the auxiliary variable to the product at every integer
# point of the binary, which is the standard Glover linearization and is
# exact rather than a relaxation.
#
# Technique: z = y·x with y binary and 0 ≤ x ≤ U becomes z ≤ Ux, z ≤ y, z ≥
#            y − U(1 − x), z ≥ 0.
#
# On this instance the optimum is 52 (maximisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Glover, F. (1975). Improved linear integer programming
# formulations of nonlinear integer problems. Management Science 22(4),
# 455–460. doi:10.1287/mnsc.22.4.455
model m
set I = {1, 2, 3}
const p = {4, 6, 6}, forall i in I
const c = {6, 4, 4}, forall i in I
const U = 5

bin y, forall i in I
int 0 <= q <= 5, forall i in I
int 0 <= z <= 5, forall i in I

max sum_{i in I}{p_{i} * z_{i}} - sum_{i in I}{c_{i} * y_{i}}

# z_i = y_i * q_i, exact at every 0/1 value of y
constr z_{i} <= U * y_{i}, forall i in I
constr z_{i} <= q_{i}, forall i in I
constr z_{i} >= q_{i} - U * [1 - y_{i}], forall i in I

constr sum_{i in I}{y_{i}} <= 2
end

import elytica
```


---

# Product mix

Chooses how much of each product to make when several products compete for the same limited resources. The optimum generally lands on a vertex with fractional levels, which is why the variables are continuous rather than integer. Continuous activity levels limited by shared resource rows; the canonical linear program.

Path: `formulations/product-mix`

```
# Product mix
#
# Chooses how much of each product to make when several products compete for
# the same limited resources. The optimum generally lands on a vertex with
# fractional levels, which is why the variables are continuous rather than
# integer.
#
# Technique: Continuous activity levels limited by shared resource rows;
#            the canonical linear program.
#
# On this instance the optimum is 26.66666666666667 (maximisation), confirmed
# independently by two phase simplex before publication.
#
# Reference: Dantzig, G. B. (1963). Linear Programming and Extensions.
# Princeton University Press. doi:10.1515/9781400884179
model m
set P = {1, 2, 3}
set R = {1, 2, 3}
const p = {5, 5, 2}, forall j in P
const a = {{1, 1, 3},
           {5, 3, 3},
           {3, 1, 5}}, forall i in R, forall j in P
const b = {29, 16, 11}, forall i in R

var 0 <= x <= infty, forall j in P

max sum_{j in P}{p_{j} * x_{j}}

# each resource is consumed within what is available
constr sum_{j in P}{a_{i,j} * x_{j}} <= b_{i}, forall i in R
end

import elytica
```


---

# Robust counterpart under box uncertainty

Protects a capacity constraint against coefficients that may each vary within a known interval. Because the variables are non-negative, the worst case is attained at the upper corner of every interval independently, so the robust counterpart is another linear constraint with no extra variables — the simplest uncertainty set, and the only one whose counterpart stays an LP with no growth. Replace each uncertain coefficient by its worst-case value over the box: for a <= constraint with non-negative variables, the nominal coefficient plus its deviation.

Path: `formulations/robust-box-uncertainty`

```
# Robust counterpart under box uncertainty
#
# Protects a capacity constraint against coefficients that may each vary
# within a known interval. Because the variables are non-negative, the worst
# case is attained at the upper corner of every interval independently, so
# the robust counterpart is another linear constraint with no extra
# variables — the simplest uncertainty set, and the only one whose
# counterpart stays an LP with no growth.
#
# Technique: Replace each uncertain coefficient by its worst-case value
#            over the box: for a <= constraint with non-negative variables,
#            the nominal coefficient plus its deviation.
#
# On this instance the optimum is 13 (maximisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Soyster, A. L. (1973). Convex programming with set-inclusive
# constraints and applications to inexact linear programming. Operations
# Research 21(5), 1154–1157.
model m
set I = {1, 2, 3, 4}
const v = {5, 3, 4, 4}, forall i in I
const a = {2, 5, 3, 5}, forall i in I
const dev = {1, 3, 1, 2}, forall i in I
const lim = 16

bin x, forall i in I

max sum_{i in I}{v_{i} * x_{i}}

# every coefficient at the top of its interval simultaneously: with x >= 0 that
# is the worst case, so no auxiliary variables are needed
constr sum_{i in I}{[a_{i} + dev_{i}] * x_{i}} <= lim
end

import elytica
```


---

# Semi-continuous variable

Allows an activity to be switched off entirely or run at no less than a minimum viable level. Two linking constraints against the same binary give the disconnected domain {0} ∪ [L, U] exactly. x = 0 or L ≤ x ≤ U, written as L·y ≤ x ≤ U·y with y binary.

Path: `formulations/semi-continuous`

```
# Semi-continuous variable
#
# Allows an activity to be switched off entirely or run at no less than a
# minimum viable level. Two linking constraints against the same binary give
# the disconnected domain {0} ∪ [L, U] exactly.
#
# Technique: x = 0 or L ≤ x ≤ U, written as L·y ≤ x ≤ U·y with y binary.
#
# On this instance the optimum is 28 (maximisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Beale, E. M. L. (1968). Mathematical Programming in Practice.
# Pitman.
model m
set I = {1, 2, 3}
const p = {6, 3, 8}, forall i in I
const l = {2, 3, 2}, forall i in I
const u = {5, 6, 3}, forall i in I
const c = 4

int 0 <= x <= 6, forall i in I
bin y, forall i in I

max sum_{i in I}{p_{i} * x_{i}}

# either off (y = 0, forcing x = 0) or running at a viable level
constr x_{i} >= l_{i} * y_{i}, forall i in I
constr x_{i} <= u_{i} * y_{i}, forall i in I
constr sum_{i in I}{x_{i}} <= c
end

import elytica
```


---

# Weighted set covering

Chooses the cheapest collection of subsets whose union is the whole ground set. The element-to-subset incidence is supplied as a parametric set, which is the natural encoding when membership is data rather than structure. Cover each element by summing the indicator of every set that contains it, using a parametric set of covering sets per element.

Path: `formulations/set-cover`

```
# Weighted set covering
#
# Chooses the cheapest collection of subsets whose union is the whole ground
# set. The element-to-subset incidence is supplied as a parametric set,
# which is the natural encoding when membership is data rather than
# structure.
#
# Technique: Cover each element by summing the indicator of every set that
#            contains it, using a parametric set of covering sets per
#            element.
#
# On this instance the optimum is 3 (minimisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Balas, E. and Padberg, M. W. (1976). Set partitioning: a
# survey. SIAM Review 18(4), 710–760. doi:10.1137/1018115
model m
set S = {1, 2, 3, 4, 5, 6}
set El = {1, 2, 3, 4}
set cov(El) = coveringSets()
const c = {5, 3, 9, 9, 6, 2}, forall s in S

bin x, forall s in S

min sum_{s in S}{c_{s} * x_{s}}

# every element must be covered by at least one chosen subset
constr sum_{s in cov(e)}{x_{s}} >= 1, forall e in El
end

import elytica
def coveringSets():
  return {1: [2, 4, 5], 2: [1, 2, 3, 4], 3: [2, 3, 4, 5], 4: [1, 2, 3]}
```


---

# Set partitioning

Chooses subsets so that every element is covered exactly once — no gaps and no overlap. The equality is what separates it from set covering, and it is the backbone of crew pairing and rostering, where a duty must be flown once rather than at least once. Cover every element exactly once: Ax = 1, rather than the Ax >= 1 of covering or the Ax <= 1 of packing.

Path: `formulations/set-partitioning`

```
# Set partitioning
#
# Chooses subsets so that every element is covered exactly once — no gaps
# and no overlap. The equality is what separates it from set covering, and
# it is the backbone of crew pairing and rostering, where a duty must be
# flown once rather than at least once.
#
# Technique: Cover every element exactly once: Ax = 1, rather than the Ax
#            >= 1 of covering or the Ax <= 1 of packing.
#
# On this instance the optimum is 12 (minimisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Balas, E. and Padberg, M. W. (1976). Set partitioning: a
# survey. SIAM Review 18(4), 710–760. doi:10.1137/1018115
model m
set S = {1, 2, 3, 4, 5, 6, 7}
set El = {1, 2, 3, 4}
set cov(El) = coveringSets()
const c = {9, 8, 6, 9, 7, 3, 2}, forall s in S

bin x, forall s in S

min sum_{s in S}{c_{s} * x_{s}}

# exactly once — not at least once, and not at most once
constr sum_{s in cov(e)}{x_{s}} = 1, forall e in El
end

import elytica
def coveringSets():
  return {1: [1, 5], 2: [2, 6], 3: [3, 7], 4: [4, 6]}
```


---

# Shortest path by arc selection

Finds a least-cost path as a unit flow. Arcs are a flat index set with script functions giving tail and head, and the balance constraint sums over parametric out/in arc sets per node. Flow conservation on node balances: outflow − inflow equals +1 at the source, −1 at the sink, 0 elsewhere.

Path: `formulations/shortest-path-arc`

```
# Shortest path by arc selection
#
# Finds a least-cost path as a unit flow. Arcs are a flat index set with
# script functions giving tail and head, and the balance constraint sums
# over parametric out/in arc sets per node.
#
# Technique: Flow conservation on node balances: outflow − inflow equals +1
#            at the source, −1 at the sink, 0 elsewhere.
#
# On this instance the optimum is 12 (minimisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Ahuja, R. K., Magnanti, T. L. and Orlin, J. B. (1993). Network
# Flows: Theory, Algorithms, and Applications. Prentice Hall.
model m
set V = {1, 2, 3, 4, 5}
set A = {1, 2, 3, 4, 5, 6, 7}
set outA(V) = outArcs()
set inA(V) = inArcs()
const c = {9, 4, 9, 5, 8, 8, 5}, forall a in A
const b = {1, 0, 0, 0, -1}, forall v in V

bin x, forall a in A

min sum_{a in A}{c_{a} * x_{a}}

# unit flow leaves the source, arrives at the sink, balances elsewhere
constr sum_{a in outA(v)}{x_{a}} - sum_{a in inA(v)}{x_{a}} = b_{v}, forall v in V
end

import elytica
def outArcs():
  return {1: [1, 2], 2: [3, 4], 3: [5, 6], 4: [7], 5: []}
def inArcs():
  return {1: [], 2: [1], 3: [2, 3], 4: [4, 5], 5: [6, 7]}
```


---

# Single-machine sequencing, disjunctive (big-M) formulation

Sequences jobs on one machine to minimise the makespan-equivalent completion of the last job. Time stays continuous and only the pairwise ordering is discrete, which keeps the model small — but the big-M rows give a weak relaxation, since a fractional y_ij releases both orderings at once. Continuous start times with a binary per pair deciding the order: s_j >= s_i + p_i - M(1 - y_ij) and the mirrored inequality.

Path: `formulations/single-machine-disjunctive`

```
# Single-machine sequencing, disjunctive (big-M) formulation
#
# Sequences jobs on one machine to minimise the makespan-equivalent
# completion of the last job. Time stays continuous and only the pairwise
# ordering is discrete, which keeps the model small — but the big-M rows
# give a weak relaxation, since a fractional y_ij releases both orderings at
# once.
#
# Technique: Continuous start times with a binary per pair deciding the
#            order: s_j >= s_i + p_i - M(1 - y_ij) and the mirrored
#            inequality.
#
# On this instance the optimum is 9 (minimisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Manne, A. S. (1960). On the job-shop scheduling problem.
# Operations Research 8(2), 219–223.
model m
set J = {1, 2, 3, 4}
set P = {1, 2, 3, 4, 5, 6}
const p = {1, 1, 1, 6}, forall j in J
const rel = {1, 0, 2, 2}, forall j in J
const M = 12

var 0 <= s <= 11, forall j in J
var 0 <= mk <= 11
bin y, forall q in P

min mk

# no job starts before it is released
constr s_{j} >= rel_{j}, forall j in J
# makespan dominates every completion
constr mk >= s_{j} + p_{j}, forall j in J
# for each pair exactly one order holds; the other row is relaxed by M
constr s_{second(q)} >= s_{first(q)} + p_{first(q)} - M * [1 - y_{q}], forall q in P
constr s_{first(q)} >= s_{second(q)} + p_{second(q)} - M * y_{q}, forall q in P
end

import elytica
def first(q):
  return {1: 1, 2: 1, 3: 1, 4: 2, 5: 2, 6: 3}[q]
def second(q):
  return {1: 2, 2: 3, 3: 4, 4: 3, 5: 4, 6: 4}[q]
```


---

# At most one nonzero (SOS1 by binaries)

Permits at most one activity to take a nonzero value, the condition a solver would otherwise express as a special ordered set of type 1. Written with explicit binaries and variable upper bounds it needs no solver-specific declaration. Bound each continuous variable by its own indicator and allow at most one indicator to be 1.

Path: `formulations/sos1-at-most-one`

```
# At most one nonzero (SOS1 by binaries)
#
# Permits at most one activity to take a nonzero value, the condition a
# solver would otherwise express as a special ordered set of type 1. Written
# with explicit binaries and variable upper bounds it needs no
# solver-specific declaration.
#
# Technique: Bound each continuous variable by its own indicator and allow
#            at most one indicator to be 1.
#
# On this instance the optimum is 18 (maximisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Beale, E. M. L. and Tomlin, J. A. (1970). Special facilities in
# a general mathematical programming system for non-convex problems using
# ordered sets of variables. OR 69, 447–454.
model m
set I = {1, 2, 3, 4, 5}
const p = {3, 3, 3, 2, 5}, forall i in I
const u = {5, 6, 2, 7, 3}, forall i in I

var 0 <= x <= infty, forall i in I
bin y, forall i in I

max sum_{i in I}{p_{i} * x_{i}}

# x_i is zero unless its indicator is on, and only one may be on
constr x_{i} <= u_{i} * y_{i}, forall i in I
constr sum_{i in I}{y_{i}} <= 1
end

import elytica
```


---

# Piecewise-linear via SOS2-style adjacency

Evaluates a piecewise-linear function using the adjacency condition a solver would express as a special ordered set of type 2. Written out with binaries it needs no solver-specific declaration, at the cost of one binary per segment — the same trade the SOS1 case makes. At most two lambda weights may be nonzero and they must be adjacent — written with one binary per breakpoint pair rather than a solver-native SOS2 declaration.

Path: `formulations/sos2-piecewise`

```
# Piecewise-linear via SOS2-style adjacency
#
# Evaluates a piecewise-linear function using the adjacency condition a
# solver would express as a special ordered set of type 2. Written out with
# binaries it needs no solver-specific declaration, at the cost of one
# binary per segment — the same trade the SOS1 case makes.
#
# Technique: At most two lambda weights may be nonzero and they must be
#            adjacent — written with one binary per breakpoint pair rather
#            than a solver-native SOS2 declaration.
#
# On this instance the optimum is 2.5 (minimisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Beale, E. M. L. and Tomlin, J. A. (1970). Special facilities in
# a general mathematical programming system for non-convex problems using
# ordered sets of variables. OR 69, 447–454.
model m
set B = {1, 2, 3}
set S = {1, 2}
const xb = {0, 2, 4}, forall b in B
const fb = {0, 5, 16}, forall b in B
const adj = {{1, 0},
           {1, 1},
           {0, 1}}, forall b in B, forall s in S
const need = 1

var 0 <= lam <= 1, forall b in B
bin z, forall s in S
var 0 <= lvl <= 4
var 0 <= cost <= 17

min cost

constr lvl = sum_{b in B}{xb_{b} * lam_{b}}
constr cost = sum_{b in B}{fb_{b} * lam_{b}}
constr sum_{b in B}{lam_{b}} = 1

# exactly one segment active; only its two endpoints may carry weight,
# which is precisely the SOS2 adjacency condition
constr sum_{s in S}{z_{s}} = 1
constr lam_{b} <= sum_{s in S}{adj_{b,s} * z_{s}}, forall b in B

constr lvl >= need
end

import elytica
```


---

# Minimum spanning tree

Connects every vertex at least total cost. The cardinality row alone would allow a forest plus a cycle, so the subset rows are what force acyclicity — the same family DFJ uses for tours, applied to trees. The LP relaxation of this description is integral, which is why a greedy algorithm solves it exactly. Pick exactly |V| - 1 edges and forbid a cycle in every subset: edges inside S number at most |S| - 1.

Path: `formulations/spanning-tree`

```
# Minimum spanning tree
#
# Connects every vertex at least total cost. The cardinality row alone would
# allow a forest plus a cycle, so the subset rows are what force acyclicity
# — the same family DFJ uses for tours, applied to trees. The LP relaxation
# of this description is integral, which is why a greedy algorithm solves it
# exactly.
#
# Technique: Pick exactly |V| - 1 edges and forbid a cycle in every subset:
#            edges inside S number at most |S| - 1.
#
# On this instance the optimum is 13 (minimisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Edmonds, J. (1971). Matroids and the greedy algorithm.
# Mathematical Programming 1(1), 127–136.
model m
set V = {1, 2, 3, 4}
set E = {1, 2, 3, 4, 5, 6}
set K = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}
const w = {2, 8, 3, 12, 6, 14}, forall e in E
const inside = {{1, 0, 0, 0, 0, 0},
           {0, 1, 0, 0, 0, 0},
           {0, 0, 0, 1, 0, 0},
           {1, 1, 0, 1, 0, 0},
           {0, 0, 1, 0, 0, 0},
           {0, 0, 0, 0, 1, 0},
           {1, 0, 1, 0, 1, 0},
           {0, 0, 0, 0, 0, 1},
           {0, 1, 1, 0, 0, 1},
           {0, 0, 0, 1, 1, 1}}, forall k in K, forall e in E
const sz = {2, 2, 2, 3, 2, 2, 3, 2, 3, 3}, forall k in K

bin x, forall e in E

min sum_{e in E}{w_{e} * x_{e}}

# a spanning tree on n vertices has exactly n - 1 edges
constr sum_{e in E}{x_{e}} = 3
# no subset may hold enough edges to contain a cycle
constr sum_{e in E}{inside_{k,e} * x_{e}} <= sz_{k} - 1, forall k in K
end

import elytica
```


---

# Subset sum

Selects items summing to exactly a target. Degenerate as an optimisation problem — the objective is a formality and every feasible point is optimal — which makes it the cleanest illustration that a MIP can be a pure feasibility question. A single equality over binaries: hit the target exactly, with no objective to optimise beyond feasibility.

Path: `formulations/subset-sum`

```
# Subset sum
#
# Selects items summing to exactly a target. Degenerate as an optimisation
# problem — the objective is a formality and every feasible point is optimal
# — which makes it the cleanest illustration that a MIP can be a pure
# feasibility question.
#
# Technique: A single equality over binaries: hit the target exactly, with
#            no objective to optimise beyond feasibility.
#
# On this instance the optimum is 0 (maximisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Karp, R. M. (1972). Reducibility among combinatorial problems.
# Complexity of Computer Computations, 85–103.
model m
set I = {1, 2, 3, 4, 5, 6}
const w = {9, 6, 11, 10, 13, 4}, forall i in I
const t = 23

bin x, forall i in I

# nothing to optimise — any feasible selection is a solution
max sum_{i in I}{0 * x_{i}}

constr sum_{i in I}{w_{i} * x_{i}} = t
end

import elytica
```


---

# Time-indexed scheduling

Schedules jobs by deciding which period each one starts in. Far more variables than the disjunctive form — one per job-period pair — but the relaxation is much tighter and resource limits become a single sum per period instead of a big-M pair per job pair. A binary x_{j,t} for starting job j in period t. Each job starts once; a machine-capacity row per period covers the jobs spanning it.

Path: `formulations/time-indexed-scheduling`

```
# Time-indexed scheduling
#
# Schedules jobs by deciding which period each one starts in. Far more
# variables than the disjunctive form — one per job-period pair — but the
# relaxation is much tighter and resource limits become a single sum per
# period instead of a big-M pair per job pair.
#
# Technique: A binary x_{j,t} for starting job j in period t. Each job
#            starts once; a machine-capacity row per period covers the jobs
#            spanning it.
#
# On this instance the optimum is 11 (minimisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Pritsker, A. A. B., Watters, L. J. and Wolfe, P. M. (1969).
# Multiproject scheduling with limited resources: a zero-one programming
# approach. Management Science 16(1), 93–108.
model m
set J = {1, 2, 3}
set T = {1, 2, 3, 4}
const w = {6, 2, 3}, forall j in J
const p = {1, 1, 1}, forall j in J

bin x, forall j in J, forall t in T

# weighted start time: later starts cost more
min sum_{j in J}{sum_{t in T}{w_{j} * t * x_{j,t}}}

# every job starts exactly once
constr sum_{t in T}{x_{j,t}} = 1, forall j in J
# a job may not start so late that it runs past the horizon
constr sum_{t in T}{[t + p_{j}] * x_{j,t}} <= 5, forall j in J
end

import elytica
```


---

# Transportation problem

Ships goods from plants to markets at least cost. With integer supplies and demands the constraint matrix is totally unimodular, so the LP optimum is already integral — the classic demonstration that not every whole-number answer needs integer variables. Supply rows, demand rows and continuous shipment quantities on every origin-destination pair.

Path: `formulations/transportation`

```
# Transportation problem
#
# Ships goods from plants to markets at least cost. With integer supplies
# and demands the constraint matrix is totally unimodular, so the LP optimum
# is already integral — the classic demonstration that not every
# whole-number answer needs integer variables.
#
# Technique: Supply rows, demand rows and continuous shipment quantities on
#            every origin-destination pair.
#
# On this instance the optimum is 19 (minimisation), confirmed
# independently by two phase simplex before publication.
#
# Reference: Hitchcock, F. L. (1941). The distribution of a product from
# several sources to numerous localities. Journal of Mathematics and Physics
# 20(1–4), 224–230. doi:10.1002/sapm1941201224
model m
set S = {1, 2}
set D = {1, 2}
const c = {{2, 4},
           {5, 1}}, forall i in S, forall j in D
const s = {9, 9}, forall i in S
const d = {6, 7}, forall j in D

var 0 <= x <= infty, forall i in S, forall j in D

min sum_{i in S}{sum_{j in D}{c_{i,j} * x_{i,j}}}

constr sum_{j in D}{x_{i,j}} <= s_{i}, forall i in S
constr sum_{i in S}{x_{i,j}} >= d_{j}, forall j in D
end

import elytica
```


---

# Transshipment

Ships from plants to markets through intermediate warehouses. The only structural difference from transportation is the presence of nodes whose balance is zero: they neither produce nor consume, they relay. Still totally unimodular, so still integral without integer variables. Node balance where intermediate nodes have zero supply, so flow passes through rather than originating or terminating.

Path: `formulations/transshipment`

```
# Transshipment
#
# Ships from plants to markets through intermediate warehouses. The only
# structural difference from transportation is the presence of nodes whose
# balance is zero: they neither produce nor consume, they relay. Still
# totally unimodular, so still integral without integer variables.
#
# Technique: Node balance where intermediate nodes have zero supply, so
#            flow passes through rather than originating or terminating.
#
# On this instance the optimum is 20 (minimisation), confirmed
# independently by two phase simplex before publication.
#
# Reference: Orden, A. (1956). The transhipment problem. Management Science
# 2(3), 276–285. doi:10.1287/mnsc.2.3.276
model m
set V = {1, 2, 3, 4, 5}
set P = {1, 2}
set W = {3}
set M = {4, 5}
set A = {1, 2, 3, 4}
set outA(V) = outArcs()
set inA(V) = inArcs()
const c = {4, 5, 8, 3}, forall a in A
const s = 1
const d = {1, 1}, forall k in M

var 0 <= f <= infty, forall a in A

min sum_{a in A}{c_{a} * f_{a}}

# plants ship no more than they hold
constr sum_{a in outA(p)}{f_{a}} <= s, forall p in P
# warehouses relay: whatever arrives leaves again
constr sum_{a in outA(w)}{f_{a}} - sum_{a in inA(w)}{f_{a}} = 0, forall w in W
# markets receive their demand
constr sum_{a in inA(k)}{f_{a}} >= d_{k}, forall k in M
end

import elytica

def outArcs():
  return {1: [1], 2: [2], 3: [3, 4], 4: [], 5: []}
def inArcs():
  return {1: [], 2: [], 3: [1, 2], 4: [3], 5: [4]}
```


---

# Travelling salesman, DFJ subtour elimination

The same tours as the MTZ formulation, described a different way. DFJ needs exponentially many constraints — one per subset — where MTZ needs a polynomial number of potentials, but DFJ's relaxation is strictly stronger. In practice the subsets are separated lazily; here they are all written out, which is only tractable because the instance is small. One constraint per proper subset: sum of arcs inside S is at most |S| - 1, so no subset can close a tour of its own.

Path: `formulations/tsp-dfj-subtour`

```
# Travelling salesman, DFJ subtour elimination
#
# The same tours as the MTZ formulation, described a different way. DFJ
# needs exponentially many constraints — one per subset — where MTZ needs a
# polynomial number of potentials, but DFJ's relaxation is strictly
# stronger. In practice the subsets are separated lazily; here they are all
# written out, which is only tractable because the instance is small.
#
# Technique: One constraint per proper subset: sum of arcs inside S is at
#            most |S| - 1, so no subset can close a tour of its own.
#
# On this instance the optimum is 33 (minimisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Dantzig, G., Fulkerson, R. and Johnson, S. (1954). Solution of
# a large-scale traveling-salesman problem. Journal of the Operations
# Research Society of America 2(4), 393–410.
model m
set V = {1, 2, 3, 4}
set K = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}
const c = {{0, 9, 5, 6},
           {9, 0, 11, 14},
           {5, 11, 0, 7},
           {6, 14, 7, 0}}, forall i in V, forall j in V
const inS = {{1, 1, 0, 0},
           {1, 0, 1, 0},
           {0, 1, 1, 0},
           {1, 1, 1, 0},
           {1, 0, 0, 1},
           {0, 1, 0, 1},
           {1, 1, 0, 1},
           {0, 0, 1, 1},
           {1, 0, 1, 1},
           {0, 1, 1, 1}}, forall k in K, forall v in V
const sz = {2, 2, 2, 3, 2, 2, 3, 2, 3, 3}, forall k in K

bin x, forall i in V, forall j in V

min sum_{i in V}{sum_{j in V setminus {i}}{c_{i,j} * x_{i,j}}}

constr sum_{j in V setminus {i}}{x_{i,j}} = 1, forall i in V
constr sum_{j in V setminus {i}}{x_{j,i}} = 1, forall i in V

# no proper subset may carry enough arcs to close its own tour
constr sum_{i in V}{sum_{j in V setminus {i}}{inS_{k,i} * inS_{k,j} * x_{i,j}}} <= sz_{k} - 1, forall k in K
end

import elytica
```


---

# Travelling salesman with MTZ subtour elimination

Finds a minimum-cost Hamiltonian tour. Degree constraints alone admit disconnected subtours; the MTZ potentials rule them out compactly, at the cost of a weaker relaxation than exponential subtour cuts. Sequence potentials u_i with u_i − u_j + n·x_ij ≤ n − 1 forbid subtours with a polynomial number of constraints.

Path: `formulations/tsp-mtz`

```
# Travelling salesman with MTZ subtour elimination
#
# Finds a minimum-cost Hamiltonian tour. Degree constraints alone admit
# disconnected subtours; the MTZ potentials rule them out compactly, at the
# cost of a weaker relaxation than exponential subtour cuts.
#
# Technique: Sequence potentials u_i with u_i − u_j + n·x_ij ≤ n − 1 forbid
#            subtours with a polynomial number of constraints.
#
# On this instance the optimum is 25 (minimisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Miller, C. E., Tucker, A. W. and Zemlin, R. A. (1960). Integer
# programming formulation of traveling salesman problems. Journal of the ACM
# 7(4), 326–329. doi:10.1145/321043.321046
model m
set V = {1, 2, 3, 4}
const c = {{0, 11, 10, 7},
           {11, 0, 1, 7},
           {10, 1, 0, 11},
           {7, 7, 11, 0}}, forall i in V, forall j in V

bin x, forall i in V, forall j in V
int 1 <= u <= 4, forall i in V

min sum_{i in V}{sum_{j in V setminus {i}}{c_{i,j} * x_{i,j}}}

constr sum_{j in V setminus {i}}{x_{i,j}} = 1, forall i in V
constr sum_{j in V setminus {i}}{x_{j,i}} = 1, forall i in V
# MTZ potentials: no subtour can close without violating the ordering
constr u_{i} - u_{j} + 4 * x_{i,j} <= 3, forall i in V setminus {1}, forall j in V setminus {i, 1}
end

import elytica
```


---

# Two-stage stochastic programme with recourse

Chooses a capacity before demand is known, then meets whatever demand arrives by buying the shortfall at a penalty. The first-stage variable is shared across every scenario while the recourse variables are indexed by scenario — that split is the whole formulation, and it is what makes the model larger than the deterministic version by a factor of the scenario count. One here-and-now decision, then a separate wait-and-see decision per scenario, with the objective weighting recourse cost by scenario probability.

Path: `formulations/two-stage-recourse`

```
# Two-stage stochastic programme with recourse
#
# Chooses a capacity before demand is known, then meets whatever demand
# arrives by buying the shortfall at a penalty. The first-stage variable is
# shared across every scenario while the recourse variables are indexed by
# scenario — that split is the whole formulation, and it is what makes the
# model larger than the deterministic version by a factor of the scenario
# count.
#
# Technique: One here-and-now decision, then a separate wait-and-see
#            decision per scenario, with the objective weighting recourse
#            cost by scenario probability.
#
# On this instance the optimum is 83 (minimisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Dantzig, G. B. (1955). Linear programming under uncertainty.
# Management Science 1(3–4), 197–206.
model m
set S = {1, 2, 3, 4}
const d = {3, 2, 4, 7}, forall s in S
const c = 4
const p = 7
const n = 4

# first stage: chosen before the scenario is known, shared by all of them
int 0 <= lim <= 7
# second stage: one shortfall variable per scenario
int 0 <= short <= 7, forall s in S

# n * (build cost) + sum of scenario penalties, i.e. n times the expected total
min n * c * lim + p * sum_{s in S}{short_{s}}

# whatever capacity does not cover must be bought at the penalty rate
constr lim + short_{s} >= d_{s}, forall s in S
end

import elytica
```


---

# Uncapacitated facility location

Opens facilities and assigns every customer to one, trading fixed opening cost against service cost. The disaggregated linking constraint is used rather than sum_i x_ij <= n·y_j, because the disaggregated form gives a substantially stronger LP relaxation. Variable upper bound x_{i,j} <= y_j links assignment to an open facility, which is tighter than aggregating into one big-M row.

Path: `formulations/uncapacitated-facility-location`

```
# Uncapacitated facility location
#
# Opens facilities and assigns every customer to one, trading fixed opening
# cost against service cost. The disaggregated linking constraint is used
# rather than sum_i x_ij <= n·y_j, because the disaggregated form gives a
# substantially stronger LP relaxation.
#
# Technique: Variable upper bound x_{i,j} <= y_j links assignment to an
#            open facility, which is tighter than aggregating into one
#            big-M row.
#
# On this instance the optimum is 16 (minimisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Balinski, M. L. (1965). Integer programming: methods, uses,
# computation. Management Science 12(3), 253–313. doi:10.1287/mnsc.12.3.253
model m
set F = {1, 2, 3}
set C = {1, 2, 3, 4}
const f = {6, 5, 9}, forall j in F
const c = {{7, 4, 1},
           {4, 1, 4},
           {5, 3, 4},
           {6, 3, 1}}, forall i in C, forall j in F

bin y, forall j in F
bin x, forall i in C, forall j in F

min sum_{i in C}{sum_{j in F}{c_{i,j} * x_{i,j}}} + sum_{j in F}{f_{j} * y_{j}}

# each customer served exactly once
constr sum_{j in F}{x_{i,j}} = 1, forall i in C
# and only by a facility that is open (disaggregated form)
constr x_{i,j} <= y_{j}, forall i in C, forall j in F
end

import elytica
```


---

# Minimum weighted vertex cover

Chooses the cheapest set of vertices touching every edge. Because sets hold plain integers, the edge list is a flat index set and incidence is supplied by two script functions mapping an edge to its endpoints. Address node variables from an edge-indexed constraint via endpoint mapping functions: y_{alpha(e)} + y_{beta(e)} >= 1.

Path: `formulations/vertex-cover`

```
# Minimum weighted vertex cover
#
# Chooses the cheapest set of vertices touching every edge. Because sets
# hold plain integers, the edge list is a flat index set and incidence is
# supplied by two script functions mapping an edge to its endpoints.
#
# Technique: Address node variables from an edge-indexed constraint via
#            endpoint mapping functions: y_{alpha(e)} + y_{beta(e)} >= 1.
#
# On this instance the optimum is 5 (minimisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Nemhauser, G. L. and Trotter, L. E. (1975). Vertex packings:
# structural properties and algorithms. Mathematical Programming 8, 232–248.
# doi:10.1007/BF01580444
model m
set V = {1, 2, 3, 4}
set E = {1, 2, 3, 4}
const w = {1, 6, 3, 1}, forall v in V

bin y, forall v in V

min sum_{v in V}{w_{v} * y_{v}}

# every edge needs at least one of its two endpoints chosen
constr y_{alpha(e)} + y_{beta(e)} >= 1, forall e in E
end

import elytica

def alpha(e):
  return {1: 1, 2: 2, 3: 3, 4: 2}[e]
def beta(e):
  return {1: 2, 2: 3, 3: 4, 4: 4}[e]
```


---

# Weighted single objective over several criteria

Trades profit against risk inside one objective row. The language admits a single min or max per model, so combining criteria is done by weighting them rather than by declaring several objectives. Varying the weights traces the convex hull of the efficient set, though not points lying in a non-convex dent -- for those, bound the secondary criterion instead. A model has exactly one objective, so competing criteria are folded into it as a weighted sum with non-negative weights.

Path: `formulations/weighted-single-objective`

```
# Weighted single objective over several criteria
#
# Trades profit against risk inside one objective row. The language admits a
# single min or max per model, so combining criteria is done by weighting
# them rather than by declaring several objectives. Varying the weights
# traces the convex hull of the efficient set, though not points lying in a
# non-convex dent -- for those, bound the secondary criterion instead.
#
# Technique: A model has exactly one objective, so competing criteria are
#            folded into it as a weighted sum with non-negative weights.
#
# On this instance the optimum is 11 (maximisation), confirmed
# independently by exhaustive enumeration before publication.
#
# Reference: Zadeh, L. (1963). Optimality and non-scalar-valued performance
# criteria. IEEE Transactions on Automatic Control 8(1), 59–60.
# doi:10.1109/TAC.1963.1105511
model m
set I = {1, 2, 3, 4, 5, 6, 7}
const p = {2, 2, 6, 4, 6, 9, 6}, forall i in I
const r = {3, 5, 3, 1, 8, 4, 9}, forall i in I

bin x, forall i in I

# one objective row: the two criteria are weighted into it
max 2 * sum_{i in I}{p_{i} * x_{i}} - 3 * sum_{i in I}{r_{i} * x_{i}}

constr sum_{i in I}{x_{i}} <= 2
end

import elytica
```


---

# Zero-sum matrix game

Finds the optimal mixed strategy and value of a two-player zero-sum game. The minimax structure becomes an LP: one variable per pure strategy plus the game value, and one row per opponent reply. Its dual is the opponent's own problem, which is von Neumann's minimax theorem read off LP duality. Maximise the value v subject to v <= the payoff of every pure opponent reply, with the mixed strategy summing to 1.

Path: `formulations/zero-sum-game`

```
# Zero-sum matrix game
#
# Finds the optimal mixed strategy and value of a two-player zero-sum game.
# The minimax structure becomes an LP: one variable per pure strategy plus
# the game value, and one row per opponent reply. Its dual is the opponent's
# own problem, which is von Neumann's minimax theorem read off LP duality.
#
# Technique: Maximise the value v subject to v <= the payoff of every pure
#            opponent reply, with the mixed strategy summing to 1.
#
# On this instance the optimum is 3 (maximisation), confirmed
# independently by two phase simplex before publication.
#
# Reference: Dantzig, G. B. (1963). Linear Programming and Extensions.
# Princeton University Press. doi:10.1515/9781400884179
model m
set R = {1, 2, 3}
set C = {1, 2, 3}
const A = {{7, 5, 3},
           {7, 9, 3},
           {6, 1, 2}}, forall i in R, forall j in C

var 0 <= p <= 1, forall i in R
var 0 <= v <= 9

max v

# the mixed strategy is a probability distribution
constr sum_{i in R}{p_{i}} = 1
# v is guaranteed against every pure reply the opponent could make
constr v <= sum_{i in R}{A_{i,j} * p_{i}}, forall j in C
end

import elytica
```


---

# What is a linear program?

0 — LP theory — A precise definition, three forms, one toy problem.

Path: `lessons/lp-what`

# What is a linear program?

A precise definition, three forms, one toy problem.

*Chapter: 0 — LP theory · lesson id `lp-what` · theory lesson*

---

Optimisation is everywhere: schedule a fleet of trucks, blend petroleum, dose chemotherapy, route data through a network. The trick that makes a particular slice of these problems tractable is $linearity$. If the objective and every constraint are linear in the decisions, we have a $linear\ program$, and we get an elegant theory and decades of polished algorithms in return.

## Notes

**Definition (Linear program (standard form)).** A linear program in standard form is the problem $$\min_{x \in \mathbb{R}^n} \; c^{\top} x \quad \text{subject to} \quad A x = b, \; x \geq 0,$$ where $c \in \mathbb{R}^n$, $A \in \mathbb{R}^{m \times n}$, and $b \in \mathbb{R}^m$ are given. The feasible set $\{x \in \mathbb{R}^n : Ax = b, \; x \geq 0\}$ is the $feasible\ region$. A point in it is $feasible$; a point achieving the minimum is $optimal$.

There is nothing sacred about standard form. Real LPs come with inequality constraints, free variables, mixed signs, and the optimisation sense flips between $\min$ and $\max$. Every such variant rewrites into the form above:

A $\leq$ inequality $a^{\top} x \leq \beta$ becomes equality $a^{\top} x + s = \beta$ by introducing a $slack\ variable$ $s \geq 0$. A free variable $x \in \mathbb{R}$ becomes $x = x^{+} - x^{-}$ with $x^{\pm} \geq 0$. A maximisation $\max c^{\top} x$ becomes $-\min (-c)^{\top} x$. The transformations are routine; do not let "standard form" make you uneasy.

**Definition (Canonical form).** It is often more convenient to work with $$\min_{x \geq 0} c^{\top} x \quad \text{subject to} \quad A x \geq b.$$ This is called $canonical\ form$. Standard and canonical forms are equivalent up to slack variables and sign flips.

### The smallest interesting example

You can make two products. Each unit of product 1 needs $1$ hour of labour and $2$ units of raw material; each unit of product 2 needs $3$ hours and $1$ unit of material. You have $12$ hours and $8$ units of material. Product 1 sells for \$$3$ per unit, product 2 for \$$5$. How much of each should you make?

$$
\begin{aligned} \max \; & 3 x_{1} + 5 x_{2} \\ \text{s.t.} \; & x_{1} + 3 x_{2} \leq 12 \\ & 2 x_{1} + x_{2} \leq 8 \\ & x_{1}, x_{2} \geq 0 \end{aligned}
$$

Every term in every inequality is either a constant or a constant times a decision variable. Same for the objective. $Linear$ programs.

*[feasible-region diagram: Feasible region of the toy LP: the polygon bounded by the labour and material constraints in the first quadrant.]*

> The shaded polygon is the feasible region. The dashed lines are the objective contours; they are parallel because the objective is linear. The optimum sits where the contour with the highest value still touches the polygon, which (we will prove next lesson) is always at a $corner$.

**Quick check.** Which of the following is <strong>not</strong> a linear program?

- $\min \; 3x + 2y \;$ s.t. $\; x + y \leq 5,\; x, y \geq 0$
- $\min \; x^{2} + y^{2} \;$ s.t. $\; x + y \leq 5$  ← correct
- $\max \; \sum_{i \in N} c_{i} x_{i} \;$ s.t. $\; A x \leq b,\; x \geq 0$

### Three outcomes

When you hand an LP to a solver, exactly one of three things happens:

$1.\ Optimal$: the feasible region is non-empty and the objective is bounded; the solver returns the optimal value and an optimal $x^{*}$.

$2.\ Infeasible$: the feasible region is empty. The constraints contradict each other. Example: $x \geq 5$ and $x \leq 2$.

$3.\ Unbounded$: the feasible region is non-empty but the objective can be made arbitrarily small (for $\min$) or large (for $\max$). Example: $\max\ x$ with no upper bound.

Every solver you will ever use must report one of these three statuses. The hands-on course covers reading them in detail; for now just know there are three.

**Quick check.** You have the LP $\max\ x_{1} + x_{2}$ subject to $x_{1} - x_{2} \leq 0$ and $x_{1}, x_{2} \geq 0$. The solver reports:

- Optimal at $(0, 0)$.
- Unbounded.  ← correct
- Infeasible.

**Recap.**

- A linear program minimises (or maximises) a linear objective subject to linear constraints.
- Standard form is $\min\ c^{\top} x$ s.t. $A x = b,\ x \geq 0$; everything else converts.
- Exactly three outcomes: optimal, infeasible, unbounded.



---

# Geometry and the Fundamental Theorem

0 — LP theory — Why LP optima sit at corners, with a proof you can step through.

Path: `lessons/lp-geometry`

# Geometry and the Fundamental Theorem

Why LP optima sit at corners, with a proof you can step through.

*Chapter: 0 — LP theory · lesson id `lp-geometry` · theory lesson*

---

Linear programming has a careful one-line punchline: when an LP has an optimum, at $least\ one$ of its optima is a vertex of the feasible region. That "at least one" matters. When the objective contour is parallel to a face of the polyhedron, every point on that face is optimal — but the face's endpoints are still vertices, so the theorem holds. This lesson states the result precisely, proves it, and unpacks the degenerate case explicitly so the algorithms (combinatorial $and$ interior-point) make sense.

## Notes

### The feasible region is a polyhedron

**Definition (Polyhedron).** A $polyhedron$ in $\mathbb{R}^n$ is the intersection of finitely many closed half-spaces: $$P = \{ x \in \mathbb{R}^n : a_{i}^{\top} x \leq b_{i}, \; i = 1, \ldots, m \}.$$ A bounded polyhedron is a $polytope$.

The feasible region of an LP is by construction the intersection of finitely many linear inequalities and equalities, so it is a polyhedron. The picture in the last lesson — the shaded polygon — is the $n = 2$ case. In $\mathbb{R}^3$ you would see a polyhedron with flat faces. In higher dimensions you cannot draw it, but the algebra still works.

**Definition (Vertex (extreme point)).** A point $x \in P$ is a $vertex$ (or $extreme\ point$) of $P$ if it cannot be written as a strict convex combination of two distinct points in $P$. Equivalently, if $x = \lambda y + (1 - \lambda) z$ with $y, z \in P$ and $0 < \lambda < 1$, then $y = z = x$.

> In two dimensions, a vertex is a corner where two constraint boundaries meet. In three dimensions, three faces meet at a vertex. In general $n$ dimensions, you need $n$ linearly-independent constraints to be active to pin down a single vertex.

### The Fundamental Theorem

**Theorem (Fundamental Theorem of Linear Programming).** Consider an LP $\min\ c^{\top} x$ subject to $x \in P$, where $P$ is a non-empty $pointed$ polyhedron — one that has at least one vertex, equivalently one that contains no line (automatic whenever the variables carry sign constraints such as $x \geq 0$, as ours always do). If the LP has a finite optimal value, then there exists an optimal solution that is a vertex of $P$.

Read it carefully. The statement does $not$ say every optimum is a vertex. It says $at\ least\ one$ optimum is a vertex. That is enough: a combinatorial algorithm only has to check vertices.

> The "at least one" matters. When the objective gradient $c$ is perpendicular to a constraint hyperplane (equivalently, the objective contours are $parallel$ to a face of $P$), the entire face becomes optimal. The Fundamental Theorem still applies because the face's endpoints are vertices — but interior points of the face are also optimal. This is the $degenerate$ case of LP.

**Example (Parallel objective and a face of optima).** For $\min\ x_{1} + x_{2}$ subject to $x_{1} + x_{2} \geq 5$ and $x_{1}, x_{2} \geq 0$, the objective gradient is $(1, 1)$, perpendicular to the binding constraint $x_{1} + x_{2} = 5$. Every point on the segment from $(5, 0)$ to $(0, 5)$ is optimal with value $5$. The vertices $(5, 0)$ and $(0, 5)$ are still optimal — they are just two of infinitely many.

> This is also where the simplex method ($vertex$-to-$vertex$ walker) and interior-point methods ($barrier$ methods that slide through the polytope interior) diverge. Simplex always returns one of the optimal vertices. Interior-point methods converge to the $analytic\ centre$ of the optimal face — a point in the relative interior of that face, $not$ a vertex. Both are correct; they just answer slightly different questions. If you need a vertex (for sensitivity analysis, basis identification, etc.) and you ran an interior-point method, most solvers run a $crossover$ step afterwards to pivot to an adjacent vertex.

**Proof, step by step (Fundamental Theorem of LP).** 

1. *Take any optimal solution $x^{*}$. What if it is not a vertex?*
   Suppose $x^{*}$ is optimal but not a vertex. Then by definition there exist $y, z \in P$ with $y \neq z$ and $\lambda \in (0, 1)$ such that $x^{*} = \lambda y + (1 - \lambda) z$.
2. *What does optimality of $x^{*}$ tell us about $c^{\top} y$ and $c^{\top} z$?*
   Both $y$ and $z$ are feasible, so by optimality of $x^{*}$, $c^{\top} y \geq c^{\top} x^{*}$ and $c^{\top} z \geq c^{\top} x^{*}$. (Recall we are minimising.)
3. *Combine the convex combination with the inequalities above.*
   Since $c^{\top}$ is linear, $c^{\top} x^{*} = \lambda c^{\top} y + (1 - \lambda) c^{\top} z$. The right-hand side is a convex combination of two values both at least $c^{\top} x^{*}$, but it equals $c^{\top} x^{*}$. The only way is equality everywhere: $c^{\top} y = c^{\top} z = c^{\top} x^{*}$. So $y$ and $z$ are also optimal.
4. *We have replaced $x^{*}$ with a whole line segment of optima. How do we drive to a vertex?*
   Pick the direction $d = y - z$. Starting from $x^{*}$, walk as far as possible in the $+d$ or $-d$ direction while staying inside $P$. The objective is constant along this walk because $c^{\top} d = c^{\top} y - c^{\top} z = 0$ (we just showed $c^{\top} y = c^{\top} z$). Because $P$ contains no line — the pointedness hypothesis, and exactly why the theorem needs it — the walk cannot run forever in $both$ directions: a constraint that was strict at $x^{*}$ must eventually become active. That new active constraint adds a linearly-independent equation to the system pinning $x$, dropping the dimension of the affine space of optima by exactly one.
5. *Iterate.*
   After $k$ such slides you are in a face of dimension $n - k$ where every point is optimal. The process terminates once you can no longer move without leaving $P$ — at that point the active constraints pin you down to a single point, which is a vertex by definition. The vertex is optimal. $\blacksquare$

This is the engine behind the simplex method: walk from vertex to vertex along edges, always moving in a direction that does not worsen the objective, and stop when no neighbour is strictly better. The argument above is why this is enough.

**Quick check.** A 2D LP has 4 inequality constraints on top of $x_1, x_2 \geq 0$ (so $m = 6$ inequalities in total, $n = 2$). What is the tight bound on the number of vertices of the (bounded, non-degenerate) feasible polygon?

- $m = 6$  ← correct
- $\binom{m}{n} = \binom{6}{2} = 15$
- Exactly 4

> The looser combinatorial bound $\binom{m}{n}$ counts $basic\ solutions$ — every choice of $n$ constraints from $m$ defines a point if those $n$ constraints are linearly independent. Most basic solutions are infeasible. The tight $worst$-$case$ bound on the number of $vertices$ of a bounded polytope in $\mathbb{R}^{n}$ with $m$ facets is given by McMullen's $Upper$ $Bound$ $Theorem$: in dimension $n$, vertex count is $O(m^{\lfloor n/2 \rfloor})$. For $n = 2$ that is $O(m)$; in higher dimensions it can grow much faster.

*[feasible-region diagram: A 2D polygon with m = 6 inequality constraints achieving the bound: a hexagon with 6 vertices and 6 facets.]*

Count the vertices on the diagram: $(1, 0)$, $(3, 0)$, $(3, 2)$, $(2, 3)$, $(0, 3)$, $(0, 1)$. Six vertices, six edges, one per inequality constraint. That is the $tight$ bound in two dimensions.

The combinatorial growth in higher dimensions is why the worst-case complexity of the simplex method is exponential — Klee–Minty constructed a cube in dimension $n$ where simplex traverses all $2^{n}$ vertices. In practice the method visits a tiny fraction, and average / smoothed-analysis bounds are far better.

**Recap.**

- The feasible region of an LP is a polyhedron — intersection of half-spaces.
- Fundamental Theorem of LP: if the LP has a finite optimum, at least one optimum is a vertex.
- Combinatorial algorithms exploit this by walking from vertex to vertex; interior-point methods take a different route through the interior.



---

# Duality — building the dual

0 — LP theory — Every LP has a twin. Here is how to build it.

Path: `lessons/lp-duality-construct`

# Duality — building the dual

Every LP has a twin. Here is how to build it.

*Chapter: 0 — LP theory · lesson id `lp-duality-construct` · theory lesson*

---

For every LP there is another LP — the $dual$ — whose variables, constraints, and objective are mechanically determined by the original (the $primal$). The dual is one of the great surprises of linear programming: it is not a contrivance, it is something you discover when you ask "what is the best bound I can prove for the primal optimum, using only its constraints?"

## Notes

### Where does the dual come from?

Suppose you want a $lower\ bound$ on the value of the primal LP $\min c^{\top} x$ s.t. $A x \geq b$, $x \geq 0$. The only tools you have are the constraints themselves. So you try the most natural thing: take a non-negative combination of the constraints and see what falls out.

Pick weights $y_{1}, \ldots, y_{m} \geq 0$ and form $y^{\top}(A x) \geq y^{\top} b$, which is $(y^{\top} A) x \geq y^{\top} b$. If every coordinate of $y^{\top} A$ is at most the corresponding coordinate of $c^{\top}$, then because $x \geq 0$ we get $$c^{\top} x \geq (y^{\top} A) x \geq y^{\top} b.$$ Read that left-to-right: any non-negative weighting $y$ with $y^{\top} A \leq c^{\top}$ gives a valid lower bound $y^{\top} b$ on the primal optimum. Which $y$ gives the strongest bound? The one that maximises $y^{\top} b$.

**Definition (Dual of a canonical-form LP).** For the primal $\min c^{\top} x$ subject to $A x \geq b$, $x \geq 0$, the dual is $$\max y^{\top} b \quad \text{subject to} \quad y^{\top} A \leq c^{\top}, \; y \geq 0.$$ Equivalently (transposing), $\max b^{\top} y$ s.t. $A^{\top} y \leq c$, $y \geq 0$. The dual variables $y_{i}$ are sometimes called $multipliers$ or $shadow\ prices$.

> There is one dual variable per primal constraint, and one dual constraint per primal variable. The roles of $A$, $b$, $c$ swap. Inequalities flip. The sense flips from min to max. The dual of the dual is the primal — duality is involutive.

### A small worked example

**Example (Primal and dual side by side).** Take the primal $\min\ 2 x_{1} + 3 x_{2}\ $ s.t. $\ x_{1} + x_{2} \geq 4,\ x_{1} + 2 x_{2} \geq 6,\ x_{1}, x_{2} \geq 0$. Two constraints means two dual variables, $y_{1}, y_{2}$. Two primal variables means two dual constraints. The dual is $\max\ 4 y_{1} + 6 y_{2}\ $ s.t. $\ y_{1} + y_{2} \leq 2,\ y_{1} + 2 y_{2} \leq 3,\ y_{1}, y_{2} \geq 0$.

**Quick check.** How many constraints does the dual of an LP with $n = 5$ variables and $m = 8$ inequality constraints have?

- 8
- 5  ← correct
- 13

### The mechanical recipe

For LPs with mixed senses, the dualisation rules are mechanical and worth memorising. For each $primal$ constraint, the $dual$ variable's sign is determined:

- Primal $A_{i} x \geq b_{i}$ → dual variable $y_{i} \geq 0$
- Primal $A_{i} x \leq b_{i}$ → dual variable $y_{i} \leq 0$ (for $\min$ primal)
- Primal $A_{i} x = b_{i}$ → dual variable $y_{i}$ free

For each $primal$ variable, the $dual$ constraint's sense is determined:

- Primal $x_{j} \geq 0$ → dual constraint $A_{\cdot j}^{\top} y \leq c_{j}$
- Primal $x_{j} \leq 0$ → dual constraint $A_{\cdot j}^{\top} y \geq c_{j}$
- Primal $x_{j}$ free → dual constraint $A_{\cdot j}^{\top} y = c_{j}$

> A useful mnemonic: a $tight$ primal feature ($=$ constraint or free variable) gives a $loose$ dual feature (free variable or $=$ constraint). Tight vs. loose swaps under duality.

**Recap.**

- The dual comes from asking: which non-negative combination of constraints gives the tightest bound on the primal?
- Dual variables $\leftrightarrow$ primal constraints. Dual constraints $\leftrightarrow$ primal variables.
- Inequalities and senses flip according to the mechanical recipe.



---

# Duality — weak and strong duality

0 — LP theory — Two theorems that change how you think about LP.

Path: `lessons/lp-duality-theorems`

# Duality — weak and strong duality

Two theorems that change how you think about LP.

*Chapter: 0 — LP theory · lesson id `lp-duality-theorems` · theory lesson*

---

We constructed the dual by hunting for a lower bound on the primal. So a bound is what we should get first. That is $weak\ duality$: the dual value is always a lower bound on the primal value. Then comes the surprise: when both LPs have finite optima, the bound is tight. That is $strong\ duality$. These two theorems are the foundation of LP sensitivity analysis, the simplex method's correctness, and the algorithms behind every commercial solver.

## Notes

**Theorem (Weak Duality).** For any primal-feasible $x$ and any dual-feasible $y$, $c^{\top} x \geq b^{\top} y$. In particular, the primal optimal value is at least the dual optimal value: $p^{*} \geq d^{*}$.

**Proof, step by step (Weak Duality).** 

1. *Start from primal feasibility.*
   Since $x$ is primal-feasible, $A x \geq b$. Since $y \geq 0$, we can multiply by $y^{\top}$ from the left without flipping the inequality: $y^{\top} A x \geq y^{\top} b = b^{\top} y$.
2. *Now use dual feasibility.*
   Since $y$ is dual-feasible, $y^{\top} A \leq c^{\top}$. Since $x \geq 0$, we can multiply by $x$ on the right without flipping: $y^{\top} A x \leq c^{\top} x$.
3. *Chain the two inequalities.*
   We have $b^{\top} y \leq y^{\top} A x \leq c^{\top} x$. Therefore $c^{\top} x \geq b^{\top} y$. Since this holds for every feasible $x$ and every feasible $y$, taking infima and suprema gives $p^{*} \geq d^{*}$. $\blacksquare$

**Corollary (Two-line bound certificate).** If you have a primal-feasible $x$ and a dual-feasible $y$ with $c^{\top} x = b^{\top} y$, then $x$ is primal-optimal and $y$ is dual-optimal.

This is a $certificate$ of optimality: anyone can verify your two vectors in linear time, no algorithm needed. Modern solvers exploit this by computing both primal and dual variables together and stopping when the gap is closed.

**Quick check.** A primal LP has feasible solution $\bar{x}$ with $c^{\top} \bar{x} = 10$. A dual feasible solution $\bar{y}$ has $b^{\top} \bar{y} = 7$. Which of the following can you conclude?

- The primal optimum is exactly 7.
- The primal optimum lies in $[7, 10]$.  ← correct
- Either the primal or the dual is infeasible.

### Strong Duality

**Theorem (Strong Duality).** If the primal LP has a finite optimal value $p^{*}$, then the dual LP also has a finite optimal value $d^{*}$, and $p^{*} = d^{*}$.

> The hypothesis matters. There is a subtle case where the primal is infeasible $and$ the dual is unbounded (and vice versa), and one even-more-subtle case where both are infeasible. The full picture is the $strong\ duality\ theorem$ in its complete form. The version above is what you reach for 95% of the time.

Proving strong duality from scratch requires either the simplex method's termination argument (which itself relies on some non-trivial linear algebra) or a separation theorem from convex analysis. We will not reproduce a full proof here — both routes take several pages of careful work. What we $can$ do is unpack what strong duality $means$, geometrically and economically.

### Geometric intuition

Imagine the primal feasible region as a polytope. The objective $c^{\top} x$ sweeps across it as a family of parallel hyperplanes; the optimum is where the lowest such hyperplane still touches. The dual variables $y$ are the $support$ data of that hyperplane — the coefficients that show $c$ can be written as a non-negative combination of the binding constraint normals. Strong duality says: not only does such a non-negative combination exist (a separation-theorem fact about convex sets), the dual LP $finds$ it.

A polytope and a supporting hyperplane meeting at a vertex is what strong duality looks like, dimension by dimension. Weak duality is "the hyperplane is below the polytope". Strong duality is "the hyperplane touches the polytope".

### Complementary slackness

**Theorem (Complementary Slackness).** Let $x^{*}$ be primal-optimal and $y^{*}$ be dual-optimal. Then for every $i$ and $j$: (a) if $y_{i}^{*} > 0$, the $i$-th primal constraint is active: $A_{i} x^{*} = b_{i}$; (b) if the $i$-th primal constraint is slack ($A_{i} x^{*} > b_{i}$), then $y_{i}^{*} = 0$; (c) if $x_{j}^{*} > 0$, the $j$-th dual constraint is active: $A_{\cdot j}^{\top} y^{*} = c_{j}$; (d) if the $j$-th dual constraint is slack, then $x_{j}^{*} = 0$.

Complementary slackness drops out of the weak-duality proof: when both inequalities in the chain $b^{\top} y \leq y^{\top} A x \leq c^{\top} x$ are equalities at $(x^{*}, y^{*})$, each individual term-by-term product must collapse. The result is one of the most useful theorems in OR: it tells you which constraints to look at when you ask "what shadow price does this resource have?".

**Quick check.** In a factory LP, the dual variable for the "labour hours" constraint comes out to $y_{\text{lab}}^{*} = \$7$ per hour. What does this mean economically?

- Labour costs the factory \$7 per hour.
- An extra hour of labour increases the optimal objective by approximately \$7.  ← correct
- The factory should hire 7 more workers.

**Recap.**

- Weak duality (easy to prove, hugely useful): $c^{\top} x \geq b^{\top} y$ for any feasible pair.
- Strong duality (harder to prove, equally useful): when finite optima exist, $p^{*} = d^{*}$.
- Complementary slackness pairs each primal variable / constraint with a dual one and tells you which is tight.



---

# From LP to MIP

0b — MIP theory — One word — "integer" — changes everything.

Path: `lessons/mip-what`

# From LP to MIP

One word — "integer" — changes everything.

*Chapter: 0b — MIP theory · lesson id `mip-what` · theory lesson*

---

A linear program with $continuous$ decision variables is solved in polynomial time and the algorithms have been engineered to within an inch of their life. Replace some of those variables with the constraint that they must be integers, and the problem becomes one of the canonical NP-hard problems. This lesson is what changes, why, and how the practical answer is "solve a relaxation and search around it".

## Notes

**Definition (Mixed-integer linear program (MIP, MILP)).** Given $c \in \mathbb{R}^{n}$, $A \in \mathbb{R}^{m \times n}$, $b \in \mathbb{R}^{m}$, and a subset $I \subseteq \{1, \ldots, n\}$ of indices declared $integer$, a $mixed$-$integer\ linear\ program$ is $$\min_{x} c^{\top} x \quad \text{subject to} \quad A x \leq b, \; x_{j} \in \mathbb{Z} \text{ for } j \in I, \; x \geq 0.$$ If $I = \{1, \ldots, n\}$ (every variable is integer), it is a $pure$ integer program. If $I$ contains only $0/1$ variables, it is a $binary\ integer\ program$.

The change from LP to MIP looks tiny on paper — one word, "integer" — but it is the difference between $\text{P}$ and $\text{NP}$-hard.

**Theorem (Complexity).** The decision version of integer programming is $\text{NP}$-complete (Karp, 1972). Equivalently, integer linear feasibility cannot be solved in time polynomial in the input size unless $\text{P} = \text{NP}$.

Several familiar problems reduce to integer programming: $0$-$1$ knapsack, set cover, vertex cover, the travelling salesman problem. Conversely, anything you can write as a polynomial-size integer program inherits the same worst-case hardness. The good news is that "worst-case hard" is not "hopeless"; commercial MIP solvers routinely tame instances with millions of variables when the structure cooperates.

### Why does adding integrality break LP?

The Fundamental Theorem of LP (from the previous chapter) gave us a finite set of candidates to check: the vertices of a polyhedron. Integer constraints destroy that. The feasible set of a MIP is the polyhedron $P = \{x : A x \leq b, x \geq 0\}$ $intersected$ with the integer lattice $\mathbb{Z}^{n}$ on the chosen coordinates. The integer hull — the convex hull of those integer feasible points — is itself a polyhedron, but with potentially exponentially many vertices, and we have no fast way to enumerate them.

*[feasible-region diagram: For max x₁ + x₂ in the shaded region, the LP optimum sits at the fractional vertex (12/7, 12/7) with Z = 24/7 ≈ 3.43. No integer feasible point reaches it — the best integer Z is 3, tied at (3,0), (0,3), (2,1), and (1,2). The LP optimum and the integer optimum genuinely differ.]*

**Quick check.** For the LP $\max\ x_{1} + x_{2}$ subject to $x_{1} + x_{2} \leq 4.5$ and $x_{1}, x_{2} \geq 0$, what is the LP optimum and what is the integer optimum?

- LP and integer optima are both $4.5$.
- LP optimum $4.5$; integer optimum $4$.  ← correct
- Both are $4$.

**Recap.**

- A MIP is an LP plus integrality on some variables.
- Worst-case it is NP-hard, but well-formulated MIPs are routinely solved by commercial solvers.
- The Fundamental Theorem of LP no longer applies — the integer optimum is not generally a vertex of the LP polyhedron.



---

# The LP relaxation as a bound

0b — MIP theory — Drop the integers, solve fast, get a bound for free.

Path: `lessons/mip-relaxation`

# The LP relaxation as a bound

Drop the integers, solve fast, get a bound for free.

*Chapter: 0b — MIP theory · lesson id `mip-relaxation` · theory lesson*

---

Almost every algorithm for integer programming starts the same way: throw out the integrality constraints, solve the resulting LP, and use what you learn. The LP $relaxation$ is cheap, mature, and — most importantly — its optimum is a $bound$ on the integer optimum.

## Notes

**Definition (LP relaxation).** Given an MIP $\min\ c^{\top} x$ s.t. $A x \leq b$, $x_{j} \in \mathbb{Z}$ for $j \in I$, $x \geq 0$, the $LP\ relaxation$ is the LP obtained by $dropping$ the integrality constraints: $\min\ c^{\top} x$ s.t. $A x \leq b$, $x \geq 0$. The relaxation has a strictly larger (or equal) feasible set than the MIP.

**Theorem (LP relaxation gives a bound).** Let $v_{\text{LP}}$ be the optimal value of the LP relaxation and $v_{\text{MIP}}$ the optimal value of the MIP. For a minimisation, $v_{\text{LP}} \leq v_{\text{MIP}}$. For a maximisation, $v_{\text{LP}} \geq v_{\text{MIP}}$.

**Proof, step by step (Why the relaxation gives a bound (min case)).** 

1. *What is the relationship between the feasible sets?*
   Every MIP-feasible point is also LP-relaxation-feasible (it satisfies the linear constraints; the integrality constraints we dropped only excluded points, never added any). So $F_{\text{MIP}} \subseteq F_{\text{LP}}$.
2. *How does the optimal value of a minimisation respond when the feasible set grows?*
   Minimising over a larger set can only decrease (or hold) the optimum. Formally, if $F \subseteq G$ then $\min_{F} f \geq \min_{G} f$.
3. *Combine.*
   Therefore $v_{\text{LP}} = \min_{F_{\text{LP}}} c^{\top} x \leq \min_{F_{\text{MIP}}} c^{\top} x = v_{\text{MIP}}$. The relaxation underestimates the integer optimum. $\blacksquare$

This is the foundation of every practical MIP algorithm. A bound is useful in three ways:

- $Stopping\ early$. If the LP relaxation already gives $v_{\text{LP}} = 100$ for a min problem and you find a feasible integer solution with value $100$, you are done: the integer solution is provably optimal.
- $Pruning\ search$. In branch-and-bound, a subproblem whose LP relaxation is worse than the best known integer solution can be pruned without searching further. The bound is the basis of the "bound" in the name.
- $Sensitivity\ analysis$. The LP dual variables (from the relaxation) tell you which constraints are economically binding even when integrality bites.

**Definition (Integrality gap).** For a minimisation MIP instance, the $absolute\ integrality\ gap$ is $v_{\text{MIP}} - v_{\text{LP}} \geq 0$; the $relative\ integrality\ gap$ is the ratio $v_{\text{MIP}} / v_{\text{LP}}$ (which is $\geq 1$). For a maximisation MIP, swap roles: gap is $v_{\text{LP}} - v_{\text{MIP}}$ or the ratio $v_{\text{LP}} / v_{\text{MIP}}$. The integrality gap of a $formulation$ is the worst-case relative gap across all instances. A formulation with gap close to $1$ is called $tight$ or $strong$; a loose formulation has a large gap and produces weak relaxations.

**Example (Tight vs. weak formulations).** Two ways to say "$x \leq M y$ for binary $y$": (a) write $x \leq M y$ literally with a large $M$; (b) write $x \leq u y$ where $u$ is the tightest upper bound on $x$. Both are correct, but (b) yields a tighter LP relaxation and faster solver runtimes. Choosing constants well — picking the smallest valid $M$ — is one of the main skills of an OR practitioner.

**Quick check.** A minimisation MIP has LP relaxation value $42.7$. The solver finds an integer feasible solution with value $44$. What can you say?

- The integer optimum is exactly $43$.
- The integer optimum is in the interval $[42.7, 44]$.  ← correct
- There is no integer optimum because $42.7$ is not an integer.

**Recap.**

- The LP relaxation drops integrality. Its optimum is a bound on the MIP optimum (under-estimate for min, over-estimate for max).
- Bounds drive every branch-and-bound search, prune large subtrees, and certify optimality.
- Tighter formulations have smaller integrality gaps and faster solves.



---

# The modelling toolkit

0b — MIP theory — Big-M, indicators, logical "or" — the patterns that turn intent into MILP.

Path: `lessons/mip-modelling`

# The modelling toolkit

Big-M, indicators, logical "or" — the patterns that turn intent into MILP.

*Chapter: 0b — MIP theory · lesson id `mip-modelling` · theory lesson*

---

A linear program can only directly express linear constraints. But real problems come with "if $y = 0$ then $x = 0$", "at most three of these binaries can be 1", "either A or B but not both". The MIP modelling toolkit is how those non-linear-looking requirements get translated into clean linear inequalities. Pick the right pattern and your solver flies; pick the wrong one and a problem that should solve in seconds takes hours.

## Notes

### The big-M pattern

You want: $y = 0 \Rightarrow x = 0$, where $y \in \{0, 1\}$ and $x \geq 0$. Equivalently, $x$ can only be non-zero when the switch $y$ is on. Pick an upper bound $M$ that you know $x$ never exceeds, and write:

$$
x \;\leq\; M \cdot y
$$

When $y = 0$, the constraint forces $x \leq 0$, and combined with $x \geq 0$ this pins $x = 0$. When $y = 1$, the constraint says $x \leq M$, which is the default upper bound and lets $x$ float anywhere up to it.

> Choose $M$ as $small$ as possible. A loose $M$ is harmless for feasibility but ruins the LP relaxation: a continuous $y = 0.001$ allows $x = 0.001 M$, which is large when $M$ is large. Loose $M$s mean loose relaxations mean long solves. If you know $x$ never exceeds $50$, write $x \leq 50 y$, not $x \leq 10{,}000 y$.

### Either / or — disjunctive constraints

You want $at\ least\ one$ of two constraints to hold: $a^{\top} x \geq \beta_{1}$ $or$ $a^{\top} x \geq \beta_{2}$ (a "logical or" — both can hold at the same time, but at least one must). Introduce a binary $z \in \{0, 1\}$ and large $M_{1}, M_{2}$:

$$
a^{\top} x + M_{1} z \;\geq\; \beta_{1} \qquad a^{\top} x + M_{2} (1 - z) \;\geq\; \beta_{2}
$$

When $z = 0$ the first constraint is forced active, the second is relaxed (the $M_{2}$ term swallows any deficit). When $z = 1$, the opposite. So whichever value of $z$ the solver picks, at least one of the two original constraints is enforced. The solver picks whichever branch costs less.

> If you really want $exclusive$ or (exactly one of the two, never both), the big-M trick alone is not enough. You need an extra constraint that forbids the unselected branch from holding, which is in general non-linear. The "exactly one" case shows up rarely in practice; "at least one" is what most disjunctive constraints actually mean.

### Indicator constraints

Major commercial solvers (CPLEX, Gurobi) support $native$ indicator constraints: write $y = 1 \Rightarrow a^{\top} x \leq \beta$ directly, no $M$ required. Open-source solvers vary — some have partial support, others none — so check yours before relying on them. Indicators are tighter than big-M because the solver can use specialised propagation. When your solver supports them, prefer indicators over big-M; when it does not, fall back to big-M and pick the tightest $M$ you can prove.

### Cardinality and SOS constraints

For a set $S$ of binaries, "at most $k$ are 1" is $\sum_{i \in S} y_{i} \leq k$, and "exactly one is 1" is $\sum_{i \in S} y_{i} = 1$. A related but distinct construct is the $special$-$ordered$-$set\ of\ type\ 1$ (SOS1): a set of variables — not necessarily binary — of which $at\ most\ one$ may be non-zero. A solver enforces an SOS1 by branching on the set directly rather than through a $\sum = 1$ constraint, so the two are not interchangeable. SOS2 — at most two $adjacent$ variables non-zero — encodes piecewise-linear functions and is supported natively in most solvers.

**Quick check.** You need: "if $y = 1$ then $x \geq -3$", where $y \in \{0, 1\}$, $x$ is free, and $x$ has known bounds $[-100, 100]$. Which big-M formulation is correct?

- $x \geq -3 \cdot y$
- $x \geq -3 + M (y - 1)$ with $M = 100$  ← correct
- $x \leq -3 \cdot (1 - y)$

> A shortcut that only works for $non$-$negative$ thresholds with $x \geq 0$ variables: "$x \geq L \cdot y$" enforces "$y = 1 \Rightarrow x \geq L$" without an extra $M$, because $y = 0$ just gives $x \geq 0$ which is already part of the model. For any other case — negative thresholds, variables that can go negative — the general $L + M(y - 1)$ pattern is the safe choice.

### Linearising the absolute value

$\min |x|$ is not linear. But if you can split $x$ into a non-negative part $x^{+}$ and a non-positive part $x^{-}$ — say $x = x^{+} - x^{-}$ with both $\geq 0$ — and minimise $x^{+} + x^{-}$, you get the same thing. This works because at the optimum at most one of $x^{+}, x^{-}$ is non-zero (otherwise you could reduce both by a constant and lower the objective).

A similar trick handles $\min \max_{i} f_{i}(x)$: introduce $t$ and rewrite as $\min t$ s.t. $t \geq f_{i}(x)$ for each $i$. The reformulation is linear if each $f_{i}$ is.

**Recap.**

- Big-M $x \leq M y$ is the simplest switch. Use the smallest valid $M$.
- Disjunctions $A \vee B$ use two big-M constraints with a binary selector.
- Indicator constraints (where supported) are tighter than big-M.
- "At most $k$", "exactly one", absolute values, and $\min$-$\max$ all have linear reformulations.



---

# Branch-and-bound (how solvers actually do it)

0b — MIP theory — A search tree, an LP at each node, and the bound that prunes it.

Path: `lessons/mip-branchbound`

# Branch-and-bound (how solvers actually do it)

A search tree, an LP at each node, and the bound that prunes it.

*Chapter: 0b — MIP theory · lesson id `mip-branchbound` · theory lesson*

---

Branch-and-bound is the algorithm every commercial MIP solver runs underneath the GUI. The idea is half a century old (Land & Doig, 1960) and has been refined into a remarkably effective beast through cuts, heuristics, and presolve. The skeleton is simple enough to write on a napkin.

## Notes

### The skeleton

> Convention for the rest of this lesson: we write $Z$ for the LP relaxation's objective value at a node, and $Z^{*}$ for the current incumbent's objective (the best integer-feasible value seen so far). This matches the notation in most OR textbooks and in the HiGHS / CPLEX / Gurobi documentation.

Maintain a tree of subproblems. The root is the original MIP. At each node:

$1.$ Solve the $LP\ relaxation$ of the subproblem. Call its optimum $Z$.

$2.$ If the LP is infeasible, $prune$ this branch.

$3.$ If $Z$ is worse than the incumbent $Z^{*}$ (i.e. $Z \geq Z^{*}$ for a min, or $Z \leq Z^{*}$ for a max), $prune\ by\ bound$ — no integer point in this subtree can beat $Z^{*}$.

$4.$ If the LP solution is integer-feasible (the relaxed variables all happen to come out integer), it is an integer feasible point for the original MIP. If $Z$ beats $Z^{*}$, update the incumbent: $Z^{*} \leftarrow Z$.

$5.$ Otherwise, pick a variable $x_{j}$ whose LP value $\tilde{x}_{j}$ is fractional and $branch$: create two child subproblems, one with $x_{j} \leq \lfloor \tilde{x}_{j} \rfloor$ and one with $x_{j} \geq \lceil \tilde{x}_{j} \rceil$. Add them to the queue.

Repeat until the queue is empty. The incumbent $Z^{*}$ at termination is the proven optimum.

### A two-variable trace

Consider $\max\ 5 x_{1} + 4 x_{2}$ s.t. $6 x_{1} + 4 x_{2} \leq 24$, $x_{1} + 2 x_{2} \leq 6$, $x_{1}, x_{2} \geq 0$ and integer.

$Root:$ LP relaxation has its optimum at the intersection of the two binding constraints: $x_{1} = 3$, $x_{2} = 1.5$, $Z = 21$. $x_{2}$ is fractional, so branch on $x_{2}$. Add child nodes for $x_{2} \leq 1$ and $x_{2} \geq 2$.

$Node\ x_{2} \geq 2:$ LP gives $x_{1} = 2$, $x_{2} = 2$, $Z = 18$. Integer! Set incumbent $Z^{*} = 18$.

$Node\ x_{2} \leq 1:$ LP gives $x_{1} = 10/3 \approx 3.33$, $x_{2} = 1$, $Z = 62/3 \approx 20.67$. $x_{1}$ is fractional; branch on it. Add $x_{1} \leq 3$ and $x_{1} \geq 4$ (both still under $x_{2} \leq 1$).

$Node\ x_{2} \leq 1, x_{1} \leq 3:$ LP gives $x_{1} = 3$, $x_{2} = 1$, $Z = 19$. Integer. Update $Z^{*} = 19$.

$Node\ x_{2} \leq 1, x_{1} \geq 4:$ LP gives $x_{1} = 4$, $x_{2} = 0$, $Z = 20$. Integer. Update $Z^{*} = 20$. This is the new incumbent.

The queue is empty. The tree closes with $Z^{*} = 20$ as the proven integer optimum at $(x_{1}, x_{2}) = (4, 0)$.

*[network-graph diagram: Branch-and-bound search tree for the worked trace. The incumbent (Z* = 20) is marked in rust; the other integer-feasible nodes are filled green; no node remained unresolved.]*

> Read the tree top-to-bottom. The root's LP is $21$, an upper bound on the integer optimum since we are maximising. Each child further restricts the feasible region and so its LP value is no greater than its parent's. Three of the five subproblems happen to have integer LP solutions and become leaves; the incumbent only improves as the search progresses.

### The same trace as a node log

Every solver records the search as a $node\ log$ — one row per significant event. The same trace from above, expressed as a log:

$$
\begin{array}{|c|l|c|c|c|c|c|} \hline \textbf{Step} & \textbf{Event} & \textbf{Nodes} & \textbf{Queue} & Z_{\text{UB}} & Z^{*} & \textbf{Gap} \\ \hline 1 & \text{Root LP solved, branch on } x_{2} & 1 & 2 & 21.00 & -\infty & - \\ 2 & \text{Node } x_{2} \geq 2:\ \text{LP} = 18,\ \text{integer} & 2 & 1 & 21.00 & 18 & 16.7\% \\ 3 & \text{Node } x_{2} \leq 1:\ \text{LP} = 20.67,\ \text{branch on } x_{1} & 3 & 2 & 20.67 & 18 & 14.8\% \\ 4 & \text{Node } x_{2} \leq 1, x_{1} \leq 3:\ \text{LP} = 19,\ \text{integer} & 4 & 1 & 20.67 & 19 & 8.8\% \\ 5 & \text{Node } x_{2} \leq 1, x_{1} \geq 4:\ \text{LP} = 20,\ \text{integer} & 5 & 0 & 20.00 & 20 & 0.0\% \\ \hline \end{array}
$$

Three quantities to track row-by-row:

- $Z_{\text{UB}}$ — the best $upper$ bound on the integer optimum (we are maximising). It is the maximum LP value across all live subproblems. As nodes resolve, this number only $falls$.
- $Z^{*}$ — the incumbent, i.e. the best integer-feasible objective seen so far. Starts at $-\infty$ before any integer point is found; only $rises$ as new integer solutions are found.
- $Gap$ — relative distance between the two: $(Z_{\text{UB}} - Z^{*}) / |Z^{*}|$. When the gap closes, the solver terminates.

Step 1 logs the root. There is no incumbent yet so the gap is undefined. Step 2 immediately produces an integer solution at $Z = 18$ — the incumbent is born. The remaining steps tighten the upper bound (by exploring the $x_{2} \leq 1$ subtree whose LP is $20.67$, not the looser parent $21$) and improve the incumbent. Step 5 closes the gap: the queue is empty and the upper bound has dropped to the incumbent's value.

### Now you try — a smaller MIP, by hand

<details><summary>Find the integer optimum of $\max\ 4 x_{1} + 3 x_{2}$ subject to $3 x_{1} + 2 x_{2} \leq 9$, $x_{1} + 2 x_{2} \leq 5$, $x_{1}, x_{2} \geq 0$ and integer. Sketch the LP feasible region, find the LP relaxation's optimum, identify the fractional variable, and branch. Keep going until the queue is empty. How many nodes do you process? What is $Z^{*}$ at termination?</summary>

$Root\ LP.$ The two constraint lines meet at $x_{1} = 2$, $x_{2} = 1.5$. Both constraints bind and the objective $4 x_{1} + 3 x_{2} = 12.5$ is maximal there. So $Z = 12.5$ and $x_{2}$ is fractional. Branch on $x_{2}$: add subproblems $x_{2} \leq 1$ and $x_{2} \geq 2$.

$Node\ x_{2} \geq 2.$ With $x_{2} = 2$ as the lower bound: $3 x_{1} + 4 \leq 9 \Rightarrow x_{1} \leq 5/3$, and $x_{1} + 4 \leq 5 \Rightarrow x_{1} \leq 1$. The tighter constraint wins: $x_{1} = 1$, $x_{2} = 2$, $Z = 4 + 6 = 10$. Integer — set incumbent $Z^{*} = 10$.

$Node\ x_{2} \leq 1.$ The LP optimum is on the boundary $3 x_{1} + 2 x_{2} = 9$. Setting $x_{2} = 1$ (the upper bound for this subtree) gives $3 x_{1} = 7 \Rightarrow x_{1} = 7/3 \approx 2.33$. $Z = 28/3 + 3 = 37/3 \approx 12.33$. Fractional in $x_{1}$. Branch on $x_{1}$: add $x_{1} \leq 2$ and $x_{1} \geq 3$.

$Node\ x_{2} \leq 1, x_{1} \leq 2.$ At $x_{1} = 2$, $x_{2} = 1$ is feasible: $6 + 2 = 8 \leq 9$, $2 + 2 = 4 \leq 5$. $Z = 8 + 3 = 11$. Integer. $Z^{*} \leftarrow 11$.

$Node\ x_{2} \leq 1, x_{1} \geq 3.$ At $x_{1} = 3$, $3 \cdot 3 + 2 x_{2} = 9 + 2 x_{2} \leq 9 \Rightarrow x_{2} \leq 0$. So $x_{1} = 3$, $x_{2} = 0$. $Z = 12$. Integer. $Z^{*} \leftarrow 12$. Queue empty.

Five nodes processed in total. Proven integer optimum: $Z^{*} = 12$ at $(x_{1}, x_{2}) = (3, 0)$.

*[network-graph diagram: The full search tree. The incumbent (Z* = 12 at the lower-right) was the last node found.]*

*[feasible-region diagram: LP feasible region with the four integer feasible points marked at their objective values.]*

</details>

### Why this works in practice

Worst-case the tree is exponential. In practice three things keep it small:

$\bullet$ $Good\ bounds$. Strong formulations (small integrality gap) mean every node's LP gives a tight bound, and many branches prune immediately.

$\bullet$ $Cuts$. The solver adds extra linear inequalities that are valid for all integer-feasible points but cut off the current fractional LP optimum. Branch-and-bound + cuts is called $branch$-$and$-$cut$ and is what every modern solver actually runs.

$\bullet$ $Heuristics$. The solver tries fast heuristics (rounding, feasibility pump, RINS) to find an early incumbent, which sharpens pruning for the rest of the search.

**Quick check.** A min-MIP branch-and-bound run reports a node with LP value $25$ and the current incumbent is $20$. What happens to this node?

- Prune by bound — no point exploring further.  ← correct
- Branch on the most-fractional variable.
- Update the incumbent to $25$.

**Recap.**

- Branch-and-bound: search tree + LP relaxation at every node + pruning when the relaxation's bound is worse than the incumbent.
- Cuts add valid inequalities that tighten the relaxation without losing integer feasible points.
- Heuristics provide early incumbents that sharpen pruning.
- The "bound" in branch-and-bound is exactly the LP relaxation theorem from the previous lesson.



---

# Log diagnostics — when the search misbehaves

0b — MIP theory — Three patterns that go wrong, and the lever that fixes each one.

Path: `lessons/mip-readlog`

# Log diagnostics — when the search misbehaves

Three patterns that go wrong, and the lever that fixes each one.

*Chapter: 0b — MIP theory · lesson id `mip-readlog` · theory lesson*

---

You met the node log in the branch-and-bound lesson: every solver streams $Z_{\text{LB}}$, $Z^{*}$, and the relative $Gap$ between them as the search progresses. When the solve is short and finishes cleanly, you barely look at the log. When the solve is slow, stalls, or terminates without proving optimality, the log is the only diagnostic you have. This lesson is about the three classic misbehaviour patterns and the lever that fixes each one.

## Notes

### The Sandwich property, restated formally

**Theorem (Sandwich property).** At every moment during a branch-and-bound search, the true integer optimum $Z_{\text{opt}}$ satisfies $$ Z_{\text{LB}} \;\leq\; Z_{\text{opt}} \;\leq\; Z^{*}, $$ where $Z_{\text{LB}}$ is the current best lower bound (over all live subproblems) and $Z^{*}$ is the current incumbent. This holds for minimisation; for maximisation, swap the inequalities to $Z^{*} \leq Z_{\text{opt}} \leq Z_{\text{UB}}$.

Diagnostics flow from the sandwich. A healthy solve shrinks both sides toward each other. A misbehaving solve fails on one or both sides in a specific way. The interesting question is: $which$ side has stopped moving, and $why$?

**Definition (Gap (relative)).** The Gap reported in the log is $\dfrac{|Z^{*} - Z_{\text{LB}}|}{|Z^{*}|}$. Termination at gap $0$ proves the incumbent is optimal. Termination at, say, $5\%$ leaves you with an approximately-optimal solution whose worst-case suboptimality is bounded by that gap.

### Pattern 1 — stalled gap

**Definition (Stalled gap).** A $stalled\ gap$ is a stretch of the log where neither $Z_{\text{LB}}$ nor $Z^{*}$ has moved for many nodes (say 10\% of the total processed so far). The solver is grinding through the search tree without proving anything new.

A stalled gap almost always means the LP relaxation is $loose$. When a child node's LP value is essentially the same as its parent's, pruning by bound is rare and the search has to enumerate combinatorially. Tighter relaxations are the lever.

- Smaller big-M constants. A loose $M$ lets continuous relaxation variables drift far above their intended bounds; the LP relaxation barely constrains the integer variables.
- Indicator constraints (where the solver supports them natively) in place of big-M.
- Problem-specific valid cuts. Cover inequalities for knapsack, subtour-elimination cuts for TSP, etc. The solver may already generate some via its cut library; supplying problem-specific ones often pays huge dividends.
- Reformulation. An $extended$ formulation with auxiliary variables sometimes gives a much tighter relaxation than the natural compact one.

**Quick check.** A maximisation MIP shows $Z_{\text{UB}} = 100$ and $Z^{*} = 80$ for hundreds of consecutive log lines, neither moving. What is most likely happening?

- The model is infeasible.
- The LP relaxation is loose — bound 100 is too far above achievable 80, pruning is rare.  ← correct
- The solver has converged and is finalising.

### Pattern 2 — no incumbent

**Definition (No incumbent).** A log where $Z^{*}$ stays at $\pm\infty$ for many nodes means no integer-feasible solution has been found yet. The solver is exploring but cannot produce a single feasible point to anchor the search.

This signals one of two situations:

- The feasible region is genuinely small / hard to find — for example, a tightly constrained scheduling problem. Generic heuristics (rounding, feasibility pump) fail to land on a feasible point.
- The model has a bug — an over-tight constraint making it infeasible or near-infeasible. Always check by solving the LP relaxation first: if the LP is infeasible, the MIP is too.

The standard lever is a $warm\ start$: supply a known feasible solution to the solver before it begins. The solver uses it to seed the incumbent, then improves from there. A poor warm start is still infinitely better than none — it gives the search something to prune against from line one of the log.

### Pattern 3 — premature termination

**Definition (Premature termination).** A $premature\ termination$ is when the solver stops because of a limit other than closing the gap — typically a time limit, a node limit, or a memory cap. $Z^{*}$ is the best integer-feasible solution found, but optimality is $not$ proven. The reported gap quantifies the worst case.

Premature termination is a $reporting$ problem, not a math problem. The solution is still feasible. You just need to know how far from optimal it might be — that is exactly what the gap is for.

- If the gap is small (say $\leq 1\%$), accept the solution and move on. Going from $1\%$ to optimal often takes most of the runtime.
- If the gap is large, you have three real options: raise the limit and let it run longer, tighten the formulation to make the search converge faster, or restructure the problem (decomposition, Benders, column generation) when the model is fundamentally too large.

### Hand exercises

**Example (Computing the relative gap).** A min-MIP log shows after 200 nodes: $Z_{\text{LB}} = 47.3$, $Z^{*} = 53.0$. Gap is $(53.0 - 47.3) / 53.0 = 5.7 / 53.0 \approx 0.1075 = 10.75\%$. Most solvers default to a gap tolerance around $0.01\%$, so this solve is still far from termination. The optimum lies in $[47.3, 53.0]$.

**Example (Estimating convergence).** Over 50 consecutive lines, $Z_{\text{LB}}$ moved from $19.1$ to $19.2$ and $Z^{*}$ stayed at $22.5$. Bound is gaining $0.1$ across 50 nodes — a rate of $0.002$ per node. Remaining gap is $22.5 - 19.2 = 3.3$. At the current rate, closing it requires roughly $3.3 / 0.002 = 1650$ more nodes. Either tighten the formulation, accept the current gap, or set a time limit and walk away with the approximate answer.

**Recap.**

- Three classic patterns: stalled gap, no incumbent, premature termination.
- Stalled gap → tighten the LP relaxation (smaller big-M, indicators, cuts, reformulation).
- No incumbent → warm-start with any feasible point; check the LP relaxation is itself feasible.
- Premature termination → accept the solution if the gap is small; otherwise raise the limit or restructure.



---

# Hello, optimizer

I — Foundations — A first run, end-to-end.

Path: `lessons/hello-optimizer`

# Hello, optimizer

A first run, end-to-end.

*Chapter: I — Foundations · lesson id `hello-optimizer` · practice lesson*

---

Welcome. This editor runs a tiny optimization runtime inside your browser — no server, no network. Before we model anything, let's confirm the loop works: edit, run, see output.

The text on the right is Python. Press Run. You should see "Hello, optimizer" in the output panel.

## Starter code

```hlpl
def main():
  print("Hello, optimizer")
  return 0
```

## Hint

Click Run. Then change the greeting and run again.

## What counts as correct

- `no-error` — Program finishes without errors
- `stdout-contains` — Output contains "Hello, optimizer"



---

# Your first variable

I — Foundations — One decision, one number.

Path: `lessons/first-variable`

# Your first variable

One decision, one number.

*Chapter: I — Foundations · lesson id `first-variable` · practice lesson*

---

An optimization model decides values for variables. The simplest possible model has one variable x, no extra constraints, and an objective. Without bounds a maximisation can run away to infinity — so we bound x between 0 and 10 and ask the solver to maximise it.

`var 0 <= x <= 10` declares the variable with its bounds attached inline — the cleanest way to say "x lives between 0 and 10". You'll see this inline-bound form throughout the rest of the course: `var 0 <= x`, `var x <= 5`, and `var 0 <= x <= 1` are all valid. Variable bounds use only the `<=` operator — the lower bound goes on the left, the upper on the right.

## Predict before running

Before you Run. Where will the solver place x?

- At the lower bound (0)
- Somewhere in the middle
- At the upper bound (10)

## Starter code

```hlpl
model tiny
var 0 <= x <= 10
max x
end

import elytica
def main():
  elytica.init_model("tiny")
  elytica.run_model("tiny")
  print("x =", elytica.get_variable_value("tiny", "x"))
  return 0
```

## Hint

Just run it. The solver pushes x to its upper bound.

## What counts as correct

- `no-error` — Model solves
- `numeric-match` — Solver pushes x to its upper bound (10)
- `code-contains` — Reads variable values from the solver (no hardcoding)

## Mastery variant

Same idea, different numbers. Bound the variable and minimise this time.

```hlpl
model tiny_v
var -4 <= w <= 7
min w
end

import elytica
def main():
  elytica.init_model("tiny_v")
  elytica.run_model("tiny_v")
  print("w =", elytica.get_variable_value("tiny_v", "w"))
  return 0
```



---

# Two variables, weighted objective

I — Foundations — Constraints + objective in one go.

Path: `lessons/two-vars-objective`

# Two variables, weighted objective

Constraints + objective in one go.

*Chapter: I — Foundations · lesson id `two-vars-objective` · practice lesson*

---

Real models have multiple variables and constraints. Here we have two — x and y, both non-negative — and a single structural constraint `x + y <= 5`.

The objective coefficients tell the solver which variables it should care about. With `max 1*x + 3*y`, each unit of y is worth three times each unit of x. Given the budget x + y ≤ 5, the solver puts everything on y.

Try flipping `max` to `min` — the optimum jumps to the origin.

## Predict before running

With `max 1*x + 3*y` and budget `x + y <= 5`, where does the solver put the budget?

- All on x (x = 5, y = 0)
- All on y (x = 0, y = 5)
- Split evenly (x = y = 2.5)

## Starter code

```hlpl
model weighted
var 0 <= x
var 0 <= y
constr x + y <= 5
max 1*x + 3*y
end

import elytica
def main():
  elytica.init_model("weighted")
  elytica.run_model("weighted")
  print("x =", elytica.get_variable_value("weighted", "x"))
  print("y =", elytica.get_variable_value("weighted", "y"))
  return 0
```

## Hint

Predict the optimum before running. Whichever variable has the larger coefficient wins.

## What counts as correct

- `no-error` — Model solves
- `numeric-match` — Solver leaves x at 0 (smaller coefficient)
- `numeric-match` — Solver pushes y to the budget (5)
- `code-contains` — Reads variable values from the solver (no hardcoding)

## Mastery variant

Different budget, different coefficients. Predict which variable wins this time.

```hlpl
model weighted_v
var 0 <= a
var 0 <= b
constr 2*a + b <= 12
max 5*a + 2*b
end

import elytica
def main():
  elytica.init_model("weighted_v")
  elytica.run_model("weighted_v")
  print("a =", elytica.get_variable_value("weighted_v", "a"))
  print("b =", elytica.get_variable_value("weighted_v", "b"))
  return 0
```



---

# Reading the solution

II — Reading the solver — Variables and the objective value.

Path: `lessons/read-solution`

# Reading the solution

Variables and the objective value.

*Chapter: II — Reading the solver · lesson id `read-solution` · practice lesson*

---

Two APIs return what the solver found: `elytica.get_variable_value(model, name)` pulls one variable at a time, and `elytica.get_best_primal_bound(model)` returns the value of the objective at the best primal solution.

You *could* recompute the objective in Python (`3*x + 2*y` here) but it's brittle — change the model and you'd have to mirror the change in Python by hand. Use the API.

Add a line that prints `obj =` followed by the best primal bound.

## Predict before running

For `max 3*x + 2*y` with `x <= 4` and `x + y <= 6`, what's the objective at the optimum?

- 12. Push x to 4, leave y at 0
- 16. X = 4, y = 2
- 18. X = 6, y = 0

## Starter code

```hlpl
model score
var 0 <= x <= 4
var 0 <= y
constr x + y <= 6
max 3*x + 2*y
end

import elytica
def main():
  elytica.init_model("score")
  elytica.run_model("score")
  x = elytica.get_variable_value("score", "x")
  y = elytica.get_variable_value("score", "y")
  print("x =", x, "y =", y)
  # TODO: print "obj =" using elytica.get_best_primal_bound("score")
  return 0
```

## Hint

print("obj =", elytica.get_best_primal_bound("score"))

## What counts as correct

- `no-error` — Model solves
- `numeric-match` — Objective reaches 16 (x=4, y=2)
- `code-contains` — Reads the objective from the solver (no hardcoding)

## Solution

```hlpl
model score
var 0 <= x <= 4
var 0 <= y
constr x + y <= 6
max 3*x + 2*y
end

import elytica
def main():
  elytica.init_model("score")
  elytica.run_model("score")
  x = elytica.get_variable_value("score", "x")
  y = elytica.get_variable_value("score", "y")
  print("x =", x, "y =", y)
  print("obj =", elytica.get_best_primal_bound("score"))
  return 0
```

## Mastery variant

Different bounds and a different budget. Read all three outputs back from the solver.

```hlpl
model score_v
var 0 <= a <= 5
var 0 <= b
constr a + b <= 9
max 4*a + b
end

import elytica
def main():
  elytica.init_model("score_v")
  elytica.run_model("score_v")
  a = elytica.get_variable_value("score_v", "a")
  b = elytica.get_variable_value("score_v", "b")
  print("a =", a, "b =", b)
  # TODO: print "obj =" using elytica.get_best_primal_bound("score_v")
  return 0
```



---

# When there is no answer

II — Reading the solver — Infeasibility and the run_model status.

Path: `lessons/solver-status`

# When there is no answer

Infeasibility and the run_model status.

*Chapter: II — Reading the solver · lesson id `solver-status` · practice lesson*

---

If you ask for `x >= 5` and `x <= 2` at the same time, no value of x satisfies both. The model is infeasible.

The clean way to know what happened: capture what `elytica.run_model(...)` hands back — a status string from the underlying solver. Values like "Optimal", "Infeasible", "Unbounded".

Run the deliberately broken model, capture the status, and print it. The check below passes once your output reports an infeasibility status.

## Predict before running

What status will the solver report for `x >= 5` and `x <= 2`?

- Optimal
- Infeasible
- Unbounded

## Starter code

```hlpl
model broken
var x
constr x >= 5
constr x <= 2
max x
end

import elytica
def main():
  elytica.init_model("broken")
  elytica.run_model("broken")
  # TODO: capture the return of elytica.run_model above and print it as "status ="
  return 0
```

## Hint

status = elytica.run_model("broken"); then print("status =", status)

## What counts as correct

- `stdout-regex` — Output reports an infeasibility status

## Solution

```hlpl
model broken
var x
constr x >= 5
constr x <= 2
max x
end

import elytica
def main():
  elytica.init_model("broken")
  status = elytica.run_model("broken")
  print("status =", status)
  if "infeas" in str(status).lower():
    print("No feasible point exists for this model.")
  return 0
```

## Mastery variant

A different infeasible model. Capture and print the status the same way.

```hlpl
model broken_v
var z
constr z >= 10
constr z <= 3
min z
end

import elytica
def main():
  elytica.init_model("broken_v")
  elytica.run_model("broken_v")
  # TODO: capture the return of elytica.run_model above and print it as "status ="
  return 0
```



---

# Sets, indices, and parameters

III — Sets and sums — Declare many variables at once.

Path: `lessons/indexed-vars`

# Sets, indices, and parameters

Declare many variables at once.

*Chapter: III — Sets and sums · lesson id `indexed-vars` · practice lesson*

---

Writing `var x1`, `var x2`, …, `var x100` doesn't scale. Declare a set `I` and a family of variables indexed over it with `var x, forall i in I`. Each x_i is a separate decision variable.

Inline bounds carry over — `var 0 <= x <= 1, forall i in I` declares one bounded variable per element of I. Parameters work the same way: `const v = {1, 3, 5, 2, 4}, forall i in I` attaches a value to each element. The objective body uses v_{i} and x_{i} together via `sum_{i in I}{ … }`.

With no other constraints, the solver picks the upper bound for every x_i.

## Predict before running

With no constraints beyond `0 <= x_i <= 1`, what does each x_i end up at?

- 0 for all
- 1 for all
- 1 only for items with v_i > 3

## Starter code

```hlpl
model picks
set I = {1, 2, 3, 4, 5}
const v = {1, 3, 5, 2, 4}, forall i in I
var 0 <= x <= 1, forall i in I
max sum_{i in I}{v_{i} * x_{i}}
end

import elytica
def main():
  elytica.init_model("picks")
  elytica.run_model("picks")
  for i in [1,2,3,4,5]:
    print("x"+str(i), "=", elytica.get_variable_value("picks", "x"+str(i)))
  print("obj =", elytica.get_best_primal_bound("picks"))
  return 0
```

## Hint

No code changes needed. Read the model and run it.

## What counts as correct

- `no-error` — Model solves
- `numeric-match` — All five x_i hit the upper bound (obj = 1+3+5+2+4 = 15)
- `code-contains` — Reads the objective from the solver (no hardcoding)

## Mastery variant

Six items now, different values. Still no constraints, so the result follows the same pattern.

```hlpl
model picks_v
set I = {1, 2, 3, 4, 5, 6}
const v = {2, 6, 1, 4, 3, 5}, forall i in I
var 0 <= x <= 1, forall i in I
max sum_{i in I}{v_{i} * x_{i}}
end

import elytica
def main():
  elytica.init_model("picks_v")
  elytica.run_model("picks_v")
  for i in [1,2,3,4,5,6]:
    print("x"+str(i), "=", elytica.get_variable_value("picks_v", "x"+str(i)))
  print("obj =", elytica.get_best_primal_bound("picks_v"))
  return 0
```



---

# A constraint over a set

III — Sets and sums — Σ in your constraints, not just the objective.

Path: `lessons/sum-constraint`

# A constraint over a set

Σ in your constraints, not just the objective.

*Chapter: III — Sets and sums · lesson id `sum-constraint` · practice lesson*

---

`sum_{i in I}{expr}` is the modelling language's big-Σ. You've seen it in the objective; here we put it in a constraint too — a budget cap on total weight.

Items have values v_i and weights w_i. You have W units of capacity. Pick the most valuable subset that fits. (Yes — this is already a knapsack. We'll formalise it in its own chapter.)

## Predict before running

Items have values {3,5,2,7,4} and weights {2,4,1,5,3} with budget W = 8. What's the best value?

- 21. Every item
- 12. Items 1, 3, 4 (weights 2 + 1 + 5 = 8)
- 14. Items 2, 4 (weights 4 + 5 = 9)

## Starter code

```hlpl
model picks
set I = {1, 2, 3, 4, 5}
const v = {3, 5, 2, 7, 4}, forall i in I
const w = {2, 4, 1, 5, 3}, forall i in I
const W = 8
var 0 <= x <= 1, forall i in I
constr sum_{i in I}{w_{i} * x_{i}} <= W
max sum_{i in I}{v_{i} * x_{i}}
end

import elytica
def main():
  elytica.init_model("picks")
  elytica.run_model("picks")
  for i in [1,2,3,4,5]:
    print("x"+str(i), "=", elytica.get_variable_value("picks", "x"+str(i)))
  print("obj =", elytica.get_best_primal_bound("picks"))
  return 0
```

## Hint

No code changes. Look at the budget — it forces the solver to drop items.

## What counts as correct

- `no-error` — Model solves
- `numeric-match` — Best feasible value is 12 (items 1, 3, and 4)
- `code-contains` — Reads the objective from the solver (no hardcoding)

## Mastery variant

Different values, weights, and a tighter budget. Which subset wins?

```hlpl
model picks_v
set I = {1, 2, 3, 4, 5}
const v = {4, 2, 6, 3, 5}, forall i in I
const w = {2, 1, 3, 2, 2}, forall i in I
const W = 6
var 0 <= x <= 1, forall i in I
constr sum_{i in I}{w_{i} * x_{i}} <= W
max sum_{i in I}{v_{i} * x_{i}}
end

import elytica
def main():
  elytica.init_model("picks_v")
  elytica.run_model("picks_v")
  for i in [1,2,3,4,5]:
    print("x"+str(i), "=", elytica.get_variable_value("picks_v", "x"+str(i)))
  print("obj =", elytica.get_best_primal_bound("picks_v"))
  return 0
```



---

# Binary variables

IV — Discrete decisions — Yes or no, on or off.

Path: `lessons/binary-variables`

# Binary variables

Yes or no, on or off.

*Chapter: IV — Discrete decisions · lesson id `binary-variables` · practice lesson*

---

`bin x` declares a 0/1 variable — you either pick it or you don't. This is the cornerstone of discrete decision-making.

Three binary variables compete under a sum cap. The objective tells the solver which to prefer.

## Predict before running

For `max 5*a + 3*b + 4*c` with `a + b + c <= 2`, which two binaries flip on?

- a and b (objective 8)
- a and c (objective 9)
- b and c (objective 7)

## Starter code

```hlpl
model binary_pick
bin a
bin b
bin c
constr a + b + c <= 2
max 5*a + 3*b + 4*c
end

import elytica
def main():
  elytica.init_model("binary_pick")
  elytica.run_model("binary_pick")
  print("a =", elytica.get_variable_value("binary_pick", "a"))
  print("b =", elytica.get_variable_value("binary_pick", "b"))
  print("c =", elytica.get_variable_value("binary_pick", "c"))
  print("obj =", elytica.get_best_primal_bound("binary_pick"))
  return 0
```

## Hint

The constraint allows at most two of the three. Pick the two with the largest weights.

## What counts as correct

- `no-error` — Model solves
- `numeric-match` — Optimal value is 9 (a + c)
- `numeric-match` — Picks a
- `numeric-match` — Picks c
- `numeric-match` — Skips b
- `code-contains` — Reads the objective from the solver (no hardcoding)
- `code-contains` — Reads variable values from the solver (no hardcoding)

## Mastery variant

Four binaries this time. Pick at most three. Which one gets dropped?

```hlpl
model binary_pick_v
bin p
bin q
bin r
bin s
constr p + q + r + s <= 3
max 7*p + 4*q + 6*r + 5*s
end

import elytica
def main():
  elytica.init_model("binary_pick_v")
  elytica.run_model("binary_pick_v")
  print("p =", elytica.get_variable_value("binary_pick_v", "p"))
  print("q =", elytica.get_variable_value("binary_pick_v", "q"))
  print("r =", elytica.get_variable_value("binary_pick_v", "r"))
  print("s =", elytica.get_variable_value("binary_pick_v", "s"))
  print("obj =", elytica.get_best_primal_bound("binary_pick_v"))
  return 0
```



---

# Integer variables

IV — Discrete decisions — Whole numbers only.

Path: `lessons/integer-variables`

# Integer variables

Whole numbers only.

*Chapter: IV — Discrete decisions · lesson id `integer-variables` · practice lesson*

---

An `int` variable must take a whole-number value. Asking for 3.5 trucks is fine for the LP relaxation but nonsense in practice — `int` enforces reality.

How many widgets can we produce if each takes 3 hours and we have 11 hours? The LP would say 3.666… The integer programme says 3.

## Predict before running

For `int 0 <= n`, `3*n <= 11`, `max n`, what does n become?

- 3.666… (the LP relaxation)
- 3
- 4

## Starter code

```hlpl
model widgets
int 0 <= n
constr 3*n <= 11
max n
end

import elytica
def main():
  elytica.init_model("widgets")
  elytica.run_model("widgets")
  print("n =", elytica.get_variable_value("widgets", "n"))
  return 0
```

## Hint

Run it. The answer should be a whole number.

## What counts as correct

- `no-error` — Model solves
- `numeric-match` — Solver rounds down to a whole number (3)
- `code-contains` — Reads variable values from the solver (no hardcoding)

## Mastery variant

5 hours per widget, 38-hour budget. How many whole widgets?

```hlpl
model widgets_v
int 0 <= m
constr 5*m <= 38
max m
end

import elytica
def main():
  elytica.init_model("widgets_v")
  elytica.run_model("widgets_v")
  print("m =", elytica.get_variable_value("widgets_v", "m"))
  return 0
```



---

# Either / or via big-M

V — Modelling tricks — Disjunctions in linear models.

Path: `lessons/either-or-bigm`

# Either / or via big-M

Disjunctions in linear models.

*Chapter: V — Modelling tricks · lesson id `either-or-bigm` · practice lesson*

---

Linear programmes can't natively express "either constraint A or constraint B". The classic trick: introduce a binary `z` and a large constant M, then write

  A active when z = 0:   lhs_A + M · z       ≥ required
  B active when z = 1:   lhs_B + M · [1 − z] ≥ required

When z = 0, A is binding and B is relaxed away by the huge M term; when z = 1, the opposite. The solver picks whichever side fits the objective better.

Two delivery options for the same shipment: truck (variable x₁) or ship (variable x₂). At least one must carry at least 5 units. Truck costs 3 per unit, ship costs 2. The model has to choose a single mode and minimise cost.

Note `[ ]` around `1 - z` — the modelling language uses square brackets for algebraic grouping in expressions; parentheses are reserved for function calls.

## Predict before running

Truck costs 3/unit, ship costs 2/unit. Which side does the disjunction pick?

- Truck (z = 0, x₁ = 5)
- Ship (z = 1, x₂ = 5)
- Split (some of each)

## Starter code

```hlpl
model either_or
var 0 <= x1 <= 10      # units carried by truck
var 0 <= x2 <= 10      # units carried by ship
bin z                   # 0 = truck side, 1 = ship side
constr x1 + 100*z       >= 5   # if z = 0, truck must carry >= 5
constr x2 + 100*[1 - z] >= 5   # if z = 1, ship must carry >= 5
min 3*x1 + 2*x2
end

import elytica
def main():
  elytica.init_model("either_or")
  elytica.run_model("either_or")
  print("x1 =", elytica.get_variable_value("either_or", "x1"))
  print("x2 =", elytica.get_variable_value("either_or", "x2"))
  print("z =", elytica.get_variable_value("either_or", "z"))
  print("obj =", elytica.get_best_primal_bound("either_or"))
  return 0
```

## Hint

Predict: ship is cheaper. The solver picks z = 1, x₁ = 0, x₂ = 5, cost 10.

## What counts as correct

- `no-error` — Model solves
- `numeric-match` — Truck side stays at 0 (more expensive)
- `numeric-match` — Ship side carries exactly the required 5 units
- `numeric-match` — Selector z = 1 (ship side chosen)
- `numeric-match` — Cost is 10 (5 units × $2 ship)
- `code-contains` — Reads the objective from the solver (no hardcoding)
- `code-contains` — Reads variable values from the solver (no hardcoding)

## Mastery variant

Bus vs train this time, with a different required volume. Which mode wins?

```hlpl
model either_or_v
var 0 <= x1 <= 20      # units on the bus
var 0 <= x2 <= 20      # units on the train
bin z                   # 0 = bus, 1 = train
constr x1 + 200*z       >= 8
constr x2 + 200*[1 - z] >= 8
min 3*x1 + 4*x2
end

import elytica
def main():
  elytica.init_model("either_or_v")
  elytica.run_model("either_or_v")
  print("x1 =", elytica.get_variable_value("either_or_v", "x1"))
  print("x2 =", elytica.get_variable_value("either_or_v", "x2"))
  print("z =", elytica.get_variable_value("either_or_v", "z"))
  print("obj =", elytica.get_best_primal_bound("either_or_v"))
  return 0
```



---

# Fixed cost + variable cost

V — Modelling tricks — Open a production line only if it pays.

Path: `lessons/fixed-cost`

# Fixed cost + variable cost

Open a production line only if it pays.

*Chapter: V — Modelling tricks · lesson id `fixed-cost` · practice lesson*

---

A common pattern: opening a facility (or production line, or contract) costs a fixed amount, and then each unit produced has its own variable cost or revenue. You only want to pay the fixed cost if the line is actually used.

Model it with a binary `y` (line open?) and a continuous `x` (units produced). Tie them together with `x ≤ M · y` — if y = 0, x is forced to 0; if y = 1, x is free up to M.

Here we earn 2 per unit, pay a setup cost of 30 to open, and cap output at 50. Should the line open?

## Predict before running

Setup cost 30, revenue 2/unit, max 50 units. Does the line open?

- No. Keep y = 0, profit = 0
- Yes. Open, profit 70
- Open partially (y = 0.5)

## Starter code

```hlpl
model fixed_cost
var 0 <= x          # units produced
bin y               # 1 if production line is open
constr x <= 50 * y  # only produce if the line is open (M = 50)
max 2*x - 30*y
end

import elytica
def main():
  elytica.init_model("fixed_cost")
  elytica.run_model("fixed_cost")
  print("x =", elytica.get_variable_value("fixed_cost", "x"))
  print("y =", elytica.get_variable_value("fixed_cost", "y"))
  print("obj =", elytica.get_best_primal_bound("fixed_cost"))
  return 0
```

## Hint

Profit with line open: 2·50 − 30 = 70. With line closed: 0. The solver will pick open.

## What counts as correct

- `no-error` — Model solves
- `numeric-match` — Line opens (y = 1)
- `numeric-match` — Run at full capacity (x = 50)
- `numeric-match` — Profit = 2·50 − 30 = 70
- `code-contains` — Reads the objective from the solver (no hardcoding)
- `code-contains` — Reads variable values from the solver (no hardcoding)

## Mastery variant

Higher setup cost but better unit margin. Worth opening the line?

```hlpl
model fixed_cost_v
var 0 <= x          # units produced
bin y               # 1 if production line is open
constr x <= 30 * y  # only produce if the line is open (M = 30)
max 5*x - 40*y
end

import elytica
def main():
  elytica.init_model("fixed_cost_v")
  elytica.run_model("fixed_cost_v")
  print("x =", elytica.get_variable_value("fixed_cost_v", "x"))
  print("y =", elytica.get_variable_value("fixed_cost_v", "y"))
  print("obj =", elytica.get_best_primal_bound("fixed_cost_v"))
  return 0
```



---

# Knapsack — variables and objective

VI — Knapsack — Start with the decisions.

Path: `lessons/knapsack-vars`

# Knapsack — variables and objective

Start with the decisions.

*Chapter: VI — Knapsack · lesson id `knapsack-vars` · practice lesson*

---

The knapsack problem: you have items, each with a value and a weight. Your bag holds a fixed amount of weight. Pick items to maximise value.

We'll build it in three lessons. First step: just the variables and the objective. Each item gets a binary decision x_i — do we pick it or not? — and the objective sums values.

Run it. Without a capacity constraint, the solver picks everything.

## Predict before running

Five binaries, no capacity, `max 6*x1 + 4*x2 + 5*x3 + 3*x4 + 2*x5`. What's the optimum?

- All five picked (obj = 20)
- Only the heavy hitters (obj = 11)
- None picked (obj = 0)

## Starter code

```hlpl
model knap
bin x1
bin x2
bin x3
bin x4
bin x5
max 6*x1 + 4*x2 + 5*x3 + 3*x4 + 2*x5
end

import elytica
def main():
  elytica.init_model("knap")
  elytica.run_model("knap")
  for i in [1,2,3,4,5]:
    print("x"+str(i), "=", elytica.get_variable_value("knap", "x"+str(i)))
  print("obj =", elytica.get_best_primal_bound("knap"))
  return 0
```

## Hint

Predict: with no constraint, what's the optimum? (Every item, sum of all values.)

## What counts as correct

- `no-error` — Model solves
- `numeric-match` — Solver picks everything (obj = 6+4+5+3+2 = 20)
- `code-contains` — Reads the objective from the solver (no hardcoding)

## Mastery variant

Six items, different values. Same trick: no capacity, all positive values pick.

```hlpl
model knap_v
bin x1
bin x2
bin x3
bin x4
bin x5
bin x6
max 7*x1 + 3*x2 + 8*x3 + 5*x4 + 2*x5 + 4*x6
end

import elytica
def main():
  elytica.init_model("knap_v")
  elytica.run_model("knap_v")
  for i in [1,2,3,4,5,6]:
    print("x"+str(i), "=", elytica.get_variable_value("knap_v", "x"+str(i)))
  print("obj =", elytica.get_best_primal_bound("knap_v"))
  return 0
```



---

# Knapsack — add the capacity

VI — Knapsack — One constraint, everything changes.

Path: `lessons/knapsack-capacity`

# Knapsack — add the capacity

One constraint, everything changes.

*Chapter: VI — Knapsack · lesson id `knapsack-capacity` · practice lesson*

---

Now the bag. Each item has a weight w_i, and total weight can't exceed W. Add a single constraint to the model from the previous lesson — and now the solver has to make trade-offs.

Items with weights [2, 3, 4, 2, 1] and capacity W = 6. Which subset wins?

## Predict before running

Values {6,4,5,3,2}, weights {2,3,4,2,1}, capacity 6. Which items win?

- Items 1, 2, 5. Value 12, weight 6
- Items 1, 3. Value 11, weight 6
- Items 1, 2, 4. Value 13, weight 7

## Starter code

```hlpl
model knap
bin x1
bin x2
bin x3
bin x4
bin x5
constr 2*x1 + 3*x2 + 4*x3 + 2*x4 + 1*x5 <= 6
max 6*x1 + 4*x2 + 5*x3 + 3*x4 + 2*x5
end

import elytica
def main():
  elytica.init_model("knap")
  elytica.run_model("knap")
  for i in [1,2,3,4,5]:
    print("x"+str(i), "=", elytica.get_variable_value("knap", "x"+str(i)))
  print("obj =", elytica.get_best_primal_bound("knap"))
  return 0
```

## Hint

The capacity is 6. Items {1, 2, 5} weigh 2+3+1 = 6 — fits exactly, value 6+4+2 = 12.

## What counts as correct

- `no-error` — Model solves
- `numeric-match` — Optimal value is 12 (items 1, 2, and 5)
- `numeric-match` — Item 1 is in
- `numeric-match` — Item 5 is in
- `code-contains` — Reads the objective from the solver (no hardcoding)
- `code-contains` — Reads variable values from the solver (no hardcoding)

## Mastery variant

New values, weights, and a tighter bag. Which three items pack best now?

```hlpl
model knap_v
bin x1
bin x2
bin x3
bin x4
bin x5
constr 3*x1 + 2*x2 + 4*x3 + 1*x4 + 2*x5 <= 7
max 8*x1 + 5*x2 + 7*x3 + 4*x4 + 3*x5
end

import elytica
def main():
  elytica.init_model("knap_v")
  elytica.run_model("knap_v")
  for i in [1,2,3,4,5]:
    print("x"+str(i), "=", elytica.get_variable_value("knap_v", "x"+str(i)))
  print("obj =", elytica.get_best_primal_bound("knap_v"))
  return 0
```



---

# Knapsack — indexed form

VI — Knapsack — Five items in five lines.

Path: `lessons/knapsack-indexed`

# Knapsack — indexed form

Five items in five lines.

*Chapter: VI — Knapsack · lesson id `knapsack-indexed` · practice lesson*

---

The scalar form doesn't scale past a handful of items. Real models declare a set I, parameters v_i and w_i, and a single sum constraint. Same problem, same optimum — far less typing.

Notice how the entire model fits in five lines.

## Starter code

```hlpl
model knap
set I = {1, 2, 3, 4, 5}
const v = {6, 4, 5, 3, 2}, forall i in I
const w = {2, 3, 4, 2, 1}, forall i in I
const W = 6
bin x, forall i in I
constr sum_{i in I}{w_{i} * x_{i}} <= W
max sum_{i in I}{v_{i} * x_{i}}
end

import elytica
def main():
  elytica.init_model("knap")
  elytica.run_model("knap")
  for i in [1,2,3,4,5]:
    print("x"+str(i), "=", elytica.get_variable_value("knap", "x"+str(i)))
  print("obj =", elytica.get_best_primal_bound("knap"))
  return 0
```

## Hint

Compare to the previous lesson. Same problem, same answer.

## What counts as correct

- `no-error` — Model solves
- `numeric-match` — Same optimum as the scalar version (12)
- `code-contains` — Reads the objective from the solver (no hardcoding)

## Mastery variant

Five items, fresh numbers. Indexed form, same five-line template.

```hlpl
model knap_v
set I = {1, 2, 3, 4, 5}
const v = {5, 7, 3, 4, 2}, forall i in I
const w = {2, 3, 4, 1, 1}, forall i in I
const W = 5
bin x, forall i in I
constr sum_{i in I}{w_{i} * x_{i}} <= W
max sum_{i in I}{v_{i} * x_{i}}
end

import elytica
def main():
  elytica.init_model("knap_v")
  elytica.run_model("knap_v")
  for i in [1,2,3,4,5]:
    print("x"+str(i), "=", elytica.get_variable_value("knap_v", "x"+str(i)))
  print("obj =", elytica.get_best_primal_bound("knap_v"))
  return 0
```



---

# Assignment — workers pick jobs

VII — Assignment — One row constraint at a time.

Path: `lessons/assignment-rows`

# Assignment — workers pick jobs

One row constraint at a time.

*Chapter: VII — Assignment · lesson id `assignment-rows` · practice lesson*

---

Three workers, three jobs. Each cell c[i][j] is the cost of worker i doing job j. We'll build the model up over three lessons.

First constraint: each worker takes exactly one job. We say nothing yet about whether a job can be taken by multiple workers — so they'll all pile onto whichever job they each find cheapest.

In this cost matrix every worker's cheapest job is J1, so the solver assigns all three to J1. Not realistic — we'll fix that next.

## Predict before running

Only row constraints (one job per worker), no column constraint. What happens?

- Every worker picks their cheapest column
- The solver spreads them across J1, J2, J3
- The model is infeasible

## Starter code

```hlpl
model assign
set I = {1, 2, 3}
set J = {1, 2, 3}
const c = {{1, 5, 6}, {2, 4, 7}, {3, 8, 9}}, forall i in I, forall j in J
bin x, forall i in I, forall j in J
constr sum_{j in J}{x_{i,j}} = 1, forall i in I
min sum_{i in I}{sum_{j in J}{c_{i,j} * x_{i,j}}}
end

import elytica
def main():
  elytica.init_model("assign")
  elytica.run_model("assign")
  for i in [1,2,3]:
    for j in [1,2,3]:
      name = "x"+str(i)+","+str(j)
      print(name, "=", elytica.get_variable_value("assign", name))
  print("obj =", elytica.get_best_primal_bound("assign"))
  return 0
```

## Hint

Each row of the matrix has its smallest entry in column 1. All workers pick J1.

## What counts as correct

- `no-error` — Model solves
- `numeric-match` — All workers pick J1 (1+2+3 = 6)
- `code-contains` — Reads the objective from the solver (no hardcoding)

## Mastery variant

New cost matrix — same trap (every row minimum is in the same column).

```hlpl
model assign_v
set I = {1, 2, 3}
set J = {1, 2, 3}
const c = {{4, 1, 6}, {3, 1, 5}, {7, 2, 9}}, forall i in I, forall j in J
bin x, forall i in I, forall j in J
constr sum_{j in J}{x_{i,j}} = 1, forall i in I
min sum_{i in I}{sum_{j in J}{c_{i,j} * x_{i,j}}}
end

import elytica
def main():
  elytica.init_model("assign_v")
  elytica.run_model("assign_v")
  for i in [1,2,3]:
    for j in [1,2,3]:
      name = "x"+str(i)+","+str(j)
      print(name, "=", elytica.get_variable_value("assign_v", name))
  print("obj =", elytica.get_best_primal_bound("assign_v"))
  return 0
```



---

# Assignment — one-to-one

VII — Assignment — Both directions of the matching.

Path: `lessons/assignment-bipartite`

# Assignment — one-to-one

Both directions of the matching.

*Chapter: VII — Assignment · lesson id `assignment-bipartite` · practice lesson*

---

Add the symmetric constraint: each job is taken by exactly one worker. Now the solver has to spread the workers across jobs — a proper assignment.

With the same cost matrix as before, the optimum jumps from 6 to 13 because no two workers can share a job.

## Predict before running

Add column constraints too. Each job goes to exactly one worker. Cost?

- Higher than the row-only optimum (some workers forced off their cheapest)
- Same as row-only
- Lower (more constraints help)

## Starter code

```hlpl
model assign
set I = {1, 2, 3}
set J = {1, 2, 3}
const c = {{1, 5, 6}, {2, 4, 7}, {3, 8, 9}}, forall i in I, forall j in J
bin x, forall i in I, forall j in J
constr sum_{j in J}{x_{i,j}} = 1, forall i in I
# TODO: add a constraint forcing each job to exactly one worker
min sum_{i in I}{sum_{j in J}{c_{i,j} * x_{i,j}}}
end

import elytica
def main():
  elytica.init_model("assign")
  elytica.run_model("assign")
  for i in [1,2,3]:
    for j in [1,2,3]:
      name = "x"+str(i)+","+str(j)
      print(name, "=", elytica.get_variable_value("assign", name))
  print("obj =", elytica.get_best_primal_bound("assign"))
  return 0
```

## Hint

Add: constr sum_{i in I}{x_{i,j}} = 1, forall j in J

## What counts as correct

- `no-error` — Model solves
- `numeric-match` — Cheapest one-to-one assignment costs 13
- `code-contains` — Reads the objective from the solver (no hardcoding)

## Solution

```hlpl
model assign
set I = {1, 2, 3}
set J = {1, 2, 3}
const c = {{1, 5, 6}, {2, 4, 7}, {3, 8, 9}}, forall i in I, forall j in J
bin x, forall i in I, forall j in J
constr sum_{j in J}{x_{i,j}} = 1, forall i in I
constr sum_{i in I}{x_{i,j}} = 1, forall j in J
min sum_{i in I}{sum_{j in J}{c_{i,j} * x_{i,j}}}
end

import elytica
def main():
  elytica.init_model("assign")
  elytica.run_model("assign")
  for i in [1,2,3]:
    for j in [1,2,3]:
      name = "x"+str(i)+","+str(j)
      print(name, "=", elytica.get_variable_value("assign", name))
  print("obj =", elytica.get_best_primal_bound("assign"))
  return 0
```

## Mastery variant

A different matrix where the diagonal is cheap. The optimum is the perfect diagonal.

```hlpl
model assign_v
set I = {1, 2, 3}
set J = {1, 2, 3}
const c = {{2, 7, 4}, {5, 3, 8}, {9, 6, 1}}, forall i in I, forall j in J
bin x, forall i in I, forall j in J
constr sum_{j in J}{x_{i,j}} = 1, forall i in I
constr sum_{i in I}{x_{i,j}} = 1, forall j in J
min sum_{i in I}{sum_{j in J}{c_{i,j} * x_{i,j}}}
end

import elytica
def main():
  elytica.init_model("assign_v")
  elytica.run_model("assign_v")
  for i in [1,2,3]:
    for j in [1,2,3]:
      name = "x"+str(i)+","+str(j)
      print(name, "=", elytica.get_variable_value("assign_v", name))
  print("obj =", elytica.get_best_primal_bound("assign_v"))
  return 0
```



---

# Assignment — extra workers

VII — Assignment — When the matching is uneven.

Path: `lessons/assignment-unbalanced`

# Assignment — extra workers

When the matching is uneven.

*Chapter: VII — Assignment · lesson id `assignment-unbalanced` · practice lesson*

---

Real assignments aren't always square. With four workers and three jobs, one worker has to sit out. The trick: relax the per-worker constraint from `= 1` to `≤ 1`, while keeping each job at `= 1`.

Worker 3 has a brutal cost row [3, 8, 9] and gets dropped. Total cost: 9.

## Predict before running

Four workers, three jobs — one must sit out. Cost rows W1=[1,5,6], W2=[2,4,7], W3=[3,8,9], W4=[5,2,4]. Which worker is least useful?

- W3 — dominated on every job
- W1 — it is cheap everywhere
- Any of them. The solver picks arbitrarily

## Starter code

```hlpl
model assign
set I = {1, 2, 3, 4}
set J = {1, 2, 3}
const c = {{1, 5, 6}, {2, 4, 7}, {3, 8, 9}, {5, 2, 4}}, forall i in I, forall j in J
bin x, forall i in I, forall j in J
constr sum_{j in J}{x_{i,j}} <= 1, forall i in I
constr sum_{i in I}{x_{i,j}} = 1, forall j in J
min sum_{i in I}{sum_{j in J}{c_{i,j} * x_{i,j}}}
end

import elytica
def main():
  elytica.init_model("assign")
  elytica.run_model("assign")
  for i in [1,2,3,4]:
    for j in [1,2,3]:
      name = "x"+str(i)+","+str(j)
      print(name, "=", elytica.get_variable_value("assign", name))
  print("obj =", elytica.get_best_primal_bound("assign"))
  return 0
```

## Hint

sum_{j in J}{x_{i,j}} <= 1 (≤ 1, not = 1) lets a worker stay idle.

## What counts as correct

- `no-error` — Model solves
- `numeric-match` — Cheapest assignment is 9 (W3 sits out)
- `code-contains` — Reads the objective from the solver (no hardcoding)

## Mastery variant

Another over-supplied lineup. Which worker gets benched this time?

```hlpl
model assign_v
set I = {1, 2, 3, 4}
set J = {1, 2, 3}
const c = {{2, 4, 5}, {3, 1, 6}, {7, 8, 9}, {5, 4, 2}}, forall i in I, forall j in J
bin x, forall i in I, forall j in J
constr sum_{j in J}{x_{i,j}} <= 1, forall i in I
constr sum_{i in I}{x_{i,j}} = 1, forall j in J
min sum_{i in I}{sum_{j in J}{c_{i,j} * x_{i,j}}}
end

import elytica
def main():
  elytica.init_model("assign_v")
  elytica.run_model("assign_v")
  for i in [1,2,3,4]:
    for j in [1,2,3]:
      name = "x"+str(i)+","+str(j)
      print(name, "=", elytica.get_variable_value("assign_v", name))
  print("obj =", elytica.get_best_primal_bound("assign_v"))
  return 0
```



---

# Shipping — one source

VIII — Transportation — Distribute a fixed supply.

Path: `lessons/shipping-one-source`

# Shipping — one source

Distribute a fixed supply.

*Chapter: VIII — Transportation · lesson id `shipping-one-source` · practice lesson*

---

Simplest transportation: one warehouse with 100 units to distribute across three destinations. Each destination has a minimum demand. Shipping to destination j costs c_j per unit. Minimise total cost.

Demands {20, 30, 40} sum to 90; you have 100 to send. Where does the slack of 10 go? Onto the cheapest route.

## Predict before running

Supply 100 must all ship; minimum demands {20, 30, 40} sum to 90, costs {3, 5, 4}. Where do the 10 slack units land?

- Spread evenly across destinations
- Onto destination 1 (cheapest at cost 3)
- Onto destination 3 (highest demand)

## Starter code

```hlpl
model shipping
var 0 <= x1
var 0 <= x2
var 0 <= x3
constr x1 >= 20
constr x2 >= 30
constr x3 >= 40
constr x1 + x2 + x3 = 100
min 3*x1 + 5*x2 + 4*x3
end

import elytica
def main():
  elytica.init_model("shipping")
  elytica.run_model("shipping")
  for i in [1,2,3]:
    print("x"+str(i), "=", elytica.get_variable_value("shipping", "x"+str(i)))
  print("obj =", elytica.get_best_primal_bound("shipping"))
  return 0
```

## Hint

c₁ = 3 is the cheapest. The extra 10 units pile onto destination 1.

## What counts as correct

- `no-error` — Model solves
- `numeric-match` — Slack lands on the cheapest destination
- `numeric-match` — Min cost is 400
- `code-contains` — Reads the objective from the solver (no hardcoding)
- `code-contains` — Reads variable values from the solver (no hardcoding)

## Mastery variant

New demands and costs. Where does the slack land this time?

```hlpl
model shipping_v
var 0 <= x1
var 0 <= x2
var 0 <= x3
constr x1 >= 15
constr x2 >= 25
constr x3 >= 30
constr x1 + x2 + x3 = 80
min 4*x1 + 6*x2 + 2*x3
end

import elytica
def main():
  elytica.init_model("shipping_v")
  elytica.run_model("shipping_v")
  for i in [1,2,3]:
    print("x"+str(i), "=", elytica.get_variable_value("shipping_v", "x"+str(i)))
  print("obj =", elytica.get_best_primal_bound("shipping_v"))
  return 0
```



---

# Transportation — two sources

VIII — Transportation — Supply and demand both bite.

Path: `lessons/transportation-two-source`

# Transportation — two sources

Supply and demand both bite.

*Chapter: VIII — Transportation · lesson id `transportation-two-source` · practice lesson*

---

Two sources with supplies {50, 60} and three destinations with demands {30, 40, 40}. Total supply 110 = total demand 110 (balanced).

Variables x_{i,j} = units shipped from source i to destination j. Two families of constraints: sources can't ship more than their supply, destinations must get at least their demand. Minimise total transport cost.

## Predict before running

Which source-destination pairs will the solver favour?

- S1→D1 (cost 3) and S2→D3 (cost 2)
- S1 ships everything (cheaper supplier)
- The cells with smallest demand

## Starter code

```hlpl
model transport
set I = {1, 2}
set J = {1, 2, 3}
const c = {{3, 5, 7}, {6, 4, 2}}, forall i in I, forall j in J
const supply = {50, 60}, forall i in I
const demand = {30, 40, 40}, forall j in J
var 0 <= x, forall i in I, forall j in J
constr sum_{j in J}{x_{i,j}} = supply_{i}, forall i in I
constr sum_{i in I}{x_{i,j}} = demand_{j}, forall j in J
min sum_{i in I}{sum_{j in J}{c_{i,j} * x_{i,j}}}
end

import elytica
def main():
  elytica.init_model("transport")
  elytica.run_model("transport")
  for i in [1,2]:
    for j in [1,2,3]:
      name = "x"+str(i)+","+str(j)
      print(name, "=", elytica.get_variable_value("transport", name))
  print("obj =", elytica.get_best_primal_bound("transport"))
  return 0
```

## Hint

Costs are [[3, 5, 7], [6, 4, 2]]. Source 1 likes dest 1; source 2 likes dest 3.

## What counts as correct

- `no-error` — Model solves
- `numeric-match` — Optimal transport cost is 350
- `code-contains` — Reads the objective from the solver (no hardcoding)

## Mastery variant

Two sources, three destinations. Different sizes, different cheapest cells.

```hlpl
model transport_v
set I = {1, 2}
set J = {1, 2, 3}
const c = {{2, 6, 4}, {5, 3, 7}}, forall i in I, forall j in J
const supply = {40, 50}, forall i in I
const demand = {25, 30, 35}, forall j in J
var 0 <= x, forall i in I, forall j in J
constr sum_{j in J}{x_{i,j}} = supply_{i}, forall i in I
constr sum_{i in I}{x_{i,j}} = demand_{j}, forall j in J
min sum_{i in I}{sum_{j in J}{c_{i,j} * x_{i,j}}}
end

import elytica
def main():
  elytica.init_model("transport_v")
  elytica.run_model("transport_v")
  for i in [1,2]:
    for j in [1,2,3]:
      name = "x"+str(i)+","+str(j)
      print(name, "=", elytica.get_variable_value("transport_v", name))
  print("obj =", elytica.get_best_primal_bound("transport_v"))
  return 0
```



---

# Transportation — when supply is tight

VIII — Transportation — What if total supply < total demand?

Path: `lessons/transportation-shortage`

# Transportation — when supply is tight

What if total supply < total demand?

*Chapter: VIII — Transportation · lesson id `transportation-shortage` · practice lesson*

---

Real distribution problems are often unbalanced. If sources can't fully cover demand, you have to relax the demand constraint from `=` to `≤` — destinations get at most their demand, possibly less. Add a penalty term to the objective for unmet demand, or just maximise what gets shipped.

Here total supply is 80 and demand is 110. Maximise total shipped value (per-destination prices p_j) minus transport cost.

## Predict before running

Total supply 80 < total demand 110. Which destinations get fully served?

- All of them, partially
- Only the ones with the highest margin (price − cost)
- Only destinations with smallest demand

## Starter code

```hlpl
model transport
set I = {1, 2}
set J = {1, 2, 3}
const c = {{3, 5, 7}, {6, 4, 2}}, forall i in I, forall j in J
const supply = {40, 40}, forall i in I
const demand = {30, 40, 40}, forall j in J
const price = {10, 12, 9}, forall j in J
var 0 <= x, forall i in I, forall j in J
constr sum_{j in J}{x_{i,j}} <= supply_{i}, forall i in I
constr sum_{i in I}{x_{i,j}} <= demand_{j}, forall j in J
max sum_{i in I}{sum_{j in J}{[price_{j} - c_{i,j}] * x_{i,j}}}
end

import elytica
def main():
  elytica.init_model("transport")
  elytica.run_model("transport")
  for i in [1,2]:
    for j in [1,2,3]:
      name = "x"+str(i)+","+str(j)
      print(name, "=", elytica.get_variable_value("transport", name))
  print("obj =", elytica.get_best_primal_bound("transport"))
  return 0
```

## Hint

Switch to max. Use ≤ on destination demand. Solver will favour high-price destinations.

## What counts as correct

- `no-error` — Model solves
- `stdout-contains` — Output reports an objective
- `code-contains` — Reads the objective from the solver (no hardcoding)

## Mastery variant

Different prices and a tighter shortfall. Same `≤` relaxation lets demand go unmet.

```hlpl
model transport_v
set I = {1, 2}
set J = {1, 2, 3}
const c = {{4, 2, 5}, {3, 5, 1}}, forall i in I, forall j in J
const supply = {30, 30}, forall i in I
const demand = {25, 35, 25}, forall j in J
const price = {8, 9, 7}, forall j in J
var 0 <= x, forall i in I, forall j in J
constr sum_{j in J}{x_{i,j}} <= supply_{i}, forall i in I
constr sum_{i in I}{x_{i,j}} <= demand_{j}, forall j in J
max sum_{i in I}{sum_{j in J}{[price_{j} - c_{i,j}] * x_{i,j}}}
end

import elytica
def main():
  elytica.init_model("transport_v")
  elytica.run_model("transport_v")
  for i in [1,2]:
    for j in [1,2,3]:
      name = "x"+str(i)+","+str(j)
      print(name, "=", elytica.get_variable_value("transport_v", name))
  print("obj =", elytica.get_best_primal_bound("transport_v"))
  return 0
```



---

# Multi-resource production

IX — Resource allocation — Two products, two resources.

Path: `lessons/multi-resource`

# Multi-resource production

Two products, two resources.

*Chapter: IX — Resource allocation · lesson id `multi-resource` · practice lesson*

---

A factory makes two products. Each consumes labour and material at different rates, and each sells at a different price.

You have caps on labour (100 hours) and material (90 units). Variables q_p are continuous (any real quantity ≥ 0). Maximise total revenue.

This is a classic LP. The optimum sits where the two resource constraints meet — both bind.

## Predict before running

At an LP optimum with two constraints, how many constraints typically bind?

- Zero. The optimum sits in the interior
- Both
- Just the cheaper one

## Starter code

```hlpl
model production
set P = {1, 2}
const price = {3, 5}, forall p in P
const labour = {2, 4}, forall p in P
const material = {3, 2}, forall p in P
const LAB = 100
const MAT = 90
var 0 <= q, forall p in P
constr sum_{p in P}{labour_{p} * q_{p}} <= LAB
constr sum_{p in P}{material_{p} * q_{p}} <= MAT
max sum_{p in P}{price_{p} * q_{p}}
end

import elytica
def main():
  elytica.init_model("production")
  elytica.run_model("production")
  for i in [1,2]:
    print("q"+str(i), "=", elytica.get_variable_value("production", "q"+str(i)))
  print("obj =", elytica.get_best_primal_bound("production"))
  return 0
```

## Hint

Solve the two equations simultaneously: 2q₁+4q₂=100, 3q₁+2q₂=90. Both bind at the optimum.

## What counts as correct

- `no-error` — Model solves
- `numeric-match` — q₁ = 20
- `numeric-match` — q₂ = 15
- `numeric-match` — Revenue = 135
- `code-contains` — Reads the objective from the solver (no hardcoding)
- `code-contains` — Reads variable values from the solver (no hardcoding)

## Mastery variant

Different prices and resource budgets. Where do both constraints meet now?

```hlpl
model production_v
set P = {1, 2}
const price = {4, 7}, forall p in P
const labour = {3, 2}, forall p in P
const material = {1, 4}, forall p in P
const LAB = 60
const MAT = 80
var 0 <= q, forall p in P
constr sum_{p in P}{labour_{p} * q_{p}} <= LAB
constr sum_{p in P}{material_{p} * q_{p}} <= MAT
max sum_{p in P}{price_{p} * q_{p}}
end

import elytica
def main():
  elytica.init_model("production_v")
  elytica.run_model("production_v")
  for i in [1,2]:
    print("q"+str(i), "=", elytica.get_variable_value("production_v", "q"+str(i)))
  print("obj =", elytica.get_best_primal_bound("production_v"))
  return 0
```



---

# Multi-period planning

IX — Resource allocation — Inventory carries forward.

Path: `lessons/multi-period`

# Multi-period planning

Inventory carries forward.

*Chapter: IX — Resource allocation · lesson id `multi-period` · practice lesson*

---

Add time. Demand changes period to period, and so does production capacity. You can pre-produce and carry inventory forward — at a cost per unit per period.

Demand {30, 50, 20} over three periods, capacity {60, 30, 25}. Period 2 demand (50) exceeds capacity (30) — you have to pre-produce 20 units in period 1 and carry them. Carrying cost = 2 per unit per period.

Minimum carry: 20 units from t1 to t2 → carry cost 2·20 = 40.

## Predict before running

Period 2 demand 50 exceeds period 2 capacity 30. How does the solver cope?

- Pre-produce 20 in period 1 and carry them
- Demand drops to capacity (50 → 30)
- The model is infeasible

## Starter code

```hlpl
model multi_period
set T = {1, 2, 3}
const demand = {30, 50, 20}, forall t in T
const capacity = {60, 30, 25}, forall t in T
const inv_cost = 2
var 0 <= prod, forall t in T
var 0 <= inv, forall t in T

constr prod_{t} <= capacity_{t}, forall t in T
constr inv_{1} = prod_{1} - demand_{1}
constr inv_{2} = inv_{1} + prod_{2} - demand_{2}
constr inv_{3} = inv_{2} + prod_{3} - demand_{3}

min sum_{t in T}{inv_cost * inv_{t}}
end

import elytica
def main():
  elytica.init_model("multi_period")
  elytica.run_model("multi_period")
  for i in [1,2,3]:
    print("prod"+str(i), "=", elytica.get_variable_value("multi_period", "prod"+str(i)))
  for i in [1,2,3]:
    print("inv"+str(i), "=", elytica.get_variable_value("multi_period", "inv"+str(i)))
  print("obj =", elytica.get_best_primal_bound("multi_period"))
  return 0
```

## Hint

Inventory balance: inv_{t} = inv_{t-1} + prod_{t} − demand_{t}.

## What counts as correct

- `no-error` — Model solves
- `numeric-match` — Minimum carrying cost is 40 (carry 20 units t1→t2)
- `code-contains` — Reads the objective from the solver (no hardcoding)

## Mastery variant

Different demand, capacity, and a higher carrying cost. Where does the bottleneck sit?

```hlpl
model multi_period_v
set T = {1, 2, 3}
const demand = {20, 45, 30}, forall t in T
const capacity = {40, 25, 35}, forall t in T
const inv_cost = 3
var 0 <= prod, forall t in T
var 0 <= inv, forall t in T

constr prod_{t} <= capacity_{t}, forall t in T
constr inv_{1} = prod_{1} - demand_{1}
constr inv_{2} = inv_{1} + prod_{2} - demand_{2}
constr inv_{3} = inv_{2} + prod_{3} - demand_{3}

min sum_{t in T}{inv_cost * inv_{t}}
end

import elytica
def main():
  elytica.init_model("multi_period_v")
  elytica.run_model("multi_period_v")
  for i in [1,2,3]:
    print("prod"+str(i), "=", elytica.get_variable_value("multi_period_v", "prod"+str(i)))
  for i in [1,2,3]:
    print("inv"+str(i), "=", elytica.get_variable_value("multi_period_v", "inv"+str(i)))
  print("obj =", elytica.get_best_primal_bound("multi_period_v"))
  return 0
```



---

# Shortest path — edges and distances

X — Shortest path — Start with what you decide.

Path: `lessons/sp-edges`

# Shortest path — edges and distances

Start with what you decide.

*Chapter: X — Shortest path · lesson id `sp-edges` · practice lesson*

---

Network: 4 nodes, 5 directed edges. The plan is to route a unit of flow from node 1 (source) to node 4 (sink) along the cheapest path.

Edges: 1→2 (d=4), 1→3 (d=2), 3→2 (d=1), 2→4 (d=3), 3→4 (d=5). Binary x_e per edge.

For now: just declare the decision variables and the objective. With no constraints, the solver picks zero edges — cost 0. Run it, see the trivial answer, understand why we need flow conservation in the next lesson.

## Predict before running

Edge variables and a minimise-cost objective, but no conservation yet. What's the optimum?

- 0. The solver picks no edges
- The shortest s-to-t path cost
- Infinite (unbounded)

## Starter code

```hlpl
model sp
set E = {12, 13, 32, 24, 34}
const d = {4, 2, 1, 3, 5}, forall e in E
bin x, forall e in E
min sum_{e in E}{d_{e} * x_{e}}
end

import elytica
def main():
  elytica.init_model("sp")
  elytica.run_model("sp")
  for i in [12,13,32,24,34]:
    print("x"+str(i), "=", elytica.get_variable_value("sp", "x"+str(i)))
  print("obj =", elytica.get_best_primal_bound("sp"))
  return 0
```

## Hint

No constraints yet → solver picks nothing → cost 0. That's the point.

## What counts as correct

- `no-error` — Model solves
- `numeric-match` — Without conservation, cost is trivially 0
- `code-contains` — Reads the objective from the solver (no hardcoding)

## Mastery variant

Same network shape, different costs. Without conservation, still nothing picked.

```hlpl
model sp_v
set E = {12, 13, 32, 24, 34}
const d = {6, 3, 2, 4, 8}, forall e in E
bin x, forall e in E
min sum_{e in E}{d_{e} * x_{e}}
end

import elytica
def main():
  elytica.init_model("sp_v")
  elytica.run_model("sp_v")
  for i in [12,13,32,24,34]:
    print("x"+str(i), "=", elytica.get_variable_value("sp_v", "x"+str(i)))
  print("obj =", elytica.get_best_primal_bound("sp_v"))
  return 0
```



---

# Shortest path — flow conservation

X — Shortest path — Force a path from source to sink.

Path: `lessons/sp-conservation`

# Shortest path — flow conservation

Force a path from source to sink.

*Chapter: X — Shortest path · lesson id `sp-conservation` · practice lesson*

---

A path is defined by flow conservation: at the source one unit flows out; at the sink one unit flows in; at every internal node, inflow equals outflow.

Translate to linear constraints:

  node 1 (source): out − in =  1   →  x₁₂ + x₁₃         = 1
  node 2:          out − in =  0   →  x₂₄ − x₁₂ − x₃₂   = 0
  node 3:          out − in =  0   →  x₃₂ + x₃₄ − x₁₃   = 0
  node 4 (sink):   out − in = −1   →  x₂₄ + x₃₄         = 1

Run it. The solver finds 1 → 3 → 2 → 4 with cost 2 + 1 + 3 = 6.

## Predict before running

Edges 1→2 (4), 1→3 (2), 3→2 (1), 2→4 (3), 3→4 (5), routing one unit from 1 to 4. What's the shortest path?

- 1 → 3 → 4 (cost 7)
- 1 → 3 → 2 → 4 (cost 6)
- 1 → 2 → 4 (cost 7)

## Starter code

```hlpl
model sp
set E = {12, 13, 32, 24, 34}
const d = {4, 2, 1, 3, 5}, forall e in E
bin x, forall e in E
# TODO: four flow-conservation constraints, one per node
min sum_{e in E}{d_{e} * x_{e}}
end

import elytica
def main():
  elytica.init_model("sp")
  elytica.run_model("sp")
  for i in [12,13,32,24,34]:
    print("x"+str(i), "=", elytica.get_variable_value("sp", "x"+str(i)))
  print("obj =", elytica.get_best_primal_bound("sp"))
  return 0
```

## Hint

Add the four conservation constraints. Each one says "outgoing − incoming = balance".

## What counts as correct

- `no-error` — Model solves
- `numeric-match` — Shortest 1→4 path costs 6 (1 → 3 → 2 → 4)
- `code-contains` — Reads the objective from the solver (no hardcoding)

## Solution

```hlpl
model sp
set E = {12, 13, 32, 24, 34}
const d = {4, 2, 1, 3, 5}, forall e in E
bin x, forall e in E
constr x_{12} + x_{13} = 1
constr x_{24} - x_{12} - x_{32} = 0
constr x_{32} + x_{34} - x_{13} = 0
constr x_{24} + x_{34} = 1
min sum_{e in E}{d_{e} * x_{e}}
end

import elytica
def main():
  elytica.init_model("sp")
  elytica.run_model("sp")
  for i in [12,13,32,24,34]:
    print("x"+str(i), "=", elytica.get_variable_value("sp", "x"+str(i)))
  print("obj =", elytica.get_best_primal_bound("sp"))
  return 0
```

## Mastery variant

Different edge costs on the same network. Which path wins now?

```hlpl
model sp_v
set E = {12, 13, 32, 24, 34}
const d = {6, 3, 2, 4, 8}, forall e in E
bin x, forall e in E
constr x_{12} + x_{13} = 1
constr x_{24} - x_{12} - x_{32} = 0
constr x_{32} + x_{34} - x_{13} = 0
constr x_{24} + x_{34} = 1
min sum_{e in E}{d_{e} * x_{e}}
end

import elytica
def main():
  elytica.init_model("sp_v")
  elytica.run_model("sp_v")
  for i in [12,13,32,24,34]:
    print("x"+str(i), "=", elytica.get_variable_value("sp_v", "x"+str(i)))
  print("obj =", elytica.get_best_primal_bound("sp_v"))
  return 0
```



---

# Max flow — variables and capacities

XI — Max flow — Continuous flow on each edge.

Path: `lessons/flow-vars-caps`

# Max flow — variables and capacities

Continuous flow on each edge.

*Chapter: XI — Max flow · lesson id `flow-vars-caps` · practice lesson*

---

Same kind of network, different question: how much *total* flow can we push from a source s to a sink t given per-edge capacities?

Network: s, a, b, t. Edges with capacities — s→a (8), s→b (6), a→b (3), a→t (7), b→t (5).

We label nodes 1=s, 2=a, 3=b, 4=t so the edge IDs read as their endpoints: edge 12 is s→a, 23 is a→b, and so on. Variables x_e are continuous (any non-negative real), each capped at its edge's capacity. The objective is the flow *out* of s, namely x_{12} + x_{13}.

Run it. Without conservation, the solver naively saturates the source edges — total 14. But this isn't a valid flow!

## Predict before running

Capacities {8, 6, 3, 7, 5}, maximise total at source. No conservation yet. What does the solver report?

- 14. Sum of source-edge capacities
- 12. The real max flow
- 0. No path to maximise

## Starter code

```hlpl
model flow
# Edges labelled by node pair (s=1, a=2, b=3, t=4):
#   12 = s→a   13 = s→b   23 = a→b   24 = a→t   34 = b→t
set E = {12, 13, 23, 24, 34}
const capacity = {8, 6, 3, 7, 5}, forall e in E
var 0 <= x, forall e in E
constr x_{e} <= capacity_{e}, forall e in E
max x_{12} + x_{13}
end

import elytica
def main():
  elytica.init_model("flow")
  elytica.run_model("flow")
  for i in [12,13,23,24,34]:
    print("x"+str(i), "=", elytica.get_variable_value("flow", "x"+str(i)))
  print("obj =", elytica.get_best_primal_bound("flow"))
  return 0
```

## Hint

Without conservation, the solver maxes x_{12}=8 and x_{13}=6, total 14. Real max flow is lower.

## What counts as correct

- `no-error` — Model solves
- `numeric-match` — Without conservation, naive max is 14 (sum of source caps)
- `code-contains` — Reads the objective from the solver (no hardcoding)

## Mastery variant

Same network shape, fresh capacities. Source-saturation gives the naive answer.

```hlpl
model flow_v
set E = {12, 13, 23, 24, 34}
const capacity = {9, 5, 4, 6, 7}, forall e in E
var 0 <= x, forall e in E
constr x_{e} <= capacity_{e}, forall e in E
max x_{12} + x_{13}
end

import elytica
def main():
  elytica.init_model("flow_v")
  elytica.run_model("flow_v")
  for i in [12,13,23,24,34]:
    print("x"+str(i), "=", elytica.get_variable_value("flow_v", "x"+str(i)))
  print("obj =", elytica.get_best_primal_bound("flow_v"))
  return 0
```



---

# Max flow — add conservation

XI — Max flow — Inflow = outflow at internal nodes.

Path: `lessons/flow-conservation`

# Max flow — add conservation

Inflow = outflow at internal nodes.

*Chapter: XI — Max flow · lesson id `flow-conservation` · practice lesson*

---

A valid flow conserves at every internal node — whatever enters must leave.

  node a:  x_{12} = x_{23} + x_{24}
  node b:  x_{13} + x_{23} = x_{34}

Add these two constraints and the max drops from 14 to 12. The min cut is the pair of edges into t — a→t (7) and b→t (5) — totalling 12.

## Predict before running

Add conservation at the two internal nodes. What's the true max flow s→t?

- 14. Same as without conservation
- 12. Bottlenecked by the edges into t
- 11. Bottlenecked by some other cut

## Starter code

```hlpl
model flow
# Edges (s=1, a=2, b=3, t=4): 12=s→a, 13=s→b, 23=a→b, 24=a→t, 34=b→t
set E = {12, 13, 23, 24, 34}
const capacity = {8, 6, 3, 7, 5}, forall e in E
var 0 <= x, forall e in E
constr x_{e} <= capacity_{e}, forall e in E
# TODO: conservation at node a (12 = 23 + 24) and node b (13 + 23 = 34)
max x_{12} + x_{13}
end

import elytica
def main():
  elytica.init_model("flow")
  elytica.run_model("flow")
  for i in [12,13,23,24,34]:
    print("x"+str(i), "=", elytica.get_variable_value("flow", "x"+str(i)))
  print("obj =", elytica.get_best_primal_bound("flow"))
  return 0
```

## Hint

Two constraints — one per internal node. The solver figures out the right split.

## What counts as correct

- `no-error` — Model solves
- `numeric-match` — Real max flow is 12 (bottlenecked by b→t cap 5)
- `code-contains` — Reads the objective from the solver (no hardcoding)

## Solution

```hlpl
model flow
set E = {12, 13, 23, 24, 34}
const capacity = {8, 6, 3, 7, 5}, forall e in E
var 0 <= x, forall e in E
constr x_{e} <= capacity_{e}, forall e in E
constr x_{12} = x_{23} + x_{24}
constr x_{13} + x_{23} = x_{34}
max x_{12} + x_{13}
end

import elytica
def main():
  elytica.init_model("flow")
  elytica.run_model("flow")
  for i in [12,13,23,24,34]:
    print("x"+str(i), "=", elytica.get_variable_value("flow", "x"+str(i)))
  print("obj =", elytica.get_best_primal_bound("flow"))
  return 0
```

## Mastery variant

Same network, fresh capacities. Where's the min-cut this time?

```hlpl
model flow_v
set E = {12, 13, 23, 24, 34}
const capacity = {9, 5, 4, 6, 7}, forall e in E
var 0 <= x, forall e in E
constr x_{e} <= capacity_{e}, forall e in E
constr x_{12} = x_{23} + x_{24}
constr x_{13} + x_{23} = x_{34}
max x_{12} + x_{13}
end

import elytica
def main():
  elytica.init_model("flow_v")
  elytica.run_model("flow_v")
  for i in [12,13,23,24,34]:
    print("x"+str(i), "=", elytica.get_variable_value("flow_v", "x"+str(i)))
  print("obj =", elytica.get_best_primal_bound("flow_v"))
  return 0
```



---

# Max flow — alternative formulation

XI — Max flow — Measure flow at the sink instead.

Path: `lessons/flow-sink-balance`

# Max flow — alternative formulation

Measure flow at the sink instead.

*Chapter: XI — Max flow · lesson id `flow-sink-balance` · practice lesson*

---

An equivalent way to state max flow: maximise what arrives at the sink. By conservation, the two formulations always agree, but writing the objective at the sink makes the model robust when you forget the source side.

Change the objective to `max x_{24} + x_{34}` (the two edges into t). The optimum is still 12.

Bonus: in a richer formulation you'd add a variable F for total flow and constraints outflow_s − inflow_s = F, inflow_t − outflow_t = F, then `max F`. That's the canonical form.

## Starter code

```hlpl
model flow
set E = {12, 13, 23, 24, 34}
const capacity = {8, 6, 3, 7, 5}, forall e in E
var 0 <= x, forall e in E
constr x_{e} <= capacity_{e}, forall e in E
constr x_{12} = x_{23} + x_{24}
constr x_{13} + x_{23} = x_{34}
# TODO: change the objective to measure flow INTO t (x_24 + x_34)
max x_{12} + x_{13}
end

import elytica
def main():
  elytica.init_model("flow")
  elytica.run_model("flow")
  print("obj =", elytica.get_best_primal_bound("flow"))
  return 0
```

## Hint

Change one line. The objective.

## What counts as correct

- `no-error` — Model solves
- `numeric-match` — Same max flow measured at the sink
- `code-contains` — Reads the objective from the solver (no hardcoding)

## Solution

```hlpl
model flow
set E = {12, 13, 23, 24, 34}
const capacity = {8, 6, 3, 7, 5}, forall e in E
var 0 <= x, forall e in E
constr x_{e} <= capacity_{e}, forall e in E
constr x_{12} = x_{23} + x_{24}
constr x_{13} + x_{23} = x_{34}
max x_{24} + x_{34}
end

import elytica
def main():
  elytica.init_model("flow")
  elytica.run_model("flow")
  print("obj =", elytica.get_best_primal_bound("flow"))
  return 0
```

## Mastery variant

Same fresh capacities as the conservation variant. Confirm the sink sees the same total.

```hlpl
model flow_v
set E = {12, 13, 23, 24, 34}
const capacity = {9, 5, 4, 6, 7}, forall e in E
var 0 <= x, forall e in E
constr x_{e} <= capacity_{e}, forall e in E
constr x_{12} = x_{23} + x_{24}
constr x_{13} + x_{23} = x_{34}
# TODO: change the objective to measure flow INTO t (x_24 + x_34)
max x_{12} + x_{13}
end

import elytica
def main():
  elytica.init_model("flow_v")
  elytica.run_model("flow_v")
  print("obj =", elytica.get_best_primal_bound("flow_v"))
  return 0
```



---

# Set cover — minimum number of sets

XII — Set covering — Cover every element with as few sets as possible.

Path: `lessons/set-cover-basic`

# Set cover — minimum number of sets

Cover every element with as few sets as possible.

*Chapter: XII — Set covering · lesson id `set-cover-basic` · practice lesson*

---

Five elements {1, 2, 3, 4, 5}. Four candidate sets:

  S₁ = {1, 2}
  S₂ = {2, 3}
  S₃ = {3, 4, 5}
  S₄ = {1, 4}

Pick the minimum number of sets that together cover every element. Each set is a binary y_s.

One constraint per element: at least one chosen set must include it. Element 5 lives only in S₃, so S₃ is forced. Then we need any single set covering both 1 and 2 — S₁ does it. Optimum: 2 sets {S₁, S₃}.

## Predict before running

Element 5 appears only in S₃. What does this force?

- S₃ must be picked
- S₃ should be avoided (it has the fewest elements)
- Doesn't affect anything. The solver decides

## Starter code

```hlpl
model set_cover
bin y1
bin y2
bin y3
bin y4
constr y1 + y4 >= 1     # element 1
constr y1 + y2 >= 1     # element 2
constr y2 + y3 >= 1     # element 3
constr y3 + y4 >= 1     # element 4
constr y3 >= 1          # element 5
min y1 + y2 + y3 + y4
end

import elytica
def main():
  elytica.init_model("set_cover")
  elytica.run_model("set_cover")
  for i in [1,2,3,4]:
    print("y"+str(i), "=", elytica.get_variable_value("set_cover", "y"+str(i)))
  print("obj =", elytica.get_best_primal_bound("set_cover"))
  return 0
```

## Hint

Element 5 is only in S₃ → S₃ must be picked. Then S₁ covers the rest.

## What counts as correct

- `no-error` — Model solves
- `numeric-match` — Minimum cover uses 2 sets
- `numeric-match` — S₃ is forced (element 5)
- `code-contains` — Reads the objective from the solver (no hardcoding)
- `code-contains` — Reads variable values from the solver (no hardcoding)

## Mastery variant

Different sets and elements. Still find the smallest cover.

```hlpl
model set_cover_v
# S1 = {1,2,3}, S2 = {3,4}, S3 = {4,5}, S4 = {1,5}
bin y1
bin y2
bin y3
bin y4
constr y1 + y4 >= 1     # element 1
constr y1 >= 1          # element 2 (only in S1)
constr y1 + y2 >= 1     # element 3
constr y2 + y3 >= 1     # element 4
constr y3 + y4 >= 1     # element 5
min y1 + y2 + y3 + y4
end

import elytica
def main():
  elytica.init_model("set_cover_v")
  elytica.run_model("set_cover_v")
  for i in [1,2,3,4]:
    print("y"+str(i), "=", elytica.get_variable_value("set_cover_v", "y"+str(i)))
  print("obj =", elytica.get_best_primal_bound("set_cover_v"))
  return 0
```



---

# Set cover — minimum cost

XII — Set covering — Sets are not all equal.

Path: `lessons/set-cover-weighted`

# Set cover — minimum cost

Sets are not all equal.

*Chapter: XII — Set covering · lesson id `set-cover-weighted` · practice lesson*

---

In practice each set has a cost — opening a warehouse, running a sensor, buying coverage. Same coverage matrix, but now minimise the total *cost* of the chosen sets.

Costs: S₁ = 3, S₂ = 2, S₃ = 5, S₄ = 4. Element 5 still forces S₃ (cost 5). For the rest we compare: cheapest add-on covering both 1 and 2 is S₁ alone (cost 3). Total: 8.

## Predict before running

Set costs are S₁=3, S₂=2, S₃=5, S₄=4, and element 5 still lives only in S₃. What is the minimum-cost cover?

- 8 — pick S₃ (forced) plus S₁
- 7 — pick S₃ plus S₂ (cheaper than S₁)
- 5 — pick the two cheapest sets, S₂ and S₁

## Starter code

```hlpl
model set_cover
bin y1
bin y2
bin y3
bin y4
constr y1 + y4 >= 1
constr y1 + y2 >= 1
constr y2 + y3 >= 1
constr y3 + y4 >= 1
constr y3 >= 1
min 3*y1 + 2*y2 + 5*y3 + 4*y4
end

import elytica
def main():
  elytica.init_model("set_cover")
  elytica.run_model("set_cover")
  for i in [1,2,3,4]:
    print("y"+str(i), "=", elytica.get_variable_value("set_cover", "y"+str(i)))
  print("obj =", elytica.get_best_primal_bound("set_cover"))
  return 0
```

## Hint

S₃ is still forced (cost 5). Cheapest way to cover {1, 2}: S₁ alone, cost 3. Total = 8.

## What counts as correct

- `no-error` — Model solves
- `numeric-match` — Minimum-cost cover is 8
- `code-contains` — Reads the objective from the solver (no hardcoding)

## Mastery variant

Same sets as the basic variant, now with prices. Pick the cheapest cover.

```hlpl
model set_cover_v
# S1 = {1,2,3}, S2 = {3,4}, S3 = {4,5}, S4 = {1,5}
bin y1
bin y2
bin y3
bin y4
constr y1 + y4 >= 1
constr y1 >= 1
constr y1 + y2 >= 1
constr y2 + y3 >= 1
constr y3 + y4 >= 1
min 4*y1 + 6*y2 + 3*y3 + 5*y4
end

import elytica
def main():
  elytica.init_model("set_cover_v")
  elytica.run_model("set_cover_v")
  for i in [1,2,3,4]:
    print("y"+str(i), "=", elytica.get_variable_value("set_cover_v", "y"+str(i)))
  print("obj =", elytica.get_best_primal_bound("set_cover_v"))
  return 0
```



---

# Graphs, degree, and three questions

XIIb — Graph theory — Vertices, edges, the handshaking lemma, and the problems we will model.

Path: `lessons/gt-intro`

# Graphs, degree, and three questions

Vertices, edges, the handshaking lemma, and the problems we will model.

*Chapter: XIIb — Graph theory · lesson id `gt-intro` · theory lesson*

---

A $graph$ is the barest description of "things and the connections between them": a set of $vertices$ and a set of $edges$ joining pairs of them. Roads between cities, friendships between people, dependencies between tasks — all graphs. This optional chapter takes three of the most famous questions you can ask about a graph — how few vertices touch every edge, how many vertices you can pick with no edge between them, and how many edges you can pick sharing no vertex — and writes each one as a small integer program you already know how to solve. One graph, three models, two clean theorems tying them together.

## Notes

**Definition (Graph).** A $graph$ $G = (V, E)$ is a finite set of $vertices$ $V$ together with a set of $edges$ $E$, where each edge is an unordered pair $\{u, v\}$ of distinct vertices. Two vertices joined by an edge are $adjacent$; an edge and a vertex it contains are $incident$. Unless we say otherwise the graph is $undirected$ (edges have no direction) and $simple$ (no loops, no repeated edges).

**Definition (Degree).** The $degree$ $\deg(v)$ of a vertex $v$ is the number of edges incident to it — how many neighbours it has.

### Our graph for the whole chapter

Every lesson here works on the same six-vertex graph so you can watch the three answers relate to one another. Its edges are $\{1,2\}, \{1,3\}, \{1,4\}, \{2,5\}, \{4,5\}, \{5,6\}$.

*[network-graph diagram: The chapter graph: six vertices, six edges. Vertices 1 and 5 are the hubs (degree 3); vertices 3 and 6 are leaves (degree 1).]*

### The handshaking lemma

The first thing to know about degrees is that they are not free to be anything — they must add up correctly.

**Theorem (Handshaking lemma).** In any graph $G = (V, E)$, the sum of the vertex degrees equals twice the number of edges: $$\sum_{v \in V} \deg(v) = 2\,|E|.$$ In particular, the number of vertices of odd degree is even.

**Proof, step by step (Handshaking lemma).** 

1. *Count the same thing two ways. What are we counting?*
   Count the incidences — pairs $(v, e)$ where vertex $v$ is an endpoint of edge $e$.
2. *Count incidences by summing over vertices.*
   Each vertex $v$ contributes exactly $\deg(v)$ incidences, one per edge touching it. So the total is $\sum_{v \in V} \deg(v)$.
3. *Now count the same incidences by summing over edges.*
   Each edge has exactly two endpoints, so it contributes exactly $2$ incidences. With $|E|$ edges the total is $2\,|E|$.
4. *Conclude.*
   Both count the same set, so $\sum_{v \in V} \deg(v) = 2\,|E|$. The right side is even, so $|\{v \in V : \deg(v) \text{ odd}\}|$ is even. $\blacksquare$

Check it on our graph: the degrees are $\deg(1)=3,\ \deg(2)=2,\ \deg(3)=1,\ \deg(4)=2,\ \deg(5)=3,\ \deg(6)=1$. Their sum is $3+2+1+2+3+1 = 12 = 2 \times 6$, matching the six edges. Four vertices have odd degree — $1, 3, 5, 6$ — and four is even, exactly as the lemma requires.

**Quick check.** The handshaking lemma forces the number of odd-degree vertices to be even. Which degree sequence does it rule out on the spot?

- $(3, 2, 2, 2)$  ← correct
- $(3, 2, 2, 1)$
- $(2, 2, 2, 2)$

### Bipartite graphs

**Definition (Bipartite graph).** A graph is $bipartite$ if its vertices can be split into two sets $A$ and $B$ so that every edge joins a vertex in $A$ to a vertex in $B$ — no edge stays inside $A$ or inside $B$. Equivalently (König, 1936): a graph is bipartite if and only if it contains no cycle of odd length.

> Our chapter graph is bipartite: take $A = \{1, 5\}$ and $B = \{2, 3, 4, 6\}$ and check that all six edges cross between the two sides. That fact will matter in the last lesson — bipartite graphs make one of our two theorems especially sharp.

### Three questions, three integer programs

1. $Vertex\ cover$ — fewest vertices touching every edge: $\min \sum_{v \in V} y_v$ subject to $y_u + y_v \geq 1 \ \forall \{u,v\} \in E$, $y_v \in \{0,1\} \ \forall v \in V$.
2. $Independent\ set$ — most vertices with no edge between them: $\max \sum_{v \in V} z_v$ subject to $z_u + z_v \leq 1 \ \forall \{u,v\} \in E$, $z_v \in \{0,1\} \ \forall v \in V$.
3. $Matching$ — most edges sharing no vertex: $\max \sum_{e \in E} x_e$ subject to $\sum_{e \in E : v \in e} x_e \leq 1 \ \forall v \in V$, $x_e \in \{0,1\} \ \forall e \in E$.

Notice cover and independent set are the same skeleton with the inequality flipped and the sense reversed. That is not a coincidence — it is the next lesson.

**Recap.**

- A graph is vertices plus edges; $\deg(v)$ counts a vertex's incident edges.
- Handshaking: $\sum_{v \in V} \deg(v) = 2|E|$, so odd-degree vertices come in an even number.
- Bipartite = 2-colourable = no odd cycle. Our chapter graph is bipartite.
- Vertex cover, independent set, and matching are each one small binary program.



---

# Minimum vertex cover

XIIb — Graph theory — The fewest vertices that touch every edge.

Path: `lessons/gt-vertex-cover`

# Minimum vertex cover

The fewest vertices that touch every edge.

*Chapter: XIIb — Graph theory · lesson id `gt-vertex-cover` · practice lesson*

---

A $vertex\ cover$ is a set of vertices such that every edge has at least one endpoint in the set — think of it as placing a guard on a vertex so it watches every incident corridor, and wanting every corridor watched with the fewest guards.

One binary variable y_v per vertex (1 = chosen). One constraint per edge {u, v}: y_u + y_v >= 1, i.e. at least one endpoint is chosen. Minimise the number of chosen vertices.

On our graph the answer is 2: guarding the two hubs, vertices 1 and 5, covers all six edges. Every edge touches 1 or 5 — which is exactly what it means for {1, 5} to be one side of the bipartition.

## Predict before running

Edges {1,2},{1,3},{1,4},{2,5},{4,5},{5,6}. What is the fewest vertices that together touch every edge?

- 2 — the two hubs {1, 5}
- 3 — one hub plus a leaf
- 4 — the independent-set side {2, 3, 4, 6}

## Starter code

```hlpl
model vc
set V = {1, 2, 3, 4, 5, 6}
bin y, forall v in V
# TODO: one "y_u + y_v >= 1" constraint per edge
#   edges: 12, 13, 14, 25, 45, 56
min sum_{v in V}{y_{v}}
end

import elytica
def main():
  elytica.init_model("vc")
  elytica.run_model("vc")
  for i in [1,2,3,4,5,6]:
    print("y"+str(i), "=", elytica.get_variable_value("vc", "y"+str(i)))
  print("obj =", elytica.get_best_primal_bound("vc"))
  return 0
```

## Hint

Six edges → six "y_u + y_v >= 1" constraints. Vertices 1 and 5 alone cover everything.

## What counts as correct

- `no-error` — Model solves
- `numeric-match` — Minimum vertex cover uses 2 vertices
- `numeric-match` — Hub 1 is in the cover
- `numeric-match` — Hub 5 is in the cover
- `code-contains` — Reads the objective from the solver (no hardcoding)
- `code-contains` — Reads variable values from the solver (no hardcoding)

## Solution

```hlpl
model vc
set V = {1, 2, 3, 4, 5, 6}
bin y, forall v in V
constr y_{1} + y_{2} >= 1
constr y_{1} + y_{3} >= 1
constr y_{1} + y_{4} >= 1
constr y_{2} + y_{5} >= 1
constr y_{4} + y_{5} >= 1
constr y_{5} + y_{6} >= 1
min sum_{v in V}{y_{v}}
end

import elytica
def main():
  elytica.init_model("vc")
  elytica.run_model("vc")
  for i in [1,2,3,4,5,6]:
    print("y"+str(i), "=", elytica.get_variable_value("vc", "y"+str(i)))
  print("obj =", elytica.get_best_primal_bound("vc"))
  return 0
```

## Mastery variant

A different graph: a triangle {1,2,3} with a tail out to vertex 4. Cover every edge.

```hlpl
model vc_v
# triangle 1-2-3 plus a pendant edge 3-4
set V = {1, 2, 3, 4}
bin y, forall v in V
# TODO: cover edges 12, 13, 23, 34
min sum_{v in V}{y_{v}}
end

import elytica
def main():
  elytica.init_model("vc_v")
  elytica.run_model("vc_v")
  for i in [1,2,3,4]:
    print("y"+str(i), "=", elytica.get_variable_value("vc_v", "y"+str(i)))
  print("obj =", elytica.get_best_primal_bound("vc_v"))
  return 0
```



---

# Maximum independent set

XIIb — Graph theory — The most vertices with no edge between any two.

Path: `lessons/gt-independent-set`

# Maximum independent set

The most vertices with no edge between any two.

*Chapter: XIIb — Graph theory · lesson id `gt-independent-set` · practice lesson*

---

An $independent\ set$ is the opposite instinct: pick as $many$ vertices as you can such that no edge joins two of them — a set of mutually non-adjacent vertices.

Same variables, flipped constraint. Binary z_v per vertex; for each edge {u, v} at most one endpoint may be chosen, so z_u + z_v <= 1. Maximise the number chosen.

On our graph the answer is 4: {2, 3, 4, 6} has no edge inside it. Look at what happened — that is exactly the four vertices the minimum cover {1, 5} left out. Cover and independent set are complements.

## Predict before running

Same six-vertex graph. What is the largest set of vertices with no edge between any two of them?

- 4 — the vertices {2, 3, 4, 6}
- 2 — the two hubs {1, 5}
- 3 — a path's worth of vertices

## Starter code

```hlpl
model is
set V = {1, 2, 3, 4, 5, 6}
bin z, forall v in V
# TODO: one "z_u + z_v <= 1" constraint per edge
#   edges: 12, 13, 14, 25, 45, 56
max sum_{v in V}{z_{v}}
end

import elytica
def main():
  elytica.init_model("is")
  elytica.run_model("is")
  for i in [1,2,3,4,5,6]:
    print("z"+str(i), "=", elytica.get_variable_value("is", "z"+str(i)))
  print("obj =", elytica.get_best_primal_bound("is"))
  return 0
```

## Hint

Flip the cover: for each edge, z_u + z_v <= 1. The four non-hub vertices {2,3,4,6} are mutually non-adjacent.

## What counts as correct

- `no-error` — Model solves
- `numeric-match` — Maximum independent set has 4 vertices
- `numeric-match` — Hub 1 is excluded
- `numeric-match` — Hub 5 is excluded
- `code-contains` — Reads the objective from the solver (no hardcoding)
- `code-contains` — Reads variable values from the solver (no hardcoding)

## Solution

```hlpl
model is
set V = {1, 2, 3, 4, 5, 6}
bin z, forall v in V
constr z_{1} + z_{2} <= 1
constr z_{1} + z_{3} <= 1
constr z_{1} + z_{4} <= 1
constr z_{2} + z_{5} <= 1
constr z_{4} + z_{5} <= 1
constr z_{5} + z_{6} <= 1
max sum_{v in V}{z_{v}}
end

import elytica
def main():
  elytica.init_model("is")
  elytica.run_model("is")
  for i in [1,2,3,4,5,6]:
    print("z"+str(i), "=", elytica.get_variable_value("is", "z"+str(i)))
  print("obj =", elytica.get_best_primal_bound("is"))
  return 0
```

## Mastery variant

The same triangle-with-a-tail graph. How many mutually non-adjacent vertices this time?

```hlpl
model is_v
set V = {1, 2, 3, 4}
bin z, forall v in V
# TODO: z_u + z_v <= 1 for edges 12, 13, 23, 34
max sum_{v in V}{z_{v}}
end

import elytica
def main():
  elytica.init_model("is_v")
  elytica.run_model("is_v")
  for i in [1,2,3,4]:
    print("z"+str(i), "=", elytica.get_variable_value("is_v", "z"+str(i)))
  print("obj =", elytica.get_best_primal_bound("is_v"))
  return 0
```



---

# Maximum matching and König's theorem

XIIb — Graph theory — The most edges sharing no vertex — and why it equals the cover.

Path: `lessons/gt-matching`

# Maximum matching and König's theorem

The most edges sharing no vertex — and why it equals the cover.

*Chapter: XIIb — Graph theory · lesson id `gt-matching` · practice lesson*

---

A $matching$ picks edges instead of vertices: as many edges as possible so that no vertex is used twice — think of pairing people off, where nobody can be in two pairs.

One binary variable x_e per edge (1 = in the matching). One constraint per vertex: the edges incident to it sum to at most 1. Maximise the number of edges.

On our graph the answer is 2 — for example {13, 45}. Vertices 3 and 6 are leaves that both compete for a hub, so no perfect (three-edge) pairing exists.

Now the punchline. Maximum matching = 2, and minimum vertex cover = 2 (lesson 2). That is no accident: König's theorem says that in any *bipartite* graph, the size of a maximum matching equals the size of a minimum vertex cover. Our graph is bipartite, so the two numbers must agree.

## Predict before running

Same graph. What is the largest set of edges you can pick so that no two of them share a vertex?

- 2 — e.g. {1-3, 4-5}
- 3 — a perfect matching pairing all six vertices
- 1 — any two edges must touch

## Starter code

```hlpl
model match
set E = {12, 13, 14, 25, 45, 56}
bin x, forall e in E
# TODO: one constraint per vertex — its incident edges sum to <= 1
#   v1: 12,13,14   v2: 12,25   v3: 13   v4: 14,45   v5: 25,45,56   v6: 56
max sum_{e in E}{x_{e}}
end

import elytica
def main():
  elytica.init_model("match")
  elytica.run_model("match")
  for i in [12,13,14,25,45,56]:
    print("x"+str(i), "=", elytica.get_variable_value("match", "x"+str(i)))
  print("obj =", elytica.get_best_primal_bound("match"))
  return 0
```

## Hint

One constraint per vertex: sum of its incident edge-variables <= 1. Leaves 3 and 6 both need a hub, capping the matching at 2.

## What counts as correct

- `no-error` — Model solves
- `numeric-match` — Maximum matching has 2 edges — equal to the minimum vertex cover (König)
- `code-contains` — Reads the objective from the solver (no hardcoding)

## Solution

```hlpl
model match
set E = {12, 13, 14, 25, 45, 56}
bin x, forall e in E
constr x_{12} + x_{13} + x_{14} <= 1
constr x_{12} + x_{25} <= 1
constr x_{13} <= 1
constr x_{14} + x_{45} <= 1
constr x_{25} + x_{45} + x_{56} <= 1
constr x_{56} <= 1
max sum_{e in E}{x_{e}}
end

import elytica
def main():
  elytica.init_model("match")
  elytica.run_model("match")
  for i in [12,13,14,25,45,56]:
    print("x"+str(i), "=", elytica.get_variable_value("match", "x"+str(i)))
  print("obj =", elytica.get_best_primal_bound("match"))
  return 0
```

## Mastery variant

A plain path 1-2-3-4-5-6. How many disjoint edges fit on a six-vertex path?

```hlpl
model match_v
# path: 1-2-3-4-5-6
set E = {12, 23, 34, 45, 56}
bin x, forall e in E
# TODO: one <= 1 constraint per vertex
max sum_{e in E}{x_{e}}
end

import elytica
def main():
  elytica.init_model("match_v")
  elytica.run_model("match_v")
  for i in [12,23,34,45,56]:
    print("x"+str(i), "=", elytica.get_variable_value("match_v", "x"+str(i)))
  print("obj =", elytica.get_best_primal_bound("match_v"))
  return 0
```



---

# Facility location — open or not?

XIII — Facility location — Pay to open, save on transport.

Path: `lessons/facility-uncapacitated`

# Facility location — open or not?

Pay to open, save on transport.

*Chapter: XIII — Facility location · lesson id `facility-uncapacitated` · practice lesson*

---

Two candidate facilities, three customers. Opening facility f costs `f_f`. Serving customer c from facility f costs `c_{c,f}`. Each customer must be served by exactly one facility, and a facility can only serve a customer if it's open.

Two variable families: y_f binary (open / not), x_{c,f} binary (assignment). The coupling constraint `x_{c,f} ≤ y_f` is what makes this an integer programme rather than two independent problems.

Open costs {5, 6}, transport costs [[2, 4], [3, 1], [4, 2]]. Optimum: open only facility 2, total cost 6 + (4 + 1 + 2) = 13.

## Predict before running

Setup costs {5, 6}, transport per customer-facility. Without capacities, how many facilities open?

- Both. To keep transport cheap
- Just facility 2. Pays 6, then serves everyone
- Just facility 1. It's cheaper to open

## Starter code

```hlpl
model facility
set F = {1, 2}
set C = {1, 2, 3}
const f = {5, 6}, forall j in F
const t = {{2, 4}, {3, 1}, {4, 2}}, forall i in C, forall j in F
bin y, forall j in F
bin x, forall i in C, forall j in F
constr sum_{j in F}{x_{i,j}} = 1, forall i in C
constr x_{i,j} <= y_{j}, forall i in C, forall j in F
min sum_{j in F}{f_{j} * y_{j}} + sum_{i in C}{sum_{j in F}{t_{i,j} * x_{i,j}}}
end

import elytica
def main():
  elytica.init_model("facility")
  elytica.run_model("facility")
  for i in [1,2]:
    print("y"+str(i), "=", elytica.get_variable_value("facility", "y"+str(i)))
  for i in [1,2,3]:
    for j in [1,2]:
      name = "x"+str(i)+","+str(j)
      print(name, "=", elytica.get_variable_value("facility", name))
  print("obj =", elytica.get_best_primal_bound("facility"))
  return 0
```

## Hint

Open just facility 2 — pays 6, then serves all three customers for 4+1+2 = 7. Total 13.

## What counts as correct

- `no-error` — Model solves
- `numeric-match` — Facility 2 opens
- `numeric-match` — Facility 1 stays closed
- `numeric-match` — Total cost is 13
- `code-contains` — Reads the objective from the solver (no hardcoding)
- `code-contains` — Reads variable values from the solver (no hardcoding)

## Mastery variant

New setup and transport costs. Which facility is worth opening this time?

```hlpl
model facility_v
set F = {1, 2}
set C = {1, 2, 3}
const f = {6, 3}, forall j in F
const t = {{4, 2}, {5, 1}, {3, 2}}, forall i in C, forall j in F
bin y, forall j in F
bin x, forall i in C, forall j in F
constr sum_{j in F}{x_{i,j}} = 1, forall i in C
constr x_{i,j} <= y_{j}, forall i in C, forall j in F
min sum_{j in F}{f_{j} * y_{j}} + sum_{i in C}{sum_{j in F}{t_{i,j} * x_{i,j}}}
end

import elytica
def main():
  elytica.init_model("facility_v")
  elytica.run_model("facility_v")
  for i in [1,2]:
    print("y"+str(i), "=", elytica.get_variable_value("facility_v", "y"+str(i)))
  for i in [1,2,3]:
    for j in [1,2]:
      name = "x"+str(i)+","+str(j)
      print(name, "=", elytica.get_variable_value("facility_v", name))
  print("obj =", elytica.get_best_primal_bound("facility_v"))
  return 0
```



---

# Facility location — with capacities

XIII — Facility location — Each open facility has a limit.

Path: `lessons/facility-capacitated`

# Facility location — with capacities

Each open facility has a limit.

*Chapter: XIII — Facility location · lesson id `facility-capacitated` · practice lesson*

---

Real facilities have throughput limits. Add `capacity_j` to each: the number of customers a facility can serve when it's open.

With `capacity = {2, 1}` and three customers, neither facility alone can cover everyone — both must open (cost 11). The tight cap on facility 2 forces facility 1 to absorb the two customers it's not the cheapest match for. Best assignment: facility 1 takes C₁ and C₂, facility 2 takes C₃. Total 11 + 2 + 3 + 2 = 18.

## Predict before running

Capacity {2, 1} means F2 can take only one customer. Compared to uncapacitated (13), the new total is:

- Lower. Capacities help
- Higher. Both facilities forced open + suboptimal assignments
- Same. The assignment didn't change

## Starter code

```hlpl
model facility
set F = {1, 2}
set C = {1, 2, 3}
const f = {5, 6}, forall j in F
const t = {{2, 4}, {3, 1}, {4, 2}}, forall i in C, forall j in F
const capacity = {2, 1}, forall j in F
bin y, forall j in F
bin x, forall i in C, forall j in F
constr sum_{j in F}{x_{i,j}} = 1, forall i in C
constr x_{i,j} <= y_{j}, forall i in C, forall j in F
# TODO: a capacity constraint per facility
min sum_{j in F}{f_{j} * y_{j}} + sum_{i in C}{sum_{j in F}{t_{i,j} * x_{i,j}}}
end

import elytica
def main():
  elytica.init_model("facility")
  elytica.run_model("facility")
  for i in [1,2]:
    print("y"+str(i), "=", elytica.get_variable_value("facility", "y"+str(i)))
  for i in [1,2,3]:
    for j in [1,2]:
      name = "x"+str(i)+","+str(j)
      print(name, "=", elytica.get_variable_value("facility", name))
  print("obj =", elytica.get_best_primal_bound("facility"))
  return 0
```

## Hint

Add: constr sum_{i in C}{x_{i,j}} <= capacity_{j}, forall j in F

## What counts as correct

- `no-error` — Model solves
- `numeric-match` — Facility 1 must open
- `numeric-match` — Facility 2 must open
- `numeric-match` — Total cost is 18
- `code-contains` — Reads the objective from the solver (no hardcoding)
- `code-contains` — Reads variable values from the solver (no hardcoding)

## Solution

```hlpl
model facility
set F = {1, 2}
set C = {1, 2, 3}
const f = {5, 6}, forall j in F
const t = {{2, 4}, {3, 1}, {4, 2}}, forall i in C, forall j in F
const capacity = {2, 1}, forall j in F
bin y, forall j in F
bin x, forall i in C, forall j in F
constr sum_{j in F}{x_{i,j}} = 1, forall i in C
constr x_{i,j} <= y_{j}, forall i in C, forall j in F
constr sum_{i in C}{x_{i,j}} <= capacity_{j}, forall j in F
min sum_{j in F}{f_{j} * y_{j}} + sum_{i in C}{sum_{j in F}{t_{i,j} * x_{i,j}}}
end

import elytica
def main():
  elytica.init_model("facility")
  elytica.run_model("facility")
  for i in [1,2]:
    print("y"+str(i), "=", elytica.get_variable_value("facility", "y"+str(i)))
  for i in [1,2,3]:
    for j in [1,2]:
      name = "x"+str(i)+","+str(j)
      print(name, "=", elytica.get_variable_value("facility", name))
  print("obj =", elytica.get_best_primal_bound("facility"))
  return 0
```

## Mastery variant

Fresh costs and capacities. F₂ is the cheapest setup but the tightest cap.

```hlpl
model facility_v
set F = {1, 2}
set C = {1, 2, 3}
const f = {5, 4}, forall j in F
const t = {{4, 3}, {2, 6}, {7, 2}}, forall i in C, forall j in F
const capacity = {2, 1}, forall j in F
bin y, forall j in F
bin x, forall i in C, forall j in F
constr sum_{j in F}{x_{i,j}} = 1, forall i in C
constr x_{i,j} <= y_{j}, forall i in C, forall j in F
constr sum_{i in C}{x_{i,j}} <= capacity_{j}, forall j in F
min sum_{j in F}{f_{j} * y_{j}} + sum_{i in C}{sum_{j in F}{t_{i,j} * x_{i,j}}}
end

import elytica
def main():
  elytica.init_model("facility_v")
  elytica.run_model("facility_v")
  for i in [1,2]:
    print("y"+str(i), "=", elytica.get_variable_value("facility_v", "y"+str(i)))
  for i in [1,2,3]:
    for j in [1,2]:
      name = "x"+str(i)+","+str(j)
      print(name, "=", elytica.get_variable_value("facility_v", name))
  print("obj =", elytica.get_best_primal_bound("facility_v"))
  return 0
```



---

# TSP — variables, no constraints

XIV — Travelling salesman — Just the decisions.

Path: `lessons/tsp-vars`

# TSP — variables, no constraints

Just the decisions.

*Chapter: XIV — Travelling salesman · lesson id `tsp-vars` · practice lesson*

---

A salesman must visit four cities and return home, minimising total distance.

Variable x_{i,j} = 1 if the tour goes directly from i to j. The objective is the sum of travelled distances. One subtle thing: we forbid self-loops (x_{i,i} = 0) — no city goes to itself.

Run it. With only the no-self-loops constraint, the solver picks no edges — cost 0. The next lesson adds the degree constraints that force a tour.

## Predict before running

TSP variables defined, no-self-loops, min cost. But no degree constraints yet. What's the optimum?

- The true tour cost
- 0. No edges picked
- Sum of all edge costs

## Starter code

```hlpl
model tsp
set C = {1, 2, 3, 4}
const d = {{0, 4, 5, 7}, {4, 0, 3, 6}, {5, 3, 0, 2}, {7, 6, 2, 0}}, forall i in C, forall j in C
bin x, forall i in C, forall j in C
constr x_{i,i} = 0, forall i in C
min sum_{i in C}{sum_{j in C}{d_{i,j} * x_{i,j}}}
end

import elytica
def main():
  elytica.init_model("tsp")
  elytica.run_model("tsp")
  print("obj =", elytica.get_best_primal_bound("tsp"))
  return 0
```

## Hint

No structural constraints yet → solver picks zero edges → cost 0.

## What counts as correct

- `no-error` — Model solves
- `numeric-match` — Without degree constraints, cost is 0
- `code-contains` — Reads the objective from the solver (no hardcoding)

## Mastery variant

Different distance matrix, same naked-skeleton model. Still 0.

```hlpl
model tsp_v
set C = {1, 2, 3, 4}
const d = {{0, 3, 8, 6}, {3, 0, 5, 9}, {8, 5, 0, 2}, {6, 9, 2, 0}}, forall i in C, forall j in C
bin x, forall i in C, forall j in C
constr x_{i,i} = 0, forall i in C
min sum_{i in C}{sum_{j in C}{d_{i,j} * x_{i,j}}}
end

import elytica
def main():
  elytica.init_model("tsp_v")
  elytica.run_model("tsp_v")
  print("obj =", elytica.get_best_primal_bound("tsp_v"))
  return 0
```



---

# TSP — degree constraints (assignment trap)

XIV — Travelling salesman — Force exactly one in and one out per city.

Path: `lessons/tsp-degree`

# TSP — degree constraints (assignment trap)

Force exactly one in and one out per city.

*Chapter: XIV — Travelling salesman · lesson id `tsp-degree` · practice lesson*

---

Force each city to have exactly one outgoing and one incoming edge — the *assignment relaxation* of TSP. Looks right? Not quite.

Run it. The solver returns cost 12 — *cheaper* than the true TSP optimum of 16! It found two 2-cycles: 1↔2 (cost 4 + 4 = 8) and 3↔4 (cost 2 + 2 = 4). Two disconnected sub-tours instead of a single Hamiltonian cycle.

This is the classic assignment-relaxation trap. We need extra constraints to forbid subtours — that's the next lesson.

## Predict before running

Add degree constraints (one in, one out per city). How does the cost compare to the true TSP optimum?

- Equal. Degree constraints are enough for TSP
- Lower. Relaxations under-estimate the true optimum
- Higher. Degree constraints make things harder

## Starter code

```hlpl
model tsp
set C = {1, 2, 3, 4}
const d = {{0, 4, 5, 7}, {4, 0, 3, 6}, {5, 3, 0, 2}, {7, 6, 2, 0}}, forall i in C, forall j in C
bin x, forall i in C, forall j in C
constr x_{i,i} = 0, forall i in C
constr sum_{j in C}{x_{i,j}} = 1, forall i in C
constr sum_{i in C}{x_{i,j}} = 1, forall j in C
min sum_{i in C}{sum_{j in C}{d_{i,j} * x_{i,j}}}
end

import elytica
def main():
  elytica.init_model("tsp")
  elytica.run_model("tsp")
  for i in [1,2,3,4]:
    for j in [1,2,3,4]:
      name = "x"+str(i)+","+str(j)
      print(name, "=", elytica.get_variable_value("tsp", name))
  print("obj =", elytica.get_best_primal_bound("tsp"))
  return 0
```

## Hint

Run it. Note the impossibly-low cost — the solver cheated by picking subtours.

## What counts as correct

- `no-error` — Model solves
- `numeric-match` — Assignment-relaxation cost is 12 — two subtours, not a tour
- `code-contains` — Reads the objective from the solver (no hardcoding)

## Mastery variant

New distance matrix. Spot the subtour trap on a fresh instance.

```hlpl
model tsp_v
set C = {1, 2, 3, 4}
const d = {{0, 3, 8, 6}, {3, 0, 5, 9}, {8, 5, 0, 2}, {6, 9, 2, 0}}, forall i in C, forall j in C
bin x, forall i in C, forall j in C
constr x_{i,i} = 0, forall i in C
constr sum_{j in C}{x_{i,j}} = 1, forall i in C
constr sum_{i in C}{x_{i,j}} = 1, forall j in C
min sum_{i in C}{sum_{j in C}{d_{i,j} * x_{i,j}}}
end

import elytica
def main():
  elytica.init_model("tsp_v")
  elytica.run_model("tsp_v")
  for i in [1,2,3,4]:
    for j in [1,2,3,4]:
      name = "x"+str(i)+","+str(j)
      print(name, "=", elytica.get_variable_value("tsp_v", name))
  print("obj =", elytica.get_best_primal_bound("tsp_v"))
  return 0
```



---

# TSP — MTZ subtour elimination

XIV — Travelling salesman — Forbid the cheating subtours.

Path: `lessons/tsp-mtz`

# TSP — MTZ subtour elimination

Forbid the cheating subtours.

*Chapter: XIV — Travelling salesman · lesson id `tsp-mtz` · practice lesson*

---

The Miller-Tucker-Zemlin (MTZ) formulation adds order variables u_i (one per city except the start) and a constraint that effectively says "if you go from i to j, then i comes before j in the tour order". This rules out any cycle that doesn't include the start node — kills the sub-tours.

  u_i − u_j + n · x_{i,j} ≤ n − 1   for all i, j ∈ {2, …, n}

For our 4-city instance (n = 4), u_i lives in [1, 3]. The constraint is tight when x_{i,j} = 1 (forcing u_j ≥ u_i + 1) and slack otherwise. Run it — the true TSP optimum is 16, achieved by the tour 1 → 2 → 3 → 4 → 1.

## Predict before running

Distance matrix is symmetric. What's the true TSP optimum for cities 1, 2, 3, 4?

- 12 (the assignment-relaxation answer)
- 16 (tour 1 → 2 → 3 → 4 → 1)
- 22 (the worst-case tour)

## Starter code

```hlpl
model tsp
set C  = {1, 2, 3, 4}
set CB = {2, 3, 4}
const d = {{0, 4, 5, 7}, {4, 0, 3, 6}, {5, 3, 0, 2}, {7, 6, 2, 0}}, forall i in C, forall j in C
bin x, forall i in C, forall j in C
var 1 <= u <= 3, forall i in CB
constr x_{i,i} = 0, forall i in C
constr sum_{j in C}{x_{i,j}} = 1, forall i in C
constr sum_{i in C}{x_{i,j}} = 1, forall j in C
constr u_{i} - u_{j} + 4*x_{i,j} <= 3, forall i in CB, forall j in CB
min sum_{i in C}{sum_{j in C}{d_{i,j} * x_{i,j}}}
end

import elytica
def main():
  elytica.init_model("tsp")
  elytica.run_model("tsp")
  for i in [1,2,3,4]:
    for j in [1,2,3,4]:
      name = "x"+str(i)+","+str(j)
      print(name, "=", elytica.get_variable_value("tsp", name))
  print("obj =", elytica.get_best_primal_bound("tsp"))
  return 0
```

## Hint

MTZ adds u variables and one constraint per ordered pair (i,j) of non-start cities.

## What counts as correct

- `no-error` — Model solves
- `numeric-match` — True TSP optimum is 16 (tour 1 → 2 → 3 → 4 → 1)
- `code-contains` — Reads the objective from the solver (no hardcoding)

## Mastery variant

Same fresh distances as the degree variant. MTZ now finds the real tour.

```hlpl
model tsp_v
set C  = {1, 2, 3, 4}
set CB = {2, 3, 4}
const d = {{0, 3, 8, 6}, {3, 0, 5, 9}, {8, 5, 0, 2}, {6, 9, 2, 0}}, forall i in C, forall j in C
bin x, forall i in C, forall j in C
var 1 <= u <= 3, forall i in CB
constr x_{i,i} = 0, forall i in C
constr sum_{j in C}{x_{i,j}} = 1, forall i in C
constr sum_{i in C}{x_{i,j}} = 1, forall j in C
constr u_{i} - u_{j} + 4*x_{i,j} <= 3, forall i in CB, forall j in CB
min sum_{i in C}{sum_{j in C}{d_{i,j} * x_{i,j}}}
end

import elytica
def main():
  elytica.init_model("tsp_v")
  elytica.run_model("tsp_v")
  for i in [1,2,3,4]:
    for j in [1,2,3,4]:
      name = "x"+str(i)+","+str(j)
      print(name, "=", elytica.get_variable_value("tsp_v", name))
  print("obj =", elytica.get_best_primal_bound("tsp_v"))
  return 0
```



---

# Capstone — a project portfolio

XV — Capstone — Two constraints, one binary objective.

Path: `lessons/capstone-portfolio`

# Capstone — a project portfolio

Two constraints, one binary objective.

*Chapter: XV — Capstone · lesson id `capstone-portfolio` · practice lesson*

---

You have five candidate projects. Each has a value v_p, a cost c_p, and a team-size demand t_p. You have a budget of 15 and a team capacity of 7. Pick projects to maximise total value.

  project 1: v=10, c=5, t=2
  project 2: v= 7, c=3, t=1
  project 3: v= 8, c=4, t=1
  project 4: v= 5, c=2, t=1
  project 5: v=12, c=6, t=3

Write the model yourself. The check below confirms your optimum equals 32.

## Predict before running

Five projects, budget and team constraint. About how many will the solver pick?

- All five. Every project has positive value
- Around four. Drop the worst-fit project
- Just one or two. Budget is tight

## Starter code

```hlpl
model portfolio
set P = {1, 2, 3, 4, 5}
const v = {10, 7, 8, 5, 12}, forall p in P
const c = {5, 3, 4, 2, 6}, forall p in P
const t = {2, 1, 1, 1, 3}, forall p in P
# TODO: declare bin x indexed over P, the budget constraint (sum c*x <= 15),
#       the team constraint (sum t*x <= 7), and the max sum v*x objective.
end

import elytica
def main():
  elytica.init_model("portfolio")
  elytica.run_model("portfolio")
  for i in [1,2,3,4,5]:
    print("x"+str(i), "=", elytica.get_variable_value("portfolio", "x"+str(i)))
  print("obj =", elytica.get_best_primal_bound("portfolio"))
  return 0
```

## Hint

Five binary x_p variables. Two ≤ constraints (budget and team). One max sum objective.

## What counts as correct

- `no-error` — Model solves
- `numeric-match` — Optimal portfolio value is 32 (projects 2, 3, 4, 5)
- `code-contains` — Reads the objective from the solver (no hardcoding)

## Solution

```hlpl
model portfolio
set P = {1, 2, 3, 4, 5}
const v = {10, 7, 8, 5, 12}, forall p in P
const c = {5, 3, 4, 2, 6}, forall p in P
const t = {2, 1, 1, 1, 3}, forall p in P
bin x, forall p in P
constr sum_{p in P}{c_{p} * x_{p}} <= 15
constr sum_{p in P}{t_{p} * x_{p}} <= 7
max sum_{p in P}{v_{p} * x_{p}}
end

import elytica
def main():
  elytica.init_model("portfolio")
  elytica.run_model("portfolio")
  for i in [1,2,3,4,5]:
    print("x"+str(i), "=", elytica.get_variable_value("portfolio", "x"+str(i)))
  print("obj =", elytica.get_best_primal_bound("portfolio"))
  return 0
```

## Mastery variant

Five new projects with different values, costs, and teams. Pick the best portfolio.

```hlpl
model portfolio_v
set P = {1, 2, 3, 4, 5}
const v = {8, 6, 9, 4, 11}, forall p in P
const c = {4, 3, 5, 2, 5}, forall p in P
const t = {2, 2, 2, 1, 3}, forall p in P
# TODO: bin x indexed over P, budget (sum c*x <= 13), team (sum t*x <= 8),
#       and max sum v*x.
end

import elytica
def main():
  elytica.init_model("portfolio_v")
  elytica.run_model("portfolio_v")
  for i in [1,2,3,4,5]:
    print("x"+str(i), "=", elytica.get_variable_value("portfolio_v", "x"+str(i)))
  print("obj =", elytica.get_best_primal_bound("portfolio_v"))
  return 0
```