Reasoning About Change Without Numbers
A hands-on tutorial for qrlib, a library for qualitative reasoning about dynamical systems. You'll learn to describe how a system works using only signs and orderings — no exact numbers — and have the computer work out every way it can behave over time.
Who this is for
Undergraduates who can read a little Python and have met the idea of a derivative (the rate at which something changes). You do not need any background in differential equations, control theory, or artificial intelligence. Each lesson is short, runnable, and ends with exercises.
What you'll be able to do by the end
The first nine lessons are the core track. By the end of it you can:
- Describe a system — a draining tank, a swinging spring — as a model of qualitative constraints.
- Simulate it and read the tree of possible behaviors.
- Understand the library's central promise: it never misses a real behavior (and why that guarantee runs one direction only).
- Add numbers back in to get time bounds ("it fills between t=1 and t=2").
- Reach for the analysis tools: guided simulation, fault diagnosis, causal ordering, and comparative "what-if" analysis.
The advanced track then shows how to use the rest of the public library: portable models and results, hybrid numeric trajectories, structure learning, total envisionment, alternative authoring front ends, decomposition, tensor execution, and differentiable losses.
See the feature map for an explicit accounting of every public package area and the research lineage of the features it teaches.
Core track
| # | Lesson | You'll learn |
|---|---|---|
| 1 | What is qualitative reasoning? | Why sign-and-order reasoning is powerful, and the one big promise |
| 2 | Quantities and values | Landmarks, quantity spaces, magnitude + direction |
| 3 | Constraints and models | Building a model out of M+, Add, Deriv, … |
| 4 | Your first simulation | qsim, behaviors, terminal classes |
| 5 | Cycles and the spring | Oscillations, point vs. interval time, timelines |
| 6 | Taming spurious behaviors | Landmark discovery, chatter, and the EnergyFilter |
| 7 | The soundness guarantee | The coverage oracle — the heart of the library |
| 8 | Adding numbers back | Semi-quantitative refinement and time bounds |
| 9 | Regions and a tour of the reasoning layer | Piecewise systems; guided sim, diagnosis, causes, what-ifs |
Advanced and applied track
| # | Lesson | You'll learn |
|---|---|---|
| 10 | Portable models and reproducible results | Compact syntax, schemas, model identity, and result provenance |
| 11 | Trustworthy hybrid trajectory abstraction | Crossing events, mode channels, batching, and honest coverage failures |
| 12 | Learning and checking structure from data | Landmark harvest, sign estimation, induction, consistency, and diagnosis |
| 13 | Reasoning beyond one simulation | Total envisionment, temporal logic, monotonicity, and stronger pruning |
| 14 | Composition, tensors, and scale | QPT/devices, DecSIM, backend selection, interval batches, and losses |
| 15 | End-to-end host integration | A complete model → simulate → abstract → check → serialize workflow |
Running the examples
For the browser edition, open index.html. Every lesson also has
an HTML mirror in this directory. The browser edition works offline and can
be served as static files; share the hosted docs/tutorial/index.html URL.
After editing the Markdown, regenerate the HTML with Node.js and the
marked package (version 17):
node docs/tutorial/build_html.mjs
The build script accepts MARKED_MODULE as an optional path to an existing
marked ES module. The generated pages do not need Node.js or JavaScript to
read; JavaScript only adds navigation and code-copy conveniences.
Examples use only a normal qrlib install unless an optional dependency is
called out. Blocks build cumulatively within a lesson; Lessons 4 and 6 also
reuse the model and initial state from the preceding lesson. Output and deliberately
incomplete sketches are marked as text rather than executable Python. From
the repository root:
pip install -e . # install qrlib in editable mode
python -c "import qrlib; print(qrlib.__version__)"
Copy a lesson's code into a file (or a REPL) and run it. Where a lesson shows a picture, that picture was produced by the library itself — regenerate them all with:
python docs/tutorial/make_figures.py
The script in make_figures.py is also worth reading: it
is a compact tour of the same API the lessons introduce.
A note on honesty
Qualitative reasoning trades precision for coverage. This library is careful about what it can and cannot promise, and so is this tutorial — Lesson 7 is entirely about that boundary. Keep it in mind: the goal is not to predict the future, but to enumerate every possible future soundly.