nimopt 0.1.0__tar.gz

nimopt-0.1.0/.claude/skills/nimopt/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: nimopt
+description: Use when writing, reading or debugging a model built with nimopt or nimblend -- declaring sets, parameters, variables, expressions and constraints, or reading a solution.
+---
+# For agents
+
+The whole manual is at [`/llms-full.txt`](/llms-full.txt); the index is at
+[`/llms.txt`](/llms.txt).
+
+## The mental model
+
+**A variable is a dimension.** `m.var("x", (P, W))` occupies a block of the
+model's single column space. A member's column is computed from its
+multi-index rather than stored, so a variable over millions of columns
+costs its members and not its columns.
+
+**An expression is symbolic.** `cost[P, W] * x[P, W]` holds references,
+not arrays. Writing it costs nothing. It becomes matrix entries only when a
+constraint is materialised.
+
+**A constraint is an array.** It is a `nimblend` array over its free sets
+crossed with the column space, so there is no assembly step: the array is
+the matrix.
+
+**A definition is a model without its data.** `Definition` mirrors the
+vocabulary a model is written in, `set`, `param`, `var`, `eq` and
+`set_objective`, over symbols declared with no members and no values.
+`explain()` reports what it declares; `build(data)` binds a copy and returns
+a `Model`, so one definition builds as many models as it is given datasets.
+
+**A built model answers questions about itself.** `explain()` reports what
+it built, `row(name, **coords)` reads one row back out of the assembled
+matrix, and `absent(name)` reports which coordinates were dropped from a
+constraint and by which rule. All three read what was built rather than
+walking the expression a second time.
+
+**A session keeps the solver open.** `model.session()` assembles once and
+keeps the solver's model, so `diagnose()` asks the solved instance which
+rows conflict, or which direction an unbounded model runs off in.
+`available()` lists the adapters installed and `capabilities(name)` reports
+what each does, including what it refuses: a model with integer columns has
+no duals, because a mixed-integer model's duals are not its relaxation's.
+
+**`nimblend` is the layer below.** It knows dimensions, labels, entries and
+alignment, and nothing about optimization. Import from `nimblend` itself,
+never from `nimblend.sparse` or another submodule, and never read an array's
+`.index` or `.data` or a domain's `.codes`. Each has a reader above it:
+`coordinates()`, `values()`, `positions_of_coordinates()` and `as_coord()`.
+Nor build one: a domain returns the array over its own members through
+`array(values)` and `identity(into, coord, start)`.
+
+## The public surface
+
+<!-- surface -->
+| From | Names |
+| --- | --- |
+| `nimopt` | `COLUMN`, `ROW`, `Absence`, `Alias`, `Assembled`, `Coefficient`, `Constraint`, `Definition`, `Diagnosis`, `Explanation`, `Expression`, `Model`, `Option`, `Param`, `Relation`, `Row`, `Session`, `Set`, `Solution`, `Sum`, `Term`, `Variable`, `available`, `capabilities`, `load`, `loads`, `options`, `product`, `save`, `subset`, `subset_of` |
+| `nimblend` | `Array`, `DenseArray`, `Domain`, `EntryBuffer`, `SparseArray`, `combined_dims`, `from_long`, `from_dense`, `is_canonical`, `StoredCoord`, `ProductCoord`, `SubsetCoord` |
+<!-- /surface -->
+
+**A coefficient composes.** A coefficient is a parameter read at its sets
+or an arithmetic combination of such readings: `price[G, T] / eta[G, T]` is
+a coefficient written before any data exists, read at its sets like a
+parameter, and evaluated once when the matrix is built. `+`, `-`, `*`, `/`
+and a power by a number combine coefficients. An expression also carries a
+constant, so `x + 1 <= 5` produces the row `x <= 4`.
+
+## What goes wrong
+
+**A chained comparison.** `0 <= expr <= 10` raises `TypeError`. Python
+evaluates it as two comparisons joined by `and`, which keeps only the
+second, so a relation has no truth value rather than letting the first
+bound be dropped. Write each bound as its own constraint.
+
+**A sum over a lag.** `Sum(T - 1, ...)` raises: a sum runs over a set's
+members. Put the lag on the variable reference, `x[T - 1]`.
+
+**The built-in `sum` over a set's members.** `sum(x[S, t] for t in members)`
+gives the correct answer at a cost: it produces one term per member, where
+`Sum(T, x[S, T])` produces one term and reduces a dimension. The terms
+concatenate pairwise and each materialises its own block, so building a
+model that way runs 24 times slower at 25 members and 275 times at 400, and
+the gap widens. Use the built-in `sum` for a short list of distinct
+expressions and `Sum` for a set's members.
+
+**A right-hand side over the wrong dimensions.** A constraint's right-hand
+side is a parameter over exactly its free dimensions. The error message
+gives both.
+
+**Reading values from a model that did not solve.** `objective`, `primal`
+and `dual` raise unless `status` is `"optimal"`. Read `status` first.
+
+**A domain over a definition's sets.** `product((B, T))` needs each set's
+coordinate, and a declared set has none. In a definition, give `where=`,
+`over=` and `subset=` as a tuple of its sets or as one of its parameters,
+whose coefficients are the coordinates.
+
+**A row that is not there.** `row()` raises for a coordinate at which the
+constraint has no row. `absent()` reports which rule dropped it: a
+coefficient absent inside a sum removes a **term** and leaves the row
+standing; a term absent along a **free** dimension removes the **row**.
+
+**Reading a MILP's duals.** A model with integer columns has none, and
+`dual()` raises rather than returning the relaxation's. Read `primal`.
+
+**A conflict HiGHS cannot prove.** HiGHS computes its conflict over the
+linear relaxation, so a model infeasible only through its integrality
+produces none and `diagnose()` raises. Gurobi's covers the integrality.
+
+**Two operands that share no dimension.** Every binary operator combines two
+dimensioned operands only where they share a dimension, and the rule
+applies to a coefficient meeting a variable exactly as it applies to two
+coefficients. Frames sharing nothing raise: their combination would be an
+outer product no model asks for. A number has no dimension and scales.
+
+**A division by zero.** A divisor that is zero raises `ZeroDivisionError`
+with the coordinate, for a Python number, a NumPy scalar and a coefficient
+with a zero at one coordinate alike. Handle the divisor before it reaches an
+expression.
+
+**A derived coefficient read at the wrong sets.** A combination is read at
+its sets as a parameter is, and the reading is checked against the
+dimensions it has: `unit_cost[T, G]` raises where it is written, naming
+`('G', 'T')`.
+
+**Reaching into `nimblend`.** A test fails on an import from a `nimblend`
+submodule, on any read of an array's `.index` or `.data` or a domain's
+`.codes`, and on a module of the package assembling an index matrix of its
+own.
+
+## Every refusal, and where it is shown
+
+The prose above covers the mistakes worth explaining. This is every
+refusal the documentation demonstrates, each executed to produce the
+message beside it.
+
+<!-- refusals -->
+| Raises | Message | Shown at |
+| --- | --- | --- |
+| `ValueError` | the upper bound 'cap' carries no value for member ('b',) of variable 'x'; a bound covers every column of the variable it bounds | [/guides/bounds-from-parameters](/guides/bounds-from-parameters) |
+| `ValueError` | variable 'x' is declared over ('G',) and does not carry ['W']; its upper bound 'cap' is declared over ('W',) | [/guides/bounds-from-parameters](/guides/bounds-from-parameters) |
+| `TypeError` | a coefficient is a parameter; build one with `Param.from_dense` or `Param.from_long` and read it at its sets. A product of two expressions is not linear. | [/guides/coefficient-arithmetic](/guides/coefficient-arithmetic) |
+| `ValueError` | coefficient (fuel_price / efficiency) is over ('G', 'T'); got ('T', 'G') | [/guides/coefficient-arithmetic](/guides/coefficient-arithmetic) |
+| `ZeroDivisionError` | divisor holed carries a zero at 1 coordinate(s), the first at {'G': 'base', 'T': 1}; a quotient there states a coefficient no solver can read | [/guides/coefficient-arithmetic](/guides/coefficient-arithmetic) |
+| `ValueError` | frames ('G',) and ('T',) share no dimension; there is nothing to align them on | [/guides/coefficient-arithmetic](/guides/coefficient-arithmetic) |
+| `ValueError` | constraint 'capacity' has free dimensions ('P',); its condition is over ('W',) | [/guides/conditions](/guides/conditions) |
+| `ValueError` | constraint 'capacity' states its rows with over= and narrows them with where=; state one | [/guides/conditions](/guides/conditions) |
+| `ValueError` | variable 'x' is read at member 't9' of dimension 'T', which that set does not carry | [/guides/fixed-members](/guides/fixed-members) |
+| `ValueError` | a lag is a whole number of members; got 1.7 | [/guides/lags](/guides/lags) |
+| `ValueError` | a sum is over the members of ['T'], so it takes the set and not a lag of it; state the lag at the variable's reference | [/guides/lags](/guides/lags) [/reference/expression](/reference/expression) |
+| `ValueError` | parameter 'rate' is read at a lag ['T']; state the lag at the variable's reference, where a coefficient multiplies the row it lands on | [/guides/lags](/guides/lags) |
+| `ValueError` | 'max(gen[G, T]) <= 10': Sum is the one call the spelling carries | [/guides/saving-and-loading](/guides/saving-and-loading) |
+| `ValueError` | capital does not fall from base to what follows it | [/models/expansion](/models/expansion) |
+| `ValueError` | frames ('P',) and ('Q',) share no dimension; there is nothing to align them on | [/nimblend/arrays](/nimblend/arrays) |
+| `ValueError` | label column 't' has length 2 and the value column has length 1; they name the same entries | [/nimblend/arrays](/nimblend/arrays) |
+| `ValueError` | this array declares absence 'unknown' and does not carry every coordinate of its frame, so densifying must state fill=<value> to place at the rest | [/nimblend/arrays](/nimblend/arrays) [/tutorial/reading-the-answer](/tutorial/reading-the-answer) |
+| `ValueError` | 3 member(s) numbered from 4 reach position 6, and dimension 'k' spans 6 | [/nimblend/domains](/nimblend/domains) |
+| `ValueError` | a domain of 3 member(s) takes one value each, as a column of that length; got shape (2,) | [/nimblend/domains](/nimblend/domains) |
+| `ValueError` | constraint 'supply' has free dimensions ('P',); its right-hand side 'demand' is over ('W',) | [/reference/constraint](/reference/constraint) [/tutorial/constraints](/tutorial/constraints) |
+| `ValueError` | data does not cover ['S'] | [/reference/definition](/reference/definition) |
+| `ValueError` | parameter 'S' is already declared as a set; a name means one symbol, in an expression and in the data | [/reference/definition](/reference/definition) |
+| `TypeError` | a relation has no truth value; a chained comparison such as 0 <= expr <= 10 reads as two comparisons joined by `and` and keeps only the second, so state each bound separately | [/reference/expression](/reference/expression) [/tutorial/constraints](/tutorial/constraints) |
+| `TypeError` | a relation is already an equation and states one bound; compare the expression a second time in its own equation rather than comparing the relation | [/reference/expression](/reference/expression) |
+| `TypeError` | an LP has no row for a strict inequality; state `<=` or `>=`. `min` and `max` compare two expressions this way and are not linear either, so reduce with `Sum` over the sets instead | [/reference/expression](/reference/expression) |
+| `TypeError` | an expression is reduced over the sets it is summed across; state them with `Sum(I, J, expression)` | [/reference/expression](/reference/expression) |
+| `TypeError` | nimopt expresses a linear term, so a variable in a denominator is not one; state the reciprocal as a coefficient the variable multiplies | [/reference/expression](/reference/expression) |
+| `TypeError` | nimopt expresses a linear term, so a variable raised to a power is not one; a coefficient takes the power instead, and a variable multiplies it | [/reference/expression](/reference/expression) |
+| `TypeError` | nimopt expresses a linear term, so the absolute value of one is not linear; reduce with `Sum` over its sets, or state the magnitude with two rows bounding the expression | [/reference/expression](/reference/expression) |
+| `ValueError` | term 'x' already sums over ['T']; a dimension is reduced once, and a second reduction has nothing left to reduce | [/reference/expression](/reference/expression) |
+| `ValueError` | constraint 'cap' states where= with a domain that has no name; declare its members as a parameter and name that | [/reference/files](/reference/files) |
+| `ValueError` | parameter 'c' is given columns ['value', 'S']; a table states the dimensions then value: ['S', 'value'] | [/reference/files](/reference/files) |
+| `ValueError` | variable 'x' carries ['bound'], which the format does not; it takes ('sets', 'subset', 'lower', 'upper', 'integer') | [/reference/files](/reference/files) |
+| `ValueError` | constraint 'cap' states no row at {'P': 'p3'}; `absent('cap')` names the rule that dropped it | [/reference/inspection](/reference/inspection) |
+| `ValueError` | parameter 'cost': label column 'P' has length 1 and the value column has length 2; they name the same entries | [/reference/param](/reference/param) |
+| `TypeError` | parameter 'price' carries ('G',) and states no coefficient until it is read; read it at its sets as price[G] | [/reference/param](/reference/param) |
+| `ValueError` | the model's status is 'infeasible', so it carries no objective; read `status` before reading values | [/reference/solution](/reference/solution) [/tutorial/solving](/tutorial/solving) |
+| `ValueError` | this model carries integer columns and 'highs' refuses duals for a model with integrality, so there is no dual for constraint 'cap' to read: a mixed-integer model's duals are not its relaxation's | [/reference/solvers](/reference/solvers) |
+| `TypeError` | parameter 'supply' carries ('P',) and states no coefficient until it is read; read it at its sets as supply[P] | [/tutorial/constraints](/tutorial/constraints) |
+| `ValueError` | parameter 'cost' is over sets of shape (2, 3); got values of shape (2, 2) | [/tutorial/sets-and-parameters](/tutorial/sets-and-parameters) |
+<!-- /refusals -->

