Model Format Reference

Lecture 1.1 introduces this form. This page is where to come back when a model gets complicated enough that the question is not what to write but which slot it goes in.

The form is how the lectures present a model, and how a model is handed to an AI assistant: a statement in this form is a specification the assistant can descend from, while a paragraph of prose is an invitation to guess.

Quick reference

Six keywords, in this order, and no others.

Keyword Holds
minimize: / maximize: what is being optimized
solve for: what is being determined, and over what values
subject to: what restricts the solutions
return: what a model that determines nothing computes
assumptions: what must be true about the world
where: what was given: data and symbol meanings (formulation rung only)

A model can be written on up to three rungs, which together make up the model ladder: the concept, in words only; the formulation, the same model committed to symbols or pseudocode; and the implementation, runnable Julia. The six keywords are the model format, and five of them are used on every rung. where: is the exception, because it defines symbols and the concept has none, so the first appearance of where: is the signal that a model has descended past the concept. Sec. 7 sets the ladder out in full.

The pair to keep straight is subject to: against assumptions:. A constraint restricts the solutions; an assumption is something that has to be true about the world. Sec. 2 gives the test.

Four rules govern the slots:

  • minimize:/maximize: and return: take exactly one entity. If a return seems to need three things, it is one composite thing: name it.
  • solve for:, subject to: and assumptions: are always lettered lists, (a) (b) (c), one item per line, even at a single item.
  • where: is a definition list keyed by symbol, not lettered, since every entry is a symbol and its meaning.
  • The six are the whole list. A seventh keyword is an error, however plausible it reads. What it would say belongs in solve for: if it names an unknown, or in return: if it names what a model that determines nothing computes.

The first line shows what kind of model it is:

Kind Opens with Determines? Prefers?
Optimization minimize: / maximize: yes yes
Feasibility solve for: yes no
Descriptive return: no no

A model that determines something has no return:. solve for: already names its output, and the optimal value is the objective evaluated at the solution. Lectures before 3.4 still write a return: in such models, and this semester either form is accepted.

A model written this way can be checked mechanically; see Sec. 11.

1. Why the slots are shaped this way

Every model has the same slots in the same order, so a slot that is thin or missing is visible as a slot rather than as an absence nobody notices.

The always-a-list rule exists for the same reason. A single constraint written inline reads as a sentence; written as (a) it reads as a list with one entry, and the reader asks what (b) would have been.

Omitted, or present and empty

A slot is omitted when the category does not apply to that kind of model. A descriptive model has nothing to determine, so solve for: is absent, and its absence is how the reader knows what kind of model it is.

A slot is written with none when the category applies but is empty. An optimization model with no constraints gets subject to: none, which is a real finding about the problem rather than an omission: the unconstrained economic-order-quantity model is the standard example.

Slot Descriptive Feasibility Optimization
minimize: / maximize: absent absent required
solve for: absent required required
subject to: absent required required, may be none
return: required absent absent
assumptions: required required required

A feasibility model whose subject to: would read none is not a feasibility model at all: with nothing to satisfy, every candidate works and there is nothing to solve.

2. Which slot does it go in?

Ask these in order. The first yes is the answer.

1. Is it the single thing being made best? → the objective

minimize: or maximize:, and there is only one. Two competing objectives means either choosing one and turning the other into a constraint, or stating the resolution explicitly: in order of priority, weighted, or Pareto.

In the concept the objective is a phrase, not an equation with the symbols removed. “The total annual cost of opening hubs and serving every store” is a concept objective. “The sum over sites of fixed cost plus the sum over pairs of flow times distance” is a formulation objective wearing words.

2. Is it an unknown the model determines? → solve for:

This slot names each unknown and says what values it may take. That second half is what makes it a declaration rather than a list of nouns, and it is the half most often left out.

A useful tell: statements here are permissive. They name or enlarge the set of possibilities and never remove any. “The warehouse may be placed anywhere in the service region” removes nothing, so it is not a constraint however much it sounds like one.

