The methodology¶
Every example in this guide follows the same workflow. It is a loop: the first pass produces a working model, and you then go back to the conversation to add constraints, cover new cases, or change the problem, as many times as needed.
The Modeler workflow
The specification is produced by the conversation; the implementation and tests are derived from it, and the formulation on request.
Business question
Plain terms, incomplete
Clarifying questions
One at a time, by importance
Specification
Business language, no mathematics
Derived from the specification
Implementation
gurobipy
Tests
One per scenario; run until they pass
Formulation
Optional, on request
Then round again
The first pass gives you a working model, not a final one. A new constraint, a revised objective or a missing edge case goes back through the conversation, reaches the specification first, and propagates outward in the same order — which is what keeps the artifacts in sync.
1. The problem definition is built through questioning¶
You start with the business question in plain terms, without a complete specification. Modeler builds the definition from there.
Questions are asked one at a time, in order of importance. The business objective is settled first, then the constraints, then the data entities and the expected output. A constraint that changes the structure of the model is resolved before one that only changes a value.
Each question comes with ranked candidate answers, drawn from comparable problems in the knowledge base. Select one by number or describe your own case.
Constraints accumulate one at a time. Each is recorded with an identifier (
C1,C2, …) so it can be traced into the implementation and tests.The specification is rewritten after every answer, including while it is still incomplete.
Gaps are not filled in silently. An unresolved question is asked.
The specification is the central artifact¶
The specification is what the conversation produces. The implementation and the tests are derived from it, as is the formulation if you request one, and it is the only artifact you are asked to review and approve.
It is written in business language and contains no mathematics, so the person who owns the problem can confirm that it is correct. This matters because a correct implementation of a misstated problem still returns the wrong answer. The specification is where that is caught, before any code is generated.
Two of its sections are used later in the workflow:
Test scenarios (
T1,T2, …) are business cases with acceptance criteria, written before the implementation exists. They become the test suite in step 2.Out of scope records what was deliberately excluded from the model.
For the full section-by-section structure of the document, see Modeler in the User Manual.
2. Code is generated with tests and iterated until they pass¶
Modeler generates a gurobipy implementation and a pytest suite together.
The suite contains one test per scenario in the specification, and each test
names the scenario it covers.
The tests are derived from the specification, not from the implementation. A test written from the code would only confirm the code’s current behaviour; a test written from the business scenarios is an independent check.
Modeler then runs the suite, reads the output, corrects the implementation, and re-runs until the tests pass. The result is a model that has been executed and checked, not only generated. Tests use small hard-coded data and a short solver time limit, so the loop runs quickly.
The loop has one other outcome. If a failure is a contradiction between the specification, the implementation, and the tests rather than a defect in the code, no edit resolves it. Modeler stops, reports what it found, and asks you which side to correct.
3. The mathematical formulation is optional¶
The specification, the implementation, and the tests contain no mathematics, and none is needed to build, run, or change the model. The formulation is produced only if you ask for it.
Request it at any point and Modeler derives it — sets, parameters, decision variables, objective, constraints — from the current specification and implementation. Because it is derived on request rather than maintained by hand, it describes the model as it currently stands.
Ask for it when you need to review or document the model, or hand it to someone who works in constraints rather than code. The formulation states the structure more compactly than the code does, so a reviewer can confirm the decision variables and their domains, check the constraints for correctness and redundancy, and verify the objective. It covers what the tests do not: the tests check behaviour on the scenarios listed in the specification, while the formulation exposes the full structure of the model.
4. The workflow is a loop, and that is what keeps the artifacts in sync¶
Steps 1 to 3 are not a one-way sequence. What the first pass produces is a first working version, not a final one. From there you go back to the conversation and keep going: add a constraint you had not thought of, revise the objective, cover an edge case the tests miss, correct something the specification got wrong. Each pass round the loop leaves you with a model that has been solved and tested again.
Going back through the conversation is also what keeps the artifacts in sync, because every pass re-enters at the same place and moves outward in the same order:
A change re-enters through the conversation and lands in the specification first. A new rule becomes a new constraint (
C3,C4, …); a new edge case becomes a new test scenario (T4,T5, …).It then propagates in order: specification, implementation, tests, and the formulation the next time one is requested.
The implementation is not edited directly. Adding a rule to the code that the specification does not mention is what causes the artifacts to diverge.
Existing inconsistencies are reported rather than assumed away. If the specification and the implementation already disagree, Modeler asks which one is correct before making the change.
The specification, the implementation, and the tests therefore stay in agreement by construction, as does the formulation whenever one has been generated. This is the difference from a hand-maintained project, where the artifacts drift apart — the specification describes an earlier version than the code, the tests cover a third — until there is no reliable way to tell which one is authoritative.
Next¶
See Develop with Modeler for how each page presents this workflow. Facility is the most fully worked one.