nimopt-0.1.0/.github/workflows/pages.yml

@@ -0,0 +1,60 @@
+name: pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: the wheels the playground imports
+        run: |
+          uvx --from pip pip download nimblend==0.1.0 --no-deps --only-binary=:all: --python-version 3.13 --dest website/static/wheels
+          uv build --wheel -o website/static/wheels
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+          cache-dependency-path: website/pnpm-lock.yaml
+
+      - name: the site
+        working-directory: website
+        run: |
+          pnpm install --frozen-lockfile
+          pnpm run build
+
+      - uses: actions/configure-pages@v5
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: website/build
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

nimopt-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+benchmarks/data/large/
+website/node_modules/
+website/build/
+website/.docusaurus/
+.coverage
+coverage.json
+htmlcov/
+.ruff_cache/
+website/scripts/cache/

nimopt-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,30 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.3
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: ty
+        name: ty
+        entry: .venv/bin/ty check
+        language: system
+        pass_filenames: false
+        always_run: true
+
+      - id: vulture
+        name: vulture
+        entry: .venv/bin/vulture
+        language: system
+        pass_filenames: false
+        always_run: true
+
+      - id: pytest
+        name: pytest
+        entry: .venv/bin/pytest tests/ -q --tb=short
+        language: system
+        pass_filenames: false
+        always_run: true