3. Would it eliminate a solution that is otherwise available? → subject to:

A constraint binds the solution. Each one carries a short name before its text, because that name is what it will be called in the code:

subject to:
  (a) demand:   every store's demand is fully served;
  (b) capacity: no hub exceeds its throughput limit;
  (c) linkage:  a site serves demand only if it is open

4. Does the model take it as given rather than representing it? → assumptions:

An assumption is a condition about the world or the data that the model treats as determined, so that it does not have to be modeled. Every model simplifies something, and writing the simplifications down here is what makes them legitimate instead of hidden.

“Stops are uniformly distributed over the service region” is an assumption because the model does not represent where the stops actually are, it takes a claim about them instead. “Store demands are known and constant” is an assumption because the model does not represent demand varying, it assumes it away.

The test against a constraint is falsifiability. A constraint is imposed, so it cannot be untrue; an assumption is a claim about how things are, so it can. A constraint binds the solution; an assumption binds the model, and a false assumption gives not a worse answer but the wrong model.

So when an answer looks wrong, the first question is usually not “was the arithmetic right?” but “is one of the assumptions still true?”

5. Is it what a model that determines nothing computes? → return:

Only a descriptive model has this slot.

Its one entity, named in words, is the most consequential line of a descriptive concept, since it is where “what would I actually do with this answer?” gets determined.

return: is not a place for by-products. If a quantity is computed along the way and is worth reporting, it belongs inside the one composite thing being returned, described as part of it.

6. Is it a symbol definition or given data? → where:

where: never appears in the concept. It defines every symbol the formulation uses: the given data, with units, and the meaning of each decision variable. The concept’s solve for: names the decision in words.

3. The three mistakes this form catches

A domain choice written as a constraint. If a warehouse must sit at one of eight existing stores, the wrong repair is adding a constraint. The right repair is changing what the unknown is, from a point in the plane to a choice among eight sites, in solve for:. That makes it a different kind of problem, with a different solution method, which solve for: shows and a list of constraints buries.

An assumption written as a constraint. “The warehouse has no capacity limit” sounds restrictive and is not. It is a falsifiable claim about the world that justifies the absence of a capacity constraint, so it is an assumption.

A decision hidden in return:. Writing “return: which six locations to open and the hub each demand point uses” puts the decision in the output slot and leaves solve for: empty. The decision goes in solve for:, and once it is there the model needs no return: at all.

4. Worked: a descriptive model

Nothing is determined; a quantity is computed.

return:      the average distance from the depot to a stop
assumptions:
  (a) stops are uniform over the service region;
  (b) travel is straight-line, so road circuity is ignored

No objective and no solve for:, and their absence is the information: this model answers a question rather than making a choice.

5. Worked: a feasibility model

Something is determined, but no solution is preferred over another that also works.

solve for:
  (a) the apartment location, a point along the corridor
subject to:
  (a) equity: the two partners' weighted travel is equal

No return:: the apartment location is the unknown, and solve for: has named it.

6. Worked: an optimization model, mixed variable types

The form does not change as models get harder; only the lists get longer.

Concept, words only.

minimize:   the total annual cost of opening and serving
solve for:
  (a) which of the five candidate sites to open;
  (b) how much of each store's demand each open hub serves;
  (c) the fleet size based at each open hub
subject to:
  (a) demand:   every store's demand is fully served;
  (b) capacity: no hub exceeds its throughput limit;
  (c) linkage:  a site serves demand only if it is open
assumptions:
  (a) store demands are known and constant;
  (b) transport cost is proportional to weighted distance

Formulation: the same slots, now with symbols, and where: appears.

solve for:
(a) y_k \in \{0, 1\}, k \in K;
(b) x_{jk} \geq 0, j \in J, k \in K;
(c) f_k \in \mathbb{Z}_{+}, k \in K

where:

y_k
= 1 if site k is opened, 0 otherwise
x_{jk}
= demand of store j served from site k
f_k
= vehicles based at site k
K
= set of candidate sites
J
= set of stores
d_j
= annual demand of store j (ton)
c_k
= annual fixed cost of operating site k ($).

solve for: gives each unknown its symbol and the values it may take; where: says what every symbol means, unknowns and given data alike.

7. The model ladder

The three rungs of a model ladder are not three models or three stages of a process but one model stated three ways, in words, in mathematics and in code, each a complete statement of it. (The ladder is not Lecture 1.1’s levels of modeling, which rank different models by cost and faithfulness.)

Rung Content What it determines
Concept Words only, no symbols: the slots above, verbally what is being determined and why
Formulation Symbols and equations, or pseudocode; where: enters how it is represented and solved
Implementation Runnable Julia how it is computed

Not every model goes all the way down. A concept alone is a legitimate model, and often the only one worth writing. A concept with a formulation and no implementation is equally legitimate when the point is the mathematics rather than an answer.

How the rungs are titled

The concept carries no rung word. The concept is what a model is, so its caption is the number and name alone; the other two rungs add their rung word:

Model 3: Poisson arrival simulation                 <- the concept
Model 3 formulation: Poisson arrival simulation
Model 3 implementation: Poisson arrival simulation

Everything carrying “Model 3” is one model.

Descending is a fill-in, not a rewrite

Each rung commits detail the one above left open; it must not change what the one above said. If the formulation carries a constraint the concept never mentioned, something was determined silently. The same holds further down: an implementation that quietly assumes a bound the formulation did not state is not an implementation of that model.

When one concept has more than one formulation

Two approaches to one concept are not two models but two formulations under it, each with its own implementation, told apart by a parenthetical rather than a new number:

Model 5: single-facility minisum location
Model 5 formulation (analytic): ...      Model 5 implementation (analytic): ...
Model 5 formulation (numerical): ...     Model 5 implementation (numerical): ...

Renumbering would claim a second problem where there is one problem and two methods.

Branching below the formulation is almost never wanted. Two implementations of one formulation are a coding difference, not a modeling one. The course’s habit is to parameterize instead: minisum(w, P, dist) takes the distance function as an argument, so one implementation serves straight-line and great-circle distance.

8. Two cases at the edge of the form

More than one objective

minimize: still holds one entity, but that entity may be an ordered preference rather than a single quantity. Give the objectives in order and say how they are resolved:

minimize:   first the number of vehicles used, then, among the solutions
            that use the fewest, the total distance travelled

That is the lexicographic resolution, and it is the one this course uses most: the second objective is a tie-break among the answers that are already best on the first. The alternatives are a weighted sum, which trades the objectives against each other at a stated exchange rate, and a Pareto treatment, which declines to trade them and returns the set of answers where improving one means worsening another.

Whichever is used, say which. An unresolved list of objectives is not a model, since it does not determine an answer.

Models whose constraints contain another model

Some problems are genuinely two-storey: one decision is made in anticipation of how somebody else will then respond, and the second party’s response is itself the answer to an optimization. Siting facilities knowing that competitors will site theirs afterwards is the standard example, and the beach models of Lecture 2.1 are its simplest form.

The slots do not yet express this, and how they should is an open question. The follower’s problem is not a condition a solution satisfies but a whole model whose solution the leader’s constraints refer to, and it is not an assumption either, since it is derived rather than given.

A convention would state the follower’s model in the same slots and have the leader’s subject to: name it. If a bi-level model appears in the course, this section will be filled in rather than the model forced into the flat form.

9. Comparing two models

A lecture often presents one model as a change to another, and five words name how the two are related. Four come in two pairs that answer different questions, and the fifth names two very similar models that fit neither:

Special case / generalization Restriction / relaxation Variant
Compares two problems, over all their instances two feasible sets, on one instance two very similar models, with the same decisions
Test Can every instance of A be posed as an instance of B, with the same solutions? Then A is a special case of B, and B a generalization of A. Is every feasible solution of R feasible for Q, with Q’s objective never worse on them? Then R is a restriction of Q, and Q a relaxation of R. Is B made from A by changing a few of its parts and keeping its decisions, in a way none of the other four words describes on every instance? Then B is a variant of A.
Bounds the optimum? no yes: minimizing, relaxation \leq original \leq restriction; maximizing reverses it no bound holds on every instance
Why it matters a special case can admit a faster method; a generalization covers more situations a relaxation gives a bound; a restriction gives a feasible answer records that the two models are close when no class or bound relation holds

A special case narrows the problem; a restriction narrows the solutions. Only the second pair gives a bound, the reasoning behind the Bounds check of Lecture 1.2. A special case gives no bound: on its own instances it has the general problem’s optimum. A relaxation may also replace the objective with one never worse on the original’s solutions; Lagrangian relaxation, named in Lecture 4.4, works that way.

Which slot the change is in

The slot a change touches usually says which word applies:

Change to the model Slot The new model is a
Fix given data, or add an assumption where:, assumptions: special case
Add given data, or let fixed data vary where:, often with a subject to: row that uses it generalization
Add a rule no choice of the given data reproduces subject to:, or a narrower solve for: domain restriction
Drop a rule subject to:, or a wider solve for: domain relaxation
Widen one part and narrow another, keeping the decisions two slots at once, such as a where: entry and a subject to: row both added variant
Replace the objective with one no choice of data reproduces, neither always the lower minimize: or maximize: variant

A two-variable linear program shows all five. On the formulation rung, Model A is

\begin{array}{rlrclll} \textbf{Model A} : & \text{Minimize} & c_1 x_1 + c_2 x_2 & & & & \\[2pt] & \text{subject to} & & & & & \\[2pt] & & 2x_1 + x_2 & \geq & 6 & & (a) \\[2pt] & & x_1 + 2x_2 & \geq & 9 & & (b) \\[2pt] & & x_1,\, x_2 & \geq & 0 & & \end{array}

where

c_1, c_2
= given cost per unit of x_1 and of x_2.

On the instance c_1 = c_2 = 1 its best is 5, at (1, 4). Each model below makes one change to it.

Model Change to Model A Relation to Model A Best, c_1 = c_2 = 1
B costs fixed at 1: minimize x_1 + x_2 special case 5 at (1, 4)
C add (c) x_2 \leq u, with u given generalization; u = \infty is Model A 5 at (1, 4) with u = 4; 7 at (5, 2) with u = 2
D add (c) x_1 \geq x_2 restriction 6 at (3, 3)
E drop (b) relaxation 3 at (3, 0)
F add (c) x_2 \leq 2 restriction 7 at (5, 2)
G make the 9 in (b) a given b, and add (c) x_1 \geq x_2 variant 6 at (3, 3) with b = 9; 4 at (2, 2) with b = 6

The bounds hold as the second pair promises: the relaxation’s 3 is below Model A’s 5, and the restrictions’ 6 and 7 are above it.

Where a number lives determines the relation. Models C and F add the same-looking row. In Model C the bound u is given data, and set to \infty it never binds, so every instance of Model A is an instance of Model C. In Model F the 2 is written into the row and holds on every instance, so the row only removes solutions. An added constraint generalizes only when it carries data that can make it slack.

The reverse holds too. A constraint gives a special case when some choice of the general model’s given data has the same effect. Model F is a special case of Model C, since setting u = 2 imposes it, though only a restriction of Model A, which has no u. A traveling salesman problem (TSP) that forbids arc (i, j) is the TSP with c_{ij} = \infty, and an integer program is a mixed-integer program with every variable chosen to be integer.

When neither holds: a variant

A variant is a model very like another: made from it by changing a few of its parts while keeping its decisions, when none of the four words describes the change on every instance. Calling it a variant records that the two are close even though no class or bound relation holds. Two models that share no decisions, such as a TSP and a facility location model, are not variants of each other; they are different models. A change escapes all four words in one of two ways. One part can be widened while another is narrowed, as in Model G: the 9 in row (b) becomes given data b, which generalizes, and x_1 \geq x_2 is added, which restricts. Its best is 6 with b = 9 but 4 with b = 6, above and below Model A’s 5. Or the objective can change in a way no choice of data reproduces, with neither objective always the lower. Either way, no bound between the two answers holds on every instance. A changed objective that is never above the other on every solution makes a relaxation instead: with nonnegative costs a tour’s largest arc cost never exceeds its total, so the bottleneck TSP is a relaxation of the TSP.

State the strongest relation that holds

A pair can stand in more than one relation, so the one to state is the first of these that is true:

  1. special case or generalization;
  2. restriction or relaxation, when it holds on every instance;
  3. variant.

The TSP against the assignment problem is the standard case. Neither is a special case of the other, since no choice of costs keeps an assignment from forming subtours. But every tour is an assignment, so the TSP is a restriction of the assignment problem, and the assignment problem’s optimum is a lower bound on the shortest tour.

10. Using this as a prompt

Hand an assistant a model written in this form and it has what it needs: what to optimize, what to determine, what must hold, what to give back, and what it may take for granted. Hand it a paragraph and it will supply all five itself, plausibly and invisibly.

The model does not go in the chat. It goes in a file, and the prompt points at the file. Keep it beside the work as model.md, and ask for what is wanted this time:

Read model.md, produce the formulation, then a Julia
script implementing it, and run it.

A file has four advantages over the chat.

It is revisable. Editing one slot in a file and re-running beats retyping a paragraph and hoping the change was the only one.

It survives the session. A model stated in conversation erodes as the window fills; a file is re-read whole, as precise on the hundredth turn as the first.

It separates the specification from the task. model.md says what the model is. The prompt says what to do with it now: formulate it, implement it, vary a parameter, check a result against it. Keeping them apart stops a prompt from quietly becoming the model.

It leaves a history. The file can be committed, so the model’s evolution is visible and a slot that was silently dropped can be found.

Where each rung lives

The concept and the formulation are one model on two rungs, so they share one file. The formulation goes into model.md beneath the concept, exactly as a lecture’s model callout shows both in a single object.

The concept is the only rung written by hand. The assistant produces the formulation and the implementation; both are then checked.

Rung Written by Lives in
Concept the reader model.md, written first
Formulation the assistant, asked for model.md, beneath the concept
Implementation the assistant, asked for a Julia script, because it has to run

Turning a stated model into symbols and then into code is translation, and translation is what the assistant is for. Determining what is being optimized, what is being determined, what must hold and what may be assumed is not translation, and it is not delegated.

Give the script a header comment naming the model file it came from, so the pair does not drift apart.

Keeping both in one file is what makes the descent checkable. A constraint present in the formulation and absent from the concept above it is then visible at a glance.

11. Checking a model mechanically

Because the form is strict, a program can check whether a model statement follows it. One ships with the course materials:

julia ../materials/env/check_model.jl model.md

Run from the folder holding the model, so the relative path reaches across to materials. It prints a line per finding with its line number, and exits nonzero when any finding is an error.

What it checks. That every keyword is one of the six and spelled as such; that the keywords appear in the order above; that minimize:, maximize: and return: carry exactly one entity; that solve for:, subject to: and assumptions: are lettered lists running from (a) without gaps, or read none; that every constraint carries a name; that where: is keyed by symbol rather than lettered; that a model determining nothing has a return:; and that the slots are mutually coherent, so an objective without solve for: is an error and solve for: without subject to: is queried.

What it cannot check is the modeling. It cannot tell that something written as a constraint is really an assumption, that a domain choice was buried in subject to: instead of solve for:, that a return: is naming a by-product, or that an assumption is false. Those are judgments, and a clean report says only that the statement is well formed:

OK  model.md conforms to the model format.
    Note: the format is checked, not the modeling. Whether a
    constraint should have been an assumption is still yours.

Run it every time, since it is cheap, but read a clean result as evidence about form alone, the same distinction the course makes about AI-produced work.