nimopt-0.1.0/CITATION.cff

@@ -0,0 +1,11 @@
+cff-version: 1.2.0
+title: nimopt
+message: If you use this software, please cite it as below.
+type: software
+authors:
+  - family-names: Gaete-Morales
+    given-names: Carlos
+    email: cdgaete@gmail.com
+abstract: An LP/MILP builder whose constraint blocks are labeled sparse arrays
+version: 0.1.0
+license: MIT

nimopt-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Carlos Gaete-Morales
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nimopt-0.1.0/PKG-INFO

@@ -0,0 +1,280 @@
+Metadata-Version: 2.5
+Name: nimopt
+Version: 0.1.0
+Summary: An LP/MILP builder whose constraint blocks are labeled sparse arrays
+Project-URL: Homepage, https://github.com/cdgaete/nimopt
+Project-URL: Documentation, https://cdgaete.github.io/nimopt/
+Project-URL: Repository, https://github.com/cdgaete/nimopt
+Project-URL: Issues, https://github.com/cdgaete/nimopt/issues
+Author-email: Carlos Gaete-Morales <cdgaete@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: linear programming,mathematical programming,milp,optimization,solver,sparse
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Typing :: Typed
+Requires-Python: <3.15,>=3.13
+Requires-Dist: nimblend>=0.1.0
+Requires-Dist: numpy>=2.5.2
+Requires-Dist: pyyaml>=6
+Provides-Extra: bench
+Requires-Dist: highspy>=1.15; extra == 'bench'
+Requires-Dist: linopy>=0.5; extra == 'bench'
+Requires-Dist: pypsa>=1.2; extra == 'bench'
+Provides-Extra: dev
+Requires-Dist: coverage>=7.16; extra == 'dev'
+Requires-Dist: gurobipy>=12; extra == 'dev'
+Requires-Dist: highspy>=1.15; extra == 'dev'
+Requires-Dist: hypothesis>=6; extra == 'dev'
+Requires-Dist: mosek>=11; extra == 'dev'
+Requires-Dist: pre-commit>=4.6.2; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.16; extra == 'dev'
+Requires-Dist: scipy>=1.11; extra == 'dev'
+Requires-Dist: ty>=0.0.78; extra == 'dev'
+Requires-Dist: vulture>=2.14; extra == 'dev'
+Provides-Extra: gurobi
+Requires-Dist: gurobipy>=12; extra == 'gurobi'
+Requires-Dist: scipy>=1.11; extra == 'gurobi'
+Provides-Extra: highs
+Requires-Dist: highspy>=1.15; extra == 'highs'
+Provides-Extra: mosek
+Requires-Dist: mosek>=11; extra == 'mosek'
+Description-Content-Type: text/markdown
+
+# nimopt
+
+`nimopt` is a Python library for building linear and mixed-integer programs. A model is declared symbolically over named index sets — as parameters, variables and constraints — and is expanded into a coefficient matrix only when it is assembled or solved. Solutions are returned as arrays over those same index sets, so a primal value is read by label rather than by column position.
+
+`nimopt` is built on `nimblend`, a labelled sparse N-dimensional array library with no knowledge of optimisation. The dependency runs in one direction, and `nimblend` is documented in [its own section](website/docs/nimblend/index.md).
+
+## Design
+
+**A variable is a dimension.** A constraint is an array indexed over its free sets crossed with the model's column space, with the coefficients as values. There is no assembly step converting the model into a matrix, because the array is the matrix.
+
+**Absence is distinct from zero.** An entry is either stored or absent, and every array declares what absence means: `"empty"` for a coordinate that contributes nothing, `"unknown"` for one that was never modelled. A missing result is never counted as zero, and division by an absent value raises rather than producing an infinity.
+
+**A subset stays a subset.** A variable declared over a subset of a set product has one column per member of the subset and none for the rest. The full product is never materialised, at declaration or at any point after it.
+
+**Expressions are symbolic.** An expression holds references to variables and parameters rather than their values. `cost[P, W] * x[P, W]` costs the same to write over a million routes as over six; the values are read when the matrix is built.
+
+**Dropped rows are reported.** A row whose terms have no value at some coordinate is dropped rather than written incompletely. `absent()` lists every dropped row with the rule that dropped it, and `row()` returns one row of the assembled matrix as the solver receives it.
+
+## Install
+
+Neither package is published yet, so both are installed from a checkout. `nimblend` is a dependency and is installed first, from wherever it is cloned; `nimopt` then installs from its own root:
+
+```bash
+pip install /path/to/nimblend
+pip install ".[highs]"
+```
+
+HiGHS is the default solver, and `[highs]` installs it. `[gurobi]` and `[mosek]` add those adapters instead, `[bench]` adds the comparison suite and `[dev]` the test and lint tooling. `available()` reports the solvers whose backend can be imported in the current environment, and `capabilities(name)` answers for an adapter whether or not its backend is installed.
+
+## A first model
+
+A transport problem: two plants with limited supply ship to three warehouses with fixed demand, and the objective is total shipping cost.
+
+```python
+import numpy as np
+from nimopt import Model, Param, Set, Sum
+
+P = Set("P", np.array(["lisbon", "porto"]))
+W = Set("W", np.array(["berlin", "paris", "rome"]))
+
+cost = Param.from_dense("cost", (P, W), np.array([[2.0, 4.0, 5.0], [3.0, 1.0, 6.0]]))
+supply = Param.from_dense("supply", (P,), np.array([30.0, 25.0]))
+demand = Param.from_dense("demand", (W,), np.array([20.0, 15.0, 15.0]))
+
+m = Model("transport")
+x = m.var("x", (P, W))
+
+m.eq("supply", Sum(W, x[P, W]) <= supply[P])
+m.eq("demand", Sum(P, x[P, W]) >= demand[W])
+m.set_objective(Sum(P, W, cost[P, W] * x[P, W]))
+
+solution = m.solve()
+print(solution.status, solution.objective)
+print(solution.primal("x").to_dense())
+```
+
+<!-- output -->
+<details open>
+<summary>Output</summary>
+
+```text
+optimal 135.0
+[[20.  0. 10.]
+ [ 0. 15.  5.]]
+```
+
+</details>
+<!-- /output -->
+
+The primal values are returned as a 2 by 3 array over plants and warehouses, in the order the sets declare their members.
+
+## Declaring before the data exists
+
+A `Definition` states the same model without binding any data. Its sets and parameters are declared by name, its constraints are written in the same expression syntax, and `explain()` reports the whole declaration before a single value has been read.
+
+```python
+import numpy as np
+from nimopt import Definition, Sum
+
+d = Definition("transport")
+P, W = d.set("P"), d.set("W")
+cost = d.param("cost", (P, W))
+supply = d.param("supply", (P,))
+demand = d.param("demand", (W,))
+x = d.var("x", (P, W))
+
+d.eq("supply", Sum(W, x[P, W]) <= supply[P])
+d.eq("demand", Sum(P, x[P, W]) >= demand[W])
+d.set_objective(Sum(P, W, cost[P, W] * x[P, W]))
+
+print(d.explain())
+```
+
+<!-- output -->
+<details open>
+<summary>Output</summary>
+
+```text
+transport  min  not built
+  sets        P · W
+  parameters  cost (P,W) · supply (P) · demand (W)
+  variables   x (P×W) [0.0, inf]
+  constraint  supply (P)  Sum(W, x[P, W]) <= supply[P]
+  constraint  demand (W)  Sum(P, x[P, W]) >= demand[W]
+  objective   min  Sum(P, W, cost[P, W] * x[P, W])
+```
+
+</details>
+<!-- /output -->
+
+A definition is copied before it is bound, so one definition builds as many models as it is given datasets for and is unchanged by any of them. The built model is inspected the same way, and `row()` reads one row back out of the assembled matrix as the solver receives it.
+
+```python
+import numpy as np
+from nimopt import Definition, Sum
+
+d = Definition("transport")
+P, W = d.set("P"), d.set("W")
+cost = d.param("cost", (P, W))
+supply = d.param("supply", (P,))
+demand = d.param("demand", (W,))
+x = d.var("x", (P, W))
+d.eq("supply", Sum(W, x[P, W]) <= supply[P])
+d.eq("demand", Sum(P, x[P, W]) >= demand[W])
+d.set_objective(Sum(P, W, cost[P, W] * x[P, W]))
+
+data = {
+    "P": np.array(["lisbon", "porto"]),
+    "W": np.array(["berlin", "paris", "rome"]),
+    "cost": np.array([[2.0, 4.0, 5.0], [3.0, 1.0, 6.0]]),
+    "supply": np.array([30.0, 25.0]),
+    "demand": np.array([20.0, 15.0, 15.0]),
+}
+m = d.build(data)
+print(m)
+print(m.row("demand", W="paris"))
+print(m.absent("demand"))
+```
+
+<!-- output -->
+<details open>
+<summary>Output</summary>
+
+```text
+Model('transport', 1 variables, 6 columns, 5 rows)
+demand[W='paris']  row 3
+  1·x[lisbon,paris] + 1·x[porto,paris] >= 15
+demand  3 of 3 rows  stated by terms
+```
+
+</details>
+<!-- /output -->
+
+## A variable over a subset
+
+Where a variable spans an arc list rather than a full product, it has a column per arc and the product is never built. A thousand plants each serving three warehouses is three thousand columns, not a million.
+
+```python
+import numpy as np
+from nimopt import Model, Set, subset
+
+P = Set("P", np.array([f"p{i}" for i in range(1000)]))
+W = Set("W", np.array([f"w{i}" for i in range(1000)]))
+
+served = np.array([f"w{(i * 7 + k) % 1000}" for i in range(1000) for k in range(3)])
+arcs = subset((P, W), {"P": np.repeat(P.labels, 3), "W": served})
+
+m = Model("transport")
+x = m.var("x", (P, W), subset=arcs)
+print(f"{m.n_columns} columns over a product of {len(P) * len(W)}")
+```
+
+<!-- output -->
+<details open>
+<summary>Output</summary>
+
+```text
+3000 columns over a product of 1000000
+```
+
+</details>
+<!-- /output -->
+
+## Features
+
+- Sets, aliases, subsets and set products as the index structure of every declaration
+- Parameters from dense arrays or long-form columns, broadcast where a parameter is narrower than the variable it multiplies
+- Composable coefficients: a parameter read at its sets, or an arithmetic of parameters written before data exists
+- Conditions on a sum and on a constraint, lags that drop or wrap at the ends of a set, and members fixed at a label
+- Per-column bounds from a parameter, and variables declared over a subset of a set product
+- A `Definition` written before data exists and built against any number of datasets
+- `explain()` on a definition or a built model, `row()` into the assembled matrix, and `absent()` reporting dropped rows and the rule that dropped each
+- A `Session` that keeps the solved instance open, and `diagnose()` reporting the conflicting rows of an infeasible model or the ray of an unbounded one
+- Primals and duals returned over their index sets, with absence distinct from zero
+- Continuous and integer columns, solved through HiGHS, Gurobi or Mosek behind one adapter contract, with `capabilities()` stating what each adapter does and which capabilities it refuses together
+- One option vocabulary translated into each solver's own spelling, so a time limit is stated the same way whatever solves the model
+- A model written to and read back from YAML, with its data inline or in a sidecar
+- A corpus of worked models under `nimopt.models`, each stating its formulation, inputs at any size, and an objective computed by arithmetic rather than by a solver
+
+## Performance
+
+Where a variable's columns are a subset of a set product, not materialising the product is worth a great deal. On a transport model of 400 000 arcs over a 20 000 000-cell product, `nimopt` builds the same matrix in 72.9 MB of resident memory against a dense rival's 1 682.9 MB, and in 292.9 ms against 844.5 ms.
+
+Where nothing is sparse, the alignment work is a cost with no corresponding saving. On a fully dense temporally-coupled model at 2 111 080 rows, the same comparison reverses: the rival builds the matrix three times faster, for seven per cent more resident memory.
+
+Both rows are in the suite for the same reason. The [benchmark page](website/docs/explanation/what-the-numbers-measure.md) gives each figure, the baseline it is measured against, and what it does not claim.
+
+## Documentation
+
+- [Get started](website/docs/get-started/index.md): installation, and the transport model above solved and read back.
+- [Vocabulary](website/docs/vocabulary/index.md): the terms used throughout the documentation.
+- [Tutorial](website/docs/tutorial/sets-and-parameters.md): the transport model built in six steps, one concept per page.
+- Playground: every example runs in the browser and can be edited.
+- [For agents](website/docs/for-agents.md): the mental model, the public surface and the failure modes on one page.
+
+Every Python example on this site is executed by the test suite and shows the output it produced.
+
+## Licence
+
+MIT. See `LICENSE`.
+
+## Citing
+
+The package carries a `CITATION.cff`. Cite it by author, name and version:
+
+> Gaete-Morales, Carlos. *nimopt* (version 0.1.0). MIT.
+
+## Contributing
+
+Issues and patches are welcome once the repositories are published. Until then, the most useful contribution is a model that does not fit: the formulations that are awkward to write determine the next